Skip to main content

​
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:
  1. Preview — faça o upload do XML e visualize os itens antes de confirmar. Nenhum estoque é alterado nessa etapa.
  2. 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:
CampoTipoObrig.Descrição
fileFile✅Arquivo XML da NF-e (max: 10 MB)
warehouseIdUUIDDepó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:
StatusDescrição
matchedItem encontrado automaticamente no catálogo
not_foundNenhum produto correspondente encontrado
skippedItem ignorado (ex: serviço, frete)
manualVinculado 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
}
CampoTipoDescrição
warehouseIdUUIDSobrescreve o depósito definido no preview
skipNotFoundbooleanSe 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âmetroTipoDescrição
statusstringpending, completed, cancelled
startDatedateFiltrar por data de emissão da NF (YYYY-MM-DD)
endDatedateFiltrar por data de emissão da NF (YYYY-MM-DD)
pagenumberPaginação
limitnumberRegistros 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).