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:
- 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.
- Crie uma chave de API em Desenvolvedor → API keys.
sk_test_...emite em Sandbox esk_live_...emite em Live. A API e os webhooks estão no plano Pro e no trial de 14 dias. - Emita e acompanhe. Envie
POST /api/v1/invoicescom a chave e umIdempotency-Key. A resposta é202com a nota emqueued. Para saber quando ela for autorizada, cadastre um webhook em Desenvolvedor → Webhooks e trate o eventoinvoice.authorized, ou consulteGET /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
- Conta: a pessoa que entra pelo login (Clowk). O plano é da conta.
- Empresa: o prestador, com CNPJ, município e o certificado A1. Uma conta pode ter várias empresas e trocar entre elas no console.
- Membros: pessoas convidadas para uma empresa, como dono, admin ou membro.
Live e Sandbox
Cada empresa tem dois ambientes, separados em tudo o que emite:
- Live: notas reais, com valor fiscal, no Sefin Nacional de produção.
- Sandbox: a produção restrita do Sefin. Serve para testar e não tem valor fiscal. Alguns municípios ainda não têm convênio ativo na produção restrita; nesse caso, o Cronota avisa e a primeira nota sai em Live.
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
- Tomador: quem recebe a nota, por CNPJ ou CPF, com o email que recebe o PDF e o XML.
- Modelo: o que se repete numa nota: tomador, serviço (código nacional e
NBS), valor e a descrição. A descrição aceita variáveis trocadas pela
competência:
{mes}(11),{mes_extenso}(novembro) e{ano}(2026); o mês anterior,{mes_anterior}(10) e{mes_anterior_extenso}(outubro); e o mês seguinte,{mes_posterior}(12) e{mes_posterior_extenso}(dezembro). - Agendamento: emite um modelo sozinho, todo mês, toda semana ou em datas fixas. Pode pedir aprovação antes de emitir: um link por email para conferir e aprovar.
O caminho de uma nota
- A nota é criada (no console, por um agendamento ou pela API) e entra na fila.
- O Cronota monta a DPS, assina com o A1 e envia ao Sefin.
- O Sefin autoriza (devolve o número da NFS-e e a chave de acesso) ou rejeita (devolve os códigos de erro).
- Autorizada, a nota tem o XML guardado; o PDF (DANFSe) é gerado logo depois.
- 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_...
sk_live_...emite em Live;sk_test_...emite em Sandbox. A chave decide a empresa e o ambiente: não há parâmetro para trocar.- A chave vale 30, 90, 180 ou 365 dias e pode ser revogada no console. O Cronota guarda só o hash dela.
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"
}
amounté uma string com ponto decimal, em reais.public_urlé o link público da nota para o comprador (PDF e XML, sem login), assinado e válido por 7 dias (public_url_expires_at). Só vem em notas criadas pela API ou por integração, depois da autorização; nas outras énull. Cada resposta traz um link novo.competenceé o mês da prestação,AAAA-MM.errorstrazcode,messageesefin_codede cada erro do Sefin, numa nota rejeitada.
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.
GET /api/v1/templateslista os modelos:{id, object, name, service_code_national, amount, customer_id}.POST /api/v1/templates/:id/invoicescria a nota e responde202. Todos os campos são opcionais:customer(senão, o tomador do modelo),amount(senão, o valor do modelo),competence(senão, o mês atual) edescription(senão, a do modelo).
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
GET /api/v1/invoicesresponde{"object": "list", "data": [...]}, as mais novas primeiro. Filtros:status,competence(AAAA-MM),customer_id,limit(1 a 100, padrão 50).GET /api/v1/invoices/:idresponde a nota.GET /api/v1/invoices/:id/xmleGET /api/v1/invoices/:id/pdfentregam o arquivo (por um redirect com link válido por 5 minutos), ou respondem404 file_not_ready.
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
POST /api/v1/invoices/:id/approve: uma notapending_approvaloublocked_planvai para a fila (202).POST /api/v1/invoices/:id/discard: uma notarejectedviradiscarded.
Tomadores
GET /api/v1/customers(qbusca nome, e-mail e documento),GET /api/v1/customers/:id.POST /api/v1/customerscom{document, name, email, phone, address}acha o tomador pelo CNPJ ou CPF, ou cria (201novo,200existente). Pode repetir.PATCH /api/v1/customers/:idmuda só os campos enviados;DELETEremove um tomador sem notas (409se tiver).
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"
}
- O CNPJ vai com ou sem pontuação, numérico ou alfanumérico.
statusé a situação cadastral: confiraATIVAantes de emitir.- Erros:
400 invalid_cnpj(dígitos não conferem),404 cnpj_not_found(a Receita não tem o CNPJ),503 lookup_unavailable(a fonte não respondeu; tente de novo). - Limite: 60 consultas por minuto por chave. Acima,
429 rate_limitedcom o headerRetry-After(segundos). Toda resposta trazX-RateLimit-LimiteX-RateLimit-Remaining. - A resposta vem de um cache: 7 dias para uma empresa, 1 hora para um CNPJ inexistente.
fetched_atdiz quando o dado foi lido na fonte. POST /api/v1/customerscom só{"document": "<CNPJ>"}cria o tomador já com o nome, o e-mail, o telefone e o endereço da consulta.
Modelos
GET /api/v1/templates,GET /api/v1/templates/:id.POST /api/v1/templatescom{name, service_code_national, description}(obrigatórios) e, se quiser,customer_id,amount,nbs_code,service_municipality_code,complement,iss,ibscbs,federal,tax_totals,intermediary(com os nomes da DPS).PATCH /api/v1/templates/:id;DELETEremove um modelo sem agendamentos (409se tiver).
Agendamentos
No modo da chave. O modelo precisa ter tomador e valor fixos.
GET /api/v1/schedules(active=true|false),GET /api/v1/schedules/:id.POST /api/v1/schedulescom{template_id, frequency}eday_of_month(monthly),weekday(weekly) oucron(custom); opcionaisweekend_rule,competence_rule,mode(auto/approve),starts_on,ends_on. Responde comnext_run_on. Ativo em Live conta no plano (402).PATCH /api/v1/schedules/:id,DELETE /api/v1/schedules/:id.POST /api/v1/schedules/:id/pause,/resume,/skip(pula a próxima),/unskipe/run(emite agora;409se a nota da competência já existe).
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:
X-Cronota-Event-Id: o id do evento, o mesmo em todas as tentativas. Use para não processar duas vezes.X-Cronota-Signature:t=<unix>,v1=<hex>.User-Agent: Cronota-Webhooks/1.0.
{
"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 |
- Trial: toda conta nova tem 14 dias do Pro, sem cartão e sem cobrança. No fim, a conta fica no Grátis sozinha.
- Nada é cobrado sem o usuário clicar em "Assinar o Pro". O botão funciona também durante o trial: ele abre o pagamento de R$ 9,90 do 1º mês, e o Pro pago começa quando o pagamento é confirmado.
- Depois, no dia 1º de cada mês: a mensalidade do mês que começa mais R$ 1,00 por nota autorizada em Live no mês que terminou. A nota conta no mês em que o Sefin a autorizou.
- Voltar ao Grátis termina o Pro na hora, sem devolução do mês já pago. As notas já autorizadas saem na próxima fatura, sem mensalidade.
- Não são cobradas: notas de Sandbox, rejeitadas, canceladas e importadas, e as notas do trial e do Grátis.
- Os limites somam todas as empresas da conta.
- Na volta ao Grátis, nada é apagado: os agendamentos em Live além do primeiro são pausados, as API keys são revogadas e os webhooks param.
- No Grátis, a 2ª nota em Live do mês fica em
blocked_plane não vai ao Sefin. Depois de assinar o Pro, ou no mês seguinte, ela sai pelo botão "Emitir agora", na página da nota.
Perguntas frequentes
- Preciso de certificado digital? Sim, o A1 (.pfx) da empresa.
- Funciona no meu município? Funciona nos municípios que aderiram ao padrão nacional da NFS-e. Se a empresa já emite pelo portal do Emissor Nacional, o Cronota emite também.
- O Sandbox vale como nota? Não, é a produção restrita do Sefin, sem valor fiscal.
- Posso cancelar o Pro? Quando quiser, pela página Plano.