# Cronota: documentação completa > 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`. ```bash 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": "financeiro@acme.com.br"}, "amount": "1188.00", "description": "Licença do sistema", "service_code_national": "010501"}' ``` Os detalhes de cada passo estão em [API REST v1](#api-rest-v1) e [Webhooks](#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 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_... ``` - `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: ```json {"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. ```json { "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`. - `errors` traz `code`, `message` e `sefin_code` de 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](#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 | ```bash 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": "financeiro@acme.com.br"}, "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/templates` lista os modelos: `{id, object, name, service_code_national, amount, customer_id}`. - `POST /api/v1/templates/:id/invoices` cria a nota e responde `202`. 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) e `description` (senão, a do modelo). ```bash 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/invoices` responde `{"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/:id` responde a nota. - `GET /api/v1/invoices/:id/xml` e `GET /api/v1/invoices/:id/pdf` entregam o arquivo (por um redirect com link válido por 5 minutos), ou respondem `404 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 nota `pending_approval` ou `blocked_plan` vai para a fila (`202`). - `POST /api/v1/invoices/:id/discard`: uma nota `rejected` vira `discarded`. ### Tomadores - `GET /api/v1/customers` (`q` busca nome, e-mail e documento), `GET /api/v1/customers/:id`. - `POST /api/v1/customers` com `{document, name, email, phone, address}` acha o tomador pelo CNPJ ou CPF, ou cria (`201` novo, `200` existente). Pode repetir. - `PATCH /api/v1/customers/:id` muda só os campos enviados; `DELETE` remove um tomador sem notas (`409` se 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. ```json { "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": "financeiro@acme.com.br", "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: confira `ATIVA` antes 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_limited` com o header `Retry-After` (segundos). Toda resposta traz `X-RateLimit-Limit` e `X-RateLimit-Remaining`. - A resposta vem de um cache: 7 dias para uma empresa, 1 hora para um CNPJ inexistente. `fetched_at` diz quando o dado foi lido na fonte. - `POST /api/v1/customers` com só `{"document": ""}` 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/templates` com `{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`; `DELETE` remove um modelo sem agendamentos (`409` se 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/schedules` com `{template_id, frequency}` e `day_of_month` (`monthly`), `weekday` (`weekly`) ou `cron` (`custom`); opcionais `weekend_rule`, `competence_rule`, `mode` (`auto`/`approve`), `starts_on`, `ends_on`. Responde com `next_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), `/unskip` e `/run` (emite agora; `409` se 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=,v1=`. - `User-Agent: Cronota-Webhooks/1.0`. ```json { "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 `"."`, 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). ```ruby 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 ``` ```javascript 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_plan` e 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.