> ## 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 do eNotas

> Guia completo de migração do eNotas para engineAPI: mapeamento de endpoints, campos e checklist de zero downtime.

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](/guides/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/{chave ou id}`           | Chave de acesso da nota autorizada. O `id` também serve, e é o único caminho para o XML de uma emissão rejeitada |
| `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 NF-e)                                   |
| `endereco.codigo_municipio`    | `destinatario.endereco.codigoMunicipio` | Mesmo código IBGE                                            |

### Item

O payload de NF-e 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

<AccordionGroup>
  <Accordion title="Autenticação mudou">
    O eNotas usa API Key no header `Authorization`. A engineAPI usa **API Key** no header `x-api-key` para integrações server-to-server (o caso comum de software house); **JWT Bearer** (via login) é o fluxo do dashboard. Não misture os dois formatos.
  </Accordion>

  <Accordion title="issuerId vai no body, não na URL">
    No eNotas, a empresa vai na URL (`/empresas/{id}/nfes`). Na engineAPI, o `issuerId` é um campo dentro do body do JSON, opcional com um único emissor, obrigatório a partir do segundo.
  </Accordion>

  <Accordion title="Webhooks em vez de callbacks">
    O eNotas usa callbacks por polling ou por URL de callback. A engineAPI usa **webhooks** com payload padronizado e verificação HMAC. Configure em `PATCH /v1/webhooks/config`.
  </Accordion>

  <Accordion title="Resposta de emissão diferente">
    O eNotas retorna `ref` como identificador. A engineAPI retorna `id` (UUID) e `accessKey` (chave de acesso de 44 dígitos) diretamente.
  </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).
  </Step>

  <Step title="Cadastrar empresas emissoras">
    `POST /v1/companies` para cada CNPJ que emite notas.
  </Step>

  <Step title="Fazer 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 sem precisar configurar nada.
  </Step>

  <Step title="Adaptar a integração">
    Ajuste os campos do payload conforme a tabela de mapeamento acima.
  </Step>

  <Step title="Configurar webhooks">
    `PATCH /v1/webhooks/config` com os eventos que precisa receber.
  </Step>

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

## Próximos passos

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