// guias
Migrar do NFe.io
Guia de migração do NFe.io para engineAPI: mapeamento de endpoints, campos e diferenças de comportamento.
Migrar do NFe.io
Tempo estimado de migração: 1–3 horas de desenvolvimento
Diferenças Principais
| Aspecto | NFe.io | engineAPI |
|---|---|---|
| Autenticação | API Key no header Authorization | x-api-key (integração) ou Bearer JWT (dashboard) |
| Estrutura de URL | /v1/companies/{companyId}/productinvoices/{id} | /v1/nfe/{id} (sem empresa na URL) |
| Empresa no pedido | companyId na URL | issuerId no body |
| Tipo de nota | Separado por endpoint (productinvoices, serviceinvoices) | Separado por módulo (/nfe, /nfse) |
| Webhooks | Configurados por empresa | Uma configuração por partner (PATCH /v1/webhooks/config) |
Mapeamento de Endpoints
| NFe.io | engineAPI | Notas |
|---|---|---|
POST /v1/companies/{id}/productinvoices | POST /v1/nfe | issuerId no body é opcional com um único emissor cadastrado; com 2+, é obrigatório (ver aviso em Autenticação) |
GET /v1/companies/{id}/productinvoices/{inv} | GET /v1/nfe/{id} | N/A |
GET /v1/companies/{id}/productinvoices | GET /v1/nfe | N/A |
DELETE /v1/companies/{id}/productinvoices/{inv} | POST /v1/nfe/{idOuChave}/cancelar | Método diferente |
POST /v1/companies/{id}/serviceinvoices | POST /v1/nfse | issuerId obrigatório no body (única exceção) |
GET /v1/companies/{id}/serviceinvoices/{inv} | GET /v1/nfse/{id} | N/A |
DELETE /v1/companies/{id}/serviceinvoices/{inv} | POST /v1/nfse/{id}/cancelar | N/A |
POST /v1/companies | POST /v1/companies | N/A |
GET /v1/companies/{id} | GET /v1/companies/{id} | N/A |
PUT /v1/companies/{id}/certificate | POST /v1/companies/{id}/certificate | Multipart/form-data, campo file |
Mapeamento de Campos
NFe (productinvoices → nfe)
| Campo NFe.io | Campo engineAPI | Notas |
|---|---|---|
cityServiceCode | N/A | Não aplicável para NFe |
description | naturezaOperacao | N/A |
borrower.federalTaxNumber | destinatario.cnpjCpf | Campo único (11 a 14 dígitos), não há cnpj/cpf separados |
borrower.name | destinatario.nome | N/A |
borrower.address.street | destinatario.endereco.logradouro | N/A |
borrower.address.number | destinatario.endereco.numero | N/A |
borrower.address.district | destinatario.endereco.bairro | N/A |
borrower.address.city.code | destinatario.endereco.codigoMunicipio | Código IBGE |
borrower.address.city.name | destinatario.endereco.municipio | N/A |
borrower.address.state | destinatario.endereco.uf | N/A |
borrower.address.postalCode | destinatario.endereco.cep | N/A |
Diferenças importantes
Checklist de Migração
·
Criar conta na engineAPI
Registre-se em app.engineapi.com.br.
·
Cadastrar empresas emissoras
POST /v1/companies para cada CNPJ. Guarde os id retornados.
·
Upload dos certificados
POST /v1/companies/{issuerId}/certificate para cada empresa.
·
Testar em homologação
Todo emissor novo já nasce em homologação (ambienteFiscal: 2). Emita notas de teste e valide os campos mapeados, sem precisar configurar nada.
·
Adaptar endpoints
Remova companyId da URL e mova para issuerId no body.
·
Configurar webhooks globais
Um webhook global recebe eventos de todas as empresas. Filtre por issuerId.
·
Migrar para produção
Promover o emissor para produção é self-service, ver Sandbox.