Migrar do eNotas
Guia completo de migração do eNotas para engineAPI: mapeamento de endpoints, campos e checklist de zero downtime.
Migrar do eNotas
Migre do eNotas para a engineAPI mantendo sua operação ativa. A engineAPI é compatível com os mesmos conceitos. A diferença está na estrutura de payload e autenticação.
Tempo estimado de migração: 2–4 horas de desenvolvimento
Diferenças Principais
| Aspecto | eNotas | engineAPI |
|---|---|---|
| Autenticação | Authorization: ApiKey {key} | x-api-key: {key} (integração) ou Authorization: Bearer {jwt} (dashboard) |
| Multi-tenancy | Empresa no URL | issuerId no body |
| Notificações | Callbacks por request | Webhooks configuráveis |
| Formato de resposta | Próprio | JSON padronizado |
| Ambiente | Header X-Ambiente | Todo emissor nasce em homologação (ambienteFiscal: 2); promover para produção é self-service, ver Sandbox |
Mapeamento de Endpoints
| eNotas | engineAPI | Notas |
|---|---|---|
POST /empresas/{id}/nfes | POST /v1/nfe | issuerId no body é opcional com um único emissor cadastrado; com 2+, é obrigatório |
GET /empresas/{id}/nfes/{nfeId} | GET /v1/nfe/{id} | N/A |
GET /empresas/{id}/nfes | GET /v1/nfe | N/A |
POST /empresas/{id}/nfes/{nfeId}/cancelar | POST /v1/nfe/{idOuChave}/cancelar | Campo obrigatório justificativa (mín. 15 caracteres) |
POST /empresas/{id}/nfes/{nfeId}/carta-correcao | POST /v1/nfe/{accessKey}/carta-correcao | N/A |
GET /empresas/{id}/nfes/{nfeId}/xml | GET /v1/nfe/xml/{accessKey} | Chave de acesso, não id |
GET /empresas/{id}/nfes/{nfeId}/pdf | GET /v1/nfe/pdf/{accessKey} | Chave de acesso, não id |
POST /empresas | POST /v1/companies | N/A |
POST /empresas/{id}/certificado | POST /v1/companies/{id}/certificate | Multipart/form-data, campo file |
Mapeamento de Campos
Emitente
| Campo eNotas | Campo engineAPI | Notas |
|---|---|---|
empresa_id (URL) | issuerId (body) | UUID retornado em POST /v1/companies |
Destinatário
| Campo eNotas | Campo engineAPI | Notas |
|---|---|---|
cnpj_cpf | destinatario.cnpjCpf | Campo único (11 a 14 dígitos), não há cnpj/cpf separados |
razao_social | destinatario.nome | N/A |
indicador_inscricao_estadual | destinatario.indicadorIE | Número (indIEDest da NFe) |
endereco.codigo_municipio | destinatario.endereco.codigoMunicipio | Mesmo código IBGE |
Item
O payload de NFe usa o array items (mínimo 1 item).
| Campo eNotas | Campo engineAPI | Notas |
|---|---|---|
item_numero | N/A | Não existe campo de número por item: o índice do array já identifica o item |
codigo_produto | items[].codigo | N/A |
descricao | items[].descricao | N/A |
codigo_ncm | items[].ncm | N/A |
cfop | items[].cfop | N/A |
unidade_comercial | items[].unidade | N/A |
quantidade_comercial | items[].quantidade | N/A |
valor_unitario_comercial | items[].valorUnitario | N/A |
valor_total_bruto | items[].valorTotal | Opcional, recalculado se ausente |
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 que emite notas.
Fazer upload dos certificados
POST /v1/companies/{issuerId}/certificate com o .pfx de cada empresa.
Testar em homologação
Todo emissor novo já nasce em homologação (ambienteFiscal: 2). Emita notas de teste sem precisar configurar nada.
Adaptar a integração
Ajuste os campos do payload conforme a tabela de mapeamento acima.
Configurar webhooks
PATCH /v1/webhooks/config com os eventos que precisa receber.
Migrar para produção
Promover o emissor para produção é self-service, ver Sandbox.