API - Documentos Fiscais

Autenticação

Todos os endpoints requerem JWT com role admin ou superadmin.

---

POST /t/:slug/fiscal/emit

Emite uma NF-e ou NFC-e para um pedido.

Body:

{
  "orderId": "6650a1b2c3d4e5f6a7b8c9d0",
  "tipo": "nfce",
  "customerCpf": "12345678900"
}

Campo	Tipo	Obrigatório	Descrição
orderId	string	Sim	ID do pedido no MongoDB
tipo	nfe | nfce	Sim	Tipo de nota fiscal
customerCpf	string	Não	CPF do destinatário (11 dígitos, sem formatação)

Response 201:

{
  "_id": "6650b1c2d3e4f5a6b7c8d9e0",
  "order": {
    "_id": "6650a1b2c3d4e5f6a7b8c9d0",
    "orderNumber": "20260301-0042",
    "total": 8500,
    "customerName": "João Silva"
  },
  "tenant": "6640a1b2c3d4e5f6a7b8c9d0",
  "tipo": "nfce",
  "status": "authorized",
  "nfeKey": "35260312345678000195650010000000421234567890",
  "nfeNumber": "42",
  "serie": "1",
  "danfeUrl": "https://focusnfe.com.br/danfe/...",
  "xmlUrl": "https://focusnfe.com.br/xml/...",
  "focusNfeRef": "abc123",
  "emittedAt": "2026-03-01T14:32:00.000Z",
  "createdAt": "2026-03-01T14:31:50.000Z"
}

Erros:

Código	Motivo
400	Pedido não encontrado ou tenant sem CNPJ/token configurado
422	Rejeitado pela SEFAZ — ver campo errorDetails
503	Focus NFe indisponível

---

GET /t/:slug/fiscal

Lista documentos fiscais do tenant.

Query params:

Param	Tipo	Descrição
status	string	Filtrar por status (pending, authorized, rejected, cancelled)
page	number	Página (padrão 1)
limit	number	Itens por página (padrão 20)

Response 200:

[
  {
    "_id": "...",
    "order": { "_id": "...", "orderNumber": "20260301-0042", "total": 8500, "customerName": "João Silva" },
    "tipo": "nfce",
    "status": "authorized",
    "nfeKey": "35260312345678000195650010000000421234567890",
    "danfeUrl": "https://focusnfe.com.br/danfe/...",
    "emittedAt": "2026-03-01T14:32:00.000Z"
  }
]

---

DELETE /t/:slug/fiscal/:id/cancel

Cancela um documento fiscal autorizado.

Response 200:

{
  "_id": "...",
  "status": "cancelled"
}

Erros:

Código	Motivo
404	Documento não encontrado
400	Documento não está no status authorized
422	SEFAZ recusou o cancelamento (prazo expirado ou outro motivo)

---

Configuração do Tenant para NF-e

Os campos abaixo devem ser preenchidos via PUT /t/:slug/tenants (ou via Settings no admin):

{
  "cnpj": "12345678000195",
  "inscricaoEstadual": "123456789012",
  "focusNfeToken": "token_homologacao_abc123",
  "focusNfeAmbiente": "homologacao",
  "regimeTributario": "1",
  "address": "Rua das Flores",
  "addressNumber": "100",
  "district": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "cep": "01310100"
}

---

---

Accountant Endpoints

Todos os endpoints abaixo requerem JWT com role accountant, admin ou superadmin.

GET /t/:slug/accountant/dashboard

Retorna estatísticas mensais do portal do contador.

Query params:

Param	Tipo	Descrição
year	number	Ano de referência
month	number	Mês de referência (1-12)

Response 200:

{
  "year": 2026,
  "month": 3,
  "authorized": 142,
  "rejected": 3,
  "pending": 5,
  "byType": { "nfe": 80, "nfce": 60, "nfse": 10 }
}

---

GET /t/:slug/accountant/documents

Lista documentos fiscais com paginação e filtros.

Query params:

Param	Tipo	Descrição
page	number	Página (padrão 1)
limit	number	Itens por página (padrão 20)
status	string	Filtrar por status
startDate	string	Data início (ISO 8601)
endDate	string	Data fim (ISO 8601)

Response 200:

{
  "data": [{ "...FiscalDoc" }],
  "total": 150
}

---

GET /t/:slug/accountant/documents/:id

Retorna um documento fiscal específico.

Response 200: Objeto FiscalDoc completo.

---

GET /t/:slug/accountant/export/efd

Gera relatório EFD ICMS/IPI para o período.

Query params:

Param	Tipo	Descrição
startDate	string	Data início (ISO 8601)
endDate	string	Data fim (ISO 8601)

Response 200:

{ "url": "https://s3.amazonaws.com/.../efd-icms-ipi.txt" }

---

GET /t/:slug/accountant/export/efd-contribuicoes

Gera relatório EFD Contribuições para o período.

Query params:

Param	Tipo	Descrição
startDate	string	Data início (ISO 8601)
endDate	string	Data fim (ISO 8601)

Response 200:

{ "url": "https://s3.amazonaws.com/.../efd-contribuicoes.txt" }

---

GET /t/:slug/accountant/export/xml-batch

Exporta XMLs em lote como arquivo ZIP.

Query params:

Param	Tipo	Descrição
startDate	string	Data início (ISO 8601)
endDate	string	Data fim (ISO 8601)

Response 200: Arquivo ZIP (Content-Type: application/zip).

---

GET /t/:slug/accountant/split-payment

Simulação do impacto do Split Payment nos recebimentos.

Query params:

Param	Tipo	Descrição
startDate	string	Data início (ISO 8601)
endDate	string	Data fim (ISO 8601)

Response 200:

{
  "orderCount": 320,
  "totalRevenue": 152000,
  "totalTax": 18240,
  "totalNet": 133760,
  "splitPaymentImpact": 15200,
  "taxBreakdown": {}
}

---

GET /t/:slug/accountant/dere

Demonstração do Resultado do Exercício.

Query params:

Param	Tipo	Descrição
startDate	string	Data início (ISO 8601)
endDate	string	Data fim (ISO 8601)

Response 200:

{
  "periodo": { "inicio": "2026-01-01", "fim": "2026-03-31" },
  "receitaBruta": 152000,
  "deducoes": 18240,
  "receitaLiquida": 133760,
  "orderCount": 320,
  "byType": {},
  "byPayment": {}
}

---

POST /t/:slug/accountant/invite

Convida um contador por email. Requer role admin ou superadmin.

Body:

{
  "email": "contador@exemplo.com",
  "name": "Maria Souza"
}

Campo	Tipo	Obrigatório	Descrição
email	string	Sim	Email do contador
name	string	Não	Nome do contador

Response 201:

{ "message": "Convite enviado com sucesso" }

---

GET /t/:slug/fiscal/queue/stats

Retorna métricas da fila BullMQ de emissão fiscal.

Response 200:

{
  "waiting": 2,
  "active": 1,
  "completed": 487,
  "failed": 3
}

---

GET /t/:slug/ncm/search

Busca fuzzy de códigos NCM via trigram matching.

Query params:

Param	Tipo	Descrição
q	string	Termo de busca (código ou descrição)
category	string	Filtrar por categoria
limit	number	Limite de resultados (padrão 10)

Response 200:

[
  {
    "code": "2202.10.00",
    "description": "Águas, incluindo as minerais e as gaseificadas, adicionadas de açúcar",
    "category": "bebidas",
    "score": 0.85
  }
]

---

Relacionados

• Admin — NF-e View
• Admin — Configurações
• API — Pedidos