Diferenças principais
Mapeamento de endpoints
Mapeamento de campos (emissão NF-e)
Raiz
Destinatário
Item
O payload de NF-e usa o arrayitems (mínimo 1, não itens).
Diferenças importantes
Não existe mais ref: use o id retornado
Não existe mais ref: use o id retornado
No Focus NFe, você define um
ref livre para identificar a nota. Na engineAPI, o id é um UUID gerado automaticamente no momento da emissão. Armazene-o no seu banco de dados.Cancelamento muda de método e de campo
Cancelamento muda de método e de campo
Focus NFe:
DELETE /v2/nfe/{ref}. engineAPI: POST /v1/nfe/{idOuChave}/cancelar com o campo justificativa no body (mínimo 15 caracteres), não é motivo.O prazo fiscal também importa na migração: NF-e (modelo 55) cancela em até 24
horas após a autorização; NFC-e (modelo 65) em 30 minutos, padrão nacional por
UF (Ajuste SINIEF 07/18), desde que a mercadoria não tenha circulado. Fora do prazo a
SEFAZ rejeita (cStat 501) e não há cancelamento extemporâneo via API. O remédio
legal é emitir uma NF-e de devolução com finNFe: 4, referenciadas e pagamento
sem pagamento (forma: "90", valor zero); a API valida essa combinação antes de
numerar. Detalhe completo em Emissão de NF-e e
Emissão de NFC-e.Ambiente não é mais subdomínio
Ambiente não é mais subdomínio
Focus NFe usa
sandbox.focusnfe.com.br. Na engineAPI o endpoint é sempre api.engineapi.com.br, não existe um campo environment no cadastro da empresa. Todo emissor nasce em homologação (ambienteFiscal: 2); promover para produção é self-service, ver Sandbox.Nomes de campos em camelCase
Nomes de campos em camelCase
O Focus NFe usa
snake_case nos campos. A engineAPI usa camelCase. Use a tabela de mapeamento acima como referência.Checklist de migração
1
Criar conta na engineAPI
Registre-se em app.engineapi.com.br e gere sua API Key.
2
Cadastrar empresas emissoras
POST /v1/companies para cada CNPJ. Guarde os id retornados (issuerId).3
Upload dos certificados
POST /v1/companies/{issuerId}/certificate com o .pfx de cada empresa.4
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.5
Adaptar payloads
Converta
snake_case → camelCase e reorganize os campos conforme a tabela acima.6
Configurar webhooks
Configure
PATCH /v1/webhooks/config em vez de callback por nota.7
Migrar para produção
Promover o emissor para produção é self-service, ver Sandbox.
8
Desativar Focus NFe
Após validar a estabilidade por 1-2 semanas, cancele o plano no Focus NFe.
Próximos passos
- Autenticação: JWT e API Keys da engineAPI.
- Webhooks: configurar notificações em tempo real.