API — NF-e Entrada
Autenticação
Todos os endpoints requerem JWT com role admin ou superadmin e permissão manage_fiscal.
Base: /t/:slug/inbound-nfe
POST /t/:slug/inbound-nfe/sync
Consulta o provider configurado (INBOUND_NFE_PROVIDER) por NF-es emitidas contra o CNPJ do tenant e faz upsert no banco.
Body (opcional):
{
"startDate": "2026-01-01",
"endDate": "2026-04-30"
}Response 201:
{
"created": 5,
"updated": 2,
"total": 7
}Erros:
| Código | Motivo |
|---|---|
| 400 | CNPJ do tenant não configurado |
| 400 | Token do provider não configurado |
GET /t/:slug/inbound-nfe
Lista NF-es recebidas com paginação e filtros.
Query params:
| Param | Tipo | Descrição |
|---|---|---|
status | string | pending | ciencia | confirmada | desconhecida | nao_realizada |
startDate | string | Data de emissão início (ISO 8601) |
endDate | string | Data de emissão fim (ISO 8601) |
page | number | Página (padrão 1) |
limit | number | Itens por página (padrão 20) |
Response 200:
{
"items": [
{
"_id": "...",
"nfeKey": "35260312345678000195550010000000421234567890",
"emitterCnpj": "12345678000195",
"emitterName": "FORNECEDOR LTDA",
"total": 1500.00,
"issueDate": "2026-04-01T00:00:00.000Z",
"status": "pending",
"inventoryProcessed": false,
"items": [
{ "cProd": "001", "description": "Filé Mignon", "qty": 10, "unitCost": 120.00, "vTotal": 1200.00 }
],
"createdAt": "2026-04-02T10:00:00.000Z"
}
],
"total": 42,
"page": 1,
"limit": 20,
"pages": 3
}GET /t/:slug/inbound-nfe/:id
Retorna uma NF-e específica com todos os itens.
Response 200: Objeto completo da NF-e.
POST /t/:slug/inbound-nfe/:id/manifest
Registra um evento de manifestação do destinatário.
Body:
{
"eventType": "confirmacao",
"justification": "Mercadoria recebida e confere"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
eventType | string | Sim | ciencia | confirmacao | desconhecimento | nao_realizada |
justification | string | Condicional | Obrigatório para desconhecimento e nao_realizada (mín. 15 chars) |
Response 200: NF-e atualizada com novo status.
Efeito colateral (confirmacao apenas):
- Cria
InventoryMovementde entrada para itens vinculados ao estoque - Cria
AccountsPayablecomcompetenceDate = nfe.issueDate - Dispara
BomService.recalculateAllForIngredients()
Erros:
| Código | Motivo |
|---|---|
| 404 | NF-e não encontrada |
| 400 | Justificativa obrigatória |
| 409 | NF-e já confirmada |
DELETE /t/:slug/inbound-nfe/:id
Remove a NF-e do banco (não desfaz movimentações de estoque já criadas).
Response 200: { "deleted": true }
GET /t/:slug/inbound-nfe/accounts-payable
Lista Contas a Pagar com paginação e filtros.
Query params:
| Param | Tipo | Descrição |
|---|---|---|
status | string | open | partial | paid | overdue | cancelled |
startDate | string | Data de vencimento início |
endDate | string | Data de vencimento fim |
page | number | Página (padrão 1) |
limit | number | Itens por página (padrão 20) |
Response 200:
{
"items": [
{
"_id": "...",
"supplierName": "FORNECEDOR LTDA",
"amount": 1500.00,
"dueDate": "2026-05-01T00:00:00.000Z",
"competenceDate": "2026-04-01T00:00:00.000Z",
"paymentStatus": "open",
"paidAmount": 0,
"originNfe": "..."
}
],
"total": 15,
"page": 1,
"limit": 20,
"pages": 1
}POST /t/:slug/inbound-nfe/accounts-payable
Cria uma Conta a Pagar manualmente (sem NF-e vinculada).
Body:
{
"supplierName": "Fornecedor XYZ",
"amount": 500.00,
"dueDate": "2026-05-10",
"competenceDate": "2026-04-01",
"description": "Aluguel de equipamento"
}Response 201: Objeto AccountsPayable criado.
PUT /t/:slug/inbound-nfe/accounts-payable/:id/pay
Registra pagamento de uma Conta a Pagar.
Body:
{
"paymentStatus": "paid",
"paidAmount": 1500.00,
"paidAt": "2026-04-30"
}| Campo | Tipo | Descrição |
|---|---|---|
paymentStatus | string | paid | partial | cancelled |
paidAmount | number | Valor efetivamente pago |
paidAt | string | Data do pagamento (ISO 8601) |
Response 200: AccountsPayable atualizado.
DELETE /t/:slug/inbound-nfe/accounts-payable/:id
Cancela uma Conta a Pagar (paymentStatus → cancelled).
Response 200: AccountsPayable com status cancelled.