Migrar do NFe.io
Tempo estimado de migração: 1–3 horas de desenvolvimentoDiferenças Principais
| Aspecto | NFe.io | Engine API |
|---|---|---|
| Autenticação | API Key no header Authorization | Bearer JWT ou x-api-key |
| Estrutura de URL | /v1/companies/{companyId}/productinvoices/{id} | /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 | Configurados globalmente |
Mapeamento de Endpoints
| NFe.io | Engine API | Notas |
|---|---|---|
POST /v1/companies/{id}/productinvoices | POST /nfe/emitir | issuerId no body |
GET /v1/companies/{id}/productinvoices/{inv} | GET /nfe/{id} | — |
GET /v1/companies/{id}/productinvoices | GET /nfe | — |
DELETE /v1/companies/{id}/productinvoices/{inv} | POST /nfe/{id}/cancelar | Método diferente |
POST /v1/companies/{id}/serviceinvoices | POST /nfse/emitir | — |
GET /v1/companies/{id}/serviceinvoices/{inv} | GET /nfse/{id} | — |
DELETE /v1/companies/{id}/serviceinvoices/{inv} | POST /nfse/{id}/cancelar | — |
POST /v1/companies | POST /companies | — |
GET /v1/companies/{id} | GET /companies/{id} | — |
PUT /v1/companies/{id}/certificate | POST /companies/{id}/certificate | Multipart/form-data |
Mapeamento de Campos
NFe (productinvoices → nfe)
| Campo NFe.io | Campo Engine API | Notas |
|---|---|---|
cityServiceCode | — | Não aplicável para NFe |
description | naturezaOperacao | — |
borrower.federalTaxNumber | destinatario.cnpj | — |
borrower.name | destinatario.nome | — |
borrower.address.street | destinatario.endereco.logradouro | — |
borrower.address.number | destinatario.endereco.numero | — |
borrower.address.district | destinatario.endereco.bairro | — |
borrower.address.city.code | destinatario.endereco.codigoMunicipio | Código IBGE |
borrower.address.city.name | destinatario.endereco.municipio | — |
borrower.address.state | destinatario.endereco.uf | — |
borrower.address.postalCode | destinatario.endereco.cep | — |
Gotchas — O que é diferente
Empresa sai da URL e vai para o body
Empresa sai da URL e vai para o body
O NFe.io coloca
companyId na URL: /v1/companies/{companyId}/productinvoices. Na Engine API, o identificador da empresa é o campo issuerId dentro do JSON do body.Cancelamento muda de método HTTP
Cancelamento muda de método HTTP
NFe.io:
DELETE /v1/companies/{id}/productinvoices/{inv}. Engine API: POST /nfe/{id}/cancelar com o campo obrigatório motivo (15–255 caracteres).Terminologia diferente
Terminologia diferente
NFe.io usa
productinvoices para NFe e serviceinvoices para NFSe. A Engine API usa os módulos /nfe e /nfse diretamente.Webhooks são globais, não por empresa
Webhooks são globais, não por empresa
No NFe.io, os webhooks são configurados por empresa. Na Engine API, um webhook recebe eventos de todas as empresas do seu token — filtre pelo
issuerId no payload.Checklist de Migração
Criar conta na Engine API
Registre-se em app.engineapi.com.br.
Configurar webhooks globais
Um webhook global recebe eventos de todas as empresas — filtre por
issuerId.Próximos passos
Autenticação
JWT e API Keys da Engine API
Webhooks
Filtrar eventos por empresa emissora