Histórico da Página

...

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

customerVendor (Cliente

Expandir

title	Carrier (Transportadora)

title

Cadastro: Transportadoras

Tabela no Protheus: SA4

Rotina no Protheus: MATA050.PRX

Rotina integradora no Protheus: MATS050.PRW

Deck of Cards

id	Métodos

Card

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

Expandir

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

Objetivo: Retornar lista completa de Transportadoras

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
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/fat/v1/carrier

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

Estruturação do corpo (Body) da requisição:

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: Retornar a transportadora específica passada na URL

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) da requisição:

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 transportadora 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)

Expandir

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

Objetivo: Incluir a transportadora de acordo com os dados passados 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
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/fat/v1/carrier

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

Estruturação do corpo (Body) da requisição:

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

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	400 (ERRO DURANTE INCLUSÃO DA TRANSPORTADORA)

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").

Exemplo de como ficará no Protheus:

Nova transportadora na tabela SA4.

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

)

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)

Expandir

title

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

Objetivo:

Retornar

Alterar a transportadora específica passada na URL

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) da requisição:

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

Bloco de código
{ "BranchId": "

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

Card

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

Expandir

title

404 (TRANSPORTADORA NÃO LOCALIZADA!)

200 (SUCESSO)

Dica

title	SUCESSO

warning

Se a API

não

for concluída corretamente,

voltará com esse erro

será retornado:

Bloco de código
{ "

code

BranchId": "

string

D MG 01 ",
	"

message

CompanyInternalId": "

string

T1D MG 01 000001",
	"

detailedMessage

InternalId": "

string

D MG 01 000001",
	"

helpUrl

Code": "

http://example.com

000001",
	"

details

Name":

[ { "code

 "Transportadora Ex CO",
	"ShortName": "

string

Transportadora Ex",

"message": "string", "detailedMessage

"RegisterSituation": "1",
	"governamentalInformation": [
		{}
	],
	"address": [
		{
			"items": [
				{
					"address": "Rua, Avenida, Rodovia, etc. Ex.: Avenida Braz Leme",
					"number": "string",
					"

helpUrl

complement": "

http://example.com" } ] }

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 DURANTE A ALTERAÇÃO DA TRANSPORTADORA)

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

Expandir

title	404 (TRANSPORTADORA NÃO LOCALIZADA!)

Aviso

Se a API não for concluída corretamente, pode 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 transportadora e seus detalhes.

Exemplo de como ficará no Protheus:

A transportadora (A4_COD) passada na URL (Exemplo: 000001) foi alterada no Protheus.

Card

id	DELETECARRIER
label	DELETE (Exclusão)

Expandir

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

Objetivo: Excluir a transportadora específica passada na URL

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) da requisição:

Não possui

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	400 (ERRO DURANTE A EXCLUSÃO DA TRANSPORTADORA)

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

Expandir

title	404 (TRANSPORTADORA NÃO LOCALIZADA!)

Aviso

Se a API não for concluída corretamente, pode 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 transportadora e seus detalhes.

Exemplo de como ficará no Protheus:

A transportadora (A4_COD) passada na URL (Exemplo: 000001) foi excluida no Protheus.

Expandir

title	customerVendor (Cliente)

Cadastro: Clientes

Tabela no Protheus: SA1

Rotina no Protheus: CRMA980.PRW

Rotina integradora no Protheus: MATS030.PRW

Deck of Cards

id	Métodos

Card

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

Expandir

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

Objetivo: Retornar lista completa de clientes (E fornecedores)

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/crm/v1/customerVendor
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/crm/v1/customerVendor

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
crm	Sinalização que é uma API do Protheus CRM (Faturamento)	crm	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)
customerVendor	Sinalização que é a api é para tratamento de clientes	customerVendor	Fixo, é definido pelo produto

Estruturação do corpo (Body) da requisição:

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": [
		{
			"customerVendorId": "string",
			"companyId": "string",
			"branchId": "D MG 01",
			"companyInternalId": "string",
			"code": "000001",
			"storeId": "01",
			"internalId": "string",
			"shortName": "JOHN M. CO",
			"name": "JOHN & MARY CO",
			"type": "1",
			"entityType": "1-Company",
			"marketsegment": {
				"marketSegmentCode": "string",
				"marketSegmentInternalId": "string",
				"marketSegmentDescription": "string"
			},
			"registerdate": "2018-06-29T09:34:30Z",
			"registerSituation": "1",
			"comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
			"governmentalInformation": [
				{
					"Id": [
						"string"
					],
					"scope": "Federal",
					"name": "string",
					"issueOn": "2024-12-05",
					"expiresOn": "2024-12-05"
				}
			],
			"address": {
				"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
			},
			"shippingAddress": {
				"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
			},
			"listOfCommunicationInformation": [
				{
					"Type": "1",
					"PhoneNumber": "string",
					"PhoneExtension": "string",
					"FaxNumber": "string",
					"FaxNumberExtension": "string",
					"HomePage": "string",
					"Email": "string",
					"DiallingCode": "string",
					"InternationalDiallingCode": "string"
				}
			],
			"listOfContacts": [
				{
					"ContactInformationCode": "string",
					"ContactInformationInternalId": "string",
					"ContactInformationTitle": "string",
					"ContactInformationName": "string",
					"ContactInformationDepartment": "string",
					"CommunicationInformation": {
						"PhoneNumber": "string",
						"PhoneExtension": "string",
						"FaxNumber": "string",
						"FaxNumberExtension": "string",
						"HomePage": "string",
						"Email": "string"
					},
					"ContactInformationAddress": {
						"Address": "string",
						"Number": "string",
						"Complement": "string",
						"City": {
							"cityCode": "string",
							"cityInternalId": "string",
							"cityDescription": "string"
						},
						"District": "string",
						"State": {
							"stateId": "string",
							"stateInternalId": "string",
							"stateDescription": "string"
						},
						"Country": {
							"countryCode": "string",
							"countryInternalId": "string",
							"countryDescription": "string"
						},
						"ZIPCode": "string",
						"Region": "string",
						"POBox": "string"
					}
				}
			],
			"listOfBankingInformation": [
				{
					"bankCode": 0,
					"bankInternalId": "string",
					"bankName": "Caixa Econômica Federal",
					"branchCode": "string",
					"branchKey": "string",
					"checkingAccountNumber": "string",
					"checkingAccountNumberKey": "st",
					"checkingAccountType": "1",
					"mainAccount": "1",
					"currencyAccount": "string"
				}
			],
			"billingInformation": {
				"billingCustomerCode": 0,
				"billingCustomerInternalId": "string",
				"address": {
					"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
				}
			},
			"vendorInformation": {
				"vendorClassification": "1",
				"vendorTypeCode": "string",
				"vendorTypeInternalId": "string",
				"vendorTypeDescription": "string"
			},
			"fiscalInformation": {
				"category": "str",
				"isRetentionAgent": true,
				"taxPayer": [
					{
						"taxName": "string",
						"isPayer": true,
						"mode": "string"
					}
				]
			},
			"creditInformation": {
				"creditIndicator": 0,
				"creditEvaluation": 0,
				"shipmentCreditEvaluation": 0,
				"creditLimit": 0,
				"creditLimitCurrency": 0,
				"creditLimitDate": "2018-06-29T09:34:30Z",
				"additionalCreditLimit": 0,
				"additionalCreditLimitCurrency": "string",
				"additionalCreditLimitDate": "2018-06-29T09:34:30Z",
				"latePeriods": 0,
				"balanceOfCredit": 0
			},
			"paymentConditionCode": "str",
			"paymentConditionInternalId": "string",
			"priceListHeaderItemCode": "str",
			"priceListHeaderItemInternalId": "string",
			"carrierCode": 0,
			"strategicCustomerType": "3=Revendedor",
			"rateDiscount": 0,
			"sellerCode": "string",
			"sellerInternalId": "string",
			"classification": "string",
			"recCreatedBy": "string",
			"recCreatedOn": "2018-06-29T09:34:30Z",
			"recModifiedBy": "string",
			"recModifiedOn": "2018-06-29T09:34:30Z",
			"creditLimit": 0,
			"lastChangeDate": "2018-06-29T09:34:30Z",
			"optionalValue1": 0,
			"optionalValue2": 0,
			"optionalValue3": 0,
			"patrimony": 0,
			"employeesNumber": 0,
			"classificationCompanyId": 0,
			"contributor": 0,
			"blocked": 0,
			"providerShippingPrice": 0,
			"takerType": 0,
			"issContributor": 0,
			"dependentsNumber": 0,
			"publicBody": 0,
			"selfEmployedCategory": 0,
			"customerVendorIdentityId": 0,
			"otherDeductionsIRRFCalculations": 0,
			"issRegime": "string",
			"issRetentionResponsible": "string",
			"fuelOperationType": 0,
			"size": 0,
			"activityBranch": 0,
			"typeContributorINSS": 0,
			"nationality": 0,
			"taxCodeColcfo": 0,
			"calculatesAVP": 0,
			"nif": "string",
			"nifSituation": 0,
			"incomeType": "string",
			"taxationForm": "string",
			"innovate_auto": 0,
			"formulaApplication": "string",
			"automaticDebitCheckerType": "string",
			"executingEntityPaa": "string",
			"ownWork": 0,
			"retiredPensioner": 0,
			"socialCategoryId": 0,
			"cooperativePartner": 0,
			"complementaryFields": {
				"codcoligada": 0,
				"codCfo": "string",
				"vendedor": "string",
				"comprador": "string",
				"diasAtraso": 0,
				"recCreatedBy": "string",
				"recCreatedOn": "2018-06-29T09:34:30Z",
				"recModifiedBy": "string",
				"recModifiedOn": "2018-06-29T09:34:30Z"
			}
		}
	]
}

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 todos os clientes e seus detalhes.

Exemplo de como ficará no Protheus:

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

Expandir

title	.../api/crm/v1/customerVendor/<Internal Id Cliente>

Objetivo: Retornar todos os clientes

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/crm/v1/customerVendor/<Cliente?>
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/crm/v1/customerVendor/1

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

crm

Sinalização que é uma API do Protheus Faturamento

crm

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)

customerVendor

Sinalização que é a api para tratamento de clientes

customerVendor

Fixo, é definido pelo produto

<Cliente?>

Sinalização se é cliente (1) ou fornecedor (2)

1

2

Alterável, depende da necessidade

Estruturação do corpo (Body) da requisição:

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": [
		{
			"customerVendorId": "string",
			"companyId": "string",
			"branchId": "D MG 01",
			"companyInternalId": "string",
			"code": "000001",
			"storeId": "01",
			"internalId": "string",
			"shortName": "JOHN M. CO",
			"name": "JOHN & MARY CO",
			"type": "1",
			"entityType": "1-Company",
			"marketsegment": {
				"marketSegmentCode": "string",
				"marketSegmentInternalId": "string",
				"marketSegmentDescription": "string"
			},
			"registerdate": "2018-06-29T09:34:30Z",
			"registerSituation": "1",
			"comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
			"governmentalInformation": [
				{
					"Id": [
						"string"
					],
					"scope": "Federal",
					"name": "string",
					"issueOn": "2024-12-05",
					"expiresOn": "2024-12-05"
				}
			],
			"address": {
				"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
			},
			"shippingAddress": {
				"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
			},
			"listOfCommunicationInformation": [
				{
					"Type": "1",
					"PhoneNumber": "string",
					"PhoneExtension": "string",
					"FaxNumber": "string",
					"FaxNumberExtension": "string",
					"HomePage": "string",
					"Email": "string",
					"DiallingCode": "string",
					"InternationalDiallingCode": "string"
				}
			],
			"listOfContacts": [
				{
					"ContactInformationCode": "string",
					"ContactInformationInternalId": "string",
					"ContactInformationTitle": "string",
					"ContactInformationName": "string",
					"ContactInformationDepartment": "string",
					"CommunicationInformation": {
						"PhoneNumber": "string",
						"PhoneExtension": "string",
						"FaxNumber": "string",
						"FaxNumberExtension": "string",
						"HomePage": "string",
						"Email": "string"
					},
					"ContactInformationAddress": {
						"Address": "string",
						"Number": "string",
						"Complement": "string",
						"City": {
							"cityCode": "string",
							"cityInternalId": "string",
							"cityDescription": "string"
						},
						"District": "string",
						"State": {
							"stateId": "string",
							"stateInternalId": "string",
							"stateDescription": "string"
						},
						"Country": {
							"countryCode": "string",
							"countryInternalId": "string",
							"countryDescription": "string"
						},
						"ZIPCode": "string",
						"Region": "string",
						"POBox": "string"
					}
				}
			],
			"listOfBankingInformation": [
				{
					"bankCode": 0,
					"bankInternalId": "string",
					"bankName": "Caixa Econômica Federal",
					"branchCode": "string",
					"branchKey": "string",
					"checkingAccountNumber": "string",
					"checkingAccountNumberKey": "st",
					"checkingAccountType": "1",
					"mainAccount": "1",
					"currencyAccount": "string"
				}
			],
			"billingInformation": {
				"billingCustomerCode": 0,
				"billingCustomerInternalId": "string",
				"address": {
					"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
				}
			},
			"vendorInformation": {
				"vendorClassification": "1",
				"vendorTypeCode": "string",
				"vendorTypeInternalId": "string",
				"vendorTypeDescription": "string"
			},
			"fiscalInformation": {
				"category": "str",
				"isRetentionAgent": true,
				"taxPayer": [
					{
						"taxName": "string",
						"isPayer": true,
						"mode": "string"
					}
				]
			},
			"creditInformation": {
				"creditIndicator": 0,
				"creditEvaluation": 0,
				"shipmentCreditEvaluation": 0,
				"creditLimit": 0,
				"creditLimitCurrency": 0,
				"creditLimitDate": "2018-06-29T09:34:30Z",
				"additionalCreditLimit": 0,
				"additionalCreditLimitCurrency": "string",
				"additionalCreditLimitDate": "2018-06-29T09:34:30Z",
				"latePeriods": 0,
				"balanceOfCredit": 0
			},
			"paymentConditionCode": "str",
			"paymentConditionInternalId": "string",
			"priceListHeaderItemCode": "str",
			"priceListHeaderItemInternalId": "string",
			"carrierCode": 0,
			"strategicCustomerType": "3=Revendedor",
			"rateDiscount": 0,
			"sellerCode": "string",
			"sellerInternalId": "string",
			"classification": "string",
			"recCreatedBy": "string",
			"recCreatedOn": "2018-06-29T09:34:30Z",
			"recModifiedBy": "string",
			"recModifiedOn": "2018-06-29T09:34:30Z",
			"creditLimit": 0,
			"lastChangeDate": "2018-06-29T09:34:30Z",
			"optionalValue1": 0,
			"optionalValue2": 0,
			"optionalValue3": 0,
			"patrimony": 0,
			"employeesNumber": 0,
			"classificationCompanyId": 0,
			"contributor": 0,
			"blocked": 0,
			"providerShippingPrice": 0,
			"takerType": 0,
			"issContributor": 0,
			"dependentsNumber": 0,
			"publicBody": 0,
			"selfEmployedCategory": 0,
			"customerVendorIdentityId": 0,
			"otherDeductionsIRRFCalculations": 0,
			"issRegime": "string",
			"issRetentionResponsible": "string",
			"fuelOperationType": 0,
			"size": 0,
			"activityBranch": 0,
			"typeContributorINSS": 0,
			"nationality": 0,
			"taxCodeColcfo": 0,
			"calculatesAVP": 0,
			"nif": "string",
			"nifSituation": 0,
			"incomeType": "string",
			"taxationForm": "string",
			"innovate_auto": 0,
			"formulaApplication": "string",
			"automaticDebitCheckerType": "string",
			"executingEntityPaa": "string",
			"ownWork": 0,
			"retiredPensioner": 0,
			"socialCategoryId": 0,
			"cooperativePartner": 0,
			"complementaryFields": {
				"codcoligada": 0,
				"codCfo": "string",
				"vendedor": "string",
				"comprador": "string",
				"diasAtraso": 0,
				"recCreatedBy": "string",
				"recCreatedOn": "2018-06-29T09:34:30Z",
				"recModifiedBy": "string",
				"recModifiedOn": "2018-06-29T09:34:30Z"
			}
		}
	]
}

Expandir

title	404 (ENTIDADE CLIENTES NÃO LOCALIZADA NA BASE!)

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 o cliente 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: Retorna o cliente específico

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/crm/v1/customerVendor/<Cliente?>/<Internal Id Cliente e Loja>
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/crm/v1/customerVendor/1/00000101

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

crm

Sinalização que é uma API do Protheus CRM (Faturamento)

crm

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)

customerVendor

Sinalização que é a api para alterações de transportadora

customerVendor

Fixo, é definido pelo produto

<Cliente?>

Sinalização se é para cliente (1) ou fornecedor (2)

1

2

Alterável, depende da necessidade do cliente

<Internal Id Cliente e Loja>

Código do cliente (A1_COD) + (A1_LOJA) no Protheus, no exemplo: 000001 (cliente) e 01 (loja)

00000101

Alterável, depende de cada cliente, do código do cliente no sistema dele

Estruturação do corpo (Body) da requisição:

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

{
	"customerVendorId": "string",
	"companyId": "string",
	"branchId": "D MG 01",
	"companyInternalId": "string",
	"code": "000001",
	"storeId": "01",
	"internalId": "string",
	"shortName": "JOHN M. CO",
	"name": "JOHN & MARY CO",
	"type": "1",
	"entityType": "1-Company",
	"marketsegment": {
		"marketSegmentCode": "string",
		"marketSegmentInternalId": "string",
		"marketSegmentDescription": "string"
	},
	"registerdate": "2018-06-29T09:34:30Z",
	"registerSituation": "1",
	"comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
	"governmentalInformation": [
		{
			"Id": [
				"string"
			],
			"scope": "Federal",
			"name": "string",
			"issueOn": "2024-12-05",
			"expiresOn": "2024-12-05"
		}
	],
	"address": {
		"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
	},
	"shippingAddress": {
		"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
	},
	"listOfCommunicationInformation": [
		{
			"Type": "1",
			"PhoneNumber": "string",
			"PhoneExtension": "string",
			"FaxNumber": "string",
			"FaxNumberExtension": "string",
			"HomePage": "string",
			"Email": "string",
			"DiallingCode": "string",
			"InternationalDiallingCode": "string"
		}
	],
	"listOfContacts": [
		{
			"ContactInformationCode": "string",
			"ContactInformationInternalId": "string",
			"ContactInformationTitle": "string",
			"ContactInformationName": "string",
			"ContactInformationDepartment": "string",
			"CommunicationInformation": {
				"PhoneNumber": "string",
				"PhoneExtension": "string",
				"FaxNumber": "string",
				"FaxNumberExtension": "string",
				"HomePage": "string",
				"Email": "string"
			},
			"ContactInformationAddress": {
				"Address": "string",
				"Number": "string",
				"Complement": "string",
				"City": {
					"cityCode": "string",
					"cityInternalId": "string",
					"cityDescription": "string"
				},
				"District": "string",
				"State": {
					"stateId": "string",
					"stateInternalId": "string",
					"stateDescription": "string"
				},
				"Country": {
					"countryCode": "string",
					"countryInternalId": "string",
					"countryDescription": "string"
				},
				"ZIPCode": "string",
				"Region": "string",
				"POBox": "string"
			}
		}
	],
	"listOfBankingInformation": [
		{
			"bankCode": 0,
			"bankInternalId": "string",
			"bankName": "Caixa Econômica Federal",
			"branchCode": "string",
			"branchKey": "string",
			"checkingAccountNumber": "string",
			"checkingAccountNumberKey": "st",
			"checkingAccountType": "1",
			"mainAccount": "1",
			"currencyAccount": "string"
		}
	],
	"billingInformation": {
		"billingCustomerCode": 0,
		"billingCustomerInternalId": "string",
		"address": {
			"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
		}
	},
	"vendorInformation": {
		"vendorClassification": "1",
		"vendorTypeCode": "string",
		"vendorTypeInternalId": "string",
		"vendorTypeDescription": "string"
	},
	"fiscalInformation": {
		"category": "str",
		"isRetentionAgent": true,
		"taxPayer": [
			{
				"taxName": "string",
				"isPayer": true,
				"mode": "string"
			}
		]
	},
	"creditInformation": {
		"creditIndicator": 0,
		"creditEvaluation": 0,
		"shipmentCreditEvaluation": 0,
		"creditLimit": 0,
		"creditLimitCurrency": 0,
		"creditLimitDate": "2018-06-29T09:34:30Z",
		"additionalCreditLimit": 0,
		"additionalCreditLimitCurrency": "string",
		"additionalCreditLimitDate": "2018-06-29T09:34:30Z",
		"latePeriods": 0,
		"balanceOfCredit": 0
	},
	"paymentConditionCode": "str",
	"paymentConditionInternalId": "string",
	"priceListHeaderItemCode": "str",
	"priceListHeaderItemInternalId": "string",
	"carrierCode": 0,
	"strategicCustomerType": "3=Revendedor",
	"rateDiscount": 0,
	"sellerCode": "string",
	"sellerInternalId": "string",
	"classification": "string",
	"recCreatedBy": "string",
	"recCreatedOn": "2018-06-29T09:34:30Z",
	"recModifiedBy": "string",
	"recModifiedOn": "2018-06-29T09:34:30Z",
	"creditLimit": 0,
	"lastChangeDate": "2018-06-29T09:34:30Z",
	"optionalValue1": 0,
	"optionalValue2": 0,
	"optionalValue3": 0,
	"patrimony": 0,
	"employeesNumber": 0,
	"classificationCompanyId": 0,
	"contributor": 0,
	"blocked": 0,
	"providerShippingPrice": 0,
	"takerType": 0,
	"issContributor": 0,
	"dependentsNumber": 0,
	"publicBody": 0,
	"selfEmployedCategory": 0,
	"customerVendorIdentityId": 0,
	"otherDeductionsIRRFCalculations": 0,
	"issRegime": "string",
	"issRetentionResponsible": "string",
	"fuelOperationType": 0,
	"size": 0,
	"activityBranch": 0,
	"typeContributorINSS": 0,
	"nationality": 0,
	"taxCodeColcfo": 0,
	"calculatesAVP": 0,
	"nif": "string",
	"nifSituation": 0,
	"incomeType": "string",
	"taxationForm": "string",
	"innovate_auto": 0,
	"formulaApplication": "string",
	"automaticDebitCheckerType": "string",
	"executingEntityPaa": "string",
	"ownWork": 0,
	"retiredPensioner": 0,
	"socialCategoryId": 0,
	"cooperativePartner": 0,
	"complementaryFields": {
		"codcoligada": 0,
		"codCfo": "string",
		"vendedor": "string",
		"comprador": "string",
		"diasAtraso": 0,
		"recCreatedBy": "string",
		"recCreatedOn": "2018-06-29T09:34:30Z",
		"recModifiedBy": "string",
		"recModifiedOn": "2018-06-29T09:34:30Z"
	}
}

Expandir

title	404 (CLIENTE NÃO LOCALIZADO NA BASE!)

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 o cliente 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)

Expandir

title	.../api/crm/v1/customerVendor

Objetivo: Incluir o cliente de acordo com os dados passados 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/crm/v1/customerVendor
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/crm/v1/customerVendor

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
crm	Sinalização que é uma API do Protheus CRM (Faturamento)	crm	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)
customerVendor	Sinalização que é a api para tratamento de clientes	customerVendor	Fixo, é definido pelo produto

Estruturação do corpo (Body) da requisição:

Bloco de código

{
	"customerVendorId": "string",
	"companyId": "string",
	"branchId": "D MG 01",
	"companyInternalId": "string",
	"code": "000001",
	"storeId": "01",
	"internalId": "string",
	"shortName": "JOHN M. CO",
	"name": "JOHN & MARY CO",
	"type": "1",
	"entityType": "1-Company",
	"marketsegment": {
		"marketSegmentCode": "string",
		"marketSegmentInternalId": "string",
		"marketSegmentDescription": "string"
	},
	"registerdate": "2018-06-29T09:34:30Z",
	"registerSituation": "1",
	"comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
	"governmentalInformation": [
		{
			"Id": [
				"string"
			],
			"scope": "Federal",
			"name": "string",
			"issueOn": "2024-12-05",
			"expiresOn": "2024-12-05"
		}
	],
	"address": {
		"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
	},
	"shippingAddress": {
		"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
	},
	"listOfCommunicationInformation": [
		{
			"Type": "1",
			"PhoneNumber": "string",
			"PhoneExtension": "string",
			"FaxNumber": "string",
			"FaxNumberExtension": "string",
			"HomePage": "string",
			"Email": "string",
			"DiallingCode": "string",
			"InternationalDiallingCode": "string"
		}
	],
	"listOfContacts": [
		{
			"ContactInformationCode": "string",
			"ContactInformationInternalId": "string",
			"ContactInformationTitle": "string",
			"ContactInformationName": "string",
			"ContactInformationDepartment": "string",
			"CommunicationInformation": {
				"PhoneNumber": "string",
				"PhoneExtension": "string",
				"FaxNumber": "string",
				"FaxNumberExtension": "string",
				"HomePage": "string",
				"Email": "string"
			},
			"ContactInformationAddress": {
				"Address": "string",
				"Number": "string",
				"Complement": "string",
				"City": {
					"cityCode": "string",
					"cityInternalId": "string",
					"cityDescription": "string"
				},
				"District": "string",
				"State": {
					"stateId": "string",
					"stateInternalId": "string",
					"stateDescription": "string"
				},
				"Country": {
					"countryCode": "string",
					"countryInternalId": "string",
					"countryDescription": "string"
				},
				"ZIPCode": "string",
				"Region": "string",
				"POBox": "string"
			}
		}
	],
	"listOfBankingInformation": [
		{
			"bankCode": 0,
			"bankInternalId": "string",
			"bankName": "Caixa Econômica Federal",
			"branchCode": "string",
			"branchKey": "string",
			"checkingAccountNumber": "string",
			"checkingAccountNumberKey": "st",
			"checkingAccountType": "1",
			"mainAccount": "1",
			"currencyAccount": "string"
		}
	],
	"billingInformation": {
		"billingCustomerCode": 0,
		"billingCustomerInternalId": "string",
		"address": {
			"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
		}
	},
	"vendorInformation": {
		"vendorClassification": "1",
		"vendorTypeCode": "string",
		"vendorTypeInternalId": "string",
		"vendorTypeDescription": "string"
	},
	"fiscalInformation": {
		"category": "str",
		"isRetentionAgent": true,
		"taxPayer": [
			{
				"taxName": "string",
				"isPayer": true,
				"mode": "string"
			}
		]
	},
	"creditInformation": {
		"creditIndicator": 0,
		"creditEvaluation": 0,
		"shipmentCreditEvaluation": 0,
		"creditLimit": 0,
		"creditLimitCurrency": 0,
		"creditLimitDate": "2018-06-29T09:34:30Z",
		"additionalCreditLimit": 0,
		"additionalCreditLimitCurrency": "string",
		"additionalCreditLimitDate": "2018-06-29T09:34:30Z",
		"latePeriods": 0,
		"balanceOfCredit": 0
	},
	"paymentConditionCode": "str",
	"paymentConditionInternalId": "string",
	"priceListHeaderItemCode": "str",
	"priceListHeaderItemInternalId": "string",
	"carrierCode": 0,
	"strategicCustomerType": "3=Revendedor",
	"rateDiscount": 0,
	"sellerCode": "string",
	"sellerInternalId": "string",
	"classification": "string",
	"recCreatedBy": "string",
	"recCreatedOn": "2018-06-29T09:34:30Z",
	"recModifiedBy": "string",
	"recModifiedOn": "2018-06-29T09:34:30Z",
	"creditLimit": 0,
	"lastChangeDate": "2018-06-29T09:34:30Z",
	"optionalValue1": 0,
	"optionalValue2": 0,
	"optionalValue3": 0,
	"patrimony": 0,
	"employeesNumber": 0,
	"classificationCompanyId": 0,
	"contributor": 0,
	"blocked": 0,
	"providerShippingPrice": 0,
	"takerType": 0,
	"issContributor": 0,
	"dependentsNumber": 0,
	"publicBody": 0,
	"selfEmployedCategory": 0,
	"customerVendorIdentityId": 0,
	"otherDeductionsIRRFCalculations": 0,
	"issRegime": "string",
	"issRetentionResponsible": "string",
	"fuelOperationType": 0,
	"size": 0,
	"activityBranch": 0,
	"typeContributorINSS": 0,
	"nationality": 0,
	"taxCodeColcfo": 0,
	"calculatesAVP": 0,
	"nif": "string",
	"nifSituation": 0,
	"incomeType": "string",
	"taxationForm": "string",
	"innovate_auto": 0,
	"formulaApplication": "string",
	"automaticDebitCheckerType": "string",
	"executingEntityPaa": "string",
	"ownWork": 0,
	"retiredPensioner": 0,
	"socialCategoryId": 0,
	"cooperativePartner": 0,
	"complementaryFields": {
		"codcoligada": 0,
		"codCfo": "string",
		"vendedor": "string",
		"comprador": "string",
		"diasAtraso": 0,
		"recCreatedBy": "string",
		"recCreatedOn": "2018-06-29T09:34:30Z",
		"recModifiedBy": "string",
		"recModifiedOn": "2018-06-29T09:34:30Z"
	}
}

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

{
	"customerVendorId": "string",
	"companyId": "string",
	"branchId": "D MG 01",
	"companyInternalId": "string",
	"code": "000001",
	"storeId": "01",
	"internalId": "string",
	"shortName": "JOHN M. CO",
	"name": "JOHN & MARY CO",
	"type": "1",
	"entityType": "1-Company",
	"marketsegment": {
		"marketSegmentCode": "string",
		"marketSegmentInternalId": "string",
		"marketSegmentDescription": "string"
	},
	"registerdate": "2018-06-29T09:34:30Z",
	"registerSituation": "1",
	"comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
	"governmentalInformation": [
		{
			"Id": [
				"string"
			],
			"scope": "Federal",
			"name": "string",
			"issueOn": "2024-12-05",
			"expiresOn": "2024-12-05"
		}
	],
	"address": {
		"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
	},
	"shippingAddress": {
		"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
	},
	"listOfCommunicationInformation": [
		{
			"Type": "1",
			"PhoneNumber": "string",
			"PhoneExtension": "string",
			"FaxNumber": "string",
			"FaxNumberExtension": "string",
			"HomePage": "string",
			"Email": "string",
			"DiallingCode": "string",
			"InternationalDiallingCode": "string"
		}
	],
	"listOfContacts": [
		{
			"ContactInformationCode": "string",
			"ContactInformationInternalId": "string",
			"ContactInformationTitle": "string",
			"ContactInformationName": "string",
			"ContactInformationDepartment": "string",
			"CommunicationInformation": {
				"PhoneNumber": "string",
				"PhoneExtension": "string",
				"FaxNumber": "string",
				"FaxNumberExtension": "string",
				"HomePage": "string",
				"Email": "string"
			},
			"ContactInformationAddress": {
				"Address": "string",
				"Number": "string",
				"Complement": "string",
				"City": {
					"cityCode": "string",
					"cityInternalId": "string",
					"cityDescription": "string"
				},
				"District": "string",
				"State": {
					"stateId": "string",
					"stateInternalId": "string",
					"stateDescription": "string"
				},
				"Country": {
					"countryCode": "string",
					"countryInternalId": "string",
					"countryDescription": "string"
				},
				"ZIPCode": "string",
				"Region": "string",
				"POBox": "string"
			}
		}
	],
	"listOfBankingInformation": [
		{
			"bankCode": 0,
			"bankInternalId": "string",
			"bankName": "Caixa Econômica Federal",
			"branchCode": "string",
			"branchKey": "string",
			"checkingAccountNumber": "string",
			"checkingAccountNumberKey": "st",
			"checkingAccountType": "1",
			"mainAccount": "1",
			"currencyAccount": "string"
		}
	],
	"billingInformation": {
		"billingCustomerCode": 0,
		"billingCustomerInternalId": "string",
		"address": {
			"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
		}
	},
	"vendorInformation": {
		"vendorClassification": "1",
		"vendorTypeCode": "string",
		"vendorTypeInternalId": "string",
		"vendorTypeDescription": "string"
	},
	"fiscalInformation": {
		"category": "str",
		"isRetentionAgent": true,
		"taxPayer": [
			{
				"taxName": "string",
				"isPayer": true,
				"mode": "string"
			}
		]
	},
	"creditInformation": {
		"creditIndicator": 0,
		"creditEvaluation": 0,
		"shipmentCreditEvaluation": 0,
		"creditLimit": 0,
		"creditLimitCurrency": 0,
		"creditLimitDate": "2018-06-29T09:34:30Z",
		"additionalCreditLimit": 0,
		"additionalCreditLimitCurrency": "string",
		"additionalCreditLimitDate": "2018-06-29T09:34:30Z",
		"latePeriods": 0,
		"balanceOfCredit": 0
	},
	"paymentConditionCode": "str",
	"paymentConditionInternalId": "string",
	"priceListHeaderItemCode": "str",
	"priceListHeaderItemInternalId": "string",
	"carrierCode": 0,
	"strategicCustomerType": "3=Revendedor",
	"rateDiscount": 0,
	"sellerCode": "string",
	"sellerInternalId": "string",
	"classification": "string",
	"recCreatedBy": "string",
	"recCreatedOn": "2018-06-29T09:34:30Z",
	"recModifiedBy": "string",
	"recModifiedOn": "2018-06-29T09:34:30Z",
	"creditLimit": 0,
	"lastChangeDate": "2018-06-29T09:34:30Z",
	"optionalValue1": 0,
	"optionalValue2": 0,
	"optionalValue3": 0,
	"patrimony": 0,
	"employeesNumber": 0,
	"classificationCompanyId": 0,
	"contributor": 0,
	"blocked": 0,
	"providerShippingPrice": 0,
	"takerType": 0,
	"issContributor": 0,
	"dependentsNumber": 0,
	"publicBody": 0,
	"selfEmployedCategory": 0,
	"customerVendorIdentityId": 0,
	"otherDeductionsIRRFCalculations": 0,
	"issRegime": "string",
	"issRetentionResponsible": "string",
	"fuelOperationType": 0,
	"size": 0,
	"activityBranch": 0,
	"typeContributorINSS": 0,
	"nationality": 0,
	"taxCodeColcfo": 0,
	"calculatesAVP": 0,
	"nif": "string",
	"nifSituation": 0,
	"incomeType": "string",
	"taxationForm": "string",
	"innovate_auto": 0,
	"formulaApplication": "string",
	"automaticDebitCheckerType": "string",
	"executingEntityPaa": "string",
	"ownWork": 0,
	"retiredPensioner": 0,
	"socialCategoryId": 0,
	"cooperativePartner": 0,
	"complementaryFields": {
		"codcoligada": 0,
		"codCfo": "string",
		"vendedor": "string",
		"comprador": "string",
		"diasAtraso": 0,
		"recCreatedBy": "string",
		"recCreatedOn": "2018-06-29T09:34:30Z",
		"recModifiedBy": "string",
		"recModifiedOn": "2018-06-29T09:34:30Z"
	}
}

Expandir

title	400 (ERRO NA INCLUSÃ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	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").

Exemplo de como ficará no Protheus:

Novo cliente na tabela SA1.

Card

id	PUTCARRIER
label	.../api/crm/v1/customerVendor/<Cliente?>/<Internal Id Cliente>

Expandir

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

Objetivo: Alterar o cliente específico passada na URL

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/crm/v1/customerVendor/<Cliente?>/<Internal Id Cliente e Loja>
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/crm/v1/customerVendor/1/00000101

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

crm

Sinalização que é uma API do Protheus CRM (Faturamento)

crm

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)

customerVendor

Sinalização que é a api para tratamento de clientes

customerVendor

Fixo, é definido pelo produto

<Cliente?>

Sinalização se é cliente (1) ou fornecedor (2)

1

2

Alterável, depende da necessidade

<Internal Id Cliente e Loja>

Código do cliente (A1_COD) + (A1_LOJA) no Protheus, no exemplo: 000001 (cliente) e 01 (loja)

00000101

Alterável, depende de cada cliente, do código do cliente e loja no sistema dele

Estruturação do corpo (Body) da requisição:

Bloco de código

{
	"hasNext": false,
	"items": [
		{
			"customerVendorId": "string",
			"companyId": "string",
			"branchId": "D MG 01",
			"companyInternalId": "string",
			"code": "000001",
			"storeId": "01",
			"internalId": "string",
			"shortName": "JOHN M. CO",
			"name": "JOHN & MARY CO",
			"type": "1",
			"entityType": "1-Company",
			"marketsegment": {
				"marketSegmentCode": "string",
				"marketSegmentInternalId": "string",
				"marketSegmentDescription": "string"
			},
			"registerdate": "2018-06-29T09:34:30Z",
			"registerSituation": "1",
			"comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
			"governmentalInformation": [
				{
					"Id": [
						"string"
					],
					"scope": "Federal",
					"name": "string",
					"issueOn": "2024-12-05",
					"expiresOn": "2024-12-05"
				}
			],
			"address": {
				"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
			},
			"shippingAddress": {
				"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
			},
			"listOfCommunicationInformation": [
				{
					"Type": "1",
					"PhoneNumber": "string",
					"PhoneExtension": "string",
					"FaxNumber": "string",
					"FaxNumberExtension": "string",
					"HomePage": "string",
					"Email": "string",
					"DiallingCode": "string",
					"InternationalDiallingCode": "string"
				}
			],
			"listOfContacts": [
				{
					"ContactInformationCode": "string",
					"ContactInformationInternalId": "string",
					"ContactInformationTitle": "string",
					"ContactInformationName": "string",
					"ContactInformationDepartment": "string",
					"CommunicationInformation": {
						"PhoneNumber": "string",
						"PhoneExtension": "string",
						"FaxNumber": "string",
						"FaxNumberExtension": "string",
						"HomePage": "string",
						"Email": "string"
					},
					"ContactInformationAddress": {
						"Address": "string",
						"Number": "string",
						"Complement": "string",
						"City": {
							"cityCode": "string",
							"cityInternalId": "string",
							"cityDescription": "string"
						},
						"District": "string",
						"State": {
							"stateId": "string",
							"stateInternalId": "string",
							"stateDescription": "string"
						},
						"Country": {
							"countryCode": "string",
							"countryInternalId": "string",
							"countryDescription": "string"
						},
						"ZIPCode": "string",
						"Region": "string",
						"POBox": "string"
					}
				}
			],
			"listOfBankingInformation": [
				{
					"bankCode": 0,
					"bankInternalId": "string",
					"bankName": "Caixa Econômica Federal",
					"branchCode": "string",
					"branchKey": "string",
					"checkingAccountNumber": "string",
					"checkingAccountNumberKey": "st",
					"checkingAccountType": "1",
					"mainAccount": "1",
					"currencyAccount": "string"
				}
			],
			"billingInformation": {
				"billingCustomerCode": 0,
				"billingCustomerInternalId": "string",
				"address": {
					"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
				}
			},
			"vendorInformation": {
				"vendorClassification": "1",
				"vendorTypeCode": "string",
				"vendorTypeInternalId": "string",
				"vendorTypeDescription": "string"
			},
			"fiscalInformation": {
				"category": "str",
				"isRetentionAgent": true,
				"taxPayer": [
					{
						"taxName": "string",
						"isPayer": true,
						"mode": "string"
					}
				]
			},
			"creditInformation": {
				"creditIndicator": 0,
				"creditEvaluation": 0,
				"shipmentCreditEvaluation": 0,
				"creditLimit": 0,
				"creditLimitCurrency": 0,
				"creditLimitDate": "2018-06-29T09:34:30Z",
				"additionalCreditLimit": 0,
				"additionalCreditLimitCurrency": "string",
				"additionalCreditLimitDate": "2018-06-29T09:34:30Z",
				"latePeriods": 0,
				"balanceOfCredit": 0
			},
			"paymentConditionCode": "str",
			"paymentConditionInternalId": "string",
			"priceListHeaderItemCode": "str",
			"priceListHeaderItemInternalId": "string",
			"carrierCode": 0,
			"strategicCustomerType": "3=Revendedor",
			"rateDiscount": 0,
			"sellerCode": "string",
			"sellerInternalId": "string",
			"classification": "string",
			"recCreatedBy": "string",
			"recCreatedOn": "2018-06-29T09:34:30Z",
			"recModifiedBy": "string",
			"recModifiedOn": "2018-06-29T09:34:30Z",
			"creditLimit": 0,
			"lastChangeDate": "2018-06-29T09:34:30Z",
			"optionalValue1": 0,
			"optionalValue2": 0,
			"optionalValue3": 0,
			"patrimony": 0,
			"employeesNumber": 0,
			"classificationCompanyId": 0,
			"contributor": 0,
			"blocked": 0,
			"providerShippingPrice": 0,
			"takerType": 0,
			"issContributor": 0,
			"dependentsNumber": 0,
			"publicBody": 0,
			"selfEmployedCategory": 0,
			"customerVendorIdentityId": 0,
			"otherDeductionsIRRFCalculations": 0,
			"issRegime": "string",
			"issRetentionResponsible": "string",
			"fuelOperationType": 0,
			"size": 0,
			"activityBranch": 0,
			"typeContributorINSS": 0,
			"nationality": 0,
			"taxCodeColcfo": 0,
			"calculatesAVP": 0,
			"nif": "string",
			"nifSituation": 0,
			"incomeType": "string",
			"taxationForm": "string",
			"innovate_auto": 0,
			"formulaApplication": "string",
			"automaticDebitCheckerType": "string",
			"executingEntityPaa": "string",
			"ownWork": 0,
			"retiredPensioner": 0,
			"socialCategoryId": 0,
			"cooperativePartner": 0,
			"complementaryFields": {
				"codcoligada": 0,
				"codCfo": "string",
				"vendedor": "string",
				"comprador": "string",
				"diasAtraso": 0,
				"recCreatedBy": "string",
				"recCreatedOn": "2018-06-29T09:34:30Z",
				"recModifiedBy": "string",
				"recModifiedOn": "2018-06-29T09:34:30Z"
			}
		}
	]
}

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": [
		{
			"customerVendorId": "string",
			"companyId": "string",
			"branchId": "D MG 01",
			"companyInternalId": "string",
			"code": "000001",
			"storeId": "01",
			"internalId": "string",
			"shortName": "JOHN M. CO",
			"name": "JOHN & MARY CO",
			"type": "1",
			"entityType": "1-Company",
			"marketsegment": {
				"marketSegmentCode": "string",
				"marketSegmentInternalId": "string",
				"marketSegmentDescription": "string"
			},
			"registerdate": "2018-06-29T09:34:30Z",
			"registerSituation": "1",
			"comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
			"governmentalInformation": [
				{
					"Id": [
						"string"
					],
					"scope": "Federal",
					"name": "string",
					"issueOn": "2024-12-05",
					"expiresOn": "2024-12-05"
				}
			],
			"address": {
				"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
			},
			"shippingAddress": {
				"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
			},
			"listOfCommunicationInformation": [
				{
					"Type": "1",
					"PhoneNumber": "string",
					"PhoneExtension": "string",
					"FaxNumber": "string",
					"FaxNumberExtension": "string",
					"HomePage": "string",
					"Email": "string",
					"DiallingCode": "string",
					"InternationalDiallingCode": "string"
				}
			],
			"listOfContacts": [
				{
					"ContactInformationCode": "string",
					"ContactInformationInternalId": "string",
					"ContactInformationTitle": "string",
					"ContactInformationName": "string",
					"ContactInformationDepartment": "string",
					"CommunicationInformation": {
						"PhoneNumber": "string",
						"PhoneExtension": "string",
						"FaxNumber": "string",
						"FaxNumberExtension": "string",
						"HomePage": "string",
						"Email": "string"
					},
					"ContactInformationAddress": {
						"Address": "string",
						"Number": "string",
						"Complement": "string",
						"City": {
							"cityCode": "string",
							"cityInternalId": "string",
							"cityDescription": "string"
						},
						"District": "string",
						"State": {
							"stateId": "string",
							"stateInternalId": "string",
							"stateDescription": "string"
						},
						"Country": {
							"countryCode": "string",
							"countryInternalId": "string",
							"countryDescription": "string"
						},
						"ZIPCode": "string",
						"Region": "string",
						"POBox": "string"
					}
				}
			],
			"listOfBankingInformation": [
				{
					"bankCode": 0,
					"bankInternalId": "string",
					"bankName": "Caixa Econômica Federal",
					"branchCode": "string",
					"branchKey": "string",
					"checkingAccountNumber": "string",
					"checkingAccountNumberKey": "st",
					"checkingAccountType": "1",
					"mainAccount": "1",
					"currencyAccount": "string"
				}
			],
			"billingInformation": {
				"billingCustomerCode": 0,
				"billingCustomerInternalId": "string",
				"address": {
					"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
				}
			},
			"vendorInformation": {
				"vendorClassification": "1",
				"vendorTypeCode": "string",
				"vendorTypeInternalId": "string",
				"vendorTypeDescription": "string"
			},
			"fiscalInformation": {
				"category": "str",
				"isRetentionAgent": true,
				"taxPayer": [
					{
						"taxName": "string",
						"isPayer": true,
						"mode": "string"
					}
				]
			},
			"creditInformation": {
				"creditIndicator": 0,
				"creditEvaluation": 0,
				"shipmentCreditEvaluation": 0,
				"creditLimit": 0,
				"creditLimitCurrency": 0,
				"creditLimitDate": "2018-06-29T09:34:30Z",
				"additionalCreditLimit": 0,
				"additionalCreditLimitCurrency": "string",
				"additionalCreditLimitDate": "2018-06-29T09:34:30Z",
				"latePeriods": 0,
				"balanceOfCredit": 0
			},
			"paymentConditionCode": "str",
			"paymentConditionInternalId": "string",
			"priceListHeaderItemCode": "str",
			"priceListHeaderItemInternalId": "string",
			"carrierCode": 0,
			"strategicCustomerType": "3=Revendedor",
			"rateDiscount": 0,
			"sellerCode": "string",
			"sellerInternalId": "string",
			"classification": "string",
			"recCreatedBy": "string",
			"recCreatedOn": "2018-06-29T09:34:30Z",
			"recModifiedBy": "string",
			"recModifiedOn": "2018-06-29T09:34:30Z",
			"creditLimit": 0,
			"lastChangeDate": "2018-06-29T09:34:30Z",
			"optionalValue1": 0,
			"optionalValue2": 0,
			"optionalValue3": 0,
			"patrimony": 0,
			"employeesNumber": 0,
			"classificationCompanyId": 0,
			"contributor": 0,
			"blocked": 0,
			"providerShippingPrice": 0,
			"takerType": 0,
			"issContributor": 0,
			"dependentsNumber": 0,
			"publicBody": 0,
			"selfEmployedCategory": 0,
			"customerVendorIdentityId": 0,
			"otherDeductionsIRRFCalculations": 0,
			"issRegime": "string",
			"issRetentionResponsible": "string",
			"fuelOperationType": 0,
			"size": 0,
			"activityBranch": 0,
			"typeContributorINSS": 0,
			"nationality": 0,
			"taxCodeColcfo": 0,
			"calculatesAVP": 0,
			"nif": "string",
			"nifSituation": 0,
			"incomeType": "string",
			"taxationForm": "string",
			"innovate_auto": 0,
			"formulaApplication": "string",
			"automaticDebitCheckerType": "string",
			"executingEntityPaa": "string",
			"ownWork": 0,
			"retiredPensioner": 0,
			"socialCategoryId": 0,
			"cooperativePartner": 0,
			"complementaryFields": {
				"codcoligada": 0,
				"codCfo": "string",
				"vendedor": "string",
				"comprador": "string",
				"diasAtraso": 0,
				"recCreatedBy": "string",
				"recCreatedOn": "2018-06-29T09:34:30Z",
				"recModifiedBy": "string",
				"recModifiedOn": "2018-06-29T09:34:30Z"
			}
		}
	]
}

Expandir

title	400 (ERRO NO MOMENTO DA ALTERAÇÃ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	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

Expandir

title	404 (CLIENTE NÃO LOCALIZADO NA BASE!)

Aviso

Se a API não for concluída corretamente, pode 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 o cliente e seus detalhes.

Exemplo de como ficará no Protheus:

O cliente (A1_COD + A1_LOJA) passada na URL (Exemplo: cliente 000001 e loja 01) foi alterado no Protheus.

Card

id	DELETECARRIER
label	DELETE (Exclusão)

Expandir

title	.../api/crm/v1/customerVendor/<cliente?>/<Internal Id Cliente e Loja>

Objetivo: Excluir o cliente específico passado na URL

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/crm/v1/customerVendor/<Cliente?>/<Internal Id Cliente e Loja>
Exemplo "real" de uma requisição da API com esse endpoint:	http://localhost:4321/rest/api/crm/v1/customerVendor/1/00000101

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

crm

Sinalização que é uma API do Protheus CRM (Faturamento)

crm

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)

customerVendor

Sinalização que é a api para tratamento de clientes

customerVendor

Fixo, é definido pelo produto

<Cliente?>

Sinalização se é cliente (1) ou fornecedor (2)

1

2

Alterável, depende da necessidade

<Internal Id Cliente e Loja>

Código do cliente (A1_COD) + (A1_LOJA) no Protheus, no exemplo: 000001 (cliente) e 01 (loja)

00000101

Alterável, depende de cada cliente, do código do cliente e loja no sistema dele

Estruturação do corpo (Body) da requisição:

Não possui

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": [
		{
			"customerVendorId": "string",
			"companyId": "string",
			"branchId": "D MG 01",
			"companyInternalId": "string",
			"code": "000001",
			"storeId": "01",
			"internalId": "string",
			"shortName": "JOHN M. CO",
			"name": "JOHN & MARY CO",
			"type": "1",
			"entityType": "1-Company",
			"marketsegment": {
				"marketSegmentCode": "string",
				"marketSegmentInternalId": "string",
				"marketSegmentDescription": "string"
			},
			"registerdate": "2018-06-29T09:34:30Z",
			"registerSituation": "1",
			"comments": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
			"governmentalInformation": [
				{
					"Id": [
						"string"
					],
					"scope": "Federal",
					"name": "string",
					"issueOn": "2024-12-05",
					"expiresOn": "2024-12-05"
				}
			],
			"address": {
				"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
			},
			"shippingAddress": {
				"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
			},
			"listOfCommunicationInformation": [
				{
					"Type": "1",
					"PhoneNumber": "string",
					"PhoneExtension": "string",
					"FaxNumber": "string",
					"FaxNumberExtension": "string",
					"HomePage": "string",
					"Email": "string",
					"DiallingCode": "string",
					"InternationalDiallingCode": "string"
				}
			],
			"listOfContacts": [
				{
					"ContactInformationCode": "string",
					"ContactInformationInternalId": "string",
					"ContactInformationTitle": "string",
					"ContactInformationName": "string",
					"ContactInformationDepartment": "string",
					"CommunicationInformation": {
						"PhoneNumber": "string",
						"PhoneExtension": "string",
						"FaxNumber": "string",
						"FaxNumberExtension": "string",
						"HomePage": "string",
						"Email": "string"
					},
					"ContactInformationAddress": {
						"Address": "string",
						"Number": "string",
						"Complement": "string",
						"City": {
							"cityCode": "string",
							"cityInternalId": "string",
							"cityDescription": "string"
						},
						"District": "string",
						"State": {
							"stateId": "string",
							"stateInternalId": "string",
							"stateDescription": "string"
						},
						"Country": {
							"countryCode": "string",
							"countryInternalId": "string",
							"countryDescription": "string"
						},
						"ZIPCode": "string",
						"Region": "string",
						"POBox": "string"
					}
				}
			],
			"listOfBankingInformation": [
				{
					"bankCode": 0,
					"bankInternalId": "string",
					"bankName": "Caixa Econômica Federal",
					"branchCode": "string",
					"branchKey": "string",
					"checkingAccountNumber": "string",
					"checkingAccountNumberKey": "st",
					"checkingAccountType": "1",
					"mainAccount": "1",
					"currencyAccount": "string"
				}
			],
			"billingInformation": {
				"billingCustomerCode": 0,
				"billingCustomerInternalId": "string",
				"address": {
					"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
				}
			},
			"vendorInformation": {
				"vendorClassification": "1",
				"vendorTypeCode": "string",
				"vendorTypeInternalId": "string",
				"vendorTypeDescription": "string"
			},
			"fiscalInformation": {
				"category": "str",
				"isRetentionAgent": true,
				"taxPayer": [
					{
						"taxName": "string",
						"isPayer": true,
						"mode": "string"
					}
				]
			},
			"creditInformation": {
				"creditIndicator": 0,
				"creditEvaluation": 0,
				"shipmentCreditEvaluation": 0,
				"creditLimit": 0,
				"creditLimitCurrency": 0,
				"creditLimitDate": "2018-06-29T09:34:30Z",
				"additionalCreditLimit": 0,
				"additionalCreditLimitCurrency": "string",
				"additionalCreditLimitDate": "2018-06-29T09:34:30Z",
				"latePeriods": 0,
				"balanceOfCredit": 0
			},
			"paymentConditionCode": "str",
			"paymentConditionInternalId": "string",
			"priceListHeaderItemCode": "str",
			"priceListHeaderItemInternalId": "string",
			"carrierCode": 0,
			"strategicCustomerType": "3=Revendedor",
			"rateDiscount": 0,
			"sellerCode": "string",
			"sellerInternalId": "string",
			"classification": "string",
			"recCreatedBy": "string",
			"recCreatedOn": "2018-06-29T09:34:30Z",
			"recModifiedBy": "string",
			"recModifiedOn": "2018-06-29T09:34:30Z",
			"creditLimit": 0,
			"lastChangeDate": "2018-06-29T09:34:30Z",
			"optionalValue1": 0,
			"optionalValue2": 0,
			"optionalValue3": 0,
			"patrimony": 0,
			"employeesNumber": 0,
			"classificationCompanyId": 0,
			"contributor": 0,
			"blocked": 0,
			"providerShippingPrice": 0,
			"takerType": 0,
			"issContributor": 0,
			"dependentsNumber": 0,
			"publicBody": 0,
			"selfEmployedCategory": 0,
			"customerVendorIdentityId": 0,
			"otherDeductionsIRRFCalculations": 0,
			"issRegime": "string",
			"issRetentionResponsible": "string",
			"fuelOperationType": 0,
			"size": 0,
			"activityBranch": 0,
			"typeContributorINSS": 0,
			"nationality": 0,
			"taxCodeColcfo": 0,
			"calculatesAVP": 0,
			"nif": "string",
			"nifSituation": 0,
			"incomeType": "string",
			"taxationForm": "string",
			"innovate_auto": 0,
			"formulaApplication": "string",
			"automaticDebitCheckerType": "string",
			"executingEntityPaa": "string",
			"ownWork": 0,
			"retiredPensioner": 0,
			"socialCategoryId": 0,
			"cooperativePartner": 0,
			"complementaryFields": {
				"codcoligada": 0,
				"codCfo": "string",
				"vendedor": "string",
				"comprador": "string",
				"diasAtraso": 0,
				"recCreatedBy": "string",
				"recCreatedOn": "2018-06-29T09:34:30Z",
				"recModifiedBy": "string",
				"recModifiedOn": "2018-06-29T09:34:30Z"
			}
		}
	]
}

Expandir

title	400 (ERRO NO MOMENTO DA EXCLUSÃ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	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

Expandir

title	404 (CLIENTE NÃO LOCALIZADO NA BASE!)

Aviso

Se a API não for concluída corretamente, pode 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 o cliente e quais eram seus detalhes.

Exemplo de como ficará no Protheus:

O cliente (A1_COD + A1_LOJA) passada na URL (Exemplo: cliente 000001 e loja 01) foi excluido no Protheus.

Expandir

title	customerCreditLimit (Limite de crédito do cliente)

Cross Segmentos - Backoffice Protheus - SIGAFAT - Lista de APIs de Faturamento

Expandir

title	paymentCondition (Condição de Pagamento)

Cross Segmentos - Backoffice Protheus - SIGAFAT - Lista de APIs de Faturamento

Expandir

title	salesCharge (Comissão)

Cross Segmentos - Backoffice Protheus - SIGAFAT - Lista de APIs de Faturamento

Expandir

title	PriceListHeaderItems (Tabela de Preços)

Cross Segmentos - Backoffice Protheus - SIGAFAT - Lista de APIs de Faturamento

Expandir

title	seller (Vendedor)

Cross Segmentos - Backoffice Protheus - SIGAFAT - Lista de APIs de Faturamento

Expandir

title	salesTaxes (Impostos no pedido de venda)

Cross Segmentos - Backoffice Protheus - SIGAFAT - Lista de APIs de Faturamento

Explicação das tags de retorno:

TagTipoExplicaçãoObrigatoriedadecodestringCódigo identificador do erroObrigatória, sempre estará presente no retornomessagestringDescrição do erro por idiomaObrigató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 siNã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.

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:Cross Segmentos - Backoffice Protheus - SIGAFAT - Lista de APIs de Faturamento

Árvore de páginas

Versões comparadas

Versão antiga 16

Nova versão Atual

Chave

1. Conceito

2. APIs

3. Arquivos a serem pegos para abertura do ticket