> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Vindo da Focus NFe

> Do ref livre do Focus NFe ao id UUID gerado pela engineAPI: mapeamento de endpoints e campos, e por que o cancelamento muda de DELETE para POST com justificativa.

## 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](/guides/sandbox) |

## Mapeamento de endpoints

| Focus NFe                           | engineAPI                                 | Notas                                                    |
| ----------------------------------- | ----------------------------------------- | -------------------------------------------------------- |
| `POST /v2/nfe`                      | `POST /v1/nfe`                            | Payload diferente, ver [Emitir NF-e](/guides/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 NF-e)

### 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 NF-e 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/guides/emitir-nfe#cancelamento) e
    [Emissão de NFC-e](/guides/nfce#cancelamento).
  </Accordion>

  <Accordion title="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](/guides/sandbox).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Checklist de migração

<Steps>
  <Step title="Criar conta na engineAPI">
    Registre-se em [app.engineapi.com.br](https://app.engineapi.com.br) e gere sua API Key.
  </Step>

  <Step title="Cadastrar empresas emissoras">
    `POST /v1/companies` para cada CNPJ. Guarde os `id` retornados (`issuerId`).
  </Step>

  <Step title="Upload dos certificados">
    `POST /v1/companies/{issuerId}/certificate` com o `.pfx` de cada empresa.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Adaptar payloads">
    Converta `snake_case → camelCase` e reorganize os campos conforme a tabela acima.
  </Step>

  <Step title="Configurar webhooks">
    Configure `PATCH /v1/webhooks/config` em vez de callback por nota.
  </Step>

  <Step title="Migrar para produção">
    Promover o emissor para produção é self-service, ver [Sandbox](/guides/sandbox).
  </Step>

  <Step title="Desativar Focus NFe">
    Após validar a estabilidade por 1-2 semanas, cancele o plano no Focus NFe.
  </Step>
</Steps>

## Próximos passos

* [Autenticação](/authentication): JWT e API Keys da engineAPI.
* [Webhooks](/guides/webhooks): configurar notificações em tempo real.