Importação de NF-e

Visão geral

O módulo de importação de NF-e permite que você faça entrada de estoque a partir de arquivos XML de Nota Fiscal Eletrônica emitidos por fornecedores. O fluxo tem duas etapas:

Preview — faça o upload do XML e visualize os itens antes de confirmar. Nenhum estoque é alterado nessa etapa.
Confirmação — após revisar o preview, confirme a importação. O estoque é atualizado somente neste momento.

Use o preview para identificar itens sem correspondência no catálogo antes de confirmar a entrada.

Fluxo completo

POST /import/nfe/preview
    │
    ▼
Revise os itens parseados
    │
    ├─ Tudo certo?
    │       └─ POST /import/nfe/:importId/confirm
    │
    └─ Cancelar?
            └─ DELETE /import/nfe/:importId

Endpoints

1. Preview do XML

POST /import/nfe/preview
Content-Type: multipart/form-data

Form data:

Campo	Tipo	Obrig.	Descrição
`file`	File	✅	Arquivo XML da NF-e (max: 10 MB)
`warehouseId`	UUID		Depósito de destino (usa padrão se omitido)

Resposta 200:

{
  "importId": "uuid-da-importacao",
  "nfeKey": "35250612345678901234550010000001231234567890",
  "supplier": {
    "name": "Fornecedor Exemplo Ltda",
    "cnpj": "12.345.678/0001-90"
  },
  "issueDate": "2025-06-12",
  "totalValue": 1850.00,
  "items": [
    {
      "lineNumber": 1,
      "description": "RESISTOR 10K 1/4W",
      "ncm": "85341000",
      "quantity": 100,
      "unitPrice": 0.50,
      "totalPrice": 50.00,
      "matchedProduct": {
        "id": "uuid-produto",
        "commercialName": "Resistor 10k",
        "sku": "RES-10K"
      },
      "matchStatus": "matched"
    },
    {
      "lineNumber": 2,
      "description": "CAPACITOR 100UF 25V",
      "ncm": "85322500",
      "quantity": 50,
      "unitPrice": 1.20,
      "totalPrice": 60.00,
      "matchedProduct": null,
      "matchStatus": "not_found"
    }
  ],
  "summary": {
    "totalItems": 2,
    "matched": 1,
    "notFound": 1,
    "skipped": 0
  }
}

Status de match dos itens:

Status	Descrição
`matched`	Item encontrado automaticamente no catálogo
`not_found`	Nenhum produto correspondente encontrado
`skipped`	Item ignorado (ex: serviço, frete)
`manual`	Vinculado manualmente antes da confirmação

Erro 409: NF-e com a mesma chave de acesso já importada.

2. Vincular item sem match (opcional)

Antes de confirmar, você pode vincular manualmente itens com status not_found a produtos do catálogo.

PATCH /import/nfe/:importId/items/:lineNumber/link
Content-Type: application/json

Body:

{
  "productId": "uuid-do-produto"
}

3. Confirmar importação

POST /import/nfe/:importId/confirm
Content-Type: application/json

Body (opcional):

{
  "warehouseId": "uuid-do-deposito",
  "skipNotFound": true
}

Campo	Tipo	Descrição
`warehouseId`	UUID	Sobrescreve o depósito definido no preview
`skipNotFound`	boolean	Se `true`, itens sem match são ignorados. Se `false`, falha se houver.

Resposta 200:

{
  "importId": "uuid",
  "status": "completed",
  "inventoryEntriesCreated": 1,
  "itemsSkipped": 1,
  "summary": {
    "totalAdded": 100,
    "totalValue": 50.00
  }
}

4. Cancelar importação

DELETE /import/nfe/:importId

Remove o import pendente sem alterar nenhum estoque.

Listar importações

GET /import/nfe

Query params:

Parâmetro	Tipo	Descrição
`status`	string	`pending`, `completed`, `cancelled`
`startDate`	date	Filtrar por data de emissão da NF (YYYY-MM-DD)
`endDate`	date	Filtrar por data de emissão da NF (YYYY-MM-DD)
`page`	number	Paginação
`limit`	number	Registros por página

Detalhar importação

GET /import/nfe/:importId

Retorna todos os dados do preview, incluindo o status atual e os itens vinculados.

Observações importantes

A confirmação é irreversível. Verifique o preview com atenção antes de confirmar, especialmente os itens com not_found.

Apenas uma importação pendente por chave de NF-e é permitida por tenant.
Importações com status pending expiram automaticamente após 24 horas.
O custo unitário registrado na entrada de estoque usa o unitPrice da NF-e.
Serviços e itens de frete na NF-e são automaticamente ignorados (skipped).

Introdução

Guias Práticos (Manuais)

Para Desenvolvedores

Sistema

Funcional

Importação de NF-e

Visão geral

Fluxo completo

Endpoints

1. Preview do XML

2. Vincular item sem match (opcional)

3. Confirmar importação

4. Cancelar importação

Listar importações

Detalhar importação

Observações importantes

​Visão geral

​Fluxo completo

​Endpoints

​1. Preview do XML

​2. Vincular item sem match (opcional)

​3. Confirmar importação

​4. Cancelar importação

​Listar importações

​Detalhar importação

​Observações importantes

Visão geral

Fluxo completo

Endpoints

1. Preview do XML

2. Vincular item sem match (opcional)

3. Confirmar importação

4. Cancelar importação

Listar importações

Detalhar importação

Observações importantes