Histórico da Página

...

um API etc. Ex.: concluida tranportadoras (verificar resultado do retorno 200 na aba acima)Tabela SA4Rotina : MATA050.PRX

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

Expandir

title	Carrier (Transportadora)

Cadastro: Transportadoras

Tabela no Protheus: SA4

Rotina no Protheus: MATA050.PRX

Deck of Cards

id	Métodos

Card

id	GETCARRIER
label	GET (Consulta/visualização)

Expandir

title	.../api/fat/v1/carrier

Objetivo: Retorna lista completa de Transportadoras

Deck of Cards

id	Status

Card

id	(1) Estruturação
label	(1) Estruturação

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.

Card

id	(2) Retornos e resultados
label	(2) Retornos e resultados

Expandir

title	200 (SUCESSO)

Dica

title	SUCESSO

Se a

API for concluída corretamente, será retornado:

Bloco de código

{
	"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"
		}
	]
}

Expandir

title	400 (ERRO NA REQUISIÇÃO)

Aviso
Se a API não for

concluída corretamente, voltará com esse erro:

Bloco de código

{
	"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

Card

id	(3) Conclusão
label	(3) Conclusão

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.

Expandir

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

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

Deck of Cards

id	Status

Card

id	(1) Estruturação
label	(1) Estruturaçã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.

Card

id	(2) Retornos e resultados
label	(2) Retornos e resultados

Expandir

title	200 (SUCESSO)

Dica

title	SUCESSO

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

Bloco de código

{
	"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"
}

Expandir

title	404 (TRANSPORTADORA NÃO LOCALIZADA!)

Aviso

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

Bloco de código

{
	"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

Card

id	(3) Conclusão
label	(3) Conclusão

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.

Card

id	POSTCARRIER
label	POST (Inclusão)

.../api/fat/v1/carrier

Card

id	PUTCARRIER
label	PUT (Alteração)

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

Card

id	DELETECARRIER
label	DELETE (Exclusão)

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

Expandir

title	customerVendor (Cliente)

Expandir

title	customerCreditLimit (Limite de crédito do cliente)

Expandir

title	paymentCondition (Condição de Pagamento)

Expandir

title	salesCharge (Comissão)

Expandir

title	PriceListHeaderItems (Tabela de Preços)

Expandir

title	seller (Vendedor)

Expandir

title	salesTaxes (Impostos no pedido de venda)

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?
Expandir
title Como buscar a URL da integração API e o método?
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:

Árvore de páginas

Versões comparadas

Versão antiga 14

Nova versão 15

Chave

1. Conceito

2. APIs

3. Arquivos a serem pegos para abertura do ticket