focus-nfe
title: Migrar do Focus NFe description: Guia de migração do Focus NFe para Engine API: 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 | Engine API |
|---------|-----------|-----------|
| 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.) | Campo environment na empresa |
Mapeamento de Endpoints
| Focus NFe | Engine API | Notas |
|-----------|-----------|-------|
| POST /v2/nfe | POST /nfe/emitir | Payload diferente |
| GET /v2/nfe/{ref} | GET /nfe/{id} | ref → id UUID |
| DELETE /v2/nfe/{ref} | POST /nfe/{id}/cancelar | Método diferente |
| POST /v2/nfe/{ref}/carta_correcao | POST /nfe/{id}/carta-correcao | — |
| GET /v2/nfe/{ref}.xml | GET /nfe/{id}/xml | — |
| GET /v2/nfe/{ref}.pdf | GET /nfe/{id}/pdf | — |
| GET /v2/nfce/{ref} | GET /nfce/{id} | — |
| POST /v2/nfse | POST /nfse/emitir | — |
| POST /v2/emitentes | POST /companies | — |
Mapeamento de Campos (Emissão NFe)
Raiz
| Campo Focus NFe | Campo Engine API | Notas |
|----------------|-----------------|-------|
| ref | — | Engine API gera o id automaticamente |
| natureza_operacao | naturezaOperacao | camelCase na Engine API |
| forma_pagamento | pagamento.forma | Objeto separado |
Destinatário
| Campo Focus NFe | Campo Engine API |
|----------------|-----------------|
| cnpj_destinatario | destinatario.cnpj |
| cpf_destinatario | destinatario.cpf |
| nome_destinatario | destinatario.nome |
| logradouro_destinatario | destinatario.endereco.logradouro |
| numero_destinatario | destinatario.endereco.numero |
| bairro_destinatario | destinatario.endereco.bairro |
| municipio_destinatario | destinatario.endereco.municipio |
| uf_destinatario | destinatario.endereco.uf |
| cep_destinatario | destinatario.endereco.cep |
| codigo_municipio_destinatario | destinatario.endereco.codigoMunicipio |
Item
| Campo Focus NFe | Campo Engine API |
|----------------|-----------------|
| numero_item | itens[].numero |
| codigo_produto | itens[].codigo |
| descricao | itens[].descricao |
| codigo_ncm | itens[].ncm |
| cfop | itens[].cfop |
| unidade_comercial | itens[].unidade |
| quantidade_comercial | itens[].quantidade |
| valor_unitario_comercial | itens[].valorUnitario |
| valor_total_bruto | itens[].valorTotal |
| origem_mercadoria | itens[].icms.origem |
| situacao_tributaria / csosn | itens[].icms.cst / itens[].icms.csosn |
Diferenças importantes
Checklist de Migração
Criar conta na Engine API
Registre-se em app.engineapi.com.br e gere sua API Key.
Cadastrar empresas emissoras
POST /companies para cada CNPJ. Guarde os id retornados (issuerId).
Upload dos certificados
POST /companies/{issuerId}/certificate com o .pfx de cada empresa.
Testar em homologação
Configure environment: 2 e emita notas de teste verificando os mapeamentos.
Adaptar payloads
Converta snake_case → camelCase e reorganize os campos conforme a tabela acima.
Configurar webhooks
Configure POST /webhooks em vez de callback por nota.
Migrar para produção
Mude environment: 1 e atualize a integração para usar a Engine API.
Desativar Focus NFe
Após validar a estabilidade por 1–2 semanas, cancele o plano no Focus NFe.