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

# Importação de NF-e

> Upload de XML de Nota Fiscal Eletrônica para entrada de estoque com preview e confirmação.

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

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

***

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

```http theme={null}
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`:**

```json theme={null}
{
  "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.

```http theme={null}
PATCH /import/nfe/:importId/items/:lineNumber/link
Content-Type: application/json
```

**Body:**

```json theme={null}
{
  "productId": "uuid-do-produto"
}
```

***

### 3. Confirmar importação

```http theme={null}
POST /import/nfe/:importId/confirm
Content-Type: application/json
```

**Body (opcional):**

```json theme={null}
{
  "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`:**

```json theme={null}
{
  "importId": "uuid",
  "status": "completed",
  "inventoryEntriesCreated": 1,
  "itemsSkipped": 1,
  "summary": {
    "totalAdded": 100,
    "totalValue": 50.00
  }
}
```

***

### 4. Cancelar importação

```http theme={null}
DELETE /import/nfe/:importId
```

Remove o import pendente sem alterar nenhum estoque.

***

## Listar importações

```http theme={null}
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

```http theme={null}
GET /import/nfe/:importId
```

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

***

## Observações importantes

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

* 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`).