Configurações e demais informações a respeito da Integração via API ao Protheus Faturamento

Produto:

Protheus®

Ambiente:

SIGAFAT (Faturamento)

Ocorrência:

Integração ao Protheus Faturamento via requisições de API

Processo:

1. Conceito

Esse mecanismo de consulta via API é utilizado para consultar informações de um processo de um sistema ao outro. Ele ocorre por meio de uma URL com o serviço (Rest ou WS por exemplo), o método (GET por exemplo) e a API, para consultar/alterar as tabelas e dados do outro do sistema a partir de uma Query.

2. APIs

Cadastro: Transportadoras

Tabela no Protheus: SA4

Rotina no Protheus: MATA050.PRX

Objetivo: Retorna lista completa de Transportadoras

Estruturação do link:

/api/fat/v1/carrier (não há variáveis na URL)

Estruturação do corpo (Body):

Não há, pois é o método GET.

Se a API for concluída corretamente, será retornado:

{
	"hasNext": false,
	"items": [
		{
			"BranchId": "D MG 01 ",
			"CompanyInternalId": "T1D MG 01 000001",
			"InternalId": "D MG 01 000001",
			"Code": "000001",
			"Name": "Transportadora Ex CO",
			"ShortName": "Transportadora Ex",
			"RegisterSituation": "1",
			"governamentalInformation": [
				{}
			],
			"address": [
				{
					"items": [
						{
							"address": "Rua, Avenida, Rodovia, Avenida Braz Leme",
							"number": "string",
							"complement": "string",
							"city": {
								"cityCode": "string",
								"cityInternalId": "string",
								"cityDescription": "string"
							},
							"district": "Casa Verde",
							"state": {
								"stateId": "string",
								"stateInternalId": "string",
								"stateDescription": "string"
							},
							"country": {
								"countryCode": "string",
								"countryInternalId": "string",
								"countryDescription": "string"
							},
							"zipCode": "02022010",
							"region": "Zona Norte",
							"poBox": "string",
							"mainAddress": true,
							"shippingAddress": false,
							"billingAddress": true
						}
					]
				}
			],
			"listofComunicationInformation": [
				{
					"Type": "1",
					"PhoneNumber": "string",
					"PhoneExtension": "string",
					"FaxNumber": "string",
					"FaxNumberExtension": "string",
					"HomePage": "string",
					"Email": "string",
					"DiallingCode": "string",
					"InternationalDiallingCode": "string"
				}
			],
			"CarrierType": "1"
		}
	]
}

Se a API não for concluída corretamente, voltará com esse erro:

{
	"code": "string",
	"message": "string",
	"detailedMessage": "string",
	"helpUrl": "http://example.com",
	"details": [
		{
			"code": "string",
			"message": "string",
			"detailedMessage": "string",
			"helpUrl": "http://example.com"
		}
	]
}

Explicação das tags de retorno:

Tag	Tipo	Explicação	Obrigatoriedade
code	string	Código identificador do erro	Obrigatória, sempre estará presente no retorno
message	string	Descrição do erro por idioma	Obrigatória, sempre estará presente no retorno
detailedMessage	string	Mensagem técnica e mais detalhada do erro	Obrigatória, sempre estará presente no retorno
helpUrl	string	URL para documentação do erro	Não obrigatória, caso o erro não possuir documentação, não será retornado
details	object[]	Contém as tags code, message, detailedMessage e helpURL dentro de si	Não obrigatória

Se tiver sucesso, será pego o retorno 200 (dúvidas, verificar aba acima "Retornos e resultados"), onde nesse retorno, é exibido a lista de todas as transportadoras e seus detalhes.

Exemplo de como ficará no Protheus:

Não altera-se nada no Protheus, pois é o método GET.

Objetivo: Atualiza cadastro de Transportadoras conforme dados enviados na requisição

Exemplo do endpoint da API:

Exemplo estrutural de uma requisição da API com esse endpoint:	<servidor>/api/fat/v1/carrier/<Internal Id Transportadora>
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/fat/v1/carrier/000001

Estruturação:

Trecho da URL	Significado	Exemplo real de conteúdo	Observação
<servidor>	Caminho do servidor com a porta e tipo (WS ou REST)	http://localhost:4321/rest	Alterável, depende de cada cliente
api	Sinalização que é uma API	api	Fixo, é definido pelo produto
fat	Sinalização que é uma API do Protheus Faturamento	fat	Fixo, é definido pelo produto
v1	Versão da API do Protheus Faturamento	v1	Fixo, é definido pelo produto (geralmente é alterável, porém, atualmente só há essa versão)
carrier	Sinalização que é a api para alterações de transportadora	carrier	Fixo, é definido pelo produto
<Internal Id Transportadora>	Código da transportadora (A4_COD) no Protheus	000001	Alterável, depende de cada cliente, do código da transportadora no sistema dele

Estruturação do corpo (Body):

Não há, pois é o método GET.

Se a API for concluída corretamente, será retornado:

{
	"BranchId": "D MG 01 ",
	"CompanyInternalId": "T1D MG 01 000001",
	"InternalId": "D MG 01 000001",
	"Code": "000001",
	"Name": "Transportadora Ex CO",
	"ShortName": "Transportadora Ex",
	"RegisterSituation": "1",
	"governamentalInformation": [
		{}
	],
	"address": [
		{
			"items": [
				{
					"address": "Rua, Avenida, Rodovia, etc. Ex.: Avenida Braz Leme",
					"number": "string",
					"complement": "string",
					"city": {
						"cityCode": "string",
						"cityInternalId": "string",
						"cityDescription": "string"
					},
					"district": "Casa Verde",
					"state": {
						"stateId": "string",
						"stateInternalId": "string",
						"stateDescription": "string"
					},
					"country": {
						"countryCode": "string",
						"countryInternalId": "string",
						"countryDescription": "string"
					},
					"zipCode": "02022010",
					"region": "Zona Norte",
					"poBox": "string",
					"mainAddress": true,
					"shippingAddress": false,
					"billingAddress": true
				}
			]
		}
	],
	"listofComunicationInformation": [
		{
			"Type": "1",
			"PhoneNumber": "string",
			"PhoneExtension": "string",
			"FaxNumber": "string",
			"FaxNumberExtension": "string",
			"HomePage": "string",
			"Email": "string",
			"DiallingCode": "string",
			"InternationalDiallingCode": "string"
		}
	],
	"CarrierType": "1"
}

Se a API não for concluída corretamente, voltará com esse erro:

{
	"code": "string",
	"message": "string",
	"detailedMessage": "string",
	"helpUrl": "http://example.com",
	"details": [
		{
			"code": "string",
			"message": "string",
			"detailedMessage": "string",
			"helpUrl": "http://example.com"
		}
	]
}

Explicação das tags de retorno:

Tag	Tipo	Explicação	Obrigatoriedade
code	string	Código identificador do erro	Obrigatória, sempre estará presente no retorno
message	string	Descrição do erro por idioma	Obrigatória, sempre estará presente no retorno
detailedMessage	string	Mensagem técnica e mais detalhada do erro	Obrigatória, sempre estará presente no retorno
helpUrl	string	URI para documentação do erro	Não obrigatória, caso o erro não possuir documentação, não será retornado
details	object[]	Contém as tags code, message, detailedMessage e helpURL dentro de si	Não obrigatória

Se tiver sucesso, será pego o retorno 200 (dúvidas, verificar aba acima "Retornos e resultados"), onde nesse retorno, é exibido a lista de todas as transportadoras e seus detalhes.

Exemplo de como ficará no Protheus:

Não altera-se nada no Protheus, pois é o método GET.

.../api/fat/v1/carrier

.../api/fat/v1/carrier/<Internal Id Transportadora>

3. Arquivos a serem pegos para abertura do ticket

(A) Qual o processo que está sendo realizado? (Exemplo: Consulta de impostos no pedido de venda)

(B) Qual a URL completa e Método do envio via servidor Rest ou WS?
Contate por favor o sistema origem para tirar essa dúvida, se preciso.
(C) Qual o erro apresentado?

(D) Manualmente o erro ocorre?

Pode lhe Interessar: