Nota4You

API REST

Integre o seu sistema ao Nota4You: cadastros, prévia, emissão, consulta e arquivos da nota.

Convenções

Autenticação

Crie a chave em Configurações > Chaves de API (proprietários e administradores). O token aparece uma vez só. Envie em todas as requisições:

Authorization: Bearer <sua chave>

Teste a chave com GET /api/v1/current_api_key: ela devolve o nome, a conta, os escopos e a validade.

Escopo Permite
taxpayers:read Ler empresas, serviços e clientes.
taxpayers:write Criar e alterar empresas, serviços, clientes e séries.
invoices:read Ler notas, eventos e arquivos.
invoices:write Prévia, emissão, correção e reenvio.
invoices:cancel Cancelar notas. Com invoices:write, substituir notas.
webhooks:manage Gerenciar webhooks.
mcp Usar o servidor MCP.

Uma chave também pode ficar limitada a algumas empresas. A chave nunca passa do papel de quem a criou: se essa pessoa sai da conta, a chave para de funcionar.

Endpoints principais

Método Caminho Uso
GET, POST /taxpayers Listar e cadastrar empresas.
GET, PATCH /taxpayers/:id Ler e alterar uma empresa.
GET, POST, PATCH /taxpayers/:id/services Catálogo de serviços.
GET, POST, PATCH /taxpayers/:id/customers Clientes.
POST /taxpayers/:id/invoice_previews Validar e estimar tributos, sem emitir.
GET, POST /taxpayers/:id/invoices Listar e emitir notas.
GET, PATCH /invoices/:id Ler uma nota; corrigir uma nota rejeitada.
POST /invoices/:id/retransmission Reenviar uma nota rejeitada.
POST /invoices/:id/cancellation Cancelar uma nota autorizada (escopo invoices:cancel).
POST /invoices/:id/substitution Substituir uma nota autorizada (escopos invoices:write e invoices:cancel).
GET /invoices/:id/events Eventos da nota (cancelamento e cancelamento por substituição), com as mensagens da Sefin Nacional.
GET /invoices/:id/xml, /invoices/:id/danfse XML da NFS-e e DANFSe em PDF.
GET, POST, PATCH, DELETE /webhook_endpoints Webhooks. Veja Webhooks.
GET /reference/... Municípios, códigos de serviço, NBS, CEP e CNPJ.

Emissão

  1. POST /taxpayers/:id/invoice_previews valida e estima os tributos.
  2. POST /taxpayers/:id/invoices com o mesmo corpo e o cabeçalho Idempotency-Key responde 202 Accepted com a nota em queued.
  3. O resultado chega por webhook (invoice.authorized ou invoice.rejected), ou consulte GET /invoices/:id.

Cancelamento

  1. POST /invoices/:id/cancellation com { "cancellation": { "reason_code": "1", "reason_text": "Serviço cobrado em dobro" } }. Motivos: 1 erro na emissão, 2 serviço não prestado, 9 outros. A descrição tem de 15 a 255 caracteres.
  2. A resposta é 202 Accepted com o evento em queued. Não há como desfazer.
  3. A Sefin Nacional registra o evento: a nota passa a cancelled e o webhook invoice.cancelled é enviado. Se a Sefin recusar (por exemplo, prazo vencido), o evento fica rejected, a nota continua authorized e o webhook é invoice_event.rejected.
  4. Um segundo pedido responde 409 com invoice_event_pending. Depois de um cancelamento recusado, pode pedir de novo.

Substituição

  1. POST /invoices/:id/substitution com o cabeçalho Idempotency-Key e { "invoice": { "service_value": "1450.00" }, "substitution": { "reason_code": "99", "reason_text": "Valor do serviço errado" } }. Os campos que você não mandar em invoice são copiados da nota original; a série pode mudar. Motivos: 01 desenquadramento do Simples Nacional, 02 enquadramento no Simples Nacional, 03 inclusão retroativa de imunidade ou isenção, 04 exclusão retroativa de imunidade ou isenção, 05 rejeição pelo tomador ou intermediário, 99 outros. A descrição é opcional, de 15 a 255 caracteres.
  2. A resposta é 202 Accepted com a nova nota em queued. Acompanhe como uma emissão.
  3. Quando a Sefin Nacional autoriza a nova nota, a original passa a substituted, ganha o evento 105102 (cancelamento por substituição) e o webhook invoice.substituted é enviado. Se a nova nota for rejeitada, a original continua authorized.
  4. Enquanto a nova nota está na fila ou em transmissão, outro pedido de substituição ou de cancelamento da original responde 409 com invoice_event_pending.

Idempotência

Toda requisição POST que cria um registro fiscal exige o cabeçalho Idempotency-Key (por exemplo, um UUID). Repetir a chave devolve a primeira resposta, sem emitir de novo. A mesma chave com outro corpo responde 409 com idempotency_key_reused.

Paginação

Listas são paginadas: 25 itens por página, com o parâmetro page. A resposta traz os cabeçalhos Link (rel="next", rel="prev") e Total-Count.

Erros

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "title": "Verifique os campos destacados.",
  "status": 422,
  "code": "validation_failed",
  "errors": [{ "field": "serviceValue", "code": "greater_than", "message": "deve ser maior que 0" }]
}