Migrar do Focus NFe
Guia de migração do Focus NFe para engineAPI: mapeamento de endpoints, campos e diferenças de comportamento.
Migrar do Focus NFe
Tempo estimado de migração: 2–3 horas de desenvolvimento
Diferenças Principais
| Aspecto | Focus NFe | engineAPI |
|---|---|---|
| Autenticação | Token no header Authorization: Token {key} | Bearer JWT ou x-api-key |
| Identificador da nota | ref (string livre) | id (UUID gerado automaticamente) |
| Empresa no pedido | Query param ref_emitente ou header | issuerId no body |
| Webhooks | URL de callback por nota | Webhooks configuráveis globalmente |
| Ambiente | Subdomínio diferente (sandbox.) | Todo emissor nasce em homologação (ambienteFiscal: 2); promover para produção é self-service, ver Sandbox |
Mapeamento de Endpoints
| Focus NFe | engineAPI | Notas |
|---|---|---|
POST /v2/nfe | POST /v1/nfe | Payload diferente, ver Emitir NFe |
GET /v2/nfe/{ref} | GET /v1/nfe/{id} | ref → id UUID |
DELETE /v2/nfe/{ref} | POST /v1/nfe/{idOuChave}/cancelar | Método diferente |
POST /v2/nfe/{ref}/carta_correcao | POST /v1/nfe/{accessKey}/carta-correcao | N/A |
GET /v2/nfe/{ref}.xml | GET /v1/nfe/xml/{accessKey} | N/A |
GET /v2/nfe/{ref}.pdf | GET /v1/nfe/pdf/{accessKey} | N/A |
GET /v2/nfce/{ref} | GET /v1/nfce/{id} | N/A |
POST /v2/nfse | POST /v1/nfse | N/A |
POST /v2/emitentes | POST /v1/companies | N/A |
Mapeamento de Campos (Emissão NFe)
Raiz
| Campo Focus NFe | Campo engineAPI | Notas |
|---|---|---|
ref | N/A | engineAPI gera o id automaticamente |
natureza_operacao | naturezaOperacao | camelCase na engineAPI |
forma_pagamento | pagamentos[].forma | Array obrigatório (mín. 1), não objeto singular |
Destinatário
| Campo Focus NFe | Campo engineAPI | Notas |
|---|---|---|
cnpj_destinatario | destinatario.cnpjCpf | Campo único (11 a 14 dígitos), não há cnpj/cpf separados |
cpf_destinatario | destinatario.cnpjCpf | Mesmo campo do CNPJ acima |
nome_destinatario | destinatario.nome | N/A |
logradouro_destinatario | destinatario.endereco.logradouro | N/A |
numero_destinatario | destinatario.endereco.numero | N/A |
bairro_destinatario | destinatario.endereco.bairro | N/A |
municipio_destinatario | destinatario.endereco.municipio | N/A |
uf_destinatario | destinatario.endereco.uf | N/A |
cep_destinatario | destinatario.endereco.cep | N/A |
codigo_municipio_destinatario | destinatario.endereco.codigoMunicipio | N/A |
Item
O payload de NFe usa o array items (mínimo 1, não itens).
| Campo Focus NFe | Campo engineAPI | Notas |
|---|---|---|
numero_item | 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 |
origem_mercadoria | items[].icms.origem | N/A |
situacao_tributaria / csosn | items[].icms.cst / items[].icms.csosn | N/A |
Diferenças importantes
Checklist de Migração
Criar conta na engineAPI
Registre-se em app.engineapi.com.br e gere sua API Key.
Cadastrar empresas emissoras
POST /v1/companies para cada CNPJ. Guarde os id retornados (issuerId).
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 e valide os mapeamentos, sem precisar configurar nada.
Adaptar payloads
Converta snake_case → camelCase e reorganize os campos conforme a tabela acima.
Configurar webhooks
Configure PATCH /v1/webhooks/config em vez de callback por nota.
Migrar para produção
Promover o emissor para produção é self-service, ver Sandbox.
Desativar Focus NFe
Após validar a estabilidade por 1–2 semanas, cancele o plano no Focus NFe.