Índice

Objetivo

Para os usuários que possuem algum aplicativo customizado ou integração do romaneio e necessitam que seja realizada aprovação do romaneio no produto Gestão de Frete Embarcador (SIGAGFE), foi disponibilizado o método Web Service REST para realizar a Aprovação do Romaneio.

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	GFEWSFREIGHTRELEASE
Nome do Serviço	FREIGHTRELEASE

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, inclusive as orientações para definir, opcionalmente, a filial das requisições.
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 FREIGHTRELEASE.

Métodos disponíveis no API FREIGHTRELEASE.

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 a liberação de romaneio

A API FREIGHTRELEASE 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, copie o exemplo retornado, 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 e execute a liberação do romaneio (mais abaixo tem a explicação de cada campo do arquivo JSON).

Após executar a liberação do romaneio, o resultado será retornado no formato JSON.

Exemplo de arquivo JSON

Arquivo JSON de entrada para ser utilizado como base, informando três romaneios de forma mínima.

JSON Entrada

{
    "content": [
        {
            "Items": [
                {
                    "Manifest": [
                        {
                            "Items": [
                                {
                                    "id": "ManifestNumber",
                                    "Description": "Número do Romaneio para liberação",
                                    "value": "00000006",
                                    "length": 8,
                                    "type": "string"
                                }
                            ]
                        },
                         {
                            "Items": [
                                {
                                    "id": "ManifestNumber",
                                    "Description": "Número do Romaneio para liberação",
                                    "value": "00000008",
                                    "length": 8,
                                    "type": "string"
                                }
                            ]
                        },
                        {
                            "Items": [
                                {
                                    "id": "ManifestNumber",
                                    "Description": "Número do Romaneio para liberação",
                                    "value": "99999999999999999999999999",
                                    "length": 8,
                                    "type": "string"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Arquivo JSON de entrada mínimo, utilizado como base, informando apenas um romaneio.

JSON Entrada - Mínimo para liberação

{
    "content": [
        {
            "Items": [
                {
                    "Manifest": [
                        {
                            "Items": [
                                {
                                    "id": "ManifestNumber",
                                    "value": "00000006"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Arquivo JSON exemplo do retorno com liberação executada com sucesso.

JSON Saída - Liberação Executada com Sucesso

{
   "content":[
      {
         "Items":[
            {
               "FreightReleases":[
                  {
                     "Items":[
                        {
                           "id":"ManifestNumber",
                           "Description":"Número do Romaneio para liberação",
                           "value":"00000006",
                           "Status":"ok",
                           "Message":"Romaneio liberado com sucesso"
                        }
                     ]
                  }
               ],
               "Status":"ok",
               "Message":"freightrelease: Liberação(ões) de Frete realizada(s). Verifique o Status de cada Romaneio."
            }
         ]
      }
   ]
}

Arquivo JSON exemplo de liberação não realizada.

JSON Saída - Liberação não realizada

{
   "content":[
      {
         "Items":[
            {
               "FreightReleases":[
                  {
                     "Items":[
                        {
                           "id":"ManifestNumber",
                           "Description":"Número do Romaneio para liberação",
                           "value":"00000008",
                           "Status":"error",
                           "Message":"Romaneio não possui documento de carga relacionado"
                        }
                     ]
                  }
               ],
               "Status":"ok",
               "Message":"freightrelease: Liberação(ões) de Frete realizada(s). Verifique o Status de cada Romaneio."
            }
         ]
      }
   ]
}

Arquivo JSON exemplo de validação do número do romaneio (ManifestNumber).

JSON Saída - Validação Número Romaneio

{
   "content":[
      {
         "Items":[
            {
               "FreightReleases":[
                  {
                     "Items":[
                        {
                           "id":"ManifestNumber",
                           "Description":"Número do Romaneio para liberação",
                           "value":"99999999",
                           "Status":"error",
                           "Message":"Romaneio número 99999999 não encontrado"
                        }
                     ]
                  }
               ],
               "Status":"ok",
               "Message":"freightrelease: Liberação(ões) de Frete realizada(s). Verifique o Status de cada Romaneio."
            }
         ]
      }
   ]
}

Arquivo JSON exemplo com liberações executadas e outras não executadas.

JSON Saída - Liberações executadas e outras não executadas

{
    "content": [
        {
            "Items": [
                {
                    "FreightReleases": [
                        {
                            "Items": [
                                {
                                    "id": "ManifestNumber",
                                    "Description": "Número do Romaneio para liberação",
                                    "value": "00000006",
                                    "Status": "ok",
                                    "Message": "Romaneio liberado com sucesso"
                                }
                            ]
                        },
                        {
                            "Items": [
                                {
                                    "id": "ManifestNumber",
                                    "Description": "Número do Romaneio para liberação",
                                    "value": "00000008",
                                    "Status": "error",
                                    "Message": "Romaneio não possui documento de carga relacionado"
                                }
                            ]
                        },
                        {
                            "Items": [
                                {
                                    "id": "ManifestNumber",
                                    "Description": "Número do Romaneio para liberação",
                                    "value": "99999999",
                                    "Status": "error",
                                    "Message": "Romaneio número 99999999 não encontrado"
                                }
                            ]
                        }
                    ],
                    "Status": "ok",
                    "Message": "freightrelease: Liberação(ões) de Frete realizada(s). Verifique o Status de cada Romaneio."
                }
            ]
        }
    ]
}

Arquivo JSON exemplo de Build Desatualizada.

JSON Saída Build Desatualizada

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

Detalhamento das Tags de Entrada

Manifest - Informações do romaneio. Ocorrências 1 ou mais.
Field	Descrição	Chave	Tipo	Tamanho	Observação
ManifestNumber	Número do Romaneio para liberação	*	Alfanumérico	8	Obrigatório
DepartureDate	Data de saída		Data	8
DepartureTime	Hora de saída		Alfanumérico	5
DepartureOdometer	Hodômetro de saída		Numérico	6
TrackingCode	Código de Rastreamento		Alfanumérico	18

Detalhamento das Tags de Saída

FreightRelease - Informações do romaneio. Ocorrências 1 ou mais.
Field	Conteúdo / Descrição	Observação
id	Nome da TAG - ManifestNumber	Obrigatório.
description	Descrição do campo - Número do Romaneio
value	Número do romaneio a ser liberado	Obrigatório.
status	Indica se a liberação foi realizada: ok-liberação realizada; error - liberação não realizada.
message	Mensagem da situação da liberação. Quando não realizado com sucesso, indica o motivo.

Detalhamento técnico da estrutura do arquivo

Estrutura do arquivo de entrada.

TAGS					Descrição
contents					Agrupador.
	items				Agrupador.
		manifest			Agrupador dos romaneios.
			Items		Agrupador.
				id	Nome da Tag
				Description	Descrição detalhada da Tag
				value	Número do romaneio
				length	Tamanho do campo esperado
				type	Tipo do campo

Estrutura do arquivo da liberação de romaneio realizada.

TAGS					Descrição
content					Agrupador.
	Items				Agrupador.
		FreightRelease			Agrupador.
		Status			Status.
		Message			Mensagem do Status.
			Items		Agrupador.
				id	Nome da Tag
				Description	Descrição detalhada da Tag
				value	Número do romaneio que foi realizada liberação.
				Status	Indica se o romaneio foi ou não liberado. ok - indica que foi liberado com sucesso error - indica que houve problema na liberação do romaneio.
				Message	Mensagem da liberação. Em caso de não realizada a liberação, será detalhado o motivo.

Estrutura do arquivo da liberação de romaneio não realizado.

TAGS			Descrição
content			Agrupador.
	Items		Agrupador.
		Status	Status.
		Message	Mensagem do Status.

Árvore de páginas

Liberação de Romaneio - FreightRelease - API REST