Inclusão de anexos em Documentos

Produto:

Datasul

Ocorrência:

Documentação de API

Nome físico:

cdp/apiSupplyDocuments.p


Objetivo

Esta API tem como objetivo incluir a opção de anexar arquivos em uma ordem de compra bem como ser possível realizar ações de consulta, filtro, exclusão, download e upload.


Funcionamento

A API fornece uma série de métodos que podem ser executados individualmente para apresentação de anexos na tela do documento.

A sintaxe para a chamada da API, que deve ser de forma persistente:

run cdp/apiSupplyDocuments.p persistent set h-handle.


A variável denominada h-handle irá receber o “handle” do programa, permitindo o acesso aos “métodos” internos da API.

Método Negócio


Quando a API estiver executada em modo persistente, os seguintes métodos estarão disponíveis para execução:


pi-metadata-v1

Requisito

Nenhum.

Descrição

Repassa o parâmetro do tipo de evento recebido pela API de comunicação (cdp/supplyDocuments) para a API de documentos (hubapi/apiDocuments) chamando o método pi-metadata-v1. 

Retorna o metadados com campos e ações ativos referentes a tela de Listagem ou Edição, dependendo de qual tipo foi enviado pela requisição, para a montagem dinâmica da tabela com as informações vindas do backend.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para a busca de metadados:

pathParams:  Informar: metadata.


queryParams →  type: Utilizando este atributo com uma das opções abaixo permite retornar as informações de:
  • list: Metadados da tela de listagem.
  • edit: Metadados da tela de inclusão do arquivo.


{
    "queryParams": {
    "type": "list"
  },
    "pathParams": [
       "metadata"
    ],
}
cEventCharacterINPUTIdentifica qual o tipo de evento vindo do queryParams para a busca do metadado correto.
cVersionCharacterINPUTIdentifica a versão da API.
oOutputJsonObjectOUTPUT

Retorno contendo o metadados com campos e ações conforme parâmetros recebidos:


  • Metadados List:


  {
    "keepfilters": false,
    "literals": {},
    "validateFields": [],
    "title": "Documentos",
    "fields": [
        {
            "visible": false,
            "property": "documentId",
            "label": "Código",
            "type": "number",
            "key": true,
            "order": 1
        },
        {
            "property": "processTypeDescription",
            "width": "15%",
            "label": "Tipo Processo",
            "type": "string",
            "order": 2
        },
        {
            "property": "processKey",
            "width": "15%",
            "label": "Chave Processo",
            "type": "string",
            "order": 3
        },
        {
            "property": "documentName",
            "width": "20%",
            "label": "Documento",
            "type": "string",
            "order": 4
        },
        {
            "property": "documentSize",
            "width": "5%",
            "label": "Tamanho",
            "type": "string",
            "order": 5
        },
        {
            "property": "documentDescription",
            "width": "25%",
            "label": "Descrição",
            "type": "string",
            "order": 6
        }
    ],
    "tableCustomActions": [],
    "actions": {
        "new": "/new",
        "removeAll": true,
        "remove": true
    },
    "pageCustomActions": []
}                                                                                

Para verificar o que significa cada campo de listagem, conferir abaixo: 

  • keepFilters: Mantém na modal de Busca Avançada os valores preenchidos do último filtro realizado pelo usuário.
  • literals: Objeto com as literais usadas.
  • validateFields: Lista que define os campos que irão disparar o validate do form.
  • title: Título da página.
  • fields: São os campos a serem apresentados na tabela, sendo eles: 
    • property: Nome de referência do campo.
    • label: Rótulo do campo exibido.
    • type: Tipo do valor campo.
    • key: Valor lógico que indica se o campo é chave.
    • order: Informa a ordem de exibição do campo.
    • visible: Indica se o campo será visível.
    • width: Tamanho do campo.
  • tableCustomActions: Lista de ações customizadas da tabela que serão incorporadas às ações informadas através da propriedade actions.
  • actions: Ações que o usuário poderá executar na página através de botões:
    • new: Rota ou função para criar um novo recurso, caso seja preenchida habilita a ação de "Novo" na tela de listagem para criação de um novo anexo.
    • remove: Habilita a ação de exclusão na tabela.
    • removeAll: Habilita a ação de exclusão em lote na página.
  • pageCustomActions: Lista de ações customizadas da página que serão incorporadas às ações informadas através da propriedade actions. Essas ações ficam localizadas na parte superior da página em botões com ações. Ex: "Novo", "Excluir".


  • Metadados Edit:


  {
    "defaultFields": [
        {
            "gridColumns": 4,
            "divider": "Processo",
            "label": "Tipo Processo",
            "property": "processType",
            "disabled": true,
            "options": [
                {
                    "value": 1,
                    "label": "Ordem de Compra"
                }
            ]
        },
        {
            "gridColumns": 4,
            "label": "Chave",
            "property": "processKey",
            "disabled": true
        },
        {
            "autoUpload": true,
            "gridColumns": 4,
            "divider": "Anexar Documento",
            "label": "Selecione o documento",
            "property": "documentUpload",
            "required": true,
            "type": "upload"
        },
        {
            "maxLength": 200,
            "gridColumns": 4,
            "label": "Descrição",
            "property": "documentDescription",
            "rows": 4
        }
    ],
    "title": "Novo Documento",
    "breadcrumb": {
        "items": [
            {
                "link": "/",
                "label": "Documentos"
            },
            {
                "link": "/new",
                "label": "Novo Documento"
            }
        ]
    }
}                                                                              


Para verificar o que significa cada campo de edição, conferir abaixo: 
  • defaultFields: Armazena as informações dos campos padrões do formulários: 
    • gridColumns: Tamanho de exibição do campo em telas.
    • divider: Exibirá um divisor acima, utilizando o seu conteúdo como título.
    • label: Rótulo do campo exibido.
    • property: Nome de referência do campo.
    • disabled: Função que deve retornar um booleano para habilitar ou desabilitar a ação para o registro selecionado.
    • options: Lista de opções que serão exibidas em um componente, podendo selecionar uma opção.
      • value: Valor que será usado como referência para exibição do conteúdo na coluna, representa o tipo de processo.
      • label: Rótulo do campo exibido, referenciando o nome do tipo de processo.
  • autoUpload: Define se o envio do arquivo será automático ao selecionar o mesmo.
  • required: Indica que o campo será obrigatório.
  • type: Tipo do valor do campo.
  • maxLength: Tamanho máximo de caracteres.
  • rows: Quantidade de linhas exibidas no campo "Descrição".
  • title: Título da página.
  • breadcrumb: Objeto com propriedades do breadcrumb, componente que gera uma estrutura de navegação que apresenta ao usuário a localização da URL atual, exibindo as antecessoras conforme é realizado a navegação na aplicação:
    • items: Lista de itens do breadcrumb:
      • link: Url do item.
      • label: Rótulo do item.


RowErrorsTemp-tableOUTPUTInformações sobre os erros ocorridos durante o processo de busca dos dados.

Retorno

Retorna informações do metadados ou erros ocorridos durante a busca



pi-query-v1

Requisito

Nenhum.

Descrição

Repassa os parâmetros recebidos pela API de comunicação (cdp/supplyDocuments) para a API de documentos (hubapi/apiDocuments) após a execução das validações de restrição, chamando o método pi-query-v1.

Retorna a lista de anexos relacionados a um documento.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para a busca de anexos:

queryParams:

 → processType=: Tipo do processo vinculado ao documento, sendo "1" a Ordem de Compra, com base na include uninc/i01un403.i.

 → processKey=: Código da chave do processo, identifica o processo ao qual o anexo pertence. A chave pode ou não ser composta. Caso seja, será separada por pipe "|" e deve ser enviada no formato encode. No exemplo abaixo, a chave "1234%7CABC" está no formato encode e corresponde a chave composta: "1234|ABC".


{
    "queryParams": {
       "processType": "1",
       "processKey": "1234%7CABC"
  }
}


A consulta também permite a pesquisa por campos. Os parâmetros são os mesmos utilizados na queryParams de busca, sendo apenas adicionando o "search" na requisição juntamente com o critério de filtro que pode ser: nome do anexo, descrição do anexo ou usuário criador. No exemplo abaixo está sendo solicitada uma consulta utilizando  um filtro para mostrar apenas os documentos anexados pelo usuário "super".


{
    "queryParams": {
       "processType": "1",
       "processKey": "1234%7CABC",
	   "search":"super"	
  }
}
aResultJsonArrayOUTPUT

Retorno do processo, contendo os itens da listagem de anexos conforme parâmetros enviados.

{
    "total": 3,
    "totalHits": 3,
    "hasNext": false,
    "items": [
        {
            "creationUserName": "Super",
            "documentDir": "c:\\tmp\\ERP\\1\\123\\5\\c3e349d230b2d176eefb7d58f2eb35e1.txt",
            "creationUser": "super",
            "documentDescription": "arquivo 123",
            "processKey": "123|5",
            "documentId": 392,
            "processType": 1,
            "documentName": "arquivo123.txt",
            "documentSize": "74 Bytes",
            "processTypeDescription": "Ordem de Compra",
            "creationDatetime": "2022-02-07T09:12:43.000"
        },
        {
            "creationUserName": "Super",
            "documentDir": "c:\\tmp\\ERP\\1\\123\\5\\",
            "creationUser": "SUPER",
            "documentDescription": "teste download",
            "processKey": "123|5",
            "documentId": 393,
            "processType": 1,
            "documentName": "testando.txt",
            "documentSize": "1GB",
            "processTypeDescription": "Ordem de Compra",
            "creationDatetime": "2022-02-07T18:01:17.000"
        },
        {
            "creationUserName": "Super",
            "documentDir": "c:\\tmp\\ERP\\2\\1234\\5\\2ca28ec306fb5e55c24448f2bdb1baa3",
            "creationUser": "SUPER",
            "documentDescription": "teste download",
            "processKey": "123|5",
            "documentId": 396,
            "processType": 1,
            "documentName": "testando.txt",
            "documentSize": "1GB",
            "processTypeDescription": "Ordem de Compra",
            "creationDatetime": "2022-02-07T18:08:29.000"
        }
    ]
}

Para verificar o que significa cada campo, conferir na descrição das temp-tables no final desta documentação:

  • ttDocumentFile: Contém os campos a serem retornados na busca dos documentos do processo.


lHasNextLogicalOUTPUTIndica se existem mais registros a serem mostrados na página.
iTotalHitsIntegerOUTPUTContagem do total de registros encontrados.
RowErrorsTemp-tableOUTPUTInformações sobre os erros ocorridos durante o processo.

Retorno

 Retorna a lista de arquivos relacionados a um documento ou erros ocorridos durante a busca.



pi-upload-v1

Requisito

Nenhum.

Descrição

Repassa os parâmetros recebidos pela API de comunicação (cdp/supplyDocuments) para a API de documentos (hubapi/apiDocuments) chamando o método pi-upload-v1.

Retorna informações do arquivo em que o upload está sendo efetuado.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para o upload:

pathParams:  Informar: upload.

queryParams → files=: Arquivo a ser efetuado o upload, sendo enviado também como parâmetro. 

Exemplo abaixo do formato de requisição com arquivo enviado como parâmetro:


{
  "content-type": "multipart/form-data",
   "multipart": [
    	{
         "headers": {
                     "Content-Disposition": "form-data; name=\"file\"; filename=\"Adobe Sign Form Field.pdf\""
         },
         "body": {
                   "content-type": "application/pdf",
                   "content": "@{base64(body('Get_file_content_Signed_PDF'))}"
         }
      }
   ]
}
oOutputJsonObjectOUTPUT

Informações do arquivo:


{
  "fileName": "Evidencia_DMANSUPIMPA2-419.docx",
  "content": "UEsDBBQABgAIAAAAIQCJi8MJ4gEAAF4KAAATAAgCW0NvbnRlbnRfVHlwZXN..."
}

Para verificar o que significa cada campo, conferir abaixo: 

  • fileName: Nome do arquivo que está sendo efetuado upload, seguido pela extensão.
  • content: Conteúdo presente no arquivo, convertido para base64.


RowErrorsTemp-tableOUTPUTInformações sobre os erros ocorridos durante o processo de upload.

Retorno

Retorna informações do nome do arquivo e seu conteúdo em base64 ou erros ocorridos durante o processo.



pi-download-v1

Requisito

Nenhum.

Descrição

Repassa os parâmetros recebidos pela API de comunicação (cdp/supplyDocuments) para a API de documentos (hubapi/apiDocuments) chamando o método pi-download-v1. Também realiza validações de restrição dos usuários em relação a menu e processos.

Retorna informações do arquivo em que o download está sendo efetuado.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para download do anexo:

pathParams:  Informar: download e ID do documento.


{
    "pathParams": [
    "download",
    "402"
  ],
}
oOutputJsonObjectOUTPUT

Retorno das informações do arquivo que está sendo realizado o download:


{
    "headers": {
        "Content-Type": "application/octet-stream"
    },
    "payload": {
        "file": {
            "FN_File": "Evidencia_COD_DMANSUPIMPA2-605.docx",
            "DN_File": "UEsDBBQABgAIAAAAIQBkdsOlw57DhwEAAMOKCQAAEwAIAltD..."
        }
    }
}

Para verificar o que significa cada campo, conferir abaixo: 

  • File : contém as informações do anexo
    • FN_File: Nome do arquivo com extensão, vindo da tabela arquivo_docto.
    • DN_File: Conteúdo do arquivo em base64.  


RowErrorsTemp-tableOUTPUTInformações sobre os erros ocorridos durante a busca dos códigos dos anexos.

Retorno

Retorna informações de nome e conteúdo do anexo que está sendo feito download ou erros ocorridos durante o processo.



pi-delete-v1

Requisito

Nenhum.

Descrição

Repassa os parâmetros recebidos pela API de comunicação (cdp/supplyDocuments) para a API de documentos (hubapi/apiDocuments) chamando o método pi-delete-v1. Também realiza validações de restrição dos usuários em relação a menu e processos.

Retorna informações relacionadas a exclusão dos anexos.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para eliminação de anexo individual:

pathParams:  Informar: ID do anexo.


{
    "pathParams": [
       "1234"
    ],
}


Parâmetros para eliminação de anexo em lote:

Payload: Informar os IDs a serem eliminados:


[
   {"documentId": 552, 
   {"documentId": 553},
   {"documentId": 554}
]
oOutputJsonObjectOUTPUT

Informações da exclusão:

Não há retorno direto via Output nesse método. Em caso de sucesso na exclusão individual ou lote, será retornado vazio.

A montagem do JsonObject e seu retorno ocorrerá na API de comunicações, cdp/supplyDocuments com base no conteúdo vindo da temp-table RowErrors. Para mais informações vide documentação : supplyDocuments - Anexos de Suprimentos (Compras, Contratos, entre outros).

RowErrorsTemp-tableOUTPUT 

Informações sobre os erros ocorridos durante o processo:

A temp-table vem populada com registros criados na API de documentos (cdp/apiDocuments), devido a erros ocorridos durante o processo de eliminação.

Esses registros serão usados para a montagem da mensagem de erro que será retornada via OUTPUT de um JsonObject, na API de comunicação (cdp/supplyDocuments), conforme cada caso específico. 

  • Caso haja erro na tentativa de excluir um único registro inexistente, serão repassados para a API de comunicação (cdp/supplyDocuments) valores na temp-table RowErrors para montagem e retorno do objeto Json. Exemplo do modelo da mensagem utilizando o registro 553:


{
  "detailedMessage": "Registro não encontrado na tabela anexo_docto - Id: 553.\n",
  "code": "57401",
  "message": "Registro não encontrado.",
  "type": "error"
}


  • Caso haja erro na tentativa de excluir registros inexistentes em lote, serão repassados para a API de comunicação (cdp/supplyDocuments) valores na temp-table RowErrors para montagem e retorno do objeto Json. Exemplo do modelo da mensagem utilizando os registros 552, 553 e 554:


{
    "detailedMessage": "Registro não encontrado na tabela anexo_docto - Id: 552.\n",
    "code": "57401",
    "details": [
        {
            "detailedMessage": "Registro não encontrado na tabela anexo_docto - Id: 553.\n",
            "code": "57401",
            "message": "Registro não encontrado.",
            "type": "error"
        },
        {
            "detailedMessage": "Registro não encontrado na tabela anexo_docto - Id: 554.\n",
            "code": "57401",
            "message": "Registro não encontrado.",
            "type": "error"
        }
    ],
    "message": "Registro não encontrado.",
    "type": "error"
}


  • Caso haja erro na eliminação de registros juntamente com sucesso na exclusão em lote, serão repassados para a API de comunicação (cdp/supplyDocuments) valores na temp-table RowErrors para montagem e retorno do objeto Json. Exemplo do modelo da mensagem utilizando os registros 637, 404 e 554:


{
    "_messages": [
        {
            "detailedMessage": "Registro não encontrado na tabela anexo_docto - Id: 554.\n",
            "code": 57401,
            "type": "error",
            "message": "Registro não encontrado."
        }
    ],
    "idList": "404,637"
}

Para verificar o que significa cada campo, conferir nas temp-tables no final desta documentação:

  • RowErrors: Contém os erros e informações sobre os erros ocorridos durante o processo.
    • detailedMessage: Mensagem detalhada do erro ocorrido.
    • code: Número do código do erro ocorrido.
    • message: Mensagem simplificada do erro.
    • type: Tipo da mensagem.
    • idList: Lista de IDs eliminados com sucesso em uma exclusão em lote com erros.


ListaIdsExcluidosCharacterOUTPUT IDs que foram eliminados com sucesso. Serão apresentado na mensagem de retorno caso aconteça de ter erros e sucessos em uma mesma eliminação em lote
RetornoErros ocorridos durante a eliminação via temp-table RowErrors.



pi-create-v1

Requisito

Nenhum.

Descrição

Repassa os parâmetros recebidos pela API de comunicação (cdp/supplyDocuments) para a API de documentos (hubapi/apiDocuments) chamando o método pi-create-v1. Também realiza validações de restrição dos usuários em relação a menu e processos.

Retorna informações sobre o anexo criado.

Parâmetros

Tipo

Input/Output

Descrição

oInput

JsonObject

INPUT

Parâmetros para criação:

Payload:


{
         "processType":1,
         "processKey":"12345|10",
         "documentName":"testeArquivo.txt",
         "documentDescription":"teste de arquivo",
         "documentFile": "JC9CVVNJTkVTU0hVQi9Gb250ZXNfRG9jL1N1c3RlbnRhY2FvL1YxMS9WMTEv..."
 }
oOutputJsonObjectOUTPUT

Informações do anexo criado:


{
    "items": [
        {
            "creationUserName": "Super",
            "documentDir": "\\\\moitas\\tmp\\ERP\\1\\12345\\10\\3c3bbcd88a4f01fb34fb63ae7f845f6c.txt",
            "creationUser": "super",
            "documentDescription": "teste de arquivo",
            "processKey": "12345|10",
            "documentId": 725,
            "processType": 1,
            "documentName": "testeArquivo.txt",
            "documentSize": "74 Bytes",
            "processTypeDescription": "Ordem de Compra",
            "creationDatetime": "2022-03-29T10:59:46.376"
        }
    ]
}

Para verificar o que significa cada campo conferir nas temp-tables no final desta documentação:

  • ttDocumentFile: Contém os campos a serem retornados na busca dos documentos do processo.
RowErrorsTemp-tableOUTPUTInformações sobre os erros ocorridos durante a criação de arquivo.

Retorno

Informações do anexo criado ou erros ocorridos durante o processo.



pi-valida

Requisito

Nenhum.

Descrição

Realiza a verificação dos parâmetros passados na queryParams da pi-query-v1, para restrição de consulta, permitindo buscar apenas todos os documentos do tipo e chave de processo informados.

Parâmetros

Tipo

Input/Output

Descrição

iProcessType

Integer

INPUT

Tipo do processo vindo da queryParams. Caso não tenha sido passado, será retornado um erro.

cProcessKey CharacterINPUTChave do processo vindo da queryParams. Caso não tenha sido passado, será retornado um erro.
RowErrorsTemp-tableOUTPUTInformações sobre os erros ocorridos durante o processo.

Retorno

Informações sobre os erros ocorridos durante o processo.



pi-valida-ordem

Requisito

Nenhum.

Descrição

Realiza a verificação das permissões do usuário logado em relação ao programa de ordens de compra.

Parâmetros

Tipo

Input/Output

Descrição

iProcessType

Integer

INPUTTipo do processo vindo da queryParams.
cProcessKey CharacterINPUTChave do processo vindo da queryParams.
RowErrorsTemp-tableOUTPUTInformações sobre os erros ocorridos durante o processo.

Retorno

Informações sobre os erros ocorridos durante o processo.


Definição de temp-tables:


RowErrors

Entrada/Saída

Temp-table com dados dos erros ocorridos durante o processo

Saída

Atributo

Tipo

Descrição

Obrigatório

Evolução

ErrorSequence

 INTEGER

Número da sequência do erro

Sim

Não se aplica

ErrorNumber

INTEGER Código do erro 

Sim

Não se aplica

ErrorDescriptionCHARACTER Descrição do erro SimNão se aplica
ErrorParametersCHARACTER Parâmetros da mensagem de erro SimNão se aplica
ErrorTypeCHARACTER Tipo do erro SimNão se aplica
ErrorHelpCHARACTER Texto de ajuda da mensagem de erro SimNão se aplica
ErrorSubTypeCHARACTERSubtipo do erroSimNão se aplica



ttDocumentFile

Entrada/Saída

Temp-table com os campos a serem retornados na busca dos documentos do processo.

Saída

Atributo

Nome no Objeto

Tipo

Descrição

Obrigatório

Evolução

num_id_docto

documentId

 INTEGER

Número do ID do documento

Sim

Não se aplica

cdn_tipo_processo

processTypeINTEGER Número do tipo do processo

Sim

Não se aplica

desc_tipo_procesprocessTypeDescriptionCHARACTER Descrição do tipo do processoSimNão se aplica
cod_chave_procesprocessKeyCHARACTER Código da chave do processoSimNão se aplica
cod_usuar_doctocreationUserCHARACTER Código do usuário criadorSimNão se aplica
nom_usuar_doctocreationUserNameCHARACTER Nome do usuário criadorSimNão se aplica
dtm_criac_doctocreationDatetimeDATETIMEData e hora da criação SimNão se aplica
nom_arq_docto documentNameCHARACTERNome do documentoSimNão se aplica
nom_dir_docto documentDirCHARACTERCaminho do diretório do documentoSimNão se aplica
ind_tam_doctodocumentSizeCHARACTERTamanho do documentoSimNão se aplica
des_doctodocumentDescriptionCHARACTERDescrição do documentoSimNão se aplica