cronota docs

Documentação da API do Cronota

Cronota emite NFS-e pelo Emissor Nacional (Sefin Nacional) na data certa: agende, emita e acompanhe as notas fiscais de serviço sem abrir o portal. Este arquivo reúne os conceitos, a API REST v1, os webhooks e os planos.

Site: https://cronota.clowk.in Console: https://cronota.clowk.in/c API: https://cronota.clowk.in/api/v1 Documentação em HTML: https://cronota.clowk.in/docs

Integrar em 3 passos

O caminho para o seu sistema emitir NFS-e pelo Cronota:

  1. Prepare a empresa no console. Crie a conta em https://cronota.clowk.in, envie o certificado A1 (.pfx) e confira o município. Para testar sem valor fiscal, use o ambiente Sandbox.
  2. Crie uma chave de API em Desenvolvedor → API keys. sk_test_... emite em Sandbox e sk_live_... emite em Live. A API e os webhooks estão no plano Pro e no trial de 14 dias.
  3. Emita e acompanhe. Envie POST /api/v1/invoices com a chave e um Idempotency-Key. A resposta é 202 com a nota em queued. Para saber quando ela for autorizada, cadastre um webhook em Desenvolvedor → Webhooks e trate o evento invoice.authorized, ou consulte GET /api/v1/invoices/:id.
curl https://cronota.clowk.in/api/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: pedido-1234" \
  -H "Content-Type: application/json" \
  -d '{"customer": {"document": "12345678000195", "name": "Acme Ltda", "email": "[email protected]"}, "amount": "1188.00", "description": "Licença do sistema", "service_code_national": "010501"}'

Os detalhes de cada passo estão em API REST v1 e Webhooks.

Conceitos

Conta e empresas

Live e Sandbox

Cada empresa tem dois ambientes, separados em tudo o que emite:

Notas, agendamentos, API keys e webhooks pertencem a um ambiente. Tomadores, modelos e certificados são compartilhados entre os dois.

Certificado A1

O arquivo .pfx da empresa e a sua senha. O Cronota guarda os dois criptografados, nunca deixa baixar o certificado e só o usa para assinar a DPS de cada nota. Sem certificado ativo, nenhuma nota é emitida.

Tomadores, modelos e agendamentos

O caminho de uma nota

  1. A nota é criada (no console, por um agendamento ou pela API) e entra na fila.
  2. O Cronota monta a DPS, assina com o A1 e envia ao Sefin.
  3. O Sefin autoriza (devolve o número da NFS-e e a chave de acesso) ou rejeita (devolve os códigos de erro).
  4. Autorizada, a nota tem o XML guardado; o PDF (DANFSe) é gerado logo depois.
  5. O tomador recebe o PDF e o XML por email.

Também é possível importar o XML de notas antigas e buscar no ADN as notas emitidas fora do Cronota. Notas importadas não são reenviadas ao Sefin.

Status da nota

status quer dizer
draft rascunho no console, ainda não enviado
pending_approval espera a aprovação de alguém antes de emitir
blocked_plan espera o Pro: o plano Grátis já usou a nota em Live do mês
queued na fila para o Sefin
sending sendo enviada ao Sefin
unknown a resposta do Sefin não chegou; o Cronota confere se foi autorizada, sem reenviar
authorized autorizada pelo Sefin (final)
rejected rejeitada pelo Sefin, com os erros em errors (final)
cancelled cancelada no Sefin (final)
imported trazida por XML ou pelo ADN (final)
discarded rascunho descartado (final)

API REST v1

Base: https://cronota.clowk.in/api/v1. JSON em UTF-8. A API existe no plano Pro e no trial; no plano Grátis toda chamada responde 402, menos a consulta de CNPJ. A referência completa, com cada campo e exemplo, está em https://cronota.clowk.in/docs/api e em OpenAPI 3.1 em https://cronota.clowk.in/docs/openapi.yml.

Autenticação

Crie a chave no console, em Desenvolvedor → API keys. Ela aparece uma vez só.

Authorization: Bearer sk_live_...

Idempotência

Todo POST precisa do header Idempotency-Key. A mesma chave devolve a mesma nota, sem criar outra: use o id do pedido ou da fatura do seu sistema.

Idempotency-Key: pedido-1234

Sem o header, a resposta é 400 idempotency_key_required.

Erros

Todo erro tem o mesmo formato:

{"error": {"code": "invalid_invoice", "message": "envie o certificado A1 antes de emitir"}}
HTTP code quando
400 idempotency_key_required POST sem Idempotency-Key
400 parameter_missing falta um parâmetro obrigatório
401 invalid_api_key chave ausente, errada, revogada ou vencida
402 plan_limit o plano Grátis não inclui a API; traz "limit": "api_keys"
404 not_found o recurso não existe nesta empresa e ambiente
404 file_not_ready o XML ou o PDF ainda não está pronto
422 invalid_invoice a nota não passou nas validações
422 invalid_customer / document_required tomador inválido ou sem documento
422 reason_short o motivo do cancelamento tem menos de 15 caracteres
422 cancel_refused o Sefin recusou o cancelamento; traz sefin_code

O objeto invoice

O mesmo formato na API e nos webhooks.

{
  "id": "8f1c2b9e-3d4a-4f6b-9c1d-2e7a5b0c9d11",
  "object": "invoice",
  "livemode": true,
  "status": "authorized",
  "amount": "1188.00",
  "competence": "2026-11",
  "description": "Licença do sistema - novembro de 2026",
  "customer_id": "3a9e7c21-5b4d-4e8f-a1c2-d3e4f5a6b7c8",
  "template_id": null,
  "nfse_number": "1234",
  "access_key": "41069022233049445000115000000000001234260000000000",
  "dps": {"series": "00001", "number": 42},
  "pdf_ready": true,
  "errors": [],
  "issued_at": "2026-11-05T08:00:00-03:00",
  "cancelled_at": null,
  "replaces_invoice_id": null,
  "substituted_at": null,
  "public_url": "https://cronota.clowk.in/n/eyJfcmFpbHMiOnsi...",
  "public_url_expires_at": "2026-11-20T15:00:00Z",
  "created_at": "2026-11-05T08:00:00-03:00"
}

Criar uma nota

POST /api/v1/invoices responde 202 com a nota em queued. A emissão é assíncrona: acompanhe pelo GET ou pelos webhooks.

campo obrigatório
customer_id ou customer sim customer é {document, name, email}: o tomador é achado pelo CNPJ/CPF ou criado
amount sim "1188.00"
description sim aceita as variáveis de Tomadores, modelos e agendamentos
competence não AAAA-MM; o padrão é o mês atual
invoice_template_id não usa o serviço e os impostos do modelo
service_code_national sem modelo, sim o código do serviço na lista nacional, 6 dígitos
nbs_code não o código NBS
curl https://cronota.clowk.in/api/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: pedido-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {"document": "12345678000195", "name": "Acme Ltda", "email": "[email protected]"},
    "amount": "1188.00",
    "competence": "2026-11",
    "description": "Licença do sistema - {mes_extenso} de {ano}",
    "service_code_national": "010501"
  }'

A empresa precisa ter o certificado A1 ativo e o município preenchido; sem eles, a resposta é 422 invalid_invoice com o motivo.

Emitir a partir de um modelo

O atalho mais comum: o modelo já tem o serviço, o valor e a descrição.

curl -X POST https://cronota.clowk.in/api/v1/templates/TEMPLATE_ID/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: fatura-2026-11" \
  -H "Content-Type: application/json" \
  -d '{"competence": "2026-11"}'

Listar e ler notas

Cancelar uma nota

POST /api/v1/invoices/:id/cancel cancela no Sefin e responde a nota em cancelled.

campo obrigatório
reason sim o motivo, com pelo menos 15 caracteres
reason_code não 1 erro na emissão, 2 serviço não prestado, 9 outros (padrão)

Substituir uma nota

Mande uma nota nova em POST /api/v1/invoices com o objeto replaces. Quando o Sefin autoriza a nova, ele cancela a antiga sozinho (Cancelamento por Substituição): a antiga fica em substituted e o webhook invoice.substituted é enviado. Vale em qualquer plano e não conta no limite de notas.

campo obrigatório
replaces.invoice_id sim o id da nota autorizada a substituir
replaces.reason_code sim 01 desenquadramento do Simples, 02 enquadramento no Simples, 03 inclusão de imunidade/isenção, 04 exclusão de imunidade/isenção, 05 rejeição pelo tomador, 99 outros
replaces.reason sim o motivo, de 15 a 255 caracteres

Aprovar e descartar

Tomadores

Consultar um CNPJ

GET /api/v1/companies/:cnpj responde os dados públicos da empresa na Receita Federal, para conferir o tomador antes de cadastrar ou de emitir. Vale em todos os planos.

{
  "object": "company",
  "document": "12345678000195",
  "name": "ACME LTDA",
  "trade_name": "Acme",
  "status": "ATIVA",
  "main_activity": {"code": "6201501", "description": "Desenvolvimento de programas de computador sob encomenda"},
  "email": "[email protected]",
  "phone": "1133334444",
  "simples": true,
  "mei": false,
  "address": {"zipcode": "01310100", "street": "AVENIDA PAULISTA", "number": "1000", "neighborhood": "BELA VISTA", "municipality_code": "3550308", "city": "SAO PAULO", "state": "SP"},
  "fetched_at": "2026-11-14T12:00:00-03:00"
}

Modelos

Agendamentos

No modo da chave. O modelo precisa ter tomador e valor fixos.

Filtros, ordem e páginas

Toda lista aceita q[campo_predicado]=valor (Ransack): eq, not_eq, in, gt, gteq, lt, lteq, cont, start, end, present, null. Em notas, os campos são status, source, nfse_number, access_key, amount_cents, competence, issued_at, cancelled_at, substituted_at, created_at, updated_at, customer_id, invoice_template_id, schedule_id, replaces_invoice_id e customer_document, customer_name, customer_email. sort=campo ou sort=-campo; page e limit (1 a 100); a resposta traz page, limit, total e has_more. Filtro ou ordem não aceitos respondem 400 invalid_filter.

GET /api/v1/invoices?q[status_in][]=authorized&q[issued_at_gteq]=2026-11-01&sort=-issued_at&limit=20

Erros de validação

Um 422 traz error.fields, com as mensagens de cada campo nos nomes que a API recebe (como address.street ou day_of_month).

Webhooks

O Cronota avisa o seu sistema quando uma nota muda. Crie o endpoint no console, em Desenvolvedor → Webhooks: a URL precisa ser https://, e cada endpoint escolhe os eventos e pode mandar até 10 headers próprios (por exemplo, a autenticação do seu lado). Um endpoint é de um ambiente, Live ou Sandbox. Webhooks existem no plano Pro e no trial.

Eventos

evento quando
invoice.authorized o Sefin autorizou a nota; traz o número da NFS-e e a chave de acesso
invoice.rejected o Sefin rejeitou a DPS; traz os códigos e as mensagens de erro
invoice.cancelled a nota foi cancelada no Sefin
invoice.substituted a nota foi substituída por outra; o Sefin a cancelou por substituição
invoice.pdf_ready o PDF (DANFSe) ficou pronto para baixar

A entrega

POST na URL do endpoint, com Content-Type: application/json e estes headers:

{
  "id": "1b6e0c4a-7f2d-4c1e-9a3b-5d8f0e2c4a61",
  "type": "invoice.authorized",
  "created_at": "2026-11-05T11:00:03Z",
  "livemode": true,
  "data": {"invoice": {"id": "8f1c2b9e-...", "object": "invoice", "status": "authorized", "...": "..."}}
}

data.invoice é o mesmo objeto invoice da API.

Responda qualquer 2xx em até 10 segundos. Outra resposta, ou nenhuma, faz o Cronota tentar de novo, com espera crescente, até 8 vezes. A resposta do seu servidor aparece no console, em cada entrega. O botão "Enviar teste" do console manda um invoice.authorized de exemplo com "test": true.

Verificar a assinatura

v1 é o HMAC-SHA256, em hexadecimal, de "<t>.<corpo cru>", com o segredo do endpoint (whsec_..., no console; dá para gerar um novo). Use o corpo cru, antes de qualquer parse, e recuse eventos com t antigo (por exemplo, mais de 5 minutos).

t, v1 = request.headers["X-Cronota-Signature"].split(",").map { |part| part.split("=", 2).last }
expected = OpenSSL::HMAC.hexdigest("SHA256", ENV["CRONOTA_WEBHOOK_SECRET"], "#{t}.#{request.raw_post}")

head :unauthorized unless ActiveSupport::SecurityUtils.secure_compare(expected, v1) && Time.at(t.to_i) > 5.minutes.ago
import crypto from "node:crypto"

const [t, v1] = req.headers["x-cronota-signature"].split(",").map((part) => part.split("=")[1])
const expected = crypto.createHmac("sha256", process.env.CRONOTA_WEBHOOK_SECRET).update(`${t}.${rawBody}`).digest("hex")
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Date.now() / 1000 - Number(t) < 300

Planos e limites

Grátis (para sempre) Pro
Preço R$ 0 R$ 9,90 por mês + R$ 1,00 por nota autorizada em Live
Sandbox sem limite sem limite
Notas em Live 1 por mês sem limite
Empresas 1 sem limite
Certificados A1 ativos 1 (trocar é permitido) sem limite
Agendamentos ativos em Live 1 sem limite
Membros convidados não sem limite
API e webhooks não sim
Importar XML, sync com o ADN, relatórios, PDF e XML sim sim

Perguntas frequentes