Í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. 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. 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.

JSON Entrada

{
    "content": [
        {
            "Items": [
                {
                    "DocumentBurden": [
                        {
                            "Items": [
                                {
                                    "id": "TypeOfDocument",
                                    "Description": "Tipo do Documento de Carga/Nota Fiscal",
                                    "value": "NFS  ",
                                    "length": 5,
                                    "type": "string"
                                },
                                {
                                    "id": "IssuerCode",
                                    "Description": "Emitente do Documento de Carga/Nota Fiscal",
                                    "value": "000000003     ",
                                    "length": 14,
                                    "type": "string"
                                },
                                {
                                    "id": "InvoiceSerie",
                                    "Description": "Série do Documento de Carga/Nota Fiscal",
                                    "value": "1  ",
                                    "length": 3,
                                    "type": "string"
                                },
                                {
                                    "id": "InvoiceNumber",
                                    "Description": "Número do Documento de Carga/Nota Fiscal",
                                    "value": "000026          ",
                                    "length": 16,
                                    "type": "string"
                                },
                                {
                                    "id": "ElectronicAccessKey",
                                    "Description": "Chave de Acesso Eletrônica",
                                    "value": "42170153485215000106570170000213011112155595",
                                    "length": 44,
                                    "type": "string"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Arquivo JSON de entrada mínimo para consulta/cancelamento para ser utilizado como base.

JSON Entrada - Mínimo para solicitação/cancelamento

{
    "content": [
        {
            "Items": [
                {
                    "DocumentBurden": [
                        {
                            "Items": [
                                {
                                    "id": "TypeOfDocument",
                                    "value": "NFS  "
                                },
                                {
                                    "id": "IssuerCode",
                                    "value": "000000003     "
                                },
                                {
                                    "id": "InvoiceSerie",
                                    "value": "1  "
                                },
                                {
                                    "id": "InvoiceNumber",
                                    "value": "000026          "
                                },
                                {
                                    "id": "ElectronicAccessKey",
                                    "value": "42170153485215000106570170000213011112155595"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}


// informando somente a chave eletronica


{
    "content": [
        {
            "Items": [
                {
                    "DocumentBurden": [
                        {
                            "Items": [
                                {
                                    "id": "ElectronicAccessKey",
                                    "value": "42170153485215000106570170000213011112155595"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Arquivo JSON exemplo da saída simplificada com consulta/cancelamento executado com sucesso e indicando que o documento já está cancelado.

JSON Saída Simplificada

{
    "content": [
        {
            "Items": [
                {
                    "Status": "ok",
                    "Message": "DocumentBurdenCancelations: Processamento de consulta da viabilidade do cancelamento executada com sucesso. Verifique o Status de cada documento solicitado.",
                    "DocumentBurdenCancelation": [
                        {
                            "Items": [
                                {
                                    "id": "TypeOfDocument",
                                    "Description": "Tipo do Documento de Carga/Nota Fiscal",
                                    "value": "NFS  "
                                },
                                {
                                    "id": "IssuerCode",
                                    "Description": "Emitente do Documento de Carga/Nota Fiscal",
                                    "value": "000000003     "
                                },
                                {
                                    "id": "InvoiceSerie",
                                    "Description": "Série do Documento de Carga/Nota Fiscal",
                                    "value": "1  "
                                },
                                {
                                    "id": "InvoiceNumber",
                                    "Description": "Número do Documento de Carga/Nota Fiscal",
                                    "value": "000026          "
                                },
                                {
                                    "id": "ElectronicAccessKey",
                                    "Description": "Chave de Acesso Eletrônica",
                                    "value": "42170153485215000106570170000213011112155595"
                                }
                            ],
                            "Status": "error",
                            "Message": "Documento de Carga (SIGAGFE) \r\nO Documento de Carga não pode ser cancelado pois já encontra-se nesta situação."
                        }
                    ]
                }
            ]
        }
    ]
}

Arquivo JSON exemplo de retorno de registro não encontrado.

JSON Saída Simulação não realizada

{
    "content": [
        {
            "Items": [
                {
                    "Status": "ok",
                    "Message": "DocumentBurdenCancelations: Processamento de consulta da viabilidade do cancelamento executada com sucesso. Verifique o Status de cada documento solicitado.",
                    "DocumentBurdenCancelation": [
                        {
                            "Items": [
                                {
                                    "id": "TypeOfDocument",
                                    "Description": "Tipo do Documento de Carga/Nota Fiscal",
                                    "value": "NFS  "
                                },
                                {
                                    "id": "IssuerCode",
                                    "Description": "Emitente do Documento de Carga/Nota Fiscal",
                                    "value": "000000003     "
                                },
                                {
                                    "id": "InvoiceSerie",
                                    "Description": "Série do Documento de Carga/Nota Fiscal",
                                    "value": "1  "
                                },
                                {
                                    "id": "InvoiceNumber",
                                    "Description": "Número do Documento de Carga/Nota Fiscal",
                                    "value": "000027          "
                                },
                                {
                                    "id": "ElectronicAccessKey",
                                    "Description": "Chave de Acesso Eletrônica",
                                    "value": "42170153485215000106570170000213011112155595"
                                }
                            ],
                            "Status": "error",
                            "Message": "Documento de Carga informado não é válido, Documento de Carga não encontrado na base de dados. (01NFS  000000003     1  000027          )"
                        }
                    ]
                }
            ]
        }
    ]
}

Arquivo JSON exemplo de Build Desatualizada.

JSON Saída Build Desatualizada

{
    "errorCode": 500,
    "errorMessage": "invalid class JSSONOBJECT"
}

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: Localiza um registro na tabela SX5 (Tabelas genéricas) com a tabela "MQ" e chave com o Tipo de Documento de Carga informado. Localiza um registro diretamente na tabela de Tipo de Documento de Carga (GV5) com o valor informado. Quando não informado: Procura um registro diretamente na tabela de Tipo de Documento de Carga (GV5) com o conteúdo "NFS", nota fiscal de saída. Procura um registro diretamente na tabela de Tipo de Documento de Carga (GV5) do tipo "Saída", o primeiro registro encontrado será utilizado.
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 error - Indica que o registro não pode ser 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.

Árvore de páginas

Cancelamento de Documento de Carga - DocumentBurdenCancelations - API REST