Índice
Objetivo
Para os clientes que possuem algum aplicativo customizado, e que precisam realizar o cancelamento do documento de carga no produto Gestão de Frete Embarcador (SIGAGFE), foi disponibilizado o método Web Service REST.
A API disponibilizada foi criada de forma que ao informar a chave de acesso, os dados na Nota não sejam obrigatórios.
Para utilização, é necessário a atualização do produto e a configuração do Web Service REST, conforme descrito nos pré-requisitos.
Método Publicado
Fonte | GFEWSDOCUMENTBURDENCANCELATION |
---|---|
Nome do Serviço | DocumentBurdenCancelations |
Pré-requisitos para Utilização
- Atualização do Microsiga Protheus com versão igual ou superior a 12.1.17.
- Atualização da Build 131227a a partir da versão 13.2.3.6.
- Configuração do AppServer para disponibilizar as rotinas publicadas com o Web Service REST.
- No link http://tdn.totvs.com.br/pages/viewpage.action?pageId=185748193 é possível encontrar todas as configurações necessárias.
- Após a configuração do Web Service REST, ao executar o appserver via console, será apresentada uma mensagem, informando que o Web Service REST está habilitado, vide imagem abaixo.
- Pelo navegador de Internet, é possível visualizar todos os serviços disponíveis, inclusive a API DOCUMENTBURDENCANCELATIONS.
- API DOCUMENTBURDENCANCELATIONS.
Métodos disponíveis no API DOCUMENTBURDENCANCELATIONS.
Exemplo de Utilização
Para realizar testes, pode ser utilizado qualquer programa de sua preferência, que teste API Web Service REST.
Como exemplos de programas, podemos citar o SoapUI ou a extensão Postman do Navegador Chrome. Ambos são excelentes aplicativos.
Utilizando o Postman para Realizar o Cancelamento de Documento de Carga
A API DOCUMENTBURDENCANCELATIONS disponibiliza o método GET, onde é retornado o arquivo de exemplo no formato JSON, que poderá ser utilizado para executar o método POST.
Na ferramenta Postman, siga os procedimentos abaixo para executar a verificação da possibilidade de cancelamento do documento de carga:
- Copie o exemplo retornado do método GET.
- Altere para executar o POST e cole o exemplo no Body (corpo).
- Altere as informações dos campos para dados válidos da base de dados.
- Em Headers, informe a chave codtpoperacao" (¹) com valor 1 ou 2 para consultar a possibilidade de cancelamento ou executar o cancelamento, respectivamente.
- 1 - Para consultar a possibilidade de realizar o cancelamento - A API retornará indicando a possibilidade de realizar o cancelamento ou não do documento de carga.
- 2 - Para consultar a possibilidade e executar o cancelamento - A API retornará indicando se o documento foi ou não cancelado.
- Execute o processamento (mais abaixo tem a explicação de cada campo do arquivo JSON).
Valor Padrão da Chave
(¹) Caso não seja informada a chave "codtpoperacao", será considerado como valor 2, indicando que será executada a validação e o cancelamento em seguida, no caso de não existir impedimento.
Após executar a API passando a chave codtpoperacao igual a 1, o resultado da consulta será retornado no formato JSON.
Exemplo de arquivo JSON
Arquivo JSON de entrada para ser utilizado como base.
Arquivo JSON de entrada mínimo para consulta/cancelamento para ser utilizado como base.
Arquivo JSON exemplo da saída simplificada com consulta/cancelamento executado com sucesso e indicando que o documento já está cancelado.
Arquivo JSON exemplo de retorno de registro não encontrado.
Arquivo JSON exemplo de Build Desatualizada.
Detalhamento dos Agrupadores e Tags de Entrada
DocumentBurden - Documentos de Carga - Haverá uma ou mais ocorrências de DocumentBurden. | |||||
Field | Descrição | Chave | Tipo | Tamanho | Observação |
IssuerCode | Emitente do Documento de Carga/Nota Fiscal. | Alfanumérico | 14 | Quando não informado o código do Emitente, será realizada uma busca no cadastro de emitentes pelo CNPJ da filial logada. | |
InvoiceSerie | Série do Documento de Carga/Nota Fiscal. | Alfanumérico | 3 | ||
InvoiceNumber | Número do Documento de Carga/Nota Fiscal. | Alfanumérico | 16 | ||
TypeOfDocument | Tipo do Documento de Carga/Nota Fiscal. | Alfanumérico | 5 | Quando informado:
Quando não informado:
| |
ElectronicAccessKey | Chave de Acesso Eletrônica da Nota Fiscal | Alfanumérico | 44 | A Chave de Acesso deve ser informada sem formatação, somente os algarismos. Quando informada a Chave de Acesso, os demais campos de identificação da Nota Fiscal serão desconsiderados. |
Detalhamento dos Agrupadores e Tags de Saída
DocumentBurdenCancelation - Documentos de Carga - Haverá uma ou mais ocorrências de DocumentBurdenCancelation. | ||
Field | Descrição | Tipo |
IssuerCode | Emitente do Documento de Carga/Nota Fiscal. | Alfanumérico |
InvoiceSerie | Série do Documento de Carga/Nota Fiscal. | Alfanumérico |
InvoiceNumber | Número do Documento de Carga/Nota Fiscal. | Alfanumérico |
TypeOfDocument | Tipo do Documento de Carga/Nota Fiscal. | Alfanumérico |
ElectronicAccessKey | Chave de acesso da Nota Fiscal | Alfanumérico |
Status | ok- Indica que o registro pode ser cancelado ou foi cancelado | Alfanumérico |
Message | Quando o Status retornar "error", será apresentada a mensagem do motivo da inconsistência encontrada. | Alfanumérico |
Detalhamento técnico da estrutura do arquivo
Estrutura do arquivo de entrada.
TAGS | Descrição | ||||
contents | Agrupador. | ||||
Items | Agrupador. | ||||
DocumentBurden | Agrupador dos Documentos de Carga. | ||||
Items | Agrupador. | ||||
IssuerCode | Emitente do Documento de Carga/Nota Fiscal. | ||||
InvoiceSerie | Série do Documento de Carga/Nota Fiscal. | ||||
InvoiceNumber | Número do Documento de Carga/Nota Fiscal. | ||||
TypeOfDocument | Tipo do Documento de Carga/Nota Fiscal. | ||||
ElectronicAccessKey | Chave de Acesso da Nota Fiscal |
Estrutura do arquivo da solicitação/cancelamento do documento de carga.
TAGS | Descrição | ||||
content | Agrupador. | ||||
Items | Agrupador. | ||||
Status | Status - Indica se o processamento foi executado ou encontrou algum problema na estrutura do arquivo. | ||||
Message | Mensagem do Status. Mostra a mensagem com explicação do tipo do Status. | ||||
DocumentBurdenCancelation | Agrupador. | ||||
Status | "ok" - Indica que pode cancelar ou foi cancelado conforme tipo de solicitação. "error" - Indica que não pode ser cancelado. | ||||
Message | Mensagem explicativa do Status retornado. | ||||
Items | Agrupador. | ||||
IssuerCode | Emitente do Documento de Carga/Nota Fiscal. | ||||
InvoiceSerie | Série do Documento de Carga/Nota Fiscal. | ||||
InvoiceNumber | Número do Documento de Carga/Nota Fiscal. | ||||
TypeOfDocument | Tipo do Documento de Carga/Nota Fiscal. | ||||
ElectronicAccessKey | Chave de Acesso da Nota Fiscal |
Estrutura do arquivo do cancelamento não criado corretamente.
TAGS | Descrição | ||
content | Agrupador. | ||
Items | Agrupador. | ||
Status | Status. | ||
Message | Mensagem do Status. | ||
Error | Mensagem de erro. |