> ## 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 NFe.io

> Guia de migração do NFe.io para engineAPI: mapeamento de endpoints, campos e diferenças de comportamento.

**Tempo estimado de migração: 1-3 horas de desenvolvimento**

## Diferenças principais

| Aspecto               | NFe.io                                                       | engineAPI                                                  |
| --------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
| **Autenticação**      | API Key no header `Authorization`                            | `x-api-key` (integração) ou Bearer JWT (dashboard)         |
| **Estrutura de URL**  | `/v1/companies/{companyId}/productinvoices/{id}`             | `/v1/nfe/{id}` (sem empresa na URL)                        |
| **Empresa no pedido** | `companyId` na URL                                           | `issuerId` no body                                         |
| **Tipo de nota**      | Separado por endpoint (`productinvoices`, `serviceinvoices`) | Separado por módulo (`/nfe`, `/nfse`)                      |
| **Webhooks**          | Configurados por empresa                                     | Uma configuração por partner (`PATCH /v1/webhooks/config`) |

## Mapeamento de endpoints

| NFe.io                                            | engineAPI                             | Notas                                                                                                                                             |
| ------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/companies/{id}/productinvoices`         | `POST /v1/nfe`                        | `issuerId` no body é opcional com um único emissor cadastrado; com 2+, é obrigatório (ver aviso em [Autenticação](/authentication#multi-tenancy)) |
| `GET /v1/companies/{id}/productinvoices/{inv}`    | `GET /v1/nfe/{id}`                    | N/A                                                                                                                                               |
| `GET /v1/companies/{id}/productinvoices`          | `GET /v1/nfe`                         | N/A                                                                                                                                               |
| `DELETE /v1/companies/{id}/productinvoices/{inv}` | `POST /v1/nfe/{idOuChave}/cancelar`   | Método diferente                                                                                                                                  |
| `POST /v1/companies/{id}/serviceinvoices`         | `POST /v1/nfse`                       | `issuerId` obrigatório no body (única exceção)                                                                                                    |
| `GET /v1/companies/{id}/serviceinvoices/{inv}`    | `GET /v1/nfse/{id}`                   | N/A                                                                                                                                               |
| `DELETE /v1/companies/{id}/serviceinvoices/{inv}` | `POST /v1/nfse/{id}/cancelar`         | N/A                                                                                                                                               |
| `POST /v1/companies`                              | `POST /v1/companies`                  | N/A                                                                                                                                               |
| `GET /v1/companies/{id}`                          | `GET /v1/companies/{id}`              | N/A                                                                                                                                               |
| `PUT /v1/companies/{id}/certificate`              | `POST /v1/companies/{id}/certificate` | Multipart/form-data, campo `file`                                                                                                                 |

## Mapeamento de campos

### NF-e (productinvoices → nfe)

| Campo NFe.io                  | Campo engineAPI                         | Notas                                                        |
| ----------------------------- | --------------------------------------- | ------------------------------------------------------------ |
| `cityServiceCode`             | N/A                                     | Não aplicável para NF-e                                      |
| `description`                 | `naturezaOperacao`                      | N/A                                                          |
| `borrower.federalTaxNumber`   | `destinatario.cnpjCpf`                  | Campo único (11 a 14 dígitos), não há `cnpj`/`cpf` separados |
| `borrower.name`               | `destinatario.nome`                     | N/A                                                          |
| `borrower.address.street`     | `destinatario.endereco.logradouro`      | N/A                                                          |
| `borrower.address.number`     | `destinatario.endereco.numero`          | N/A                                                          |
| `borrower.address.district`   | `destinatario.endereco.bairro`          | N/A                                                          |
| `borrower.address.city.code`  | `destinatario.endereco.codigoMunicipio` | Código IBGE                                                  |
| `borrower.address.city.name`  | `destinatario.endereco.municipio`       | N/A                                                          |
| `borrower.address.state`      | `destinatario.endereco.uf`              | N/A                                                          |
| `borrower.address.postalCode` | `destinatario.endereco.cep`             | N/A                                                          |

## Diferenças importantes

<AccordionGroup>
  <Accordion title="Empresa sai da URL e vai para o body">
    O NFe.io coloca `companyId` na URL: `/v1/companies/{companyId}/productinvoices`. Na engineAPI, o identificador da empresa é o campo `issuerId` dentro do JSON do body.
  </Accordion>

  <Accordion title="Cancelamento muda de método HTTP">
    NFe.io: `DELETE /v1/companies/{id}/productinvoices/{inv}`. engineAPI: `POST /v1/nfe/{idOuChave}/cancelar` com o campo obrigatório `justificativa` (mínimo 15 caracteres). `motivo` é o nome do campo em NFS-e, não em NF-e.
  </Accordion>

  <Accordion title="Terminologia diferente">
    NFe.io usa `productinvoices` para NF-e e `serviceinvoices` para NFS-e. A engineAPI usa os módulos `/nfe` e `/nfse` diretamente.
  </Accordion>

  <Accordion title="Webhooks são globais, não por empresa">
    No NFe.io, os webhooks são configurados por empresa. Na engineAPI, um webhook recebe eventos de **todas as empresas** do seu token. Filtre pelo `issuerId` no payload.
  </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. Guarde os `id` retornados.
  </Step>

  <Step title="Upload dos certificados">
    `POST /v1/companies/{issuerId}/certificate` para 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 campos mapeados, sem precisar configurar nada.
  </Step>

  <Step title="Adaptar endpoints">
    Remova `companyId` da URL e mova para `issuerId` no body.
  </Step>

  <Step title="Configurar webhooks globais">
    Um webhook global recebe eventos de todas as empresas. Filtre por `issuerId`.
  </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 da engineAPI.
* [Webhooks](/guides/webhooks): filtrar eventos por empresa emissora.