cronotaDocumentação da API
Referência da API · v1.0

API do Cronota

Emita, acompanhe e cancele NFS-e pelo Emissor Nacional a partir do seu sistema. A API é REST, recebe e responde JSON e usa a mesma conta do console: a chave define a empresa e o ambiente (Live ou Sandbox). A emissão é assíncrona: a nota nasce em queued e o resultado chega pelos webhooks ou por um GET.

Server URL

https://cronota.clowk.in/api/v1

Autenticação

Envie a chave no header Authorization: Bearer <chave>. sk_live_… emite notas reais (Live); sk_test_… emite na produção restrita do Sefin, sem valor fiscal (Sandbox). Crie as chaves em Desenvolvedor → API keys. A API faz parte do plano Pro e do teste grátis.

curl "https://cronota.clowk.in/api/v1/invoices" \
  -H "Authorization: Bearer $CRONOTA_API_KEY"

Idempotência

Todo POST exige o header Idempotency-Key: uma string única por operação, como o id do pedido. Repetir a mesma key devolve o primeiro resultado, sem criar outra nota.

Filtros, ordem e páginas

Toda lista aceita filtros em q, no formato q[campo_predicado]=valor, sobre os campos que cada lista diz. Predicados: eq, not_eq, in (vários: q[status_in][]=authorized&q[status_in][]=cancelled), gt, gteq, lt, lteq, cont (contém), start, end, present, null. Datas em AAAA-MM-DD; valores em centavos (amount_cents).

sort=campo ordena do menor para o maior e sort=-campo ao contrário; vários com vírgula. page e limit (1 a 100) paginam, e a resposta traz total e has_more. Um filtro ou uma ordem que a lista não aceita responde 400 invalid_filter: nada é ignorado em silêncio.

curl "https://cronota.clowk.in/api/v1/invoices?q[status_in][]=authorized&q[issued_at_gteq]=2026-11-01&q[customer_document_start]=112223&sort=-issued_at&limit=20" \
  -H "Authorization: Bearer $CRONOTA_API_KEY"

Erros

Todo erro tem o mesmo formato: {"error": {"code": "…", "message": "…"}}. O code é estável, para o seu código decidir; a message é para pessoas.

400idempotency_key_requiredPOST sem o header Idempotency-Key
400parameter_missingfalta um parâmetro obrigatório
400invalid_filterum filtro ou uma ordem que a lista não aceita
401invalid_api_keychave ausente, errada, revogada ou vencida
402plan_limito plano Grátis não inclui a API
404not_foundnão existe nesta empresa e ambiente
404file_not_readyo XML ou o PDF ainda não está pronto
422invalid_invoicea nota não passou nas validações
409customer_has_invoicestomador com notas, modelo com agendamentos, nota que não está no status da ação
422invalid_customernão passou nas validações; error.fields diz o que falta em cada campo
422cancel_refusedo Sefin recusou o cancelamento; traz sefin_code

Recursos

Notas

A NFS-e, do pedido à nota autorizada. Criar, listar, ler, baixar os arquivos e cancelar.

Modelos

O que se repete numa nota (serviço, tributos, descrição, valor). O atalho para emitir.

Tomadores

Quem recebe a nota, achado pelo CNPJ ou CPF.

Agendamentos

Emissões que se repetem (todo mês, toda semana ou por cron), a partir de um modelo com tomador e valor fixos. No modo da chave.

Webhooks

Os eventos que o Cronota envia para o seu sistema quando uma nota muda.