Histórico da Página
Manipulação
...
das informações dos
...
anexos
Linha de Produto: | Datasul |
Ocorrência: | BackOffice |
Módulo: | HUB |
Versão Expedida: | 12.1.34 |
Considerações Gerais
Documentação de API | |
Nome físico: | hubapi/apiDocuments.p |
Objetivo
Manipular e retornar informações sobre os documentos anexados nos processos tais como: chave do documento, tipo do processo, nome, extensão, diretório onde está gravado o arquivo físico, entre outros. Os processos neste caso, podem ser configurados conforme necessidade da área, para compras, por exemplo: ordens de compra, pedidos, cotações, solicitações de compra, etcentre outros.
A api de documentos permite a inclusão de anexo, consulta, download, upload e exclusão individual e em lote.
Funcionamento
Na forma padrão, realiza-se a chamada por intermédio de um comando RUN normal, passando-se as temp-tables carregadas com as informações necessárias.
A execução na forma persistente é realizada através da chamada de um comando RUN conforme exemplo a seguir.
A sintaxe para executar a API em modo persistente é:
A API fornece uma série de métodos que podem ser executados individualmente para apresentação dos anexos na tela do documento.
Segue a sintaxe para a chamada da API, que deve ser de forma persistente:
RUN hubapi/apiDocumentsRUN ccp/ccapi352.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 for executada em modo persistente, os seguintes métodos estarão disponíveis para execução:
pi-metada-v1 | ||||||
Requisito | Nenhum. | |||||
Descrição | Retorna o metadados com os campos e ações ativos referentes a tela de Listagem (list), Consulta (view) ou Edição (edit), dependendo de qual tipo foi enviado pela requisição, para a montagem dinâmica da tela 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:
Exemplo
| |||
cEvent | Character | INPUT | Identifica qual o tipo de evento vindo do queryParams para a busca do metadado correto. | |||
cVersion | Character | INPUT | Identifica a versão da API. | |||
oOutput | JsonObject | OUTPUT | Retorno contendo o metadados com os campos e ações conforme parâmetros recebidos:
Descrição dos campos:
View
Possui os mesmos campos de retorno do metadados "List", sendo que a diferença é que se trata de uma tela de Consulta apenas, então, neste caso, não estão disponíveis as ações ("actions" no json), ou seja, os botões "Novo" e "Excluir" não são carregados na tela. A requisição é igual ao do metadados List (passando no queryparams o type = list) da api supplyDocuments, apenas alterando a api de origem que é a supplyDocumentsView. No método pi-metadata da supplyDocumentsView é feito o tratamento onde, ao receber o tipo "list" ele envia o tipo "view" para a apiDocuments fazer o tratamento e omitir os campos referente as ações da tela. No caso da apiDocuments, recebe o evento = "view" da apiSupplyDocuments. Os eventos "list" e "view" também direcionam para qual título será apresentado na página. Se for "view", na página de consulta será mostrado o título "Consulta de Anexo de Documentos" e se for "list", na página de manutenção da ordem de compra será mostrado "Anexo de Documentos". | |||
RowErrors | Temp-table | OUTPUT | Informações sobre os erros ocorridos durante o processo de busca do metadados. | |||
Retorno | Retorna informações do metadados ou erros ocorridos durante a busca. |
pi-query-v1 | |||||
Requisito | Nenhum. | ||||
Descrição | Executa a consulta dos anexos no banco de dados conforme o tipo de processo e a chave do documento enviada, e 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:
Exemplo
Outros parâmetros que podem ser usados em conjunto com os queryParams de consulta dos anexos:
| ||
aResult | JsonArray | OUTPUT | Retorno do processo, contendo os itens da listagem de anexos conforme parâmetros enviados.
Para verificar o que significa cada campo, conferir no final desta documentação a descrição dos campos da temp-table: ttDocumentFile. | ||
lHasNext | Logical | OUTPUT | Indica que existem mais registros a serem mostrados. | ||
iTotalHits | Integer | OUTPUT | Contagem do total de registros encontrados. | ||
RowErrors | Temp-table | OUTPUT | Informaçõ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 | Faz o upload do arquivo na criação de um novo anexo, retornando as informações do arquivo que está sendo feito o upload. | |||
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:
| |
oOutput | JsonObject | OUTPUT | Informações do arquivo: Exemplo
Descrição dos campos:
| |
RowErrors | Temp-table | OUTPUT | Informaçõ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 | Faz o download do arquivo, retornando as informações do nome e conteúdo do anexo. | |||
Parâmetros | Tipo | Input/Output | Descrição | |
oInput | JsonObject | INPUT | Parâmetros para download do anexo: pathParams: Informar: download e o documentId do documento.
| |
oOutput | JsonObject | OUTPUT | Retorno das informações do arquivo que está sendo realizado o download:
Descrição dos campos:
| |
RowErrors | Temp-table | OUTPUT | Informações sobre os erros ocorridos durante o processo de download. | |
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 | Efetua a exclusão de um único anexo ou de vários anexos dependendo do tipo de requisição recebida. Neste método os arquivos de anexos são excluídos do banco de dados e também da pasta física no servidor de arquivos onde estão gravados. | ||||
Parâmetros | Tipo | Input/Output | Descrição | ||
oInput | JsonObject | INPUT | Parâmetros para eliminação de anexo individual: pathParams: Informar: o documentId do anexo. Exemplo
Parâmetros para eliminação de anexo em lote: Payload: Informar a relação dos documentId's a serem eliminados:
| ||
oOutput | JsonObject | OUTPUT | 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. | ||
RowErrors | Temp-table | OUTPUT | Relação dos erros ocorridos durante o processo de exclusão individual ou em lote. | ||
ListaIdsExcluidos | Character | OUTPUT | Relação dos documentIds que foram eliminados com sucesso. | ||
Retorno | Erros ocorridos durante a exclusão individual ou em lote e relação dos documentIds que foram excluídos com sucesso. |
pi-create-v1 | ||||
Requisito | Nenhum. | |||
Descrição | Efetua a inclusão de um registro com as informações de anexo no banco de dados e também grava no servidor o arquivo físico enviado. Retorna informações sobre o anexo criado. | |||
Parâmetros | Tipo | Input/Output | Descrição | |
oInput | JsonObject | INPUT | Parâmetros para criação: Payload:
Descrição dos campos do payload:
| |
oOutput | JsonObject | OUTPUT | Informações do anexo criado:
Para verificar o que significa cada campo conferir no final desta documentação o detalhamento dos campos da temp-table : ttDocumentFile . | |
RowErrors | Temp-table | OUTPUT | Informações sobre os erros ocorridos durante a criação de arquivo. | |
Retorno | Informações do anexo criado ou erros ocorridos durante o processo. |
pi-busca-lista-tipos-processos | ||||
Requisito | Nenhum. | |||
Descrição | Busca os tipos de processos cadastrados na include uninc/i01un403.i. | |||
Parâmetros | Tipo | Input/Output | Descrição | |
pListaProcessos | Character | INPUT | Lista dos processos existentes na include. | |
Retorno | Listagem dos tipos de processos existentes. |
Tabelas
Arquivo_docto | ||||
Informações dos Arquivos | ||||
Atributo | Tipo | Formato | Descrição | Obrigatório |
num_id_docto | INTEGER | 999999999 | Número sequencial de identificação do documento | Sim |
cdn_tipo_proces | INTEGER | >>9 | Tipo do processo ao qual o documento está vinculado | Sim |
cod_chave_proces | CHARACTER | X(40) | Código da chave do processo | Sim |
cod_usuar_docto | CHARACTER | X(12) | Código do usuário do documento | Sim |
dtm_criac_docto | DATETIME | 99/99/9999 HH:MM:SS.SSS | Data e hora da criação do documento | Sim |
nom_arq_docto | CHARACTER | X(100) | Nome do arquivo | Sim |
nom_dir_docto | CHARACTER | X(250) | Diretório onde está armazenado o documento | Sim |
ind_tam_docto | CHARACTER | X(10) | Tamanho do arquivo | Não |
des_docto | CHARACTER | X(200) | Descrição do Documento | Não |
...
seq_arq_docto | Incrementa o ID do campo num_id_docto |
Tabelas Temporárias
tt-anexo-ids-exclusao | |||||
ID dos anexos a serem excluídos | |||||
Atributo | Tipo | Formato | Descrição | Obrigatório | |
num_id_docto | INTEGER | 999999999 | Número sequencial de identificação do documento | Sim | |
RowErrors | Entrada/Saída | ||||
Erros ocorridos durante a execução do programa. | Saída | ||||
Atributo | Tipo | Formato | Descrição | Obrigatório | Evolução |
ErrorSequence | INTEGER | Sequência | Sim | ||
ErrorNumber | INTEGER | Número | Sim | ||
ErrorDescription | CHARACTER | Descrição | Não | ||
ErrorParameters | CHARACTER | Parãmetros | Não | ||
ErrorType | CHARACTER | Tipo de erro | Não | ||
ErrorHelp | CHARACTER | Texto de ajuda | Não | ||
ErrorSubType | CHARACTER | Sub-tipo do erro | Não |
RowErrorsAux | Entrada/Saída | ||||
Erros ocorridos durante a execução da exclusão em lote, filtra os erros ocorridos na execução da BO , retirando os do tipo INTERNAL que não devem ser passados à RowErrors. | |||||
Atributo | Tipo | Formato | Descrição | Obrigatório | Evolução |
ErrorSequence | INTEGER | Sequência | Sim | ||
ErrorNumber | INTEGER | Número | Sim | ||
ErrorDescription | CHARACTER | Descrição | Não | ||
ErrorParameters | CHARACTER | Parãmetros | Não | ||
ErrorType | CHARACTER | Tipo de erro | Não | ||
ErrorHelp | CHARACTER | Texto de ajuda | Não | ||
ErrorSubType | CHARACTER | Sub-tipo do erro | Não |
Quando a API for executada em modo persistente, os seguintes métodos estarão disponíveis para execução:
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 | |
cdn_tipo_processo | processType | INTEGER | Número do tipo do processo | Sim | |
desc_tipo_proces | processTypeDescription | CHARACTER | Descrição do tipo do processo | Sim | |
cod_chave_proces | processKey | CHARACTER | Código da chave do processo | Sim | |
cod_usuar_docto | creationUser | CHARACTER | Código do usuário criador | Sim | |
nom_usuar_docto | creationUserName | CHARACTER | Nome do usuário criador | Sim | |
dtm_criac_docto | creationDatetime | DATETIME | Data e hora da criação | Sim | |
nom_arq_docto | documentName | CHARACTER | Nome do documento | Sim | |
nom_dir_docto | documentDir | CHARACTER | Caminho do diretório do documento | Sim | |
ind_tam_docto | documentSize | CHARACTER | Tamanho do documento | Não | |
des_docto | documentDescription | CHARACTER | Descrição do documento | Não |
ttArquivoDocto | ||||
Informações dos Arquivos | ||||
Atributo | Tipo | Formato | Descrição | Obrigatório |
num_id_docto | INTEGER | 999999999 | Número sequencial de identificação do documento | Sim |
cdn_tipo_proces | INTEGER | >>9 | Tipo do processo ao qual o documento está vinculado | Sim |
cod_chave_proces | CHARACTER | X(40) | Código da chave do processo | Sim |
cod_usuar_docto | CHARACTER | X(12) | Código do usuário do documento | Sim |
dtm_criac_docto | DATETIME | 99/99/9999 HH:MM:SS.SSS | Data e hora da criação do documento | Sim |
nom_arq_docto | CHARACTER | X(100) | Nome do arquivo | Sim |
nom_dir_docto | CHARACTER | X(250) | Diretório onde está armazenado o documento | Sim |
ind_tam_docto | CHARACTER | X(10) | Tamanho do arquivo | Não |
des_docto | CHARACTER | X(200) | Descrição do Documento | Não |
r-rowid | ROWID | Rowid do registro | Não |
pi-metadata-v1
Requisito
Nenhum
Sintaxe
RUN pi-metadata-v1 in handle (INPUT <JsonObject>,
INPUT <CHARACTER>,
INPUT <CHARACTER>,
OUTPUT DATASET <JsonObject>,
OUTPUT TABLE <temp-table>).
Descrição
Retorna o json com os campos e ações que irão compor a tela dinâmica dos anexos conforme o evento:
→ list: tela de listagem dos anexos com as ações de Incluir, Excluir e Exluir todos.
→ edit: tela de inclusão de anexo.
Parâmetros
Descrição
oInput
cEvent
cVersion
oOutput
RowErrors
Número da ordem de compra
Data da cotação para conversão
Código da moeda para conversão
Informações da ordem de compra
Erros ocorridos no processo
Retorno
Retorna um dataset contendos informações da ordem de compra, parcelas, cotações, requisições, recebimentos, alterações, eventos e unidades de negócio e uma temp-table com os erros ocorridos durante o processo.