Integração para inclusão de notas fiscais via API

A API createAuthorizedInvoice permite que o integrador envie, na mesma requisição da nota fiscal autorizada, os dados cadastrais de cliente, transportadora e endereço de entrega. Com isso, o sistema realiza automaticamente a validação e o cadastro dessas informações quando necessário, eliminando a necessidade de chamadas adicionais para criação prévia de pessoas e endereços.

Durante o processamento, o sistema verifica automaticamente se os cadastros já existem na base de dados. Caso não existam, eles são criados antes da geração da nota fiscal.

O processo de integração para inclusão de notas fiscais pode ser resumido em quatro etapas principais: envio da requisição, processamento dos cadastros, validações internas e geração da nota fiscal autorizada.

Fluxo do processo

Ordem de processamento

Os cadastros são processados de forma sequencial, seguindo a ordem abaixo:

1. Cliente (pessoa do campo customer);
2. Transportadora (pessoa do campo transportInformation.shippingCompany);
3. Endereço de entrega (vinculado à pessoa do cliente).

O endereço de entrega depende do cliente já existir ou ser criado durante o processamento, pois o vínculo é realizado diretamente com a pessoa do cliente.

Interrupção do processamento em caso de erro

O processamento dos cadastros ocorre de forma sequencial. Caso seja identificado algum erro durante qualquer etapa da integração, o processo é interrompido imediatamente.

Quando isso acontece, as próximas etapas não são executadas e a nota fiscal não é gerada até que o problema seja corrigido.

Cadastro de cliente

O cadastro automático de cliente é realizado quando o campo customer.personInformation é informado na chamada da API.

Durante o processamento, o sistema tenta localizar um cliente existente utilizando a seguinte ordem de prioridade:

• customer.id: identificador interno da pessoa;
• customer.taxNumber: CPF ou CNPJ;
• customer.code: código da pessoa.

Se o cliente for localizado, os dados são atualizados. Caso contrário, um novo cadastro é criado automaticamente.

Campos disponíveis em personInformation

Campo	Tipo	Tamanho máximo	Descrição
name	string	100	Nome ou razão social
tradeName	string	100	Nome fantasia
personType	enum	-	Tipo de pessoa: VF (física) ou VJ (jurídica)
marketType	enum	-	Tipo de mercado: INTERNO ou EXTERNO
stateRegistration	string	20	Inscrição estadual
email	string	500	E-mail principal
emailForElectronicDocuments	string	100	E-mail para recebimento de NF-e
phone	string	20	Telefone
address	string	100	Logradouro
addressNumber	string	60	Número do endereço
addressComplement	string	200	Complemento
neighborhood	string	75	Bairro
postalCode	string	10	CEP
country	record	-	País
state	record	-	Estado/UF
city	record	-	Cidade
customer	record	-	Especialização de cliente
shippingCompany	record	-	Especialização de transportadora
favored	record	-	Especialização de favorecido
representative	record	-	Especialização de representante
provider	record	-	Especialização de fornecedor
taxPerson	record	-	Informações fiscais

Todos os campos são opcionais. Informe apenas os dados que deseja cadastrar ou atualizar.

Criação de novo cliente

{
 	"authorizedInvoice": {
		"externalInvoiceId": "NF-2026-001",
		"customer": {
			"taxNumber": "12345678000199",
			"personInformation": {
				"name": "Empresa Exemplo Ltda",
				"tradeName": "Exemplo",
				"personType": "VJ",
				"marketType": "INTERNO",
				"stateRegistration": "123456789",
				"email": "contato@exemplo.com.br",
				"emailForElectronicDocuments": "nfe@exemplo.com.br",
				"phone": "(47) 3333-4444",
				"address": "Rua das Flores",
				"addressNumber": "100",
				"addressComplement": "Sala 201",
				"neighborhood": "Centro",
				"postalCode": "89010-001",
				"country": {"code": 1058},
				"state": {"abbreviation": "SC"},
				"city": {"name": "Blumenau"},
				"customer": {"status": "VA"},
				"taxPerson": {
					"taxRegimeCode": "1",
					"taxPayer": true,
					"isIndustry": false
				}
			}
		},
		"branch": {"code": "1"},
		"serie": {"code": "1"},
		"issueDate": "2026-04-28T10:00:00",
		"accessKey": "35260412345678000199550010000000011000000019",
		"protocolNumber": "135260400000001",
		"authorizationDate": "2026-04-28T10:05:00",
		"items": []
	}
}

Atualização de cliente existente

{
	"authorizedInvoice": {
		"externalInvoiceId": "NF-2026-002",
		"customer": {
			"taxNumber": "12345678000199",
			"personInformation": {
				"email": "novo-email@exemplo.com.br",
				"phone": "(47) 9999-8888"
			}
		}
	}
}

Cadastro de transportadora

O cadastro automático da transportadora é realizado quando o campo transportInformation.shippingCompany.personInformation é informado na requisição.

A localização da transportadora utiliza os mesmos critérios aplicados ao cliente:

• shippingCompany.id: identificador interno da pessoa;
• shippingCompany.taxNumber: CPF ou CNPJ;
• shippingCompany.code: código da pessoa.

Quando localizada, a transportadora é atualizada. Caso contrário, um novo cadastro é criado automaticamente.

Os campos de personInformation da transportadora são os mesmos campos personInformation do cliente.

Criação de nova transportadora

{
	"authorizedInvoice": {
		"externalInvoiceId": "NF-2026-003",
		"customer": {
			"id": "uuid-do-cliente-existente"
		},
		"transportInformation": {
			"freightType": "CIF",
			"shippingCompany": {
				"taxNumber": "98765432000188",
				"personInformation": {
					"name": "Transportes Rápido Ltda",
					"tradeName": "Rápido Transportes",
					"personType": "VJ",
					"marketType": "INTERNO",
					"phone": "(11) 2222-3333",
					"shippingCompany": { "status": "VA" }
				}
			}
		},
		"branch": { "code": "1" },
		"serie": { "code": "1" },
		"issueDate": "2026-04-28T10:00:00",
		"accessKey": "35260498765432000188550010000000031000000037",
		"protocolNumber": "135260400000003",
		"authorizationDate": "2026-04-28T10:05:00",
		"items": []
	}
}

Cadastro de endereço de entrega

O cadastro automático de endereço de entrega é realizado quando o campo transportInformation.deliveryAddress é informado.

O endereço é sempre vinculado à pessoa do cliente e nunca à transportadora. Portanto, é necessário que o cliente já exista no sistema ou que seus dados cadastrais sejamsejam enviadas no momento da inclusão do registro.

Durante o processamento, o sistema verifica se já existe um endereço equivalente para o cliente utilizando os seguintes critérios:

• address: logradouro;
• addressNumber: número;
• addressComplement: complemento;
• neighborhood: bairro;
• postalCode: CEP;
• Tipo entrega: apenas endereços marcados como entrega.

Se o endereço já existir, ele é mantido sem alterações. Caso contrário, um novo endereço é criado e vinculado ao cliente.

Campos disponíveis em deliveryAddress

Campo	Tipo	Tamanho máximo	Descrição
document	string	20	CPF/CNPJ do recebedor.
address	string	100	Logradouro.
addressNumber	string	60	Número.
addressComplement	string	200	Complemento.
neighborhood	string	75	Bairro.
postalCode	string	10	CEP.
phone	string	20	Telefone.
celphone	string	20	Celular.
isDelivery	boolean	-	Indica endereço de entrega.
isBilling	boolean	-	Indica endereço de cobrança.
isCollection	boolean	-	Indica endereço de coleta.
isFiscal	boolean	-	Indica endereço fiscal.
country	record	-	País.
state	record	-	Estado/UF.
city	record	-	Cidade.
addressType	enum	-	Tipo do endereço: V3 (comercial) ou V4 (residencial).
documentType	enum	-	Tipo de pessoa: VF ou VJ.
responsibleName	string	50	Responsável pelo recebimento.

Criação de endereço de entrega

{
	"authorizedInvoice": {
		"externalInvoiceId": "NF-2026-004",
		"customer": {
			"id": "uuid-do-cliente-existente"
		},
		"transportInformation": {
			"freightType": "CIF",
			"deliveryAddress": {
				"address": "Av. Brasil",
				"addressNumber": "500",
				"addressComplement": "Galpão 3",
				"neighborhood": "Distrito Industrial",
				"postalCode": "89030-100",
				"phone": "(47) 3333-5555",
				"celphone": "(47) 99999-5555",
				"isDelivery": true,
				"country": { "code": 1058 },
				"state": { "abbreviation": "SC" },
				"city": { "name": "Blumenau" }
			}
		},
		"branch": { "code": "1" },
		"serie": { "code": "1" },
		"issueDate": "2026-04-28T10:00:00",
		"accessKey": "35260412345678000199550010000000041000000045",
		"protocolNumber": "135260400000004",
		"authorizationDate": "2026-04-28T10:05:00",
		"items": []
	}
}

Cadastro automático de CEP

Sempre que um CEP (postalCode) for informado nos dados cadastrais de pessoa ou endereço de entrega, o sistema verifica automaticamente se ele já existe na base de localização da plataforma.

Caso o CEP não exista, ele é criado automaticamente antes do processamento do cadastro da pessoa ou endereço.

1. O CEP é informado;
2. O sistema consulta a existência;
3. Se o CEP existir, o processamento continua normalmente;
4. Se não existir, o CEP é criado automaticamente;
5. CEPs já consultados na mesma requisição não são processados novamente.

Informações de localização

Os campos de localização (country, state, city) podem ser informados tanto nos dados cadastrais da pessoa quanto no endereço de entrega.

O sistema resolve automaticamente os identificadores de país, estado e cidade quando eles não forem enviados.

Informar localização

País (country)

• id: identificador interno;
• code: código do país;
• name: nome do país.

Estado (state)

• id: identificador interno;
• abbreviation: sigla da UF;
• name: nome do estado.

Cidade (city)

• id: identificador interno;
• code: código IBGE;
• name: nome da cidade.

A resolução ocorre na sequência: país → estado → cidade, pois cada nível depende do anterior.

Localização

### Exemplo: Localização por código

{
	"country": { "code": 1058 },
	"state": { "abbreviation": "SC" },
	"city": { "code": 4202404 }
}

### Exemplo: Localização por nome

						
{
	"country": { "name": "Brasil" },
	"state": { "name": "Santa Catarina" },
	"city": { "name": "Blumenau" }
}

Especializações de pessoa

As especializações definem os papéis que uma pessoa pode assumir no sistema.

Uma mesma pessoa pode possuir múltiplas especializações simultaneamente.

Especialização de pessoa

{
	"personInformation": {
		"name": "Empresa Multifuncional Ltda",
		"personType": "VJ",
		"customer": { "status": "VA" },
		"provider": { "status": "VA" }
	}
}

Dados fiscais

As informações fiscais podem ser enviadas por meio do objeto taxPerson.

Envio de dados fiscais

{
	"taxPerson": {
		"taxRegimeCode": "1",
		"taxPayer": true,
		"isIndustry": false
	}
}

Preenchimento completo: cliente, transportadora e endereço de entrega

O exemplo abaixo demonstra uma requisição completa para inclusão de nota fiscal autorizada com envio simultâneo dos dados cadastrais do cliente, da transportadora e do endereço de entrega.

Nesse cenário, caso os registros informados ainda não existam na base de dados, o sistema realiza automaticamente os cadastros necessários antes de gerar a nota fiscal.

Também são enviados os dados dos itens da nota fiscal e as informações fiscais necessárias para o processamento da integração.

Exemplo completo: cliente + transportadora + endereço

{
	"authorizedInvoice": {
		"externalInvoiceId": "NF-2026-100",
		"branch": { "code": "1" },
		"serie": { "code": "1" },
		"issueDate": "2026-04-28T14:30:00",
		"accessKey": "35260412345678000199550010000001001000001005",
		"protocolNumber": "135260400000100",
		"authorizationDate": "2026-04-28T14:35:00",

		"customer": {
			"taxNumber": "12345678000199",
			"personInformation": {
				"name": "Comércio ABC Ltda",
				"tradeName": "ABC Comércio",
				"personType": "VJ",
				"marketType": "INTERNO",
				"stateRegistration": "253667899",
				"email": "contato@abc.com.br",
				"emailForElectronicDocuments": "nfe@abc.com.br",
				"phone": "(47) 3333-4444",
				"address": "Rua XV de Novembro",
				"addressNumber": "1500",
				"neighborhood": "Centro",
				"postalCode": "89010-001",
				"country": { "code": 1058 },
				"state": { "abbreviation": "SC" },
				"city": { "name": "Blumenau" },
				"customer": { "status": "VA" },
				"taxPerson": {
					"taxRegimeCode": "1",
					"taxPayer": true,
					"isIndustry": false
				}
			}
		},

		"transportInformation": {
			"freightType": "CIF",
			"shippingCompany": {
				"taxNumber": "98765432000188",
				"personInformation": {
					"name": "Transportes Veloz Ltda",
					"tradeName": "Veloz",
					"personType": "VJ",
					"marketType": "INTERNO",
					"phone": "(11) 2222-3333",
					"shippingCompany": { "status": "VA" }
				}
			},
			"deliveryAddress": {
				"address": "Av. Industrial",
				"addressNumber": "2000",
				"addressComplement": "Galpão 5",
				"neighborhood": "Distrito Industrial",
				"postalCode": "89030-200",
				"phone": "(47) 3333-5555",
				"celphone": "(47) 99999-5555",
				"isDelivery": true,
				"country": { "code": 1058 },
				"state": { "abbreviation": "SC" },
				"city": { "name": "Blumenau" }
			}
		},

		"items": [
			{
				"productId": "uuid-do-produto",
				"saleMeasureUnit": { "code": "UN" },
				"saleQuantity": 10,
				"salePrice": 50.00,
				"grossValue": 500.00,
				"netValue": 500.00,
				"financialValue": 500.00
			}
		]
	}
}

Tratamento de erros

Quando ocorre falha durante o cadastro das entidades, o sistema registra a integração com status ERROR na tabela externalInvoiceIntegration.

As mensagens seguem o padrão abaixo:

• Cliente → Falha ao cadastrar cliente: [detalhe do erro];
• Transportadora→ Falha ao cadastrar transportadora: [detalhe do erro];
• Endereço de entrega → Falha ao cadastrar endereço de entrega: [detalhe do erro].

Quando ocorre erro, o evento authorizedInvoiceRegistrationError é publicado contendo:

• externalInvoiceId: ID externo da nota fiscal;
• serie: série da nota;
• branch: filial;
• number: número da nota (quando disponível);
• errorMessage: mensagem descritiva do erro.

Perguntas frequentes

Preciso enviar os dados cadastrais em toda chamada?

Não. Os dados cadastrais são opcionais. Se não forem informados, a API funciona normalmente sem alterações no comportamento atual.

Posso enviar apenas o endereço de entrega sem os dados do cliente?

Sim. Nesse caso, o cliente já deve existir no sistema e o identificador deve ser informado no campo customer.id. O endereço será vinculado à pessoa do cliente localizado.

O que acontece se eu enviar dados de um cliente já cadastrado?

O sistema localiza o cliente utilizando o ID, CPF/CNPJ ou código da pessoa e atualiza os dados com as informações enviadas na integração.

O que acontece se eu enviar um endereço de entrega já existente?

O sistema compara os dados do endereço informado com os endereços já cadastrados para o cliente. Se encontrar um endereço equivalente, o cadastro existente é mantido e nenhuma duplicidade é criada.

Posso enviar cliente, transportadora e endereço na mesma chamada?

Sim. Os três cadastros podem ser enviados na mesma requisição. O processamento ocorre na sequência: cliente → transportadora → endereço de entrega.

O que acontece se ocorrer erro no cadastro da transportadora?

O processamento da integração é interrompido imediatamente. Nesse cenário, o sistema não realiza o cadastro do endereço de entrega e a nota fiscal não é gerada. O erro fica registrado na tabela de integração.

A resposta da API demora mais quando envio dados cadastrais?

Não. A API responde imediatamente à requisição. O processamento dos cadastros ocorre de forma assíncrona em segundo plano e a nota fiscal é gerada após a conclusão das etapas necessárias.

Como saber se os cadastros foram processados com sucesso?

Se a nota fiscal for gerada normalmente, significa que todos os cadastros foram processados com sucesso. Em caso de erro, a integração será registrada com status ERROR e o evento authorizedInvoiceRegistrationError será publicado.

O CEP precisa estar cadastrado previamente?

Não. Caso o CEP informado não exista na base de localização, o sistema realiza automaticamente o cadastro antes de prosseguir com o processamento da pessoa ou do endereço.