# RoboFiscal

> API REST brasileira para emitir NFS-e (Nota Fiscal de Serviço eletrônica) pelo padrão
> Nacional da SEFIN, consultar notas recebidas contra o CNPJ (DistDFe), gerenciar
> clientes/tomadores e acompanhar o certificado digital A1. Multi-CNPJ: cada empresa tem
> sua própria chave de API. Autenticação por Bearer token. Respostas em JSON. O produto
> além da API: painel web, emissão recorrente agendada, integrações Hotmart/Eduzz (beta)
> e entrega ao contador por e-mail.

## Fora do escopo (não invente estas capacidades)

O RoboFiscal cuida da NOTA FISCAL DE SERVIÇO. Não faz, e não há endpoint para:

- **Guia do DAS do Simples Nacional.** Não é emitida nem consultada para o cliente — ela
  costuma vir do contador, junto da apuração do mês. Existe código de DAS no sistema, mas é
  ferramenta interna de operador — não faz parte do produto.
- **Apuração ou entrega de declarações** (DASN-SIMEI, DEFIS, EFD). Nenhuma.
- **Integração com sistema de escritório contábil.** A entrega ao contador é por E-MAIL,
  para o endereço cadastrado em `email_contador`: cópia de cada nota e/ou o pacote da
  competência. Não há conector para plataforma contábil.
- **Outros modelos de documento fiscal.** Só NFS-e (modelo nacional SEFIN). Não emite NF-e
  modelo 55, NFC-e, CT-e nem MDF-e.
- **Emissão em municípios que não aderiram ao padrão Nacional** — hoje cerca de metade dos
  5.571 municípios. Situação por cidade: `https://robofiscal.com.br/cidades/cidades.json`.
- **Cálculo do DAS ou do imposto devido.** O `pTotTribSN` na nota é a alíquota efetiva
  aproximada da faixa do Simples (Lei 12.741/2012), informativa — não é apuração.

## Como integrar (o essencial)

- Base de produção: `https://app.robofiscal.com.br/api/v1` (PLANEJADA — ainda não no ar)
- Base em uso hoje: `https://robofiscal.com.br/app/api/v1`
- Autenticação: header `Authorization: Bearer {api_key}`. A chave é por CNPJ e é gerada
  no painel (Empresas → editar → aba API). Ela identifica a empresa emitente: não se
  envia CNPJ nas requisições.
- Erros usam sempre o envelope `{"erro": "mensagem"}`.
- Status: 200 ok · 201 criado · 401 chave inválida · 404 inexistente OU de outra empresa
  · 409 conflito · 422 dado inválido · 429 excesso de tentativas de auth · 500 interno.

## Regras que um agente PRECISA respeitar ao gerar código

- **Emitir nota é irreversível.** `POST /notas` gera documento fiscal real quando a
  empresa está em ambiente `producao`. Nunca gerar código que emita em laço, em retry
  automático cego, ou em teste sem o usuário saber.
- **Sempre enviar `referencia_externa`** no `POST /notas`. É a chave de idempotência: se
  já houver nota da empresa com aquela referência, a API devolve a existente com
  `"idempotente": true` em vez de emitir outra. Sem ela, um retry duplica a nota.
- **Nunca colocar a api_key em código de front-end.** Ela permite emitir documento fiscal
  em nome do CNPJ. Chamadas devem partir do servidor; ler a chave de variável de ambiente.
- **404 é esperado** para recurso de outra empresa — não tratar como bug nem tentar
  contornar; é isolamento multi-tenant por desenho.
- **Certificado A1 sobe pela API**: `POST /api/v1/certificado` em `multipart/form-data`
  com `arquivo` (.pfx/.p12) e `senha`. O onboarding é programático de ponta a ponta.
- **Idempotência**: `POST /notas` já é idempotente por `referenciaExterna`. As demais
  rotas que mudam estado (`/notas/{id}/cancelar`, `/notas/{id}/email`,
  `/recebidas/sincronizar`, `/certificado`, `/chaves/rotacionar`) aceitam o header
  `Idempotency-Key`: mesmo header + mesmo corpo devolve a resposta gravada com
  `Idempotent-Replay: true` sem reexecutar; corpo diferente devolve 409. Use isso em
  todo retry automático.
- **Sandbox para testar sem certificado**: empresa com `ambiente = sandbox` emite de
  mentira — a DPS é montada e gravada, mas NÃO vai à SEFIN. A chave devolvida começa
  com `SANDBOX` (não tem 50 dígitos, de propósito) e a resposta traz `sandbox: true`.
  Use para exercitar emitir/consultar/PDF/webhook antes de ter um A1. Nada emitido em
  sandbox tem valor fiscal — nunca entregue essas notas a um cliente.
- **Ambiente da API ≠ ambiente fiscal.** A URL define onde a API roda; quem decide se a
  nota é real é o campo `ambiente` da empresa (`producao` | `producao_restrita`).

## Endpoints

- **Webhooks (outbound)**: `POST /api/v1/webhooks` cadastra a URL (https, não pode ser
  interna) e devolve o `segredo` UMA vez. Eventos com produtor real hoje:
  `nota.autorizada`, `nota.rejeitada`, `nota.cancelada`, `recebida.nova`,
  `certificado.vencendo`, `plano.limite_atingido`, `evento.oficio` — não construa integração para
  evento que não está nessa lista. Cada entrega traz `X-Robofiscal-Timestamp` e
  `X-Robofiscal-Signature: sha256=<hex>`; valide com
  `hmac_sha256(timestamp + "." + corpoBruto, segredo)` em comparação de tempo
  constante e rejeite timestamp antigo. Responda 2xx; falha é retentada em 5min,
  30min, 1h, 3h e 24h e depois vai para `dead_letter`, de onde só sai por
  `POST /api/v1/webhooks/entregas/{id}/replay`. Histórico em
  `GET /api/v1/webhooks/entregas`.
- **Provisionar CNPJ**: `POST /api/v1/empresas` cadastra um CNPJ novo na MESMA conta
  (vinculado ao dono da chave que chamou) e devolve a `apiKey` dele UMA vez. A empresa
  nasce em `producao_restrita` DE PROPÓSITO — só emite documento fiscal real depois de
  alguém enviar o certificado A1 e mudar o ambiente no painel. CNPJ repetido devolve 409
  com o id da empresa existente. `GET /api/v1/empresas` lista os CNPJs da conta e nunca
  devolve `apiKey`.
- `GET /api/v1/dashboard`: totais consolidados da empresa.
- `GET /api/v1/uso`: quanto da cota mensal deste CNPJ já foi consumida. Conta notas
  `autorizada` E `cancelada` (as duas consumiram numeração); a janela é o mês CIVIL
  (vira dia 1º), não 30 dias corridos. Os mesmos números vêm nos headers
  `X-Quota-Limit`/`X-Quota-Remaining`/`X-Quota-Reset`, que acompanham toda emissão
  bem-sucedida — consulte antes de disparar um lote em vez de descobrir no 422.
- `GET /api/v1/notas`: lista notas emitidas (mais recentes primeiro). Filtros:
  `status`, `chaveAcesso`, `referenciaExterna`, `clienteId`, `competencia` (AAAA-MM),
  `emitidaDe`/`emitidaAte` (AAAA-MM-DD, inclusive o dia inteiro), `limit`/`offset`.
  Formato de data inválido devolve **422**, não lista vazia. O header
  `X-Total-Count` traz o total ANTES da paginação. Para achar uma nota específica
  use `referenciaExterna` — não pagine procurando.
- `POST /api/v1/notas`: emite NFS-e. Corpo: `cliente_id` (int, obrigatório),
  `valor_servico` (decimal, obrigatório), `discriminacao` (texto, obrigatório),
  `codigo_servico` (texto, opcional — usa o padrão da empresa), `aliquota_iss` (decimal,
  opcional), `referencia_externa` (texto, opcional mas RECOMENDADO — idempotência).
  Resposta 201: `{sucesso, nota_id, numero_nfse, chave_acesso, status}`.
- `GET /api/v1/notas/{id}`: consulta uma nota.
- `GET /api/v1/notas/{id}/eventos`: linha do tempo da nota com os eventos do fisco,
  inclusive os de OFÍCIO (`e305101` cancelamento, `e305102` bloqueio, `e305103`
  desbloqueio — o município agindo sozinho). Campo `de_oficio: true` é o que
  interessa monitorar; para saber na hora, assine o webhook `evento.oficio`.
  Bloqueio/desbloqueio NÃO alteram o `status` da nota — aparecem só aqui.
- **Substituir uma nota**: emita uma nota NOVA em `POST /notas` informando
  `notaSubstituidaId` (id de uma nota sua já autorizada) ou `chaveSubstituida`,
  mais `motivoSubstituicao` (01 desenquadramento do SN · 02 enquadramento no SN ·
  03 inclusão retroativa de imunidade/isenção · 04 exclusão retroativa ·
  05 rejeição pelo tomador/intermediário · 99 outros, que exige
  `justificativaSubstituicao`). NÃO cancele a nota antiga: o Cancelamento por
  Substituição é registrado pela SEFIN automaticamente e chega na linha do tempo.
- `POST /api/v1/notas/{id}/cancelar`: cancela (sujeito a prazo/regra da SEFIN; 422 se
  fora do prazo).
- `GET /api/v1/notas/{id}/pdf`: baixa a DANFSE em PDF (`application/pdf`).
- `GET /api/v1/notas/{id}/xml`: baixa o XML autorizado (é o documento fiscal que vale).
- `POST /api/v1/notas/{id}/email`: reenvia XML+PDF ao e-mail do tomador.
- **Fechar o mês (pacote do contador)**: `POST /api/v1/competencias/{AAAA-MM}/fechar`
  monta um ZIP com os XMLs das notas emitidas e recebidas da competência, um CSV de
  resumo (valores, ISS, situação) e um LEIA-ME; baixe em
  `GET /api/v1/competencias/{AAAA-MM}/pacote`. Notas CANCELADAS entram de propósito —
  consumiram numeração e precisam aparecer na escrituração. Refechar substitui o
  pacote anterior. Para mandar direto ao contador:
  `POST /api/v1/competencias/{AAAA-MM}/enviar-contador` (usa o `email_contador` da
  empresa e gera o pacote se ainda não existir).
- `GET /api/v1/clientes`: lista tomadores.
- `POST /api/v1/clientes`: cadastra tomador (409 se o documento já existir na empresa).
- `GET /api/v1/clientes/{id}`, `PUT /api/v1/clientes/{id}`, `DELETE /api/v1/clientes/{id}`.
- `GET /api/v1/recebidas`: notas emitidas CONTRA o seu CNPJ (capturadas via DistDFe).
- `GET /api/v1/recebidas/{id}`, `GET /api/v1/recebidas/{id}/pdf`.
- `POST /api/v1/recebidas/sincronizar`: busca documentos novos agora (também roda por
  cron diariamente).
- `GET /api/v1/certificado`: situação do certificado A1 (titular, validade). Certificado
  vencido impede emissão.
- `GET /api/v1/servicos/{codigo}/nbs` e `PUT /api/v1/servicos/{codigo}/nbs`: correlação
  item LC 116 ↔ código NBS (Reforma Tributária). Os grupos IBS/CBS **estão ligados**
  (`RTC_HABILITADO=1`): a DPS sai com `cNBS` e o grupo `IBSCBS` no leiaute 1.01.
  Ressalva honesta: a tabela oficial de CST ainda não foi carregada, então
  classificação fora da família `0000*` (tributação integral) é emitida como CST
  `000` com aviso em log. Enquanto isso, confira o CST da sua operação.

## Limites

- Limite de notas por mês por CNPJ, conforme o plano (grátis 25 · Pro 250 · Max 2.000).
  Ao atingir, `POST /notas` é recusado ANTES de consumir numeração fiscal.
- Rate limit de autenticação: 20 falhas em 10 minutos por IP → 429 com `Retry-After`.
  Não é limite de uso da API; some ao autenticar com sucesso.
- Throughput: 120 requisições por minuto POR CHAVE → 429 com `Retry-After`. Toda
  resposta traz `X-RateLimit-Limit`/`X-RateLimit-Remaining`/`X-RateLimit-Reset`
  (epoch). Não confundir com a cota mensal de notas, que usa `X-Quota-*`: são
  limites diferentes, um de requisições e outro de documento fiscal.
- CORS: só origens declaradas na configuração. Chamada servidor-a-servidor (sem header
  `Origin`) é sempre aceita.

## Docs

- [Referência da API](https://robofiscal.com.br/app/docs/api-reference.md): documentação
  completa com exemplos em cURL, PHP, Python e Node.js.
- [Swagger interativo](https://robofiscal.com.br/app/api/docs): testar chamadas com sua chave.
- [Especificação OpenAPI](https://robofiscal.com.br/app/api/v1/openapi.yaml): contrato cru.

## Optional

- [Guia de notas recebidas](https://robofiscal.com.br/app/docs/GUIA_NOTAS_RECEBIDAS.md):
  como funciona a captura de NF-e/NFS-e contra o CNPJ, do zero.
- [Correlação CNAE ↔ LC 116](https://robofiscal.com.br/app/docs/CNAE_LC116_CORRELACAO.md):
  como o código de serviço é derivado da atividade da empresa.

## Cobertura por cidade

- [Cidades atendidas](https://robofiscal.com.br/cidades/): quais dos 5.571 municípios brasileiros emitem NFS-e pelo padrão Nacional, verificado diariamente. Uma página por cidade (/cidades/{cidade}-{uf}.html) e por estado (/cidades/uf/{uf}.html).
- [Dataset JSON](https://robofiscal.com.br/cidades/cidades.json): a lista completa em JSON (nome, UF, código IBGE, status de adesão), atualizada diariamente — livre para consulta.

## Planos e preços

Preço por CNPJ e por mês civil: Grátis 25 notas · Pro R$ 79/250 notas · Max R$ 179/2.000
notas; plano anual com 20% de desconto. Todos os planos incluem emissão, agendamento,
recebidas, envio ao contador, API e webhooks. Upgrade imediato ao atingir o limite.

## Integrações de plataforma (beta)

Hotmart e Eduzz: o webhook de venda aprovada da plataforma aponta para uma URL com chave
secreta própria; a venda é registrada e vira NFS-e (emissão automática OPCIONAL, desligada
por padrão; ligar exige o token de segurança da plataforma). Reenvio de evento não duplica
nota. Status: em validação — trate como beta. Kiwify foi removida em 2026-08 (origem do
webhook não verificável). Não invente suporte a outras plataformas.

## Entrega ao contador

Por e-mail, para o endereço em email_contador: cópia de cada nota autorizada (XML+PDF),
pacote da competência (ZIP com XMLs de emitidas e recebidas + resumo CSV) e resumo diário
opcional. Não há conector para sistema de escritório contábil.

## Prazos legais que afetam quem presta serviço (verificado 23/08/2026)

- MEI: NFS-e de padrão nacional obrigatória desde 01/09/2023, inclusive em município
  que não aderiu. Nota obrigatória para cliente PJ; para pessoa física é opcional HOJE.
- ME/EPP do Simples Nacional: Emissor Nacional obrigatório a partir de 01/11/2026
  (Resolução CGSN 191/2026). A data 01/09/2026 que ainda circula foi REVOGADA.
- 01/01/2027: nota do MEI passa a ser exigida também para pessoa física; Simples passa
  a preencher IBS/CBS na nota.
- 2029-2032: alíquotas de ISS reduzidas em 10%, 20%, 30% e 40%. Em 01/01/2033 o ISS é
  extinto (LC 214/2025, art. 543, IV).
- Limites 2026: MEI R$ 81.000/ano (R$ 251.600 transportador de cargas); ME até
  R$ 360.000; EPP até R$ 4.800.000. Nenhum aumento do teto do MEI foi aprovado.
- No Simples o ISS é pago no DAS: sem retenção, a nota não leva alíquota de ISS — e isso
  está correto. Com retenção, informar a alíquota efetiva é obrigatório; não informar
  faz o tomador reter 5%.
Detalhe e base legal: https://robofiscal.com.br/nota-fiscal-mei-simples-nacional.html

## Guias públicos (conteúdo citável)

- Emissor Nacional de NFS-e — emissão, recorrência e API no padrão nacional: https://robofiscal.com.br/emissor-nacional-nfs-e.html
- Como emitir NFS-e pelo padrão Nacional: https://robofiscal.com.br/como-emitir-nfs-e.html
- Nota fiscal automática Hotmart/Eduzz: https://robofiscal.com.br/nota-fiscal-hotmart-eduzz.html
- API de NFS-e (emissão, idempotência, webhooks, sandbox): https://robofiscal.com.br/api-nfs-e.html
- Reforma Tributária na NFS-e (leiaute 1.01, IBS/CBS, DANFSe): https://robofiscal.com.br/nfs-e-reforma-tributaria.html
- Notas recebidas contra o CNPJ (DistDFe): https://robofiscal.com.br/notas-recebidas-cnpj.html
- Nota fiscal para MEI e Simples Nacional (obrigações, prazos, ISS no DAS): https://robofiscal.com.br/nota-fiscal-mei-simples-nacional.html
- Soluções sob medida para empresas (emissão em escala + cobrança integrada ao banco): https://robofiscal.com.br/solucoes-sob-medida.html
- Ferramentas da Reforma — cClassTrib, NBS e cIndOp por subitem da LC 116 (200 subitens), de-para ISS → IBS/CBS e calendário da transição, com fonte oficial: https://robofiscal.com.br/ferramentas