{"openapi":"3.1.0","info":{"title":"GereNota Core API","description":"API do GereNota — emissão e gestão de NFS-e pelo Sistema Nacional (gov.br), multi-empresa.\n\n**Autenticação:** crie uma chave em Painel → Integrações e mande `Authorization: Bearer gnk_live_…`\nem toda chamada. A chave tem escopo `emissao` (lê e emite) ou `leitura` (só lê); o acesso efetivo\né sempre o MENOR entre o escopo da chave e o papel de quem a criou. Precisa de plano com API.\n\n**Teste × valendo:** `POST /companies/{id}/nfse` com `\"ambiente\": \"teste\"` valida tudo no\nSistema Nacional sem efeito fiscal (a nota de teste não aparece nas listagens nem nos totais);\nsem o campo (ou `\"producao\"`), a nota é emitida de verdade.\n\n**Idempotência:** mande `Idempotency-Key` (qualquer texto único seu) na emissão, na substituição e no\ncancelamento — repetir a chamada com a mesma chave devolve a MESMA nota (ou o mesmo cancelamento), nunca\nemite duas; uma chamada simultânea com a mesma chave recebe 409 enquanto a primeira não termina.\n\n**Erros:** todo erro volta `{\"code\", \"message\", \"field?\", \"hint?\", \"erros?\", \"volta_em?\", \"upgrade?\"}` — o\n`code` é estável (programe por ele), a `message` é para pessoas, o `hint` diz como resolver. Nos limites,\n`volta_em` diz quando o limite volta sozinho e `upgrade` (só para o dono da conta) traz o plano que resolve,\ncom o preço e o link para assinar.\n\n**Cotas e limites:** a busca de CNPJ sai do cadastro mensal da Receita (os Dados Abertos do CNPJ) sem cota; a\nconsulta em tempo real — o CPF e o CNPJ que ainda não está no cadastro do mês — tem cota mensal por plano (o CNPJ\nconsultado em tempo real nos últimos 7 dias — o CPF, nas últimas 24 h e pela mesma conta — sai do cache sem gastar);\n429 quando há muitas chamadas por minuto ou o teto do dia acabou (`volta_em` diz quando volta).\n","version":"0.1.0"},"servers":[{"url":"https://api.gerenota.com.br"}],"paths":{"/api/v1/me":{"get":{"tags":["conta"],"summary":"Ver a conta, o papel e o plano da chave","description":"Diz de quem é a chave em uso — conta, usuário e papel efetivo — e como está o plano.\n\nVale como primeira chamada de uma integração nova: confirma que a chave é válida e mostra o\nque ela pode fazer. `role` é `operador` para chave de escopo `emissao` e `leitor` para\nescopo `leitura`; o papel efetivo nunca passa do papel de quem criou a chave. `empresas`\nconta as empresas próprias da conta e `compartilhadas`, as de outras contas a que este\nusuário tem acesso; `empresa_padrao` traz o `company_id` que o painel abre por padrão — bom\npalpite quando a sua integração não recebeu a empresa de outro jeito.\n\nO bloco `plano` traz o consumo do mês (`notas.usadas` × `notas.cota`, `consultas.usadas` ×\n`consultas.cota`) e os tetos de empresas, automações e acessos, com a mesma régua que a API\nusa para barrar; `teto`/`cota` em `null` significa sem limite, e o bloco inteiro pode vir\n`null` sem que haja erro (nesse caso, siga e trate o 402 quando ele vier). Para o dono da conta\n(no painel ou no conector; a chave de API nunca é do dono), o limite já no teto traz `upgrade`,\no plano em que o próximo item cabe, com o preço e o link para assinar, e o recurso que o plano\nnão inclui traz `upgrade_relatorios` ou `upgrade_api_mcp`. `billing.bloqueada`\nem `true` quer dizer renovação vencida: as outras rotas respondem 402 `CONTA_BLOQUEADA` até o\npagamento, e só esta continua respondendo.\n\n`escopo` diz o escopo da própria chave (`emissao` ou `leitura`) antes de qualquer chamada de\nescrita; é nulo na sessão de login do painel.","operationId":"me_api_v1_me_get","responses":{"200":{"description":"Identidade da chave, com plano e sinais de cobrança","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}},"security":[{"ApiKeyBearer":[]}]}},"/api/v1/minhas-empresas":{"get":{"tags":["empresas"],"summary":"Listar as empresas que a chave pode usar","description":"Lista as empresas em que você pode operar: as da própria conta e as que outras contas\ncompartilharam com você, cada uma com o seu papel efetivo. É o ponto de partida de qualquer\nintegração: escolha aqui o `id` e use-o como `company_id` nas demais rotas.\n\nPara uma empresa compartilhada, acrescente `?company_id=<id>` às chamadas: elas rodam na conta\ndona, com o seu papel. `GET /companies` lista só as empresas próprias, com mais detalhes.","operationId":"minhas_empresas_api_v1_minhas_empresas_get","responses":{"200":{"description":"Empresas próprias e compartilhadas, com o papel em cada uma","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/MinhaEmpresaOut","additionalProperties":true,"type":"object"},"type":"array","title":"Response 200 Minhas Empresas Api V1 Minhas Empresas Get"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}},"security":[{"ApiKeyBearer":[]}]}},"/api/v1/companies":{"get":{"tags":["empresas"],"summary":"Listar as empresas da conta","description":"Lista as empresas emissoras da conta, cada uma com cadastro, regime tributário e situação.\n\nÉ por aqui que se descobre o `company_id` das demais rotas: é o campo `id` de cada item, no\nformato `cmp_…`. Só emite nota a empresa com `status` igual a `ativa` — `pendente` ainda não\nvalidou o certificado A1 e `waitlist` está em município que não emite pelo Sistema Nacional. A\nlista já vem recortada pelo acesso de quem criou a chave; empresas de outra conta compartilhadas\ncom este usuário **não** aparecem aqui, mas podem ser usadas nas demais rotas pelo `company_id`\nque o dono informou. Devolve no máximo 200 empresas, sem paginação nem filtro, e basta escopo\n`leitura`.","operationId":"list_companies_api_v1_companies_get","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CompanyOut"},"type":"array","title":"Response List Companies Api V1 Companies Get"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}},"security":[{"ApiKeyBearer":[]}]},"post":{"tags":["empresas"],"summary":"Cadastrar uma empresa emissora","description":"Cadastra uma empresa emissora na conta e devolve a ficha criada, com o `id` (`cmp_…`) que as\noutras rotas pedem como `company_id`.\n\nA empresa nasce com `status` `pendente` e ainda **não emite**: o caminho até a primeira nota é\nenviar o certificado A1 (`POST /companies/{company_id}/certificate`) e validar\n(`POST /companies/{company_id}/validate`). Mande `cnpj` sem pontuação (ela é aceita e normalizada; o CNPJ\npode ter letras nas 12 primeiras posições) e, em `endereco.cMun`, o código IBGE de 7 dígitos do município da\nempresa — confirme\npelo CEP em `GET /consultas/cep/{cep}` em vez de adivinhar, porque o código errado só aparece na\nrejeição da nota. Até 31/10/2026, a ME ou a EPP de município que ainda não emite pelo Sistema\nNacional é aceita com `status` `waitlist`, e o campo `aviso` explica: ela não emite até sair da lista.\nEm 1º/11/2026 ela sai (a partir dessa data, a ME e a EPP emitem pelo Emissor Nacional em qualquer\ncidade). O MEI não entra na lista.\n\nErros: 409 quando o CNPJ já está cadastrado nesta conta ou já chega compartilhado por outra\n(`CNPJ_JA_COMPARTILHADO`), 402 `LIMITE_DO_PLANO` quando o plano não comporta mais uma empresa e\n503 `ADN_INDISPONIVEL` quando o serviço do gov.br que informa a adesão do município não responde.\nCom o `company_id` de uma empresa compartilhada por outra conta, 403 `PERMISSAO_NEGADA`: a empresa\nnova nasce na sua conta, nunca na conta que compartilhou. Exige chave de escopo `emissao`.","operationId":"create_company_api_v1_companies_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyCreate"}}},"required":true},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}},"security":[{"ApiKeyBearer":[]}]}},"/api/v1/companies/{company_id}/status":{"get":{"tags":["empresas"],"summary":"Ver a situação de uma empresa e do certificado","description":"Devolve a ficha operacional de uma empresa: o cadastro (`company`), o certificado A1 mais\nrecente (`certificate`) e o estado da importação automática de notas (`importacao`).\n\nUse antes de emitir para saber se a empresa está de pé: `company.status` precisa ser `ativa` e\n`certificate.status`, `validado` — e olhe `certificate.dias_para_vencer`, que fica negativo\nquando o certificado já venceu (nesse caso a emissão passa a falhar). `certificate` vem `null`\nenquanto nenhum arquivo .pfx foi enviado. O bloco `importacao` é informativo e best-effort: diz\nse a rodada automática está ligada, quando foi a última e quantas notas antigas ainda faltam\nentrar; pode vir com `indisponivel: true` sem que a empresa tenha problema algum.\n\nResponde 404 quando o `company_id` não existe nesta conta e 403 `EMPRESA_FORA_DO_RECORTE` quando\na empresa está fora do acesso da chave. Basta escopo `leitura`.","operationId":"company_status_api_v1_companies__company_id__status_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyStatusOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/certificado/pedidos":{"post":{"tags":["empresas"],"summary":"Pedir o certificado digital a quem é dono","description":"Pede o certificado digital A1 da empresa a quem é dono dela — para a contabilidade e o operador; quem é dono\nlibera direto, pelo painel. O pedido não libera nada: quem é dono recebe o aviso por e-mail e WhatsApp e decide, com\no código que chega no e-mail de quem é dono; se liberar, o link vai para o e-mail do acesso de quem pediu. O pedido\nvence em 7 dias. Com um pedido da mesma pessoa para a mesma empresa ainda aberto, devolve esse pedido, sem aviso\nnovo.","operationId":"pedir_api_v1_companies__company_id__certificado_pedidos_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PedidoIn"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PedidoOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/aliquotas":{"get":{"tags":["aliquotas"],"summary":"Ver o dossiê das alíquotas do Simples da empresa","description":"O dossiê das alíquotas do Simples da empresa: `empresa` (o modo, a autorização e o regime de\napuração do ano, com a fonte), `mes` (a alíquota em vigor, a fonte —\n`pgdas`, `estimada`, `proporcionalizada`, `inicio_atividade` ou `manual` — a conta aberta e a `explicacao`\nem português, com a base legal), `proxima` (a do mês seguinte, quando o PGDAS-D já permite), `conferencia`\n(a última: alíquota declarada × aplicada, receita declarada × notas — com as frases prontas para mostrar\nao cliente em `receita.frase_titulo`, `frase` e `detalhes` —, retificações, notas com retenção\nafetadas por uma correção), `payload_divergencia` (notas que chegaram com alíquota própria), `casos` (os\ncasos relevantes, cada um com gravidade `acao` | `atencao` | `info`, título e texto — o que dizer ao\ncliente), `historico` (mês a mês, mais novo primeiro) e `declaracoes` (as PGDAS-D consultadas; o PDF de\ncada uma em `/pgdas/declaracoes/{pa}/pdf`). Só leitura — nada aqui consulta o Integra Contador. Vale para\nempresa compartilhada em qualquer papel. Qualquer papel com acesso à empresa lê, inclusive o leitor e a chave de API de `leitura`: quem vê as notas já\nvê a receita delas. Confirmar ou editar a alíquota segue com dono, operador e contabilidade.","operationId":"dossie_aliquotas_api_v1_companies__company_id__aliquotas_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DossieAliquotasOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/pgdas/declaracoes":{"get":{"tags":["aliquotas"],"summary":"Listar as declarações PGDAS-D arquivadas","description":"As declarações PGDAS-D arquivadas da empresa — TODAS as versões, da mais nova para a mais antiga (o\nhistórico de entrada traz 13 PAs; cada mês novo entra pelo dia 21; retificadora = versão nova do mesmo\nPA, a anterior fica). Cada item: PA, versão (001 = original), nº da declaração, regime de apuração,\nreceita do PA por competência e por caixa, RBT12 (e RBT12p/RBA/RBAA), efetiva total e ISS declaradas,\nanexo/faixa inferidos, meses retificados apontados pela tabela 2.2, transmissão, se o PDF está\narquivado. O detalhe de cada uma (tabela mensal de receitas, atividades) sai em `…/declaracoes/{pa}`. Qualquer papel com acesso à empresa lê, inclusive o leitor e a chave de API de `leitura`: quem vê as notas já\nvê a receita delas.","operationId":"listar_declaracoes_api_v1_companies__company_id__pgdas_declaracoes_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DeclaracaoPgdasOut"},"title":"Response Listar Declaracoes Api V1 Companies  Company Id  Pgdas Declaracoes Get"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/pgdas/declaracoes/{pa}":{"get":{"tags":["aliquotas"],"summary":"Ver uma declaração PGDAS-D como dado","description":"UMA declaração PGDAS-D como dado (`pa` = `AAAAMM`; `versao` omitida = a mais recente): tudo da\nlista mais `receitas_mensais` (a tabela 2.2 — receita por competência de cada mês desde janeiro do ano\nanterior; é dela que sai a RBT12 de qualquer mês), `atividades` (seção 2.7: receita e débitos por\natividade, o que dá a efetiva), `versoes` (todas as versões do PA) e `pdf` (o caminho do PDF arquivado).\n404 `DECLARACAO_NAO_ENCONTRADA` quando o PA não está no histórico — `POST …/pgdas/sync` com `pa` e\n`forcar=true` consulta esse PA (R$ 0,24). Qualquer papel com acesso à empresa lê, inclusive o leitor e a chave de API de `leitura`: quem vê as notas já\nvê a receita delas.","operationId":"detalhe_da_declaracao_api_v1_companies__company_id__pgdas_declaracoes__pa__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"pa","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{6}$","description":"Período de apuração, `AAAAMM`","title":"Pa"},"description":"Período de apuração, `AAAAMM`"},{"name":"versao","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{3}$"},{"type":"null"}],"description":"Versão (`001`, `002`…); omitida = a mais recente","title":"Versao"},"description":"Versão (`001`, `002`…); omitida = a mais recente"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeclaracaoPgdasDetalheOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/pgdas/declaracoes/{pa}/pdf":{"get":{"tags":["aliquotas"],"summary":"Baixar o PDF arquivado de uma declaração PGDAS-D","description":"O PDF arquivado da declaração PGDAS-D do PA (`AAAAMM`; `versao` omitida = a mais recente), servido\npela própria API (`application/pdf`, `Content-Disposition: inline`) — como o DANFSE, sem link do S3: o\npainel baixa com o token. 404 quando a declaração não foi consultada ou não tem PDF (consultas\nanteriores ao arquivamento). A empresa precisa estar no recorte de quem chama. Qualquer papel com acesso à empresa lê, inclusive o leitor e a chave de API de `leitura`: quem vê as notas já\nvê a receita delas.","operationId":"pdf_da_declaracao_api_v1_companies__company_id__pgdas_declaracoes__pa__pdf_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"pa","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{6}$","description":"Período de apuração, `AAAAMM`","title":"Pa"},"description":"Período de apuração, `AAAAMM`"},{"name":"versao","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{3}$"},{"type":"null"}],"description":"Versão (`001`, `002`…); omitida = a mais recente","title":"Versao"},"description":"Versão (`001`, `002`…); omitida = a mais recente"}],"responses":{"200":{"description":"O PDF da declaração","content":{"application/pdf":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/pgdas/sync":{"post":{"tags":["aliquotas"],"summary":"Consultar a declaração PGDAS-D no Integra Contador (paga)","description":"Consulta a declaração PGDAS-D no Integra Contador (paga) e absorve o resultado: a declaração inteira\n(regime de apuração, receita do PA por competência e por caixa, RBT12, RBA, a tabela de receitas\nmensais, a data de transmissão) entra no histórico da empresa com o PDF arquivado; a alíquota do mês é\nrecalculada (só entra se o mês ainda não tinha) e a `proxima` anunciada; a declaração é conferida contra\no mês que ela prova. `pa` pede um PA só (uma consulta); sem ele, a ordem do calendário.\n\n**PAs antigos:** cada declaração consultada fica no histórico (`GET …/pgdas/declaracoes`). Na autorização\na plataforma busca sozinha, em segundo plano (poucos minutos), os 13 PAs a partir da declaração mais recente (ela + os 12 meses\nque formam a RBT12 dela; empresa mais nova, desde a abertura) — uma consulta paga por PA, R$ 0,24, contada\ne não repassada. Para um PA específico fora disso, chame com `pa` (`AAAAMM`) e `forcar=true`: uma consulta,\na declaração entra no histórico e, se for mais antiga que a atual, a alíquota e a ficha da empresa não mudam.\nO `aceite` (termo assinado em nome da empresa) é ato do dono — 403 `ACEITE_SO_DO_DONO` para os demais\npapéis; a empresa precisa estar no recorte de quem chama (403 `EMPRESA_FORA_DO_RECORTE`). Chave de API com escopo `emissao` (papel operador/contabilidade); a de `leitura` recebe 403 — consultar é\noperação fiscal (e paga).\nCusto: cada PA consultado é uma requisição paga; pela API há um teto diário por empresa\n(429 `TETO_DIARIO_PGDAS`, 3 consultas) — o histórico entra sozinho, em segundo plano. Quando as consultas pagas\nda plataforma param até a virada do dia, a resposta é 503 `PGDAS_PAUSADO`; a alíquota do mês não muda.","operationId":"sync_pgdas_api_v1_companies__company_id__pgdas_sync_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PgdasSyncIn"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PgdasSyncOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/nfse":{"post":{"tags":["notas"],"summary":"Emitir uma nota (teste ou valendo)","description":"Emite uma NFS-e pelo Sistema Nacional (gov.br) em nome da empresa `company_id`.\n\nO corpo é a DPS: a competência (`dCompet`, AAAA-MM-DD, nunca futura), o serviço\n(`servico.cTribNac` com 6 dígitos e a descrição) e os valores como **string decimal**\n(`valores.vServ`, ex.: `\"1500.00\"`). O tomador é opcional. Não mande série, número,\nalíquota nem regime: tudo isso sai do cadastro da empresa. Com `\"ambiente\": \"teste\"` a\nnota é validada no ambiente restrito do gov.br sem efeito fiscal — não consome cota, não\naparece nas listagens e é descartada em 24 h.\n\n**Tomador só com o CNPJ** (`{\"tipo\": \"CNPJ\", \"documento\": \"…\"}`, sem `nome`): a emissão usa o\ncadastro da conta; se o CNPJ é novo, busca na Receita — pelo cadastro mensal (os Dados Abertos do\nCNPJ), sem custo e sem cota, ou, quando o CNPJ ainda não está nele, pela consulta em tempo real, que\ngasta uma unidade da cota mensal do plano —, cadastra o cliente com a razão social e o endereço e\nemite com eles. O e-mail da Receita não vira o de\nentrega. Com acesso a só algumas empresas (membro recortado ou empresa compartilhada), o cliente\ncadastrado fora do seu acesso também sai pela Receita, com a mesma regra de custo: a nota leva a\nrazão social e o endereço da Receita e o que vier no pedido — nunca o e-mail, o telefone, a\ninscrição ou o endereço do cadastro —, e o pedido não altera o cadastro. Quando a busca não sai (402\n`COTA_CONSULTAS_ESGOTADA`, 429, 503) ou a Receita não conhece o CNPJ (422\n`CNPJ_NAO_ENCONTRADO_NA_RECEITA`), nada é emitido: mande o `nome` do tomador.\n\nMande sempre um `Idempotency-Key` (um texto único seu por pedido): repetir a chamada com a\nmesma chave devolve a MESMA nota (cabeçalho `X-Idempotent-Replay: true`), e uma segunda\nchamada enquanto a primeira ainda corre recebe 409 `EMISSAO_EM_ANDAMENTO`. Se o gov.br não\nresponder a tempo e a nota não puder ser confirmada, a resposta é 503 `EMISSAO_INCERTA` e a chave\nfica guardada: repita com ela — a repetição confere a nota antes de emitir e nunca gera duas.\nExige chave com escopo `emissao`.\n\n**Avisos que não impedem a nota** (`avisos` na resposta): a nota sai, e o aviso diz o que conferir.\nHoje, `RETENCAO_COM_TOMADOR_DE_OUTRO_MUNICIPIO`: o ISS retido por um tomador de fora do município em que\no ISS é devido — a retenção só vale com o tomador no município do ISS (LC 116, arts. 3º e 6º; LC 123,\nart. 21, § 4º), salvo nos subitens em que a LC 116 faz a pessoa jurídica tomadora responsável onde\nquer que ela esteja (art. 6º, § 2º, II).\n\nQuando o gov.br rejeita, a resposta é 422 com o `code` do erro oficial (`E0160`, `E0625`…)\ne o detalhe em `erros`; as validações da plataforma chegam antes, com códigos próprios: a\ncompetência e os valores (`COMPETENCIA_FUTURA`, `VALOR_OBRIGATORIO`, `DESCONTO_MAIOR_QUE_O_SERVICO`,\n`DPS_XSD_INVALIDA`), a\nalíquota (`ALIQUOTA_NAO_CONFIRMADA`, `ALIQUOTA_SEM_RETENCAO`, `ALIQUOTA_ISS_DO_MES_AUSENTE`), a\nretenção (`RETENCAO_SEM_TOMADOR`, `INTERMEDIARIO_NAO_SUPORTADO`, `TRIBUTACAO_NAO_SUPORTADA`,\n`RETENCAO_NAO_PERMITIDA_NO_SERVICO`), o tomador (`TOMADOR_DO_EXTERIOR_NAO_SUPORTADO`,\n`TOMADOR_E_O_PROPRIO_PRESTADOR`), o MEI\n(`MEI_NAO_INFORMA_PTOTTRIBSN`, `MEI_NAO_TEM_RETENCAO`, `MUNICIPIO_DO_MEI_DIFERENTE_DO_CNPJ`), a inscrição\nmunicipal no município que a exige (`INSCRICAO_MUNICIPAL_OBRIGATORIA`), o\nlocal e o serviço (`LOCAL_PRESTACAO_OBRIGATORIO`, `MUNICIPIO_DA_PRESTACAO_NAO_ADERENTE`,\n`SERVICO_EXIGE_ENDERECO_DO_TOMADOR`, `SERVICO_EXIGE_DADOS_DA_OBRA`, `SERVICO_EXIGE_DADOS_DO_EVENTO`,\n`SERVICO_SEM_INCIDENCIA_NAO_SUPORTADO`). 402 é cota ou conta\n(`COTA_ESGOTADA`, `CONTA_BLOQUEADA`), 409 é estado (`EMPRESA_NAO_ATIVA`,\n`CERTIFICADO_NAO_VALIDADO`, `NDPS_DISPUTADO`) e 502 é o Sistema Nacional fora do ar.","operationId":"emitir_nfse_api_v1_companies__company_id__nfse_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseEmitIn"}}}},"responses":{"201":{"description":"A nota autorizada pelo Sistema Nacional","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"502":{"description":"O Sistema Nacional ou a Receita respondeu com erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/nfse/rascunho-pdf":{"post":{"tags":["notas"],"summary":"Ver o rascunho da nota em PDF","description":"Desenha, em PDF, a nota que sairia com este corpo — sem emitir nada.\n\nO corpo é exatamente o de `POST /companies/{company_id}/nfse`, e as validações são as\nmesmas: o que passa aqui passa na emissão, e o que seria recusado volta no mesmo 422, com o\nmesmo `code`. Use para mostrar a nota a quem vai aprová-la antes de gerar o documento\nfiscal, ou para conferir valores e textos sem gastar nada.\n\nNada é gravado: não há chave de acesso, não anda a numeração, não consome cota e a nota não\npassa a existir no gov.br (o `ambiente` do corpo é ignorado). O PDF sai com marca d'água de\nrascunho, sem número e sem QR Code, e os tributos são o cálculo da plataforma — o gov.br\npode ajustá-los na emissão. Exige chave com escopo `emissao`.","operationId":"rascunho_pdf_api_v1_companies__company_id__nfse_rascunho_pdf_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseEmitIn"}}}},"responses":{"200":{"description":"O rascunho do DANFSE em PDF","content":{"application/pdf":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse":{"get":{"tags":["notas"],"summary":"Listar as notas por período e filtros","description":"Lista as notas da conta, das mais recentes para as mais antigas.\n\nO período vai em `de` e `ate`, e cada um aceita mês (`2026-08`) ou dia exato (`2026-08-14`);\n`periodo_por` escolhe o campo da faixa: `competencia` (padrão, a do fechamento fiscal) ou\n`emissao`. Dá para filtrar por `status` (`ativa`, `cancelada`, `substituida`), por\n`company_id`, por `origem` (`plataforma`, `importada` ou `lote` — as que saíram de um lote), pelo número da nota (`numero`,\nque casa com o número oficial ou com o da DPS) e por texto livre em `q` (nome do cliente,\ndocumento ou descrição do serviço).\n\n`ordem` aceita `emissao_desc` (padrão), `emissao_asc`, `competencia_desc`, `competencia_asc`,\n`valor_desc`, `valor_asc`, `numero_desc`, `numero_asc`, `evento_desc` e `evento_asc` (a data em que a\nnota saiu de ativa — a ordem natural de `periodo_por=evento`). A paginação é `skip` e `limit`\n(máximo 100 por página); para saber o tamanho total e a soma do mesmo filtro, chame\n`GET /nfse/agregado`. Notas emitidas em ambiente de teste nunca aparecem aqui. Basta uma\nchave com escopo `leitura`.\n\nSituação com data: `cancelada_em` e `substituida_em` dizem quando a nota saiu de\nativa, na hora oficial do evento, e `periodo_por=evento` filtra por essa data —\n`status=cancelada&periodo_por=evento&de=2026-08&ate=2026-08` é \"o que foi cancelado em agosto\".\nNas notas fora de ativa, `evento_situacao` diz qual evento a tirou de ativa (cancelamento,\nsubstituição, cancelamento deferido por análise fiscal ou por ofício) e `substituida_por_numero`\ntraz o número da nota que entrou no lugar.\nAs bordas de `de`/`ate` valem no horário de Brasília, para qualquer `periodo_por`.","operationId":"listar_nfse_api_v1_nfse_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"company_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"}},{"name":"periodo_por","in":"query","required":false,"schema":{"type":"string","pattern":"^(competencia|emissao|evento)$","default":"competencia","title":"Periodo Por"}},{"name":"de","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"De"}},{"name":"ate","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ate"}},{"name":"origem","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origem"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"numero","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero"}},{"name":"com_problema","in":"query","required":false,"schema":{"type":"boolean","description":"true traz só as notas com algum problema (ver `alertas` em cada uma)","default":false,"title":"Com Problema"},"description":"true traz só as notas com algum problema (ver `alertas` em cada uma)"},{"name":"ordem","in":"query","required":false,"schema":{"enum":["emissao_desc","emissao_asc","competencia_desc","competencia_asc","valor_desc","valor_asc","numero_desc","numero_asc","evento_desc","evento_asc"],"type":"string","default":"emissao_desc","title":"Ordem"}},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Quantas notas pular — a paginação: 0, depois 100, 200…","default":0,"title":"Skip"},"description":"Quantas notas pular — a paginação: 0, depois 100, 200…"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Quantas notas por página: padrão 50, MÁXIMO 100 (acima disso a API devolve 100 sem avisar). Se a página voltar cheia, há mais: repita com `skip` somado; `GET /nfse/agregado` diz o total","default":50,"title":"Limit"},"description":"Quantas notas por página: padrão 50, MÁXIMO 100 (acima disso a API devolve 100 sem avisar). Se a página voltar cheia, há mais: repita com `skip` somado; `GET /nfse/agregado` diz o total"}],"responses":{"200":{"description":"As notas que casam com o filtro, em resumo","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"$ref":"#/components/schemas/NfseResumoOut"},"title":"Response 200 Listar Nfse Api V1 Nfse Get"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/agregado":{"get":{"tags":["notas"],"summary":"Somar e contar as notas do filtro","description":"Devolve quantas notas casam com o filtro e quanto elas somam.\n\nAceita exatamente os mesmos filtros de `GET /nfse` (`status`, `company_id`, `periodo_por`,\n`de`, `ate`, `origem`, `q`, `com_problema`), sem paginação: é a resposta para \"quantas notas e qual o\nfaturamento deste mês\". Use junto com a listagem para saber o total de páginas e para\nconferir o fechamento de uma competência. `valor_total` vem como string decimal com duas\ncasas. Notas de teste ficam de fora, como em toda listagem. Basta uma chave com escopo\n`leitura`.\n\n`por_status` separa as situações: `valor_total` soma tudo o que passou no filtro (como o painel\nmostra), e o faturamento válido do período é `por_status.ativa.valor_total`. Aceita também\n`periodo_por=evento`, para somar o que foi cancelado ou substituído num período. `com_problema`\nconta, dentro do mesmo filtro, as notas com algum problema (`alertas`).\n\n`exportacao` diz o que `POST /exports` faria com este mesmo recorte, ANTES de pedir: `por_volume`\n(quantas notas cabem num arquivo — 1.000 com os PDFs, 2.000 só XML), `arquivos` (quantos sairiam:\n1 quando cabe; volumes + resumo quando não), `estimativa_s` (segundos de montagem), `por_mes`\n(a contagem mês a mês no eixo de `periodo_por`, para estreitar o recorte) e\n`ultimo_mes_quinzenas` (só quando o último mês sozinho passa do volume). O bloco pode faltar se a\nconta por mês não puder ser feita — a contagem principal nunca depende dele.","operationId":"agregado_nfse_api_v1_nfse_agregado_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"company_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"}},{"name":"periodo_por","in":"query","required":false,"schema":{"type":"string","pattern":"^(competencia|emissao|evento)$","default":"competencia","title":"Periodo Por"}},{"name":"de","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"De"}},{"name":"ate","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ate"}},{"name":"origem","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origem"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"com_problema","in":"query","required":false,"schema":{"type":"boolean","description":"true soma e conta só as notas com algum problema","default":false,"title":"Com Problema"},"description":"true soma e conta só as notas com algum problema"},{"name":"incluir_pdf","in":"query","required":false,"schema":{"type":"boolean","description":"Para o bloco `exportacao`: com os PDFs o volume é de 1.000 notas; só XML, 2.000","default":true,"title":"Incluir Pdf"},"description":"Para o bloco `exportacao`: com os PDFs o volume é de 1.000 notas; só XML, 2.000"}],"responses":{"200":{"description":"Quantidade e soma das notas que casam com o filtro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseAgregadoOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/{nfse_id}":{"get":{"tags":["notas"],"summary":"Consultar uma nota pelo id","description":"Devolve uma nota inteira pelo `nfse_id` que a emissão retornou.\n\nTraz a identificação (chave de acesso, número oficial, série, número da DPS), a\ncompetência, os valores, o tomador, a tributação aplicada e a situação (`ativa`,\n`cancelada` ou `substituida`). É a rota para conferir o estado atual de uma nota depois de\num cancelamento ou de uma substituição — aí `substituida_por` aponta a nota que a\nsubstituiu. Diferente da listagem, aqui a nota de teste também pode ser consultada, pelo\nid. `local_prestacao` diz onde o serviço foi prestado, como a nota declarou — o local que a\nsubstituição mantém. Para o documento em si, use `/nfse/{nfse_id}/pdf` (DANFSE) ou\n`/nfse/{nfse_id}/xml`. Basta uma chave com escopo `leitura`.","operationId":"get_nfse_api_v1_nfse__nfse_id__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"nfse_id","in":"path","required":true,"schema":{"type":"string","title":"Nfse Id"}}],"responses":{"200":{"description":"A nota com todos os dados guardados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseDetalheOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/{nfse_id}/xml":{"get":{"tags":["notas"],"summary":"Baixar o XML autorizado da nota","description":"Devolve o XML da NFS-e autorizada — os bytes do arquivo, não JSON.\n\nÉ o documento fiscal que o Sistema Nacional assinou: guarde-o, é ele que vale para a\ncontabilidade e para o cliente. O `Content-Type` é `application/xml` e o\n`Content-Disposition` já traz um nome de arquivo pronto (\"NFS-e 8 (serie 2) - Empresa.xml\"),\nque forma par com o nome do PDF da mesma nota. Se o arquivo ainda não estiver disponível no\narmazenamento, a resposta é 409 `ARQUIVO_INDISPONIVEL` — tente de novo mais tarde. Basta\numa chave com escopo `leitura`.","operationId":"get_nfse_xml_api_v1_nfse__nfse_id__xml_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"nfse_id","in":"path","required":true,"schema":{"type":"string","title":"Nfse Id"}}],"responses":{"200":{"description":"O XML da NFS-e autorizada pelo gov.br","content":{"application/xml":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/{nfse_id}/pdf":{"get":{"tags":["notas"],"summary":"Baixar o DANFSE (PDF) da nota","description":"Devolve o DANFSE da nota em PDF — os bytes do arquivo, não JSON.\n\nÉ o documento que se manda ao cliente e se imprime, no leiaute obrigatório da NT 008/2026,\ncom QR Code e chave de acesso. O `Content-Type` é `application/pdf` e o\n`Content-Disposition` traz um nome de arquivo pronto, que forma par com o do XML da mesma\nnota. Nota cancelada ou substituída sai com a marca d'água correspondente, e nota emitida\nem ambiente de teste sai marcada como sem validade jurídica.\n\nO PDF é gerado na primeira chamada e reaproveitado nas seguintes, então a primeira pode\ndemorar alguns segundos. Se o XML autorizado não estiver acessível no momento, a resposta é\n502 `DANFSE_INDISPONIVEL` e vale repetir. Basta uma chave com escopo `leitura`.","operationId":"get_nfse_pdf_api_v1_nfse__nfse_id__pdf_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"nfse_id","in":"path","required":true,"schema":{"type":"string","title":"Nfse Id"}}],"responses":{"200":{"description":"O DANFSE em PDF","content":{"application/pdf":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"502":{"description":"O Sistema Nacional ou a Receita respondeu com erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/{nfse_id}/enviar-email":{"post":{"tags":["notas"],"summary":"Enviar a nota ao tomador por e-mail","description":"Manda a nota para o cliente por e-mail, em nome da empresa emissora.\n\nO e-mail leva o DANFSE em PDF e o XML autorizado como anexos, com o número da nota, o valor\ne a chave de acesso no corpo. Sem `para`, o destino é o e-mail do cadastro do tomador;\nquando ele não tem nenhum, a resposta é 422 `EMAIL_OBRIGATORIO`. Com\n`\"salvar_no_tomador\": true`, o endereço usado passa a constar no cadastro do cliente (só se\nele ainda não tinha um).\n\nNão há reenvio automático: cada chamada manda um e-mail, então trate a repetição com\ncuidado. Nota emitida em ambiente de teste nunca é entregue (409 `NOTA_DE_TESTE`), e falha\ndo provedor de e-mail volta como 502 `ENVIO_FALHOU`. Exige chave com escopo `emissao`. São até 10 envios por\nminuto (429 `RATE_LIMIT`) e 100 por dia (429 `LIMITE_EMAILS_DO_DIA`, renova à 0h de Brasília) por conta.","operationId":"enviar_nfse_email_api_v1_nfse__nfse_id__enviar_email_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"nfse_id","in":"path","required":true,"schema":{"type":"string","title":"Nfse Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnviarEmailIn"}}}},"responses":{"200":{"description":"Para onde a nota foi enviada e quando","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnviarEmailOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"502":{"description":"O Sistema Nacional ou a Receita respondeu com erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes":{"post":{"tags":["lotes"],"summary":"Criar um lote a partir de uma planilha","description":"Recebe a planilha (`multipart/form-data`, campo `file`: XLSX ou CSV, até 8 MB) e cria um lote no estado\n`lendo`. A leitura é feita em segundo plano: em alguns segundos o lote passa a `em_revisao`, com uma linha\nproposta por linha da planilha (`GET …/lotes/{lote_id}/itens`); o formato que a plataforma ainda não conhece\npassa por `aprendendo` e é conferido no painel. O modelo do GereNota (baixe no painel) é lido sempre na hora.\n\nMais de 200 notas: o lote fica `acima_do_limite`, e o painel divide. O mesmo arquivo já enviado à empresa nos\núltimos 90 dias volta 409 `LOTE_ARQUIVO_REPETIDO` com o lote anterior em `erros[0].lote_id`; mande\n`forcar=true` para criar outro (a linha COM DATA que já tem nota no mesmo mês, para o mesmo cliente e valor,\naparece como `ja_tem_nota`; a linha sem data não passa por essa conferência). PDF e imagem: 415.\nMontam lotes o dono, o operador e a contabilidade; nada é emitido até a confirmação.","operationId":"criar_pelo_arquivo_api_v1_companies__company_id__lotes_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_criar_pelo_arquivo_api_v1_companies__company_id__lotes_post"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"413":{"description":"Arquivo acima do limite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"415":{"description":"O arquivo não é do tipo aceito (a planilha do lote é XLSX ou CSV)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}},"get":{"tags":["lotes"],"summary":"Listar os lotes da empresa","description":"Os lotes da empresa nos últimos 90 dias, do mais novo para o mais antigo, com as contagens das linhas. Filtre\npor `estado` (ex.: `pronto_para_confirmar`). `pode_emitir` diz se o acesso em uso confirma lotes.","operationId":"listar_api_v1_companies__company_id__lotes_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estado"}},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":30,"title":"Limite"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListaDeLotesOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/linhas":{"post":{"tags":["lotes"],"summary":"Criar um lote com as linhas em JSON","description":"O lote sem arquivo: até 200 linhas, cada uma com os campos da planilha (o documento e o valor obrigatórios;\no nome, obrigatório no CPF). Os valores passam pelas mesmas conversões do arquivo (\"1.234,56\", \"05/09/2026\",\n\"04.16.01\"). O lote nasce `lendo` e, em segundos, passa a `em_revisao`: confira as linhas em\n`GET …/lotes/{lote_id}/itens` e confirme com `POST …/lotes/{lote_id}/confirmar`.","operationId":"criar_pelas_linhas_api_v1_companies__company_id__lotes_linhas_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteDeLinhasIn"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}":{"get":{"tags":["lotes"],"summary":"Consultar um lote","description":"O lote com o estado e as contagens — é o andamento: depois da confirmação, `contagens.por_estado` mostra as\nlinhas na fila (`pronto`), a que está saindo (`emitindo`), as emitidas e as recusadas. Consulte de alguns em\nalguns segundos enquanto o estado for `lendo`, `confirmado` ou `emitindo`.","operationId":"detalhe_api_v1_companies__company_id__lotes__lote_id__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/itens":{"get":{"tags":["lotes"],"summary":"As linhas de um lote","description":"As linhas do lote, na ordem do arquivo: o cliente, o serviço, o valor, a situação e o que falta\n(`pendencias`). Filtre por `estado` (pode repetir: `estado=precisa_dados&estado=proposto`). A linha recusada\ntraz `recusa` com o motivo do Sistema Nacional; a emitida, `nfse_id` e `numero`.","operationId":"itens_api_v1_companies__company_id__lotes__lote_id__itens_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Estado"}},{"name":"pagina","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Pagina"}},{"name":"por_pagina","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":200,"title":"Por Pagina"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItensDoLoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/confirmar":{"post":{"tags":["lotes"],"summary":"Confirmar o lote: as notas vão para a fila de emissão","description":"O único passo que emite. As linhas prontas (`proposto`) vão para a fila, com a data da nota fixada agora; as\nque precisam de dados ficam de fora. A fila emite uma nota por vez pelo Sistema Nacional — acompanhe em\n`GET …/lotes/{lote_id}`. Antes, confere o que pode ter mudado desde a revisão: 403\n`LOTE_SEM_PERMISSAO_DE_EMITIR` (o acesso não emite — confirmam o dono, o operador e a contabilidade com \"Pode\nemitir notas\"), 422 `CERTIFICADO_VENCIDO`, 402 `COTA_DO_LOTE` (o lote passa da cota do mês: `erros[0].restam`) e\n409 `LOTE_EM_OUTRO_ESTADO`. O cliente novo entra no cadastro, e a nota nunca sai em dobro.","operationId":"confirmar_api_v1_companies__company_id__lotes__lote_id__confirmar_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/cancelar":{"post":{"tags":["lotes"],"summary":"Cancelar o lote (só o que ainda não saiu)","description":"Antes da confirmação, o lote é descartado. Depois, sai da fila só o que ainda não foi emitido: a nota que está\nsaindo termina, e a nota emitida continua valendo (cancele-a em `POST /nfse/{nfse_id}/cancelar`). Com alguma nota\nemitida, o lote termina `parcial`; sem nenhuma, `cancelado`.","operationId":"cancelar_api_v1_companies__company_id__lotes__lote_id__cancelar_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/data":{"put":{"tags":["lotes"],"summary":"A data da prestação do lote","description":"S-CN (D-CN7, D-LT4): qual data vai nas notas — `linha` (a coluna de data de cada linha), `emissao` (o dia em que\no lote for confirmado) ou `outra` (uma data para o lote todo, em `outra`, AAAA-MM-DD). Data futura não passa.","operationId":"definir_data_api_v1_companies__company_id__lotes__lote_id__data_put","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataIn"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/itens/{item_id}":{"patch":{"tags":["lotes"],"summary":"Editar uma linha da revisão","description":"S-CN (D-CN7): corrige uma linha antes da confirmação — o nome e o e-mail do cliente, o endereço, o serviço (o\ncódigo e a descrição), o valor, a data, o incluir e o cadastro. A linha volta a ser conferida (o que falta para\nela seguir) e a resposta a traz como ficou; o documento do cliente não se edita (a linha com o documento errado vai\nnum lote novo).","operationId":"editar_item_api_v1_companies__company_id__lotes__lote_id__itens__item_id__patch","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditarItemIn"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemDoLoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/itens/acao":{"post":{"tags":["lotes"],"summary":"Uma ação em várias linhas da revisão","description":"S-CN (D-CN7): a mesma ação em várias linhas de uma vez — o código ou a descrição do serviço, a data, incluir ou\nignorar, e o que fazer com o cadastro do cliente que diverge. Devolve quantas linhas mudaram e as contagens.","operationId":"acao_em_grupo_api_v1_companies__company_id__lotes__lote_id__itens_acao_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcaoEmGrupoIn"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcaoEmGrupoOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/validar":{"post":{"tags":["lotes"],"summary":"Validar as notas prontas no ambiente de teste do gov.br","description":"D9 (D-LT3): o teste de cada nota pronta no ambiente de teste do Sistema Nacional, pela fila, uma por vez — sem\nefeito fiscal e fora da cota. Acompanhe em `validacao` no lote e em cada linha.","operationId":"validar_api_v1_companies__company_id__lotes__lote_id__validar_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidarIn"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/pausar":{"post":{"tags":["lotes"],"summary":"Pausar a emissão do lote","description":"S-CN (D-CN7): a fila para depois da nota que está saindo (ela termina); o lote fica `pausado` até continuar. As\nnotas que já saíram continuam valendo.","operationId":"pausar_api_v1_companies__company_id__lotes__lote_id__pausar_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/continuar":{"post":{"tags":["lotes"],"summary":"Continuar a emissão do lote pausado","description":"S-CN (D-CN7): o lote pausado volta à fila — só quem pode emitir continua. A fila confere o certificado e a cota\ndo mês (no Plano Free) a cada nota: se faltar algum, o lote pausa de novo, com o motivo. A partir de 1º/11/2026, a\nrecusa do convênio a uma ME/EPP de cidade sem adesão também pausa o lote de novo, com `pausado.motivo.convenio`.","operationId":"continuar_api_v1_companies__company_id__lotes__lote_id__continuar_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/entregar":{"post":{"tags":["lotes"],"summary":"Enviar aos clientes as notas do lote que ficaram sem e-mail","description":"A nota emitida pelo lote vai ao e-mail do cliente da linha ou do cadastro; sem nenhum dos dois, a linha fica\n`email.status = \"sem_email\"`. Aqui você informa o e-mail de cada cliente (pelo CPF ou CNPJ), e as notas emitidas\ndele neste lote vão para a fila de entrega: o PDF e o XML, em nome da empresa, como na entrega do lote. Vale também\npara corrigir o e-mail que falhou ou que o provedor devolveu (com `guardar_no_cadastro`, o cadastro que guardava o\nendereço devolvido passa ao novo); a correção conta no teto de e-mails do dia (429 `LIMITE_EMAILS_DO_DIA`). Só a\nnota ativa vai: a cancelada ou substituída fica de fora.\nAcompanhe em `GET …/lotes/{lote_id}/itens` (`email.status`: `a_enviar`, `enviando`, depois `enviado` ou\n`falhou`). Valem as travas da revisão: o e-mail inválido, o domínio com erro de digitação e o e-mail da própria\nempresa voltam em `recusados`. Cada nota sai uma vez por aqui. Confirmam o dono, o operador e a contabilidade com\n\"Pode emitir notas\" (403 `LOTE_SEM_PERMISSAO_DE_EMITIR`).","operationId":"entregar_api_v1_companies__company_id__lotes__lote_id__entregar_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntregarIn"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntregarOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/companies/{company_id}/lotes/{lote_id}/recibo.csv":{"get":{"tags":["lotes"],"summary":"O recibo do lote em CSV","description":"S-CN (D-CN7): o recibo do lote em CSV (separador `;`, UTF-8), sem fórmula em nenhuma célula — o mesmo do botão\n\"Baixar o recibo\" do painel.","operationId":"recibo_api_v1_companies__company_id__lotes__lote_id__recibo_csv_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"string","title":"Company Id"}},{"name":"lote_id","in":"path","required":true,"schema":{"type":"string","title":"Lote Id"}}],"responses":{"200":{"description":"Uma linha por nota proposta: a linha do arquivo, o cliente, o valor, a situação e o número da nota emitida","content":{"text/csv":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/lotes/modelo":{"get":{"tags":["lotes"],"summary":"O modelo da planilha do lote","description":"E3: o caminho mais curto — as colunas que o lote lê na hora, com a data da prestação e o e-mail (opcional).\nS-CN (D-CN7): no guia público, para a integração montar o arquivo que o lote lê sem IA.","operationId":"modelo_api_v1_lotes_modelo_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"formato","in":"query","required":false,"schema":{"enum":["csv","xlsx"],"type":"string","default":"xlsx","title":"Formato"}}],"responses":{"200":{"description":"O modelo em XLSX (padrão) ou CSV","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{},"text/csv":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/{nfse_id}/cancelar":{"post":{"tags":["eventos"],"summary":"Cancelar uma nota emitida","description":"Cancela uma NFS-e já emitida, registrando o evento assinado no Sistema Nacional.\n\nInforme o motivo (`cMotivo`) e uma justificativa (`xMotivo`) de 15 a 255 caracteres — ela\nfica no histórico da nota e aparece na consulta pública. Depois do cancelamento a nota\npassa a `cancelada` e o DANFSE volta a ser gerado com marca d'água de cancelada.\n\nSó nota `ativa` pode ser cancelada: se ela já foi cancelada ou substituída, a resposta é\n409 `NFSE_NAO_ATIVA`. O cancelamento tem prazo definido pelo município e pela legislação; se\no gov.br recusar (prazo vencido, por exemplo), a resposta é 422 com o `code` oficial do erro\ne a explicação em `message`. Para corrigir dados de uma nota em vez de simplesmente anulá-la,\nprefira `POST /nfse/{nfse_id}/substituir`. Exige chave com escopo `emissao`.\n\nAceita `Idempotency-Key`: repetir a chamada com a mesma chave devolve o MESMO cancelamento (200, cabeçalho\n`X-Idempotent-Replay: true`), em vez do 409 da nota que já está cancelada; uma chamada simultânea com a mesma\nchave recebe 409 `CANCELAMENTO_EM_ANDAMENTO`. A chave vale por nota.","operationId":"cancelar_nfse_api_v1_nfse__nfse_id__cancelar_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"nfse_id","in":"path","required":true,"schema":{"type":"string","title":"Nfse Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelarIn"}}}},"responses":{"200":{"description":"O cancelamento registrado no Sistema Nacional","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelarOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"502":{"description":"O Sistema Nacional ou a Receita respondeu com erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/{nfse_id}/substituir":{"post":{"tags":["eventos"],"summary":"Substituir uma nota por outra corrigida","description":"Emite uma nota NOVA no lugar de `nfse_id`, que passa a valer como substituída.\n\nO corpo é o mesmo de `POST /companies/{company_id}/nfse` — a nota **corrigida**, inteira —\nmais o bloco `motivo` com a justificativa fiscal (`motivo.cMotivo`). Use quando os dados de\numa nota já emitida estão errados: a substituta é um documento novo, com número e chave\npróprios, e a antiga fica com status `substituida` apontando para ela em `substituida_por`.\nSem `servico.cMunPrestacao`, a substituta mantém o local da prestação da original (o\n`local_prestacao` de `GET /nfse/{nfse_id}`) — mande o campo só para corrigir o local. Na nota\nantiga cujo XML não está guardado, vale o município da empresa.\n\nA resposta é a nota nova (201), no mesmo formato da emissão. A substituição conta como uma\nemissão para a cota do plano, herda o ambiente da nota original (substituir uma nota de\nteste emite outra de teste) e aceita `Idempotency-Key`: repetir a chamada com a mesma chave\ndevolve a MESMA nota nova em vez de emitir outra — inclusive depois de um 503\n`EMISSAO_INCERTA`, quando o gov.br não respondeu a tempo: a repetição confere a substituta antes\nde emitir.\n\nSó nota `ativa` pode ser substituída (senão 409 `NFSE_NAO_ATIVA`), e valem as mesmas\nvalidações e rejeições da emissão — 422 com o `code` oficial quando o gov.br recusa a nota\nnova, e nesse caso a original continua ativa. No Simples Nacional (MEI e ME/EPP) a substituta\nmantém o tomador, a competência e o valor da original: mudar um deles volta 422\n`SUBSTITUICAO_MUDA_O_QUE_O_SIMPLES_MANTEM` antes de ir ao gov.br, e o caminho é cancelar a nota\ne emitir outra. Exige chave com escopo `emissao`.","operationId":"substituir_nfse_api_v1_nfse__nfse_id__substituir_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"nfse_id","in":"path","required":true,"schema":{"type":"string","title":"Nfse Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseSubstituirIn"}}}},"responses":{"201":{"description":"A nota NOVA, que substitui a anterior","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"502":{"description":"O Sistema Nacional ou a Receita respondeu com erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/{nfse_id}/eventos":{"get":{"tags":["eventos"],"summary":"Listar os eventos de uma nota","description":"Devolve a linha do tempo de uma nota: cancelamento, substituição e os demais eventos do gov.br.\n\nOs eventos vêm do mais antigo para o mais recente (até 100), cada um com `tipo`, o `codigo`\noficial, a `descricao` com o nome do evento, `muda_situacao`, a data/hora `dh` e o `detalhe` do\nque foi registrado — no cancelamento, o motivo e a justificativa; na substituição, o motivo\ne o id da nota que entrou no lugar. Além dos feitos aqui, entram os que chegam pela importação do\nSistema Nacional: o cancelamento deferido por análise fiscal e o por ofício, que também tiram a\nnota de ativa, e os que só registram histórico, como a rejeição do tomador e o bloqueio por ofício.\n\nUse para explicar a situação de uma nota que não está mais `ativa`, ou para auditar o que\naconteceu com ela. Nota sem nenhum evento devolve lista vazia. Basta uma chave com escopo\n`leitura`.","operationId":"listar_eventos_api_v1_nfse__nfse_id__eventos_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"nfse_id","in":"path","required":true,"schema":{"type":"string","title":"Nfse Id"}}],"responses":{"200":{"description":"Os eventos da nota, do mais antigo ao mais recente","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"$ref":"#/components/schemas/NfseEventoOut"},"title":"Response 200 Listar Eventos Api V1 Nfse  Nfse Id  Eventos Get"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/{nfse_id}/eventos/{evento_id}/xml":{"get":{"tags":["eventos"],"summary":"Baixar o XML do evento (cancelamento ou substituição)","description":"Devolve o XML de um evento da nota — os bytes do arquivo, não JSON.\n\nÉ a prova do cancelamento ou da substituição. O XML da nota em `GET /nfse/{id}/xml` é o\nautorizado e continua idêntico depois do evento, então um sistema contábil que só recebe a\nnota a importa como válida: mande o evento junto. O `evento_id` vem de\n`GET /nfse/{id}/eventos`; id que não é desta nota devolve 404 `EVENTO_NAO_ENCONTRADO`. Nem todo\nevento tem arquivo próprio: a substituição feita por esta API registra um evento local sem XML\n(o e105102 oficial é gerado pelo Sistema Nacional e chega pela importação do DFe como outro\nevento da mesma nota) — aí a resposta é 404 `EVENTO_SEM_XML`. Arquivo ainda não disponível no\narmazenamento devolve 409 `ARQUIVO_INDISPONIVEL`. Basta uma chave com escopo `leitura`.","operationId":"get_evento_xml_api_v1_nfse__nfse_id__eventos__evento_id__xml_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"nfse_id","in":"path","required":true,"schema":{"type":"string","title":"Nfse Id"}},{"name":"evento_id","in":"path","required":true,"schema":{"type":"string","title":"Evento Id"}}],"responses":{"200":{"description":"O XML do evento, como o Sistema Nacional o registrou","content":{"application/xml":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/nfse/eventos":{"get":{"tags":["eventos"],"summary":"Listar o que mudou de situação na conta","description":"Devolve, em ordem cronológica, as notas da conta que foram canceladas ou substituídas no\nperíodo — a resposta para \"o que mudou desde a última vez que mandei ao contador\".\n\n`de`/`ate` recortam um período pela hora OFICIAL do evento (inclusivos, como nas outras listagens: \"o\nque foi cancelado em agosto\"). Para sincronizar, guarde o maior `cursor` da página e chame com `desde`\nigual a ele: o que voltar é novidade. O `cursor` é a hora em que o evento entrou aqui, e não a oficial —\no cancelamento feito pela prefeitura chega na importação do dia seguinte com data anterior, e pela hora\noficial ele nasceria \"antes\" do seu cursor e nunca seria entregue. Com `desde`, a lista vem na ordem de\nentrada; sem ele, na ordem cronológica oficial. Quem guardava a `dh` como cursor continua funcionando:\nno pior caso recebe de novo o último evento, nunca deixa de receber um. Cada item traz a nota (`nfse_id`, `numero`, `chave`), o `codigo` do evento, a situação\natual e, na substituição, `substituida_por`; `xml_disponivel` diz se o XML do evento pode ser\nbaixado em `GET /nfse/{nfse_id}/eventos/{id}/xml`. Vem uma linha por mudança: o registro feito\naqui e o espelho oficial do gov.br contam uma vez só. Entram os cancelamentos e as substituições\npor qualquer via — feitos aqui, no portal do gov.br ou pela prefeitura (cancelamento deferido por\nanálise fiscal, cancelamento por ofício) —, cada um com `descricao`. Com `todos=true` vêm também os\neventos que só registram histórico, como a rejeição do tomador e o bloqueio por ofício, com\n`muda_situacao=false`. Sem `desde`, começa do primeiro evento\nda conta; `limit` vai até 500 — se voltar cheio, repita com `desde` na última `dh`. Data fora\ndo formato devolve 422 `DATA_INVALIDA`. Respeita o recorte de empresas do seu acesso. Basta uma\nchave com escopo `leitura`.","operationId":"eventos_da_conta_api_v1_nfse_eventos_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"de","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Início do período (inclusivo): `2026-08` (mês), `2026-08-01` (dia) ou ISO 8601 com hora; sem fuso vale Brasília. Para o cursor de sincronização prefira `desde`","title":"De"},"description":"Início do período (inclusivo): `2026-08` (mês), `2026-08-01` (dia) ou ISO 8601 com hora; sem fuso vale Brasília. Para o cursor de sincronização prefira `desde`"},{"name":"ate","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Fim do período (inclusivo): mês ou dia inteiros, ou ISO 8601 com hora","title":"Ate"},"description":"Fim do período (inclusivo): mês ou dia inteiros, ou ISO 8601 com hora"},{"name":"desde","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Só o que ENTROU depois deste instante (exclusivo): o maior `cursor` da página anterior — o cursor da sincronização","title":"Desde"},"description":"Só o que ENTROU depois deste instante (exclusivo): o maior `cursor` da página anterior — o cursor da sincronização"},{"name":"todos","in":"query","required":false,"schema":{"type":"boolean","description":"Inclui os eventos que não mudam a situação da nota: análise fiscal pedida ou indeferida, bloqueio e desbloqueio por ofício, confirmação e rejeição do tomador ou do intermediário","default":false,"title":"Todos"},"description":"Inclui os eventos que não mudam a situação da nota: análise fiscal pedida ou indeferida, bloqueio e desbloqueio por ofício, confirmação e rejeição do tomador ou do intermediário"},{"name":"company_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Quantos eventos por resposta, até 500","default":200,"title":"Limit"},"description":"Quantos eventos por resposta, até 500"}],"responses":{"200":{"description":"Os cancelamentos e substituições da conta no período, do mais antigo ao mais recente","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"$ref":"#/components/schemas/EventoDaContaOut"},"title":"Response 200 Eventos Da Conta Api V1 Nfse Eventos Get"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/tomadores":{"get":{"tags":["tomadores"],"summary":"Listar e buscar tomadores da conta","description":"Lista os tomadores (clientes) da conta. Sem `q`, devolve todos; com `q`, filtra.\n\nA busca por nome ignora acento e maiúsculas — `joao`, `JOÃO` e `João` acham o mesmo cadastro.\nO termo só é tratado como **documento** quando é de fato um documento: 3 ou mais dígitos e\nnenhuma letra, ou o CNPJ com letras — letras e números juntos, sem espaço, com ou sem a pontuação\n(`12.ABC`, `12abc345`); aí o nome também vale (busca por prefixo do CNPJ/CPF, em todos os\ncadastros da conta — o documento inteiro acha o tomador). Quem acessa com recorte de empresas (membro recortado, ou empresa\ncompartilhada de outra conta) vê os clientes que já receberam nota das empresas dele e os que ele\nmesmo cadastrou — na lista, na busca por nome e no prefixo do documento; o documento inteiro (11\nou 14 caracteres) acha qualquer cadastro da conta, para ninguém cadastrar o mesmo cliente duas\nvezes — o de fora do acesso vem com `fora_do_recorte: true` e só o `id`, o documento, o tipo, o\nnome e a origem (sem e-mail, telefone, endereço, inscrição e data da última nota), e só para quem\ncadastra clientes (escopo `emissao`; o leitor e a contabilidade com recorte não o recebem).\nCom recorte, `ultima_nota_em` é a da nota mais recente das empresas do seu acesso (e a ordem\npadrão segue ela), e o cliente que a conta também atende por uma empresa de fora do seu acesso\nvem com `de_outras_empresas: true` — o contato e a exclusão dele ficam com o dono da conta.\nTermo com espaço é sempre busca por nome, mesmo que contenha números (\"Loja 2\", \"Grupo 3R\").\n\n`limit` vai de 1 a 200 (padrão 200); valores maiores são reduzidos ao teto. `ordem` aceita\n`ultima_nota_desc` (padrão — quem recebeu nota mais recentemente primeiro), `nome_asc`,\n`nome_desc` e `criado_desc`. O cabeçalho `X-Total-Count` traz o total de resultados ANTES do\ncorte por `limit`, então use-o para saber se há mais do que a página devolvida. Lista vazia\nnão é erro: é uma conta sem tomadores ou uma busca sem correspondência.","operationId":"listar_tomadores_api_v1_tomadores_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"title":"Limit"}},{"name":"ordem","in":"query","required":false,"schema":{"enum":["ultima_nota_desc","nome_asc","nome_desc","criado_desc"],"type":"string","default":"ultima_nota_desc","title":"Ordem"}}],"responses":{"200":{"description":"Tomadores encontrados, já ordenados","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"$ref":"#/components/schemas/TomadorDaBuscaOut"},"title":"Response 200 Listar Tomadores Api V1 Tomadores Get"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}},"post":{"tags":["tomadores"],"summary":"Cadastrar um tomador","description":"Cria um tomador (cliente) na conta. Exige chave com escopo `emissao` — chave de `leitura`\nrecebe 403 `PERMISSAO_NEGADA`.\n\nO `documento` pode vir com ou sem pontuação: a máscara é removida, os dígitos verificadores são\nconferidos (422 `DOCUMENTO_INVALIDO` se não baterem) e o cadastro é gravado sem pontuação (o CNPJ\npode ter letras nas 12 primeiras posições; minúscula vira maiúscula). O\ndocumento é único por conta: se já existir, a resposta é 409 `TOMADOR_JA_EXISTE` — nesse caso\nlocalize o cadastro em `GET /tomadores?q=…` e altere com `PATCH /tomadores/{id}`.\n\n**CNPJ sem `nome`: o cadastro sai da Receita.** A plataforma busca o CNPJ (a mesma consulta de\n`GET /consultas/cnpj/{documento}`: pelo cadastro mensal da Receita, sem custo e sem cota; o CNPJ que\nainda não está nele vai à consulta em tempo real, que gasta uma unidade da cota mensal do plano) e\ncadastra com a razão social como\n`nome`, o nome fantasia e o endereço da Receita. Um `nome_fantasia` mandado vale quando a Receita\nnão tem um. O e-mail da Receita **não** vira o de entrega — ele volta em `receita.email`. A\nresposta traz `receita` com a situação do CNPJ (`ativa: false` quando ele está suspenso, inapto,\nbaixado ou nulo: o cadastro sai, confira com o cliente). CNPJ que a Receita não conhece: 422\n`CNPJ_NAO_ENCONTRADO_NA_RECEITA` (a Receita cobra a resposta). Quando a busca não sai — 402\n`COTA_CONSULTAS_ESGOTADA`, 429 `LIMITE_CONSULTAS_DIA` ou `RATE_LIMIT`, 503 `SERPRO_INDISPONIVEL` ou\n`CONSULTAS_PAUSADAS` —, nada é cadastrado: mande o `nome` e o cadastro segue sem a Receita. **Com o\n`nome`, nada é consultado e nada é cobrado.** CPF sempre exige o `nome`.\n\nO endereço é opcional e pode ser parcial; se mandar `cMun`, use um código IBGE de verdade\n(`/consultas/cep/{cep}` devolve o código pelo CEP). Cadastrar aqui não emite nota nenhuma: o\ncadastro só poupa digitação na emissão e guarda o e-mail de entrega.","operationId":"criar_tomador_api_v1_tomadores_post","security":[{"ApiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/gerenota_api__tomadores__TomadorIn"}}}},"responses":{"201":{"description":"Tomador cadastrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TomadorCriadoOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/tomadores/{tomador_id}":{"patch":{"tags":["tomadores"],"summary":"Atualizar um tomador","description":"Altera um tomador já cadastrado. Exige chave com escopo `emissao`.\n\nÉ um PATCH de verdade: mande **apenas** os campos que quer mudar — o que não vier fica como\nestá. Corpo sem nenhum campo é recusado com 422 `NADA_A_ATUALIZAR`, e `tomador_id` inexistente\n(ou de outra conta) devolve 404 `TOMADOR_NAO_ENCONTRADO`. O cliente fora do seu acesso (membro\nrecortado ou empresa compartilhada) também devolve 404: quem tem recorte altera só os clientes\nque já receberam nota das empresas dele e os que ele mesmo cadastrou — mesmo que o documento\ninteiro, em `GET /tomadores?q=`, ache outro cadastro da conta. O `endereco`, quando enviado,\nsubstitui o anterior por inteiro — não é um merge campo a campo.\n\nO contato (`email`, `fone`, `inscricao_municipal`, `endereco`) vale para as notas e a entrega\nde todas as empresas da conta. Por isso quem tem recorte não o muda no cliente que a conta\ntambém atende por uma empresa de fora do seu acesso (o `de_outras_empresas: true` da lista):\n403 `TOMADOR_DE_OUTRA_EMPRESA` — quem muda é o dono da conta. Mandar de volta o mesmo valor\ngravado não conta como mudança.\n\n`documento` e `tipo` não se alteram por aqui: para corrigir o documento, exclua o cadastro e\ncrie outro. A resposta é o tomador completo já atualizado.","operationId":"atualizar_tomador_api_v1_tomadores__tomador_id__patch","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"tomador_id","in":"path","required":true,"schema":{"type":"string","title":"Tomador Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TomadorUpdate"}}}},"responses":{"200":{"description":"Tomador depois da alteração","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TomadorOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}},"delete":{"tags":["tomadores"],"summary":"Excluir um tomador","description":"Remove o cadastro de um tomador da conta. Exige chave com escopo `emissao`.\n\nSucesso devolve 204 sem corpo; `tomador_id` inexistente (ou de outra conta) devolve 404\n`TOMADOR_NAO_ENCONTRADO`. O cliente fora do seu acesso (membro recortado ou empresa\ncompartilhada) também devolve 404: quem tem recorte exclui só os clientes que já receberam nota\ndas empresas dele e os que ele mesmo cadastrou — e não exclui o cliente que a conta também\natende por uma empresa de fora do seu acesso (o `de_outras_empresas: true` da lista): 403\n`TOMADOR_DE_OUTRA_EMPRESA`, porque a entrega e as automações dessas empresas usam o cadastro.\nA exclusão apaga **somente o cadastro**: as\nnotas já emitidas para esse documento continuam intactas, e o histórico segue disponível em\n`/nfse` e em `GET /tomadores/{documento}/sugestao`. Não há desfazer — para voltar atrás,\ncadastre de novo.","operationId":"excluir_tomador_api_v1_tomadores__tomador_id__delete","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"tomador_id","in":"path","required":true,"schema":{"type":"string","title":"Tomador Id"}}],"responses":{"204":{"description":"Sem corpo"},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/tomadores/{documento}/sugestao":{"get":{"tags":["tomadores"],"summary":"Sugerir a próxima emissão pelo histórico","description":"Devolve os campos da próxima nota para este tomador, deduzidos das notas anteriores — é o\n\"emitir igual à última\". Use antes de montar um `POST /companies/{id}/nfse` para não perguntar\nao usuário o que o histórico já responde.\n\nO `documento` no caminho é o CNPJ/CPF **sem pontuação** (o CNPJ pode ter letras), e não precisa haver\ncadastro: o que\nvale é o histórico de notas. Passe `company_id` em conta com mais de uma empresa — sem ele a\nbusca varre a conta inteira e pode trazer o serviço de outra emissora; com ele, empresa fora do\nseu acesso devolve 403 `EMPRESA_FORA_DO_RECORTE`.\n\nSem nota anterior a resposta é `{\"tem_historico\": false, \"email_cadastro\": …, \"cadastrado\": …}` (200, não\n404); `cadastrado` diz se o documento está no cadastro de clientes da conta. Com acesso a só algumas\nempresas (membro recortado ou empresa compartilhada), `email_cadastro` só vem do cliente que está no\nseu acesso, e `cadastrado` do cliente de fora dele só vem `true` para quem cadastra clientes.\nCom histórico, a descrição e o código do serviço vêm da última nota, e o `sugestao.valor` só\né preenchido quando as **duas** notas mais recentes têm o mesmo valor — quando vier `null`,\npergunte o valor e use `valores_recentes` para oferecer opções. Se a nota-modelo estiver\ncancelada ou substituída (`base_cancelada: true`), o serviço ainda serve de modelo, mas o valor\nnunca é sugerido. Notas de teste não entram nessa memória. `competencia_proposta` traz pronta a data da\nprestação a propor (o mesmo dia do mês da última nota ativa, nunca no futuro; sem ela, hoje).","operationId":"sugestao_emissao_api_v1_tomadores__documento__sugestao_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"documento","in":"path","required":true,"schema":{"type":"string","title":"Documento"}},{"name":"company_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"}}],"responses":{"200":{"description":"Sugestão (ou `tem_historico: false`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SugestaoTomadorOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/consultas/cnpj/{documento}":{"get":{"tags":["consultas"],"summary":"Consultar um CNPJ na Receita (com cache)","description":"Busca o cadastro de um CNPJ na Receita Federal e devolve razão social, situação cadastral e\nendereço já no formato usado para cadastrar empresa ou tomador.\n\n**De onde vem o dado (`fonte`):** do cadastro mensal da Receita — os Dados Abertos do CNPJ, que a\nReceita publica uma vez por mês, por isso podem estar algumas semanas atrás do cadastro do dia\n(`fonte: \"gerecnpj\"`, com `mes_referencia` e `data_extracao`) —, ou da consulta em tempo real à\nReceita (`fonte: \"serpro\"`) quando o CNPJ ainda não está no cadastro do mês (aberto depois da\nextração), quando o cadastro mensal não responde e com `fresco=true`. Onde terceiros virem o dado,\ncite a fonte com o mês do dado: \"Fonte: Receita Federal (setembro/2026)\".\n\n**Cota:** a busca pelo cadastro mensal não gasta a cota do plano. A consulta em tempo real do CNPJ\nque ainda não está no cadastro, e a do `fresco=true`, gastam uma unidade da cota mensal (402\n`COTA_CONSULTAS_ESGOTADA` quando acaba) e do limite do dia do plano (429 `LIMITE_CONSULTAS_DIA`);\na que vai em tempo real porque o cadastro mensal não respondeu fica por conta da plataforma. A cota\nvale para todas as portas da conta (a API, o painel, os links de cadastro e o WhatsApp). Toda busca\n— do cache ou não, inclusive a do CNPJ que não existe — conta no teto técnico de 300 por dia por\nconta, igual em todos os planos (429 `LIMITE_CONSULTAS_DIA`, sem `upgrade`, renova à 0h de\nBrasília), e no de 10 por minuto por conta (429 `RATE_LIMIT`). O mesmo CNPJ no mesmo mês do\ncadastro, ou consultado em tempo real nos últimos 7 dias, sai do cache (`de_cache: true` e\n`consultado_em`), de qualquer conta. Consulte uma vez e guarde o resultado; não use esta rota para\nvalidar documento em laço.\n\nNuma empresa compartilhada por outra conta (o `company_id` dela na query), a busca pelo cadastro\nmensal é de todos; a consulta em tempo real gasta a cota da conta que compartilhou e é de quem\ncadastra clientes, o papel `operador`: `leitor` e `contabilidade` recebem 403 `PERMISSAO_NEGADA`\nquando o CNPJ precisa dela.\n\nO `documento` no caminho aceita com ou sem pontuação — a máscara é removida e os dígitos\nverificadores são conferidos antes de qualquer busca (422 `DOCUMENTO_INVALIDO`, sem custo e fora do\nteto). Na resposta o documento vem sem pontuação — o CNPJ pode ter letras nas 12 primeiras posições\n(o formato novo da Receita), sempre em maiúsculas.\n\nCom `completo=true` a resposta traz o quadro societário (`receita.qsa`: o nome e a qualificação; o\nsócio menor vem como \"Sócio menor\"), `receita.informacoes_adicionais` e `regime_sugerido` (com o\n`opSimpNac` pronto para a emissão; no cadastro mensal, `periodos_simples` traz só o período mais\nrecente, e a saída já marcada para uma data futura vem em `exclusao_marcada`, ainda optante). O\ncache da busca simples não atende um pedido completo. Com `fresco=true` só vale a consulta em tempo\nreal de hoje — para conferir o regime com a Receita. Com `completo=true&confirmar=true`, o veredito que\nbarraria o cadastro de uma empresa (não optante do Simples nem MEI hoje) é confirmado na Receita em\ntempo real antes de voltar, por conta da plataforma: só a confirmação traz\n`regime_sugerido.nao_optante_explicito: true`; sem ela, o cadastro do mês pode estar velho.\n\nCNPJ que nem o cadastro mensal nem a Receita em tempo real conhecem devolve 404\n`DOCUMENTO_NAO_ENCONTRADO` (a consulta em tempo real conta: a Receita cobra a resposta). Com as\nfontes indisponíveis: 503 `SERPRO_NAO_CONFIGURADO` ou `SERPRO_INDISPONIVEL`; consultas em tempo real\nda plataforma pausadas até a virada do dia, 503 `CONSULTAS_PAUSADAS`; credenciais recusadas, 502\n`SERPRO_RECUSOU`. Em qualquer um desses casos siga com o cadastro manual. Consultar aqui não cria\nnada: para cadastrar, chame `POST /tomadores`.","operationId":"consulta_cnpj_route_api_v1_consultas_cnpj__documento__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"documento","in":"path","required":true,"schema":{"type":"string","title":"Documento"}},{"name":"completo","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Completo"}},{"name":"fresco","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Fresco"}},{"name":"confirmar","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Confirmar"}}],"responses":{"200":{"description":"Cadastro do CNPJ na Receita","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultaCnpjOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"502":{"description":"O Sistema Nacional ou a Receita respondeu com erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/consultas/cpf/{documento}":{"get":{"tags":["consultas"],"summary":"Consultar um CPF na Receita (pago, com cache)","description":"Confirma nome e situação cadastral de um CPF na Receita Federal (via SERPRO), para cadastrar\num tomador pessoa física. Não devolve endereço nem telefone — para o endereço, use\n`/consultas/cep/{cep}`.\n\n**Esta consulta é paga** (é sempre em tempo real, como a do CNPJ que ainda não está no cadastro\nmensal): consome a cota mensal do plano (402 `COTA_CONSULTAS_ESGOTADA`), respeita o limite do dia do\nplano (429 `LIMITE_CONSULTAS_DIA`) e o de 10 chamadas por minuto por conta (429 `RATE_LIMIT`). O cache do CPF é mais curto e mais fechado:\no mesmo CPF, com a MESMA data de nascimento, consultado pela mesma conta nas últimas 24 h volta\ncom `de_cache: true` e `consultado_em`, sem gastar nada. Numa empresa compartilhada por outra\nconta, vale a regra do CNPJ: a consulta paga é do papel `operador` (`leitor` e `contabilidade`\nrecebem 403 `PERMISSAO_NEGADA`), e o cache segue valendo para todos.\n\nO parâmetro `nascimento` é **obrigatório**: a Receita valida o par CPF + data de nascimento e,\nsem ele, a resposta é 422 `NASCIMENTO_OBRIGATORIO`. A data é aceita em `ddmmaaaa`, `dd/mm/aaaa`\nou `aaaa-mm-dd`. O `documento` no caminho aceita com ou sem pontuação e tem os dígitos\nverificadores conferidos antes da chamada paga (422 `DOCUMENTO_INVALIDO`, sem custo).\n\nPar que não confere devolve 404 `DOCUMENTO_NAO_ENCONTRADO` — pode ser o número ou a data. CPF\nde menor de idade devolve 422 `CPF_SEM_RETORNO`: a Receita não fornece os dados, e o cadastro\nmanual é o caminho. Sem credenciais, com a Receita fora do ar ou com as consultas pausadas,\n503; credenciais recusadas, 502 `SERPRO_RECUSOU`.","operationId":"consulta_cpf_route_api_v1_consultas_cpf__documento__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"documento","in":"path","required":true,"schema":{"type":"string","title":"Documento"}},{"name":"nascimento","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nascimento"}}],"responses":{"200":{"description":"Cadastro do CPF na Receita","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultaCpfOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"502":{"description":"O Sistema Nacional ou a Receita respondeu com erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/consultas/cep/{cep}":{"get":{"tags":["consultas"],"summary":"Consultar o endereço de um CEP (grátis)","description":"Devolve o endereço de um CEP já com os nomes de campo da NFS-e (`xLgr`, `xBairro`, `CEP`,\n`cMun`), prontos para o bloco de endereço de um tomador ou de uma empresa.\n\nÉ **grátis**: não consome a cota de consultas nem passa pela Receita — a fonte é o ViaCEP. Use\nesta rota sempre que precisar do código IBGE (`cMun`) de um endereço; é a forma mais confiável\nde obtê-lo, porque o CEP identifica o município sem ambiguidade.\n\nO `cep` no caminho aceita com ou sem hífen, mas precisa ter 8 dígitos (422 `CEP_INVALIDO`). CEP\nque não existe devolve 404 `CEP_NAO_ENCONTRADO`; ViaCEP fora do ar devolve 503\n`VIACEP_INDISPONIVEL` — nesse caso o endereço pode ser preenchido à mão. Em CEP de município\ninteiro (o \"CEP geral\") `xLgr` e `xBairro` vêm `null`, e só município, UF e `cMun` são úteis.","operationId":"consulta_cep_route_api_v1_consultas_cep__cep__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"cep","in":"path","required":true,"schema":{"type":"string","title":"Cep"}}],"responses":{"200":{"description":"Endereço do CEP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultaCepOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/consultas/municipio":{"get":{"tags":["consultas"],"summary":"Buscar o código IBGE de um município pelo nome","description":"Traduz nome de município + UF no código IBGE (`cMun`) que a NFS-e exige. É grátis, não vai à\nrede e não consome cota: a tabela oficial do IBGE está embarcada na API.\n\nOs dois parâmetros são obrigatórios: `q` com o nome (3 letras ou mais, 422 `MUNICIPIO_INVALIDO`\nabaixo disso) e `uf` com a sigla de 2 letras (422 `UF_OBRIGATORIA` sem ela). A UF é exigida de\npropósito: municípios homônimos em estados diferentes são comuns.\n\nO casamento é exato, ignorando acento e maiúsculas — não abrevie (\"S. J. da Boa Vista\" não\ncasa) e não invente. Sem correspondência a resposta é 404 `MUNICIPIO_NAO_ENCONTRADO`: confira a\ngrafia ou, se souber o CEP, use `/consultas/cep/{cep}`, que é mais específico. Nunca deduza um\n`cMun` a partir de um código parecido — um dígito trocado é outra cidade e a nota sai errada.","operationId":"consulta_municipio_route_api_v1_consultas_municipio_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","title":"Q"}},{"name":"uf","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uf"}}],"responses":{"200":{"description":"Município encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultaMunicipioOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/municipios/{cmun}":{"get":{"tags":["consultas"],"summary":"Consultar a adesão de um município ao Nacional","description":"Diz como um município está no Sistema Nacional da NFS-e. Consulte ANTES de cadastrar uma\nempresa ou de emitir com a prestação em outra cidade — nem todo município brasileiro está lá.\n\nO `cmun` no caminho é o código IBGE de 7 dígitos; obtenha-o em `/consultas/cep/{cep}` ou\n`/consultas/municipio`, nunca de memória. A rota é grátis e não consome cota de consultas.\n\nSão duas perguntas diferentes, e confundi-las gera rejeição na hora de emitir.\n`emite_pelo_sistema_nacional` responde pela empresa SEDIADA no município: `false` significa que\na prefeitura mantém o sistema próprio: até 31/10/2026, a ME e a EPP de lá ficam na lista de espera;\no MEI emite por aqui em qualquer município, e a ME e a EPP também, a partir de 1º/11/2026.\n`participa_do_ambiente_nacional` responde pelo LOCAL DA PRESTAÇÃO: um município pode aceitar\nnotas com serviço prestado nele sem ser emissor nacional, e o contrário também acontece.\n\nA resposta é servida de um cache de 24 h (`verificado_em` diz de quando é). Se o gov.br não\nresponder e não houver nada em cache, a resposta é 503 `ADN_INDISPONIVEL` — tente de novo em\ninstantes; havendo cache, ele é servido mesmo vencido, em vez de travar o cadastro.","operationId":"consultar_municipio_api_v1_municipios__cmun__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"cmun","in":"path","required":true,"schema":{"type":"string","title":"Cmun"}}],"responses":{"200":{"description":"Situação do município no Sistema Nacional","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MunicipioOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/servicos/sugerir":{"post":{"tags":["servicos"],"summary":"Sugerir o código de serviço pela descrição","description":"Recebe uma descrição livre do serviço (\"consultoria em TI\", \"aula de inglês para empresa\") e\ndevolve até `limit` candidatos do catálogo nacional de serviços, com o código de 6 dígitos que\nvai em `servico.cTribNac`, o nome oficial e a semelhança. É busca semântica sobre o catálogo\noficial (anexo B do leiaute nacional): confirme o candidato com quem conhece o serviço antes de\nemitir — o código decide alíquota, retenções e se o município da prestação precisa ser informado\n(`iss_no_local`).\n\nCusta uma consulta de embedding por chamada; por isso tem teto de 20 por minuto por conta (429\n`RATE_LIMIT`). `descricao` de 3 a 500 caracteres; `limit` de 1 a 10 (padrão 5). Quem já sabe o\ncódigo usa `GET /servicos/codigo/{codigo}` para conferir o nome. 503 quando o serviço de busca\nestá indisponível.","operationId":"sugerir_codigo_api_v1_servicos_sugerir_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SugerirIn"}}},"required":true},"responses":{"200":{"description":"Candidatos do catálogo nacional, do mais parecido para o menos","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SugestaoCodigoOut","additionalProperties":true,"type":"object"},"type":"array","title":"Response 200 Sugerir Codigo Api V1 Servicos Sugerir Post"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"503":{"description":"Serviço externo indisponível ou não configurado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}},"security":[{"ApiKeyBearer":[]}]}},"/api/v1/servicos/codigo/{codigo}":{"get":{"tags":["servicos"],"summary":"Conferir um código de serviço no catálogo","description":"Confere um código de serviço (`cTribNac`, 6 dígitos; aceita com pontos) no catálogo\nnacional e devolve o nome oficial, se o ISS é devido no local da prestação e a família da\nexceção. Use antes de emitir com um código que veio de fora (do contador, de um cadastro\nantigo): 404 `CODIGO_NAO_ENCONTRADO` significa que ele não existe na lista nacional e a emissão\nseria rejeitada. Não custa nada; teto de 20 por minuto por conta.","operationId":"codigo_oficial_api_v1_servicos_codigo__codigo__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","title":"Codigo"}}],"responses":{"200":{"description":"O código existe no catálogo nacional","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodigoServicoOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"429":{"description":"Muitas chamadas — aguarde e repita; ou o teto do dia acabou, e `volta_em` diz quando volta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/reports/nfse":{"get":{"tags":["relatorios"],"summary":"Gerar o relatório de notas do período","description":"Relatório de NFS-e de um período, com os mesmos filtros da lista de notas: totais por\nstatus, quantos clientes diferentes apareceram, o fechamento mês a mês e as notas em si.\nÉ síncrono — a resposta já vem pronta; para um pacote com os XMLs e os PDFs, use\n`POST /api/v1/exports`.\n\n`formato=json` (padrão) devolve `filtros`, `totais`, `por_competencia` e `notas`;\n`formato=csv` devolve o arquivo `text/csv`, separado por ponto e vírgula, com BOM (abre\nacentuado no Excel em português) e uma linha por nota. O período vai em `de` e `ate` no\nformato `AAAA-MM` — `competencia_de`/`competencia_ate` continuam aceitos por compatibilidade,\nmas `de`/`ate` têm precedência — e `periodo_por` escolhe se a faixa vale pela competência\n(padrão) ou pela data de emissão. Filtre ainda por `company_id`, `status` (`ativa`,\n`cancelada`, `substituida`), `origem` (`plataforma` ou `importada`) e `q` (busca no nome do\ncliente, no documento e na descrição do serviço); `limite` (1 a 2000, padrão 500) corta só a\nlista de `notas` do JSON — os totais e o fechamento por competência são sempre do período\ninteiro, e o CSV vem sempre COMPLETO (em streaming, sem teto), ignorando `limite`.\nNotas de teste nunca entram no relatório. Uma empresa fora do seu acesso devolve 403\n`EMPRESA_FORA_DO_RECORTE` e um período fora de `AAAA-MM`, 422 `COMPETENCIA_INVALIDA`.\n\nAs notas trazem `cancelada_em`/`substituida_em` (hora oficial do evento) e `substituida_por`, no\nJSON e no CSV; `periodo_por=evento` monta o relatório do que saiu de ativa no período. As bordas\nde `de`/`ate` valem no horário de Brasília.\n\nO CSV (`formato=csv`) é do contador, para abrir no Excel em português: cabeçalhos em português\n(\"Chave de acesso\", \"Competência\", \"Situação\", \"Retenção do ISS\"…), códigos por extenso (situação,\ntributação e retenção do ISS, tributos aproximados), a coluna \"ISS retido (R$)\" com o valor em reais\nque o contador soma (o apurado na nota; vazia quando não há retenção), separador `;`, competência\n`dd/mm/aaaa` e as outras datas em Brasília `dd/mm/aaaa hh:mm`, vírgula decimal, texto sem quebras de linha, a nota que\nsubstituiu pelo número, e chave, CPF/CNPJ e código do serviço (`01.05.01`) como texto por fórmula\n(`=\"…\"`) para o Excel não virar notação científica nem perder o zero à esquerda. Para integrar por\nmáquina use o JSON, que mantém os nomes técnicos, UTC e ponto decimal.","operationId":"relatorio_nfse_api_v1_reports_nfse_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"de","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"AAAA-MM","title":"De"},"description":"AAAA-MM"},{"name":"ate","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"AAAA-MM","title":"Ate"},"description":"AAAA-MM"},{"name":"competencia_de","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"AAAA-MM (legado; de/ate têm precedência)","title":"Competencia De"},"description":"AAAA-MM (legado; de/ate têm precedência)"},{"name":"competencia_ate","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"AAAA-MM (legado)","title":"Competencia Ate"},"description":"AAAA-MM (legado)"},{"name":"periodo_por","in":"query","required":false,"schema":{"type":"string","pattern":"^(competencia|emissao|evento)$","default":"competencia","title":"Periodo Por"}},{"name":"company_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(ativa|cancelada|substituida)$"},{"type":"null"}],"title":"Status"}},{"name":"origem","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(plataforma|importada)$"},{"type":"null"}],"title":"Origem"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"formato","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|csv)$","default":"json","title":"Formato"}},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"default":500,"title":"Limite"}}],"responses":{"200":{"description":"O relatório: JSON com totais, fechamento por competência e as notas (`formato=json`), ou o arquivo CSV com uma linha por nota (`formato=csv`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatorioNfseOut"}},"text/csv":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/exports":{"post":{"tags":["relatorios"],"summary":"Pedir a exportação de notas em ZIP","description":"Pede um pacote ZIP com as notas do período: os XMLs autorizados, os DANFSE em PDF\n(a menos que `incluir_pdf` seja `false`), um `relatorio.csv` com uma linha por nota e um\n`relatorio.html` para ler e imprimir, com os totais do período e link para cada arquivo do pacote.\nA montagem é assíncrona — a resposta 202 sai na hora, com o `id` da exportação, e o\npacote fica pronto alguns segundos ou minutos depois.\n\nO fluxo tem três passos: chame este endpoint, acompanhe `GET /api/v1/exports/{export_id}`\naté `status` virar `concluido` e então baixe em `GET /api/v1/exports/{export_id}/download`.\nFiltre por competência (`competencia_de`/`competencia_ate`, em `AAAA-MM`), por empresa e\npor status; sem filtro nenhum, o pacote pega tudo o que você pode ver. Acima do tamanho do\nvolume (2.000 notas só com XML, 1.000 com os PDFs) o pacote sai em **volumes** — um por mês, no\neixo do recorte — e nunca cortado: veja `volumes` em `GET /api/v1/exports/{export_id}`.\nNotas de teste ficam de fora e a exportação nunca ultrapassa o seu recorte de empresas —\npedir uma empresa fora dele devolve 403 `EMPRESA_FORA_DO_RECORTE`. Quando o pacote fica\npronto, quem pediu recebe um e-mail com o relatório anexo e o link de download, na própria conta (numa\nempresa compartilhada, a pessoa com acesso; por chave de API, quem criou a chave) — se o aviso\n\"Exportação pronta\" estiver ligado nas Notificações dela.\n\nAlém da competência, o pacote aceita a faixa da listagem: `periodo_por` (`competencia`,\n`emissao` ou `evento`) com `de`/`ate` (`AAAA-MM` ou `AAAA-MM-DD`, bordas no horário de Brasília).\n`periodo_por=evento` monta o pacote do que foi cancelado ou substituído no período — com os XMLs\ndos eventos em `eventos/`. Misturar os dois jeitos de faixa devolve 422 `FILTROS_CONFLITANTES`.\nNo ZIP, as ativas ficam na raiz de `xml/` e `pdf/`; canceladas e substituídas em subpastas.","operationId":"criar_export_api_v1_exports_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportIn"}}},"required":true},"responses":{"202":{"description":"Pedido aceito: a exportação entrou na fila","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportCriadoOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}},"security":[{"ApiKeyBearer":[]}]}},"/api/v1/exports/{export_id}":{"get":{"tags":["relatorios"],"summary":"Consultar o estado de uma exportação","description":"Diz em que pé está uma exportação pedida em `POST /api/v1/exports`. Consulte de tempos\nem tempos (alguns segundos entre uma chamada e outra) até `status` virar `concluido` — só\naí o download funciona.\n\n`status` vale `pendente` (na fila), `processando` (montando o ZIP), `concluido` (pronto,\ncom `total_notas` preenchido) ou `erro`, e nesse caso o campo `erro` traz o motivo em\nportuguês. Esta chamada não recomeça nada: uma exportação que terminou em `erro` precisa\nser pedida de novo. Exportação inexistente ou de outra conta devolve 404\n`EXPORT_NAO_ENCONTRADO`; de empresa fora do seu acesso, 403 `EMPRESA_FORA_DO_RECORTE`.\n\nAcima do tamanho do volume (2.000 notas só com XML, 1.000 com os PDFs) o pacote vem em\n`volumes` (um por mês, no eixo do recorte; mês grande em partes), nunca cortado: o primeiro\nitem é o `resumo` (relatório do período inteiro + CSV completo) e os demais trazem os arquivos\nde cada mês. Baixe cada um em `GET …/download?volume=`. `total_no_recorte` é sempre igual a\n`total_notas`; ficou pela compatibilidade.","operationId":"status_export_api_v1_exports__export_id__get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"export_id","in":"path","required":true,"schema":{"type":"string","title":"Export Id"}}],"responses":{"200":{"description":"O estado atual da exportação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/exports/{export_id}/download":{"get":{"tags":["relatorios"],"summary":"Baixar o ZIP de uma exportação","description":"Baixa o pacote pronto de uma exportação. A resposta é um **302**: o `Location` aponta o arquivo\nnum link temporário do armazenamento (vale 5 minutos), e a API não relê o pacote para servi-lo.\nSiga o redirecionamento — `curl -L`, ou `requests`/`httpx` com redirecionamento ligado (os dois\nnão repassam a sua chave para o outro endereço) — e grave os bytes em disco: o arquivo é\n`application/zip`, NÃO é JSON. O nome do arquivo fica por sua conta (o link não sugere um). Não\nguarde o link do `Location`: para baixar de novo, chame esta rota de novo.\n\nDentro do ZIP vêm `relatorio.html` (o relatório do período para ler e imprimir: os totais, o\nfechamento por competência e a lista de notas, cada uma com link para os arquivos deste mesmo\npacote), `relatorio.csv` (uma linha por nota, com a situação, quando foi cancelada ou\nsubstituída e o número da nota que substituiu), `xml/` e `pdf/` com as notas ATIVAS, `xml/canceladas/` e\n`xml/substituidas/` (e o mesmo em `pdf/`) com as que saíram de ativa, e `eventos/` com o XML de\ncada cancelamento ou substituição — quem importa `xml/` sem recursão recebe só o que vale, e o\nsistema contábil que também lê `eventos/` fica com a prova. PDFs só quando a exportação foi\npedida com `incluir_pdf`. Cada arquivo é nomeado pela data de emissão (Brasília), número oficial\nda nota e chave de acesso — a ordem alfabética segue a numeração. O `relatorio.csv` é do contador e\nabre no Excel em português: cabeçalhos em português, códigos por extenso, competência `dd/mm/aaaa`,\ndatas em Brasília `dd/mm/aaaa hh:mm`, vírgula decimal, o ISS retido em reais, texto numa linha só, e\nchave, CPF/CNPJ e código do serviço como texto por fórmula `=\"…\"`. Só funciona com a\nexportação em `concluido`: enquanto ela estiver `pendente`, `processando` ou em `erro`, a\nresposta é 409 `EXPORT_NAO_CONCLUIDO`. Exportação inexistente devolve 404\n`EXPORT_NAO_ENCONTRADO` e empresa fora do seu acesso, 403 `EMPRESA_FORA_DO_RECORTE`.\n\n**Pacote em volumes** (veja `volumes` em `GET /api/v1/exports/{export_id}`): sem `volume`, ou com\n`volume=resumo`, vem o resumo — `relatorio.html` do período inteiro e o `relatorio.csv` completo;\n`volume=1`, `2`, … traz os arquivos de cada volume, na ordem da lista (cada um com a sua\n`listagem.html`, `listagem.csv`, `xml/`, `pdf/` e `eventos/`). Um número fora da lista devolve 404\n`VOLUME_NAO_ENCONTRADO`.","operationId":"download_export_api_v1_exports__export_id__download_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"export_id","in":"path","required":true,"schema":{"type":"string","title":"Export Id"}},{"name":"volume","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Num pacote em volumes: `resumo`, ou o número do volume (`1`, `2`, …) na ordem de `volumes`. Ausente = o resumo. Num pacote de um arquivo só, ignorado","title":"Volume"},"description":"Num pacote em volumes: `resumo`, ou o número do volume (`1`, `2`, …) na ordem de `volumes`. Ausente = o resumo. Num pacote de um arquivo só, ignorado"}],"responses":{"200":{"description":"O pacote ZIP (`relatorio.html`, `relatorio.csv`, `xml/…`, `pdf/…`), entregue pelo armazenamento DEPOIS do redirecionamento 302","content":{"application/zip":{}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"302":{"description":"Redireciona (`Location`) para o arquivo num link temporário do armazenamento, válido por 5 minutos — siga o redirecionamento; para baixar de novo, chame esta rota de novo"},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/exports/{export_id}/link":{"get":{"tags":["relatorios"],"summary":"Pegar o link temporário do ZIP de uma exportação","description":"O mesmo arquivo de `GET /exports/{export_id}/download`, mas o link vem no corpo, em JSON, em vez\nde um redirecionamento 302. É para quem não consegue seguir o redirecionamento sem repassar a\nprópria chave — o navegador, por exemplo: o painel pede o link aqui e abre o endereço, e o\narquivo baixa como anexo, com o nome de `arquivo`. O link vale 5 minutos e não leva a sua chave;\npara baixar de novo, peça outro. As mesmas regras do download: 409 `EXPORT_NAO_CONCLUIDO` antes de\n`concluido`, 404 `EXPORT_NAO_ENCONTRADO`, 403 `EMPRESA_FORA_DO_RECORTE` e, num pacote em volumes,\n`volume` como no download (404 `VOLUME_NAO_ENCONTRADO` fora da lista).","operationId":"link_export_api_v1_exports__export_id__link_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"export_id","in":"path","required":true,"schema":{"type":"string","title":"Export Id"}},{"name":"volume","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Num pacote em volumes: `resumo`, ou o número do volume (`1`, `2`, …) na ordem de `volumes`. Ausente = o resumo. Num pacote de um arquivo só, ignorado","title":"Volume"},"description":"Num pacote em volumes: `resumo`, ou o número do volume (`1`, `2`, …) na ordem de `volumes`. Ausente = o resumo. Num pacote de um arquivo só, ignorado"}],"responses":{"200":{"description":"O link temporário do arquivo, em JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkDoPacoteOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/automations":{"get":{"tags":["automacoes"],"summary":"Listar as automações da conta","description":"Lista tudo o que roda sozinho na conta — tanto as emissões recorrentes (uma NFS-e por mês\npara um cliente fixo) quanto os relatórios agendados —, cada uma com a agenda, a próxima\nexecução e um resumo da última vez que rodou. Com uma chamada só dá para montar um painel de\nautomações, sem consultar item por item.\n\nO campo `tipo` separa as duas famílias: `emissao_recorrente` traz o conteúdo da nota em\n`params` (empresa, tomador, serviço, valor); `relatorio` traz em `definicao` o período e os\ndestinatários do e-mail. `ativo` diz se está rodando, e `pausada_por` explica quando a pausa\nfoi automática (`falhas` seguidas ou `fatura` vencida) em vez de manual. `campos_pendentes`\ncom `valor` significa que a automação pergunta o valor antes de emitir, em vez de emitir\nsozinha. O parâmetro `ordem` aceita `criado_desc` (padrão, as mais recentes primeiro),\n`proxima_asc` (a que dispara primeiro no topo) ou `nome_asc`. Devolve no máximo 200\nautomações, sem paginação, e só as das empresas que você pode ver: o relatório de todas as\nempresas (a definição sem `company_id`) só aparece para quem vê todas as empresas da conta.","operationId":"listar_automacoes_api_v1_automations_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"ordem","in":"query","required":false,"schema":{"enum":["criado_desc","proxima_asc","nome_asc"],"type":"string","default":"criado_desc","title":"Ordem"}}],"responses":{"200":{"description":"As automações da conta, na ordem pedida","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true,"$ref":"#/components/schemas/AutomacaoOut"},"title":"Response 200 Listar Automacoes Api V1 Automations Get"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/automations/recorrente":{"post":{"tags":["automacoes"],"summary":"Criar uma automação de emissão recorrente","description":"Cria uma automação que emite, todo mês no `dia` informado (1 a 28), uma nota para o\ntomador `tomador_documento` (CPF só com números; CNPJ com 14 caracteres, sem pontuação) pela empresa da última nota emitida\npara ele — a automação copia dessa nota a empresa, o NBS e o nome do tomador.\n\nPasse `company_id` em conta com mais de uma empresa: com ele, a nota-base é a mais nova do\ntomador NESSA empresa, e a automação emite por ela; sem ele, é a mais nova entre todas as\nempresas do seu acesso, que pode ser de outra emissora. Com `company_id`, empresa fora do seu\nacesso devolve 403 `EMPRESA_FORA_DO_RECORTE`, e empresa sem nota para o tomador, 404\n`PADRAO_NAO_ENCONTRADO`.\n\nCom `valor`, a nota sai sozinha; sem `valor`, a automação pergunta o valor ao dono a cada\nrodada antes de emitir. `cTribNac` e `descricao` são opcionais: sem eles, a automação usa o\nserviço e a descrição da última nota emitida para esse tomador. Sem nota anterior para o\ntomador, 404 `PADRAO_NAO_ENCONTRADO` (emita a primeira pelo Emitir). `tributacao` sobrepõe a\ntributação da última nota; `entrega_tomador` liga o envio por e-mail ao cliente (padrão: liga\nse o cadastro tiver e-mail); `avisos` ajusta os avisos ao dono.\n\nSem `tributacao`, a retenção do ISS vem das notas do tomador na mesma empresa, quando todas\nforam retidas. Com retenção (decidida ou do histórico), o tomador precisa de endereço completo\nno cadastro (422 `RETENCAO_SEM_TOMADOR`) e de `pAliq` (422 `ALIQUOTA_OBRIGATORIA`) — menos na\nME/EPP no DAS que tem o ISS do mês: aí cada disparo usa o ISS do mês da prestação, e a `pAliq`,\nse vier, só vale quando a empresa não tiver ISS naquele mês. Com o ISS fora do DAS, a `pAliq`\né a alíquota do município.\n\nExige escopo `emissao`. Conta no limite de automações do plano (402 `LIMITE_DO_PLANO`;\npausadas também contam). Já existe automação ativa para o mesmo tomador e serviço → 409\n`AUTOMACAO_DUPLICADA` (com acesso a só algumas empresas — membro recortado ou empresa\ncompartilhada —, a duplicata é procurada nas automações dessas empresas). Valor não positivo\n→ 422 `VALOR_INVALIDO`.","operationId":"criar_recorrente_api_v1_automations_recorrente_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"company_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecorrenteIn"}}}},"responses":{"201":{"description":"Automação criada e agendada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomacaoCriadaOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/automations/{automation_id}":{"patch":{"tags":["automacoes"],"summary":"Editar, pausar ou reativar uma automação","description":"Altera uma automação existente. O corpo é um objeto solto com apenas os campos que você\nquer mudar; qualquer outro campo é ignorado em silêncio. São aceitos: `ativo` (`false` pausa,\n`true` reativa), `nome`, `cron` (a nova agenda, 5 campos, horário de Brasília), `params` (o\nconteúdo da emissão recorrente — `company_id`, `tomador`, `servico`, `valor` e os opcionais\n`tributacao`, `competencia` e `local`), `campos_pendentes` (`[\"valor\"]` faz a automação\nperguntar o valor antes de emitir, `[\"complemento\"]` idem para as informações complementares,\nlista vazia deixa tudo fixo), `avisos` e `entrega_tomador`.\n\nPausar e reativar passa por aqui: `{\"ativo\": false}` para a automação sem apagar nada e\n`{\"ativo\": true}` religa, zera a contagem de falhas e reagenda a partir de agora — nunca no\nminuto seguinte por causa de uma agenda velha; mudar o `cron` reagenda do mesmo jeito — e, numa\nrecorrente de uma nota por mês cuja nota deste mês já saiu, a agenda nova começa no mês seguinte:\nmudar o dia nunca emite uma segunda nota no mesmo mês. Numa\nautomação de emissão recorrente, mexer em `params` ou em `cron` revalida o conteúdo da nota\nna hora de salvar (serviço, valor, itens, retenção, competência e local), de modo que um 422\naqui evita uma rejeição no dia do disparo — e o tomador de uma automação nunca muda: para\noutro cliente, crie outra automação. Se houver uma emissão esperando resposta, o campo\n`pendencia_aberta` da resposta avisa que ela sairá com os dados novos. Corpo sem nenhum campo\nconhecido devolve 422 `NADA_A_ALTERAR`; automação inexistente, 404\n`AUTOMACAO_NAO_ENCONTRADA`; automação de empresa fora do seu acesso, ou `params.company_id`\ntrocado para uma delas, 403 `EMPRESA_FORA_DO_RECORTE` — e o relatório de todas as empresas só\né alterado (ou pausado) por quem vê todas as empresas da conta; reativar uma automação que foi\npausada por fatura vencida devolve 402 `PAUSADA_POR_FATURA`. Precisa de chave com escopo\n`emissao`.","operationId":"alterar_automacao_api_v1_automations__automation_id__patch","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","title":"Automation Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"A automação depois da alteração, com a agenda recalculada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomacaoOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"402":{"description":"O plano da conta não inclui isto, o teto do plano (empresas, automações, acessos) foi atingido ou a cota do mês acabou — veja `hint`, `upgrade` e `volta_em`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}},"delete":{"tags":["automacoes"],"summary":"Excluir uma automação","description":"Apaga a automação e todo o histórico de execuções dela. As notas já emitidas NÃO são\nafetadas: continuam válidas e nada é cancelado no Sistema Nacional. Uma emissão que estava\nesperando resposta (o valor do mês, por exemplo) é descartada — ninguém deve responder a uma\nautomação que não existe mais.\n\nExcluir é a única forma de liberar uma vaga na contagem de automações do plano; pausar não\nlibera. Não há como desfazer, então para parar só por um tempo prefira\n`PATCH /api/v1/automations/{automation_id}` com `{\"ativo\": false}`. Automação inexistente\ndevolve 404 `AUTOMACAO_NAO_ENCONTRADA` e empresa fora do seu acesso, 403\n`EMPRESA_FORA_DO_RECORTE` — inclusive o relatório de todas as empresas, que só quem vê todas as\nempresas da conta exclui. Precisa de chave com escopo `emissao`.","operationId":"excluir_automacao_api_v1_automations__automation_id__delete","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","title":"Automation Id"}}],"responses":{"200":{"description":"A automação e o histórico dela foram apagados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomacaoExcluidaOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/automations/{automation_id}/run":{"post":{"tags":["automacoes"],"summary":"Rodar uma automação agora","description":"Dispara a automação na hora, ignorando o cron. Isto EMITE DE VERDADE: numa automação de\nemissão recorrente sai uma NFS-e real no Sistema Nacional, que consome cota, avisa quem está\nna lista de avisos e só sai da vida do cliente por cancelamento — não é uma simulação.\nFunciona também em automação pausada, o que serve para conferir um conserto antes de\nreativar, e a agenda seguinte é recalculada normalmente.\n\nA resposta traz o `desfecho`: `emitida` (com `nfse_id` e `numero`, o número oficial da nota),\n`pendencia` (faltava o valor do mês, veja `pendencia_id`), `em_fila` (automação de relatório: o\npacote entrou na fila e o e-mail sai quando ele fica pronto — acompanhe em `runs`, onde a execução\nvira `relatorio_enviado`, `relatorio_parcial` ou `relatorio_nao_entregue`), `falha` (com `erro_codigo`) ou `pulada` (a conta não podia emitir agora,\npor cota ou por pagamento, ou a empresa do Simples está sem alíquota nenhuma —\n`ALIQUOTA_NAO_CONFIRMADA` —, numa nota retida, sem o ISS do mês — `ALIQUOTA_ISS_DO_MES_AUSENTE` — ou, desde\n1º/11/2026, o Sistema Nacional ainda recusa pelo convênio a ME/EPP de cidade sem adesão — `E0016`, `E0037`, `E0038`\nou `E0039`). Rodar agora repete o relatório mesmo que ele já tenha saído hoje. Uma\nexecução malsucedida NÃO vira erro HTTP: a chamada devolve 200 com `desfecho: falha` — sempre\nleia o campo antes de dar o disparo por bem-sucedido. Se a mesma automação já estiver rodando\n(o agendador chegou primeiro, ou outra chamada sua), a resposta é 409 `AUTOMACAO_OCUPADA`:\nespere alguns segundos e consulte `GET /api/v1/automations/{automation_id}/runs`. Precisa de\nchave com escopo `emissao` — chave de `leitura` recebe 403 `PERMISSAO_NEGADA` —, automação\ninexistente devolve 404 `AUTOMACAO_NAO_ENCONTRADA` e a de empresa fora do seu acesso, 403\n`EMPRESA_FORA_DO_RECORTE` — inclusive o relatório de todas as empresas, que só quem vê todas as\nempresas da conta roda.\n\n**Antecipar** (corpo `{\"ocorrencia\": \"<proxima_execucao>\"}`): numa emissão recorrente ativa, a nota\nda próxima ocorrência sai agora e a ocorrência fica feita — no dia dela, nada sai de novo. Rodar\nsem o corpo NÃO tira a próxima ocorrência da agenda: a nota dela também sai no dia. Só se antecipa\na nota do mês corrente, e nunca na regra de competência do mês anterior, porque a nota sairia com\na competência que já saiu: fora disso, 422 `ANTECIPACAO_FORA_DA_COMPETENCIA`. Se a agenda já andou\ndesde que você a leu, 409 `OCORRENCIA_MUDOU`; automação pausada ou de relatório, 422. Saindo a\nnota, a resposta traz `antecipada` e a nova `proxima_execucao`; não saindo, a nota continua no dia\ndela. A exceção é a falha `EMISSAO_INCERTA` (o Sistema Nacional não respondeu e a nota pode ter\nsaído): a ocorrência fica feita, e a nova tentativa em cerca de 1 hora confere a nota antes de emitir.","operationId":"rodar_uma_api_v1_automations__automation_id__run_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","title":"Automation Id"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/RodarIn"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"O desfecho da execução — inclusive quando ela falhou","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomacaoExecucaoOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/automations/{automation_id}/pular":{"post":{"tags":["automacoes"],"summary":"Pular a próxima nota de uma emissão recorrente","description":"Pula UMA nota de uma emissão recorrente: a ocorrência informada não sai, e a agenda passa\npara a seguinte. Nada é emitido nem cancelado, e o histórico de execuções não ganha linha — o\npulo fica na trilha de atividades. Mande em `ocorrencia` o `proxima_execucao` que a automação\nmostra agora: se a agenda já andou (a nota saiu, ou alguém pulou antes), a resposta é 409\n`OCORRENCIA_MUDOU`, e nada muda — recarregue e decida de novo. Se a automação estiver rodando\nneste instante, 409 `AUTOMACAO_OCUPADA`. Reativar a automação ou mudar a agenda depois não traz\na nota pulada de volta: na recorrente de uma nota por mês, nenhuma outra sai no mês da pulada.\nCom uma nota esperando (a execução saiu `pulada` ou `falha` e a automação tenta de novo), a agenda\nmostra a nova tentativa, e pular é pular a nota que espera: `pulada` traz a data dela.\nO pedido de valor que já está aberto se pula em\n`POST /api/v1/emissoes-pendentes/{pendencia_id}/pular`.\n\nSó vale para automação de emissão recorrente ativa: a de relatório ou a pausada devolve 422.\nAutomação inexistente devolve 404 `AUTOMACAO_NAO_ENCONTRADA` e a de empresa fora do seu\nacesso, 403 `EMPRESA_FORA_DO_RECORTE`. Precisa de chave com escopo `emissao`.","operationId":"pular_ocorrencia_api_v1_automations__automation_id__pular_post","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","title":"Automation Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PularIn"}}}},"responses":{"200":{"description":"A nota pulada e a próxima execução","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomacaoPuladaOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"404":{"description":"Não encontrado nesta conta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"409":{"description":"Conflito com o estado atual (ex.: nota já cancelada, empresa inativa, emissão em andamento)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/automations/{automation_id}/runs":{"get":{"tags":["automacoes"],"summary":"Listar as execuções de uma automação","description":"Histórico de uma automação, da execução mais recente para a mais antiga: quando rodou, se\no disparo foi automático ou manual, o desfecho e o que saiu dali. É por aqui que se confere\nse a nota do mês saiu, ou se investiga uma falha.\n\nCada item traz `desfecho` (`emitida`, `pendencia`, `relatorio_enviado`, `relatorio_parcial`,\n`relatorio_nao_entregue`, `em_fila`, `repetida`, `falha` ou `pulada`), `disparo` (`agendado` ou\n`manual`), `numero` — o número oficial da NFS-e — e `valor` nas emissões, `notas` nos relatórios, e\n`erro_codigo` mais `erro_msg`, já em português, quando deu errado. O relatório mensal nasce `em_fila`\n(o pacote é montado numa fila) e, quando sai, vira o que o provedor de e-mail aceitou:\n`relatorio_enviado` (todos os destinos), `relatorio_parcial` (parte deles — `erro_msg` diz quem ficou\nsem) ou `relatorio_nao_entregue` (nenhum; conta como falha e tenta de novo em 1 hora). O e-mail aos\ndestinos sai mesmo com os avisos desligados: é a entrega, não um aviso. `repetida` é o relatório da\nmesma definição que já saiu no dia.\n`pulada` não é falha da automação: é a conta que não podia emitir naquela hora, por cota ou por\npagamento, a empresa do Simples sem alíquota nenhuma (`erro_codigo` `ALIQUOTA_NAO_CONFIRMADA`), numa nota\nretida, sem o ISS do mês (`ALIQUOTA_ISS_DO_MES_AUSENTE`) ou, desde 1º/11/2026, a ME/EPP de cidade sem adesão que o\nSistema Nacional ainda recusa pelo convênio (`erro_codigo` `E0016`, `E0037`, `E0038` ou `E0039`) — tenta de novo no\ndia seguinte. A paginação é por `limit` (1 a 100, padrão 20) e `skip`, e `total`\né a contagem completa, independente da página. Automação inexistente — ou já excluída, já que\no histórico vai junto — devolve lista vazia, não 404; pedir o histórico de uma automação de\nempresa fora do seu acesso devolve 403 `EMPRESA_FORA_DO_RECORTE` — inclusive o do relatório de\ntodas as empresas, que só quem vê todas as empresas da conta acompanha.","operationId":"listar_execucoes_api_v1_automations__automation_id__runs_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string","title":"Automation Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Skip"}}],"responses":{"200":{"description":"A página pedida do histórico, da execução mais recente para a mais antiga","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomacaoRunsOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/api/v1/atividades":{"get":{"tags":["atividades"],"summary":"Listar a trilha de atividades da conta","description":"Lista o que aconteceu na conta, do mais recente para o mais antigo: notas emitidas e\ncanceladas, exportações pedidas, automações que rodaram, membros que entraram, cadastros\nalterados. Serve tanto para um feed de \"últimas atividades\" quanto para uma tela de auditoria.\n\nA paginação é por `limit` (1 a 100, padrão 10) e `skip`, e `total` traz a contagem completa\ndos filtros, independente da página. Filtros disponíveis: `company_id` (uma empresa — que\ntambém devolve os eventos da conta inteira, gravados sem empresa), `user_id` (quem fez),\n`tipo` (um ou vários, separados por vírgula) e o período `de`/`ate` em `AAAA-MM-DD`, com\n`ate` inclusivo. Numa empresa compartilhada por outra conta, a trilha da conta inteira dela\nfica de fora: vêm os eventos da empresa e, dos gravados sem empresa, só os que você mesmo fez;\nos de gestão de acesso da empresa (quem recebeu acesso, com que papel) também ficam de fora.\nQuem não é dono da conta nunca recebe eventos de cobrança, mesmo pedindo por eles em `tipo`.\nPedir uma empresa fora do seu acesso devolve 403 `EMPRESA_FORA_DO_RECORTE`; sem chave válida,\n401.","operationId":"listar_atividades_api_v1_atividades_get","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Skip"}},{"name":"company_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"}},{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"}},{"name":"tipo","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo"}},{"name":"de","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"De"}},{"name":"ate","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ate"}}],"responses":{"200":{"description":"A página pedida da trilha, do evento mais recente para o mais antigo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtividadesOut"}}}},"401":{"description":"Chave de API ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"403":{"description":"Sem permissão: escopo da chave (leitura × emissão), papel de quem a criou ou empresa fora do seu acesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}},"422":{"description":"Dados inválidos — `erros` aponta o campo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroOut"}}}}}}},"/health":{"get":{"tags":["meta"],"summary":"Conferir a saúde do serviço","description":"Diz se o serviço está de pé. É a única rota sem autenticação — feita para monitor externo\ne para o seu \"smoke test\" antes de integrar.\n\nDevolve `status` (`ok` ou `degraded`), a versão da API e do núcleo de emissão e o ambiente\nque respondeu. `degraded` quer dizer serviço no ar com algo defeituoso atrás: banco\nindisponível ou agendador de automações sem sinal há mais de 5 minutos (`scheduler_ha_s` diz\nhá quantos segundos foi o último). O código HTTP é 200 nos dois casos, então alarme pelo\ncampo `status`, nunca pelo código HTTP.","operationId":"health_health_get","responses":{"200":{"description":"O serviço respondeu (veja o campo `status`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthOut"}}}}},"security":[]}}},"components":{"schemas":{"AcaoEmGrupoIn":{"properties":{"acao":{"type":"string","enum":["codigo","descricao","data","ignorar","incluir","atualizar_cadastro","manter_cadastro","usar_cadastro","trocar_na_descricao"],"title":"Acao"},"itens":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":200},{"type":"null"}],"title":"Itens"},"valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor"},"de":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"De","description":"trocar_na_descricao: o texto que sai"},"para":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Para","description":"trocar_na_descricao: o texto que entra"}},"type":"object","required":["acao"],"title":"AcaoEmGrupoIn"},"AcaoEmGrupoOut":{"properties":{"mudou":{"type":"integer","title":"Mudou","description":"Quantas linhas a ação mudou"},"contagens":{"anyOf":[{"$ref":"#/components/schemas/ContagensDoLoteOut"},{"additionalProperties":true,"type":"object"}],"title":"Contagens","description":"As linhas por situação, depois da ação"}},"type":"object","required":["mudou","contagens"],"title":"AcaoEmGrupoOut"},"AlertaNotaOut":{"properties":{"tipo":{"type":"string","title":"Tipo","description":"\"email_nao_chegou\", \"iss_de_outro_mes\", \"aliquota_aplicada_diferente\", \"cancelada_pela_prefeitura\" ou \"em_dobro\""},"titulo":{"type":"string","title":"Titulo","description":"O nome curto do problema, o do selo na tela (ex.: \"E-mail não chegou\")"},"texto":{"type":"string","title":"Texto","description":"O que aconteceu e o que fazer, em uma ou duas frases"},"para":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Para","description":"No e-mail que não chegou: o endereço do último envio"},"situacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Situacao","description":"No e-mail que não chegou: \"devolvido\" (o destino recusou), \"spam\" ou \"falhou\" (o provedor recusou)"},"em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Em","description":"Quando: a notícia do e-mail (devolução, spam, recusa) ou o cancelamento por ofício (UTC)"},"nota_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nota Id","description":"No em dobro: a outra nota (nfse_…)"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"No em dobro: o número oficial da outra nota"}},"additionalProperties":true,"type":"object","required":["tipo","titulo","texto"],"title":"AlertaNotaOut","description":"Um problema da nota: o nome curto (o selo da tela), o que aconteceu e o que fazer."},"ArquivoDoLoteOut":{"properties":{"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"O nome do arquivo enviado (ou o `nome` das linhas em JSON)"},"tipo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo","description":"\"xlsx\", \"csv\" ou \"json\""},"tamanho":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tamanho","description":"O tamanho do arquivo, em bytes"}},"type":"object","title":"ArquivoDoLoteOut"},"AtividadesOut":{"properties":{"total":{"type":"integer","title":"Total","description":"Total de eventos que casam com os filtros, ignorando `limit`/`skip`"},"itens":{"items":{"$ref":"#/components/schemas/gerenota_api__atividades__AtividadeOut"},"type":"array","title":"Itens","description":"Eventos da página, do mais recente para o mais antigo"}},"additionalProperties":true,"type":"object","required":["total","itens"],"title":"AtividadesOut","description":"Uma página da trilha de atividades."},"AutomacaoCriadaOut":{"properties":{"id":{"type":"string","title":"Id","description":"Id da automação (use em /automations/{id}/…)"},"nome":{"type":"string","title":"Nome","description":"Nome exibido no painel e nos avisos"},"cron":{"type":"string","title":"Cron","description":"Agenda em cron de 5 campos, derivada do dia do mês informado"},"proxima_execucao":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Proxima Execucao","description":"Quando a próxima nota sai (UTC)"},"com_lacuna":{"type":"boolean","title":"Com Lacuna","description":"True quando a automação pergunta o valor a cada rodada (criada sem `valor`)","default":false}},"additionalProperties":true,"type":"object","required":["id","nome","cron"],"title":"AutomacaoCriadaOut","description":"O que volta ao criar uma automação de emissão recorrente."},"AutomacaoDefinicaoOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da definição de relatório"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Nome do relatório"},"periodo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Periodo","description":"`mes_fechado` (o mês anterior, já fechado) ou `mes_atual` (o mês corrente, parcial)"},"periodo_por":{"type":"string","title":"Periodo Por","description":"O que o mês significa: `competencia` (fechamento fiscal), `emissao` ou `evento` (o que foi cancelado ou substituído no mês)","default":"competencia"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Situação única do relatório (`ativa`, `cancelada`, `substituida`); `null` = todas"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Empresa do relatório; `null` = todas as empresas"},"incluir_zip":{"type":"boolean","title":"Incluir Zip","description":"Se o e-mail leva o pacote ZIP anexado","default":false},"destinos":{"items":{"type":"string"},"type":"array","title":"Destinos","description":"E-mails que recebem o relatório a cada disparo"}},"additionalProperties":true,"type":"object","required":["id"],"title":"AutomacaoDefinicaoOut","description":"O relatório que a automação envia — só existe em automações de `tipo: relatorio`."},"AutomacaoExcluidaOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da automação excluída"},"excluida":{"type":"boolean","title":"Excluida","description":"Sempre `true`"}},"additionalProperties":true,"type":"object","required":["id","excluida"],"title":"AutomacaoExcluidaOut","description":"Confirmação da exclusão."},"AutomacaoExecucaoOut":{"properties":{"automation_id":{"type":"string","title":"Automation Id","description":"A automação que rodou"},"run_id":{"type":"string","title":"Run Id","description":"Identificador desta execução (prefixo `run_`), o mesmo do histórico"},"desfecho":{"type":"string","title":"Desfecho","description":"`emitida`, `pendencia`, `em_fila` (automação de relatório: o pacote entrou na fila — acompanhe em `runs`, onde a execução vira `relatorio_enviado`, `relatorio_parcial` ou `relatorio_nao_entregue` pelo que o provedor de e-mail aceitou), `falha` ou `pulada`. Rodar agora sempre repete, então aqui não aparece `repetida`"},"nfse_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nfse Id","description":"Nota emitida — use em `GET /api/v1/nfse/{nfse_id}` para o XML e o PDF"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial (nNFSe) da nota emitida"},"ndps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ndps","description":"Sequência interna da DPS da nota emitida"},"pendencia_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pendencia Id","description":"A emissão que ficou esperando resposta, quando o desfecho foi `pendencia`"},"notas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Notas","description":"Quantas notas entraram no relatório enviado"},"erro_codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Erro Codigo","description":"Código do erro quando o desfecho foi `falha` ou `pulada`"},"erro_msg":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Erro Msg","description":"Motivo em português da falha ou do pulo — o mesmo texto do histórico"},"observacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Observacao","description":"O que a execução diz além do desfecho: o município do cliente que mudou pela Receita (a nota saiu com o endereço novo, que é o do cadastro do CNPJ) — uma vez só por mudança"}},"additionalProperties":true,"type":"object","required":["automation_id","run_id","desfecho"],"title":"AutomacaoExecucaoOut","description":"O resultado de uma execução disparada na hora."},"AutomacaoOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da automação (prefixo `aut_`)"},"nome":{"type":"string","title":"Nome","description":"Nome que aparece na lista"},"tipo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo","description":"`emissao_recorrente` (emite uma NFS-e) ou `relatorio` (envia um relatório por e-mail)"},"ativo":{"type":"boolean","title":"Ativo","description":"`false` = pausada: continua existindo, mas não dispara na agenda"},"cron":{"type":"string","title":"Cron","description":"A agenda em cron de 5 campos, no horário de Brasília"},"agenda":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agenda","description":"A mesma agenda em português, ex.: `todo dia 5 às 08:00`"},"proxima_execucao":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Proxima Execucao","description":"Quando a automação dispara da próxima vez, em UTC (ISO 8601)"},"last_run":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Run","description":"Última execução com desfecho final, em UTC"},"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Params","description":"O conteúdo da emissão recorrente: `company_id`, `tomador`, `servico`, `valor`, e os opcionais `tributacao`, `competencia` e `local`. `null` em automações de relatório"},"campos_pendentes":{"items":{"type":"string"},"type":"array","title":"Campos Pendentes","description":"O que a automação pergunta antes de emitir, em vez de assumir: `valor` e/ou `complemento`. Lista vazia = emite sozinha"},"entrega_tomador":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Entrega Tomador","description":"Se a nota emitida é enviada ao e-mail do cadastro do cliente"},"avisos":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Avisos","description":"Quem é avisado a cada disparo e por quais canais (`ativo`, `canais`, `para`)"},"falhas_consecutivas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Falhas Consecutivas","description":"Falhas seguidas até agora; a automação se pausa sozinha ao chegar a 2"},"pausada_por":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pausada Por","description":"Motivo de uma pausa automática: `falhas` (falhou seguidas vezes), `fatura`, `sem_destinos` (o último destino do relatório saiu da lista pelo link do e-mail) ou `empresa_inativa`. `null` quando a pausa foi manual ou não há pausa"},"report_definition_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Definition Id","description":"Definição de relatório vinculada, se houver"},"definicao":{"anyOf":[{"$ref":"#/components/schemas/AutomacaoDefinicaoOut"},{"type":"null"}],"description":"Os dados do relatório vinculado, já resolvidos (só na listagem)"},"ultima_execucao":{"anyOf":[{"$ref":"#/components/schemas/AutomacaoUltimaExecucaoOut"},{"type":"null"}],"description":"Resumo da última execução (só na listagem)"},"pendencia_aberta":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Pendencia Aberta","description":"Só na resposta do PATCH: `true` quando há uma emissão esperando resposta, que sairá com os dados novos"},"criado_por":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Criado Por","description":"Quem criou a automação"},"criado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Criado Em","description":"Quando a automação foi criada, em UTC (ISO 8601)"}},"additionalProperties":true,"type":"object","required":["id","nome","ativo","cron"],"title":"AutomacaoOut","description":"Uma automação da conta, com a agenda resolvida e o resumo da última execução."},"AutomacaoPuladaOut":{"properties":{"automation_id":{"type":"string","title":"Automation Id","description":"A automação"},"pulada":{"type":"string","format":"date-time","title":"Pulada","description":"A ocorrência que não vai sair, em UTC"},"proxima_execucao":{"type":"string","format":"date-time","title":"Proxima Execucao","description":"A próxima execução depois do pulo, em UTC"}},"type":"object","required":["automation_id","pulada","proxima_execucao"],"title":"AutomacaoPuladaOut","description":"A nota pulada e a agenda que ficou."},"AutomacaoRunOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da execução (prefixo `run_`)"},"automation_id":{"type":"string","title":"Automation Id","description":"A automação que rodou"},"disparo":{"type":"string","title":"Disparo","description":"`agendado` (a agenda venceu) ou `manual` (alguém mandou rodar agora)"},"desfecho":{"type":"string","title":"Desfecho","description":"`emitida`, `pendencia`, `relatorio_enviado`, `relatorio_parcial` (o e-mail do relatório foi aceito só para parte dos destinos — `erro_msg` diz quem ficou sem), `relatorio_nao_entregue` (nenhum destino aceitou; conta como falha e tenta de novo em 1 hora), `em_fila` (o relatório está na fila de pacotes; vira um dos três quando o trabalhador entrega), `repetida` (o relatório desta definição já saiu hoje por outra execução agendada — não se repete), `falha` ou `pulada`"},"iniciado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Iniciado Em","description":"Quando a execução começou, em UTC (ISO 8601)"},"duracao_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duracao Ms","description":"Quanto a execução demorou, em milissegundos"},"nfse_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nfse Id","description":"Nota emitida nesta execução"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial (nNFSe) da nota emitida"},"ndps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ndps","description":"Sequência interna da DPS da nota emitida"},"valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor","description":"Valor do serviço da nota emitida, em reais, como texto"},"pendencia_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pendencia Id","description":"A emissão que ficou esperando resposta"},"notas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Notas","description":"Quantas notas entraram no relatório enviado"},"erro_codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Erro Codigo","description":"Código do erro quando o desfecho foi `falha` — ou, no relatório, `relatorio_parcial` / `relatorio_nao_entregue`: `EMAIL_PARCIAL`, `EMAIL_RECUSADO`, `EMAIL_SUPRIMIDO_TESTE`, `EMAIL_SEM_DESTINO`"},"erro_msg":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Erro Msg","description":"Motivo em português da falha ou do pulo"},"observacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Observacao","description":"O que a execução diz além do desfecho: o município do cliente que mudou pela Receita (a nota saiu com o endereço novo, que é o do cadastro do CNPJ) — uma vez só por mudança"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Quem mandou rodar, no disparo manual"},"avisos":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Avisos","description":"Avisos disparados por esta execução: canal, destino e situação do envio"}},"additionalProperties":true,"type":"object","required":["id","automation_id","disparo","desfecho"],"title":"AutomacaoRunOut","description":"Uma execução no histórico da automação."},"AutomacaoRunsOut":{"properties":{"total":{"type":"integer","title":"Total","description":"Total de execuções da automação, ignorando `limit`/`skip`"},"itens":{"items":{"$ref":"#/components/schemas/AutomacaoRunOut"},"type":"array","title":"Itens","description":"Execuções da página, da mais recente para a mais antiga"}},"additionalProperties":true,"type":"object","required":["total","itens"],"title":"AutomacaoRunsOut","description":"Uma página do histórico de execuções."},"AutomacaoUltimaExecucaoOut":{"properties":{"desfecho":{"type":"string","title":"Desfecho","description":"`emitida`, `pendencia`, `relatorio_enviado`, `relatorio_parcial` (o e-mail do relatório foi aceito só para parte dos destinos — `erro_msg` diz quem ficou sem), `relatorio_nao_entregue` (nenhum destino aceitou; conta como falha e tenta de novo em 1 hora), `em_fila` (o relatório está na fila de pacotes; vira um dos três quando o trabalhador entrega), `repetida` (o relatório desta definição já saiu hoje por outra execução agendada — não se repete), `falha` ou `pulada`"},"em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Em","description":"Quando a execução começou, em UTC (ISO 8601)"},"nfse_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nfse Id","description":"Nota gerada, quando o desfecho foi `emitida`"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial (nNFSe) da nota gerada"},"ndps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ndps","description":"Sequência interna da DPS da nota gerada"},"valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor","description":"Valor do serviço da nota gerada, em reais, como texto"},"notas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Notas","description":"Quantas notas entraram no relatório enviado"},"erro_codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Erro Codigo","description":"Código do erro quando o desfecho foi `falha` — ou, no relatório, `relatorio_parcial` / `relatorio_nao_entregue`: `EMAIL_PARCIAL`, `EMAIL_RECUSADO`, `EMAIL_SUPRIMIDO_TESTE`, `EMAIL_SEM_DESTINO`"},"erro_msg":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Erro Msg","description":"Motivo em português da falha ou do pulo"}},"additionalProperties":true,"type":"object","required":["desfecho"],"title":"AutomacaoUltimaExecucaoOut","description":"Resumo da última vez que a automação rodou; `null` se ela nunca rodou."},"AvisoOut":{"properties":{"code":{"type":"string","title":"Code","description":"O código do aviso (ex.: \"RETENCAO_COM_TOMADOR_DE_OUTRO_MUNICIPIO\")"},"message":{"type":"string","title":"Message","description":"O que vale conferir, em uma frase"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hint","description":"O que fazer"}},"type":"object","required":["code","message"],"title":"AvisoOut","description":"Um aviso que não impede a nota: ela sai, e o aviso diz o que conferir."},"BillingFlagsOut":{"properties":{"bloqueada":{"type":"boolean","title":"Bloqueada","description":"`true` quando a renovação venceu: as demais rotas respondem 402"},"vence_hoje":{"type":"boolean","title":"Vence Hoje","description":"`true` quando a renovação vence hoje e ainda não foi paga"}},"additionalProperties":true,"type":"object","required":["bloqueada","vence_hoje"],"title":"BillingFlagsOut","description":"Sinais de cobrança que valem para qualquer papel."},"Body_criar_pelo_arquivo_api_v1_companies__company_id__lotes_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"forcar":{"type":"boolean","title":"Forcar","default":false}},"type":"object","required":["file"],"title":"Body_criar_pelo_arquivo_api_v1_companies__company_id__lotes_post"},"CancelarIn":{"properties":{"cMotivo":{"type":"string","enum":["1","2","9"],"title":"Cmotivo","description":"1 = erro na emissão (padrão) · 2 = serviço não prestado · 9 = outros","default":"1"},"xMotivo":{"type":"string","maxLength":255,"minLength":15,"title":"Xmotivo","description":"Justificativa em texto livre, de 15 a 255 caracteres — é ela que aparece na consulta pública"}},"type":"object","required":["xMotivo"],"title":"CancelarIn","description":"O motivo do cancelamento — vai assinado no evento e fica no histórico da nota."},"CancelarOut":{"properties":{"nfse_id":{"type":"string","title":"Nfse Id","description":"Identificador da nota cancelada (nfse_…)"},"chave":{"type":"string","title":"Chave","description":"Chave de acesso da nota cancelada, 50 dígitos"},"status":{"type":"string","title":"Status","description":"Situação da nota depois do evento: \"cancelada\""},"evento_id":{"type":"string","title":"Evento Id","description":"Identificador do evento nesta API (evt_…)"},"codigo_evento":{"type":"string","title":"Codigo Evento","description":"Código oficial do evento de cancelamento (101101)"},"elapsed_ms":{"type":"integer","title":"Elapsed Ms","description":"Tempo da conversa com o Sistema Nacional, em milissegundos"}},"type":"object","required":["nfse_id","chave","status","evento_id","codigo_evento","elapsed_ms"],"title":"CancelarOut","description":"A confirmação do cancelamento registrado no Sistema Nacional."},"CertificateOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador do certificado (`crt_…`)"},"company_id":{"type":"string","title":"Company Id","description":"Empresa dona do certificado"},"subject_cn":{"type":"string","title":"Subject Cn","description":"Titular do certificado, como está no arquivo (ex.: `EMPRESA LTDA:11222333000181`)"},"subject_cnpj":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject Cnpj","description":"CNPJ extraído do certificado, sem pontuação (pode ter letras); `null` quando não veio"},"not_after":{"type":"string","format":"date-time","title":"Not After","description":"Fim da validade do certificado (ISO 8601, UTC)"},"status":{"type":"string","title":"Status","description":"`recebido` (enviado, ainda não validado), `validado` (pronto para emitir), `vencido` ou `substituido`"},"dias_para_vencer":{"type":"integer","title":"Dias Para Vencer","description":"Dias que faltam para o vencimento — negativo quando já venceu"}},"type":"object","required":["id","company_id","subject_cn","subject_cnpj","not_after","status","dias_para_vencer"],"title":"CertificateOut"},"CodigoDescricaoOut":{"properties":{"codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo","description":"Código na tabela da Receita"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao","description":"O que o código quer dizer, por extenso"}},"additionalProperties":true,"type":"object","title":"CodigoDescricaoOut","description":"Par código + descrição de uma tabela da Receita (CNAE, natureza jurídica, município)."},"CodigoServicoOut":{"properties":{"cTribNac":{"type":"string","title":"Ctribnac","description":"Código de tributação nacional, 6 dígitos"},"descricao":{"type":"string","title":"Descricao","description":"Nome oficial do serviço"},"iss_no_local":{"type":"boolean","title":"Iss No Local","description":"True quando o ISS é devido no local da prestação (mande `servico.cMunPrestacao`)"},"familia_local":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Familia Local","description":"`local`, `obra`, `evento`, `tomador` ou `rateio` (`obra` e `evento` também nos códigos em que o Sistema Nacional pede o grupo da obra ou do evento, Anexo I regras 340 e 357); nulo nos demais"},"regra_local":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regra Local","description":"Onde o ISS é devido, em uma frase, quando há exceção"},"tomador_pj_responsavel":{"type":"boolean","title":"Tomador Pj Responsavel","description":"True nos subitens em que a LC 116 (art. 6º, § 2º, II) faz a pessoa jurídica tomadora responsável pelo ISS onde quer que ela esteja — ali, a retenção por um tomador de outro município não pede aviso","default":false}},"additionalProperties":true,"type":"object","required":["cTribNac","descricao","iss_no_local"],"title":"CodigoServicoOut","description":"O código de serviço conferido no catálogo nacional."},"CompanyCreate":{"properties":{"cnpj":{"type":"string","title":"Cnpj","description":"CNPJ da empresa emissora: 14 caracteres (letras A–Z ou números nas 12 primeiras posições; os 2 últimos, números); pontuação é aceita e normalizada; letra minúscula vira maiúscula"},"inscricao_municipal":{"anyOf":[{"type":"string","maxLength":15},{"type":"null"}],"title":"Inscricao Municipal","description":"Inscrição municipal, até 15 caracteres. Na maioria das cidades, o Sistema Nacional identifica a empresa pelo CNPJ; onde a prefeitura exige a inscrição na nota (como São Paulo e Recife), a ME e a EPP só ativam e emitem com ela"},"razao_social":{"type":"string","title":"Razao Social","description":"Razão social exatamente como está no cadastro da Receita"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia, só para exibição no painel"},"regime":{"$ref":"#/components/schemas/RegimeTributarioIn","description":"Regime tributário da empresa; omitido, assume Simples Nacional ME/EPP","default":{"op_simp_nac":"3","reg_ap_trib_sn":"1","reg_esp_trib":"0"}},"endereco":{"$ref":"#/components/schemas/Endereco","description":"Endereço da empresa; `cMun` (código IBGE de 7 dígitos) define o município de emissão"},"telefone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telefone","description":"Telefone com DDD, só dígitos (o nono dígito é completado quando falta)"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail de contato da empresa"},"serie_padrao":{"type":"string","title":"Serie Padrao","description":"Série da numeração das notas — número de 1 a 49999, sem zeros à esquerda (de 50000 em diante a série é reservada aos emissores do governo)","default":"1"}},"type":"object","required":["cnpj","razao_social","endereco"],"title":"CompanyCreate"},"CompanyOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da empresa (`cmp_…`) — é o `company_id` das demais rotas"},"cnpj":{"type":"string","title":"Cnpj","description":"CNPJ da empresa, sem pontuação (14 caracteres; pode ter letras nas 12 primeiras)"},"inscricao_municipal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inscricao Municipal","description":"Inscrição municipal, quando cadastrada"},"razao_social":{"type":"string","title":"Razao Social","description":"Razão social da empresa"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia, quando cadastrado"},"status":{"type":"string","title":"Status","description":"`pendente` (cadastrada, sem certificado validado), `ativa` (pode emitir), `inativa` (pausada pelo dono), `waitlist` (lista de espera: a ME ou a EPP de município que ainda não emite pelo Sistema Nacional, até 31/10/2026) ou `suspensa`"},"serie_padrao":{"type":"string","title":"Serie Padrao","description":"Série usada na numeração das notas desta empresa"},"criado_em":{"type":"string","format":"date-time","title":"Criado Em","description":"Data e hora do cadastro (ISO 8601, UTC)"},"endereco":{"anyOf":[{"$ref":"#/components/schemas/Endereco"},{"type":"null"}],"description":"Endereço da empresa; `cMun` é o código IBGE"},"regime":{"anyOf":[{"$ref":"#/components/schemas/RegimeTributario"},{"type":"null"}],"description":"Regime tributário usado na emissão (Simples Nacional, regime especial, alíquotas)"},"telefone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telefone","description":"Telefone de contato, só dígitos"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail de contato da empresa"},"pgdas":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Pgdas","description":"Último retrato do PGDAS-D que alimentou as alíquotas, quando houver"},"tributacao_modo":{"type":"string","title":"Tributacao Modo","description":"`auto` (alíquotas renovadas pelo PGDAS-D) ou `manual` (o dono informa)","default":"auto"},"aviso":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aviso","description":"Recado sobre o que acabou de acontecer — ex.: município em lista de espera"},"sync_opcoes":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Sync Opcoes","description":"Preferências da importação automática de notas — hoje só `importar_legado_convertido` (bool)"},"receita":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Receita","description":"Dados cadastrais trazidos da Receita (CNAEs, natureza, porte, capital, Simples), quando consultados, com a fonte (`fonte`: `gerecnpj`, o cadastro mensal, com `mes_referencia`; ou `serpro`, em tempo real). O quadro societário não vem nas listas: só a contagem (`qsa_total`); os sócios estão em `GET /companies/{id}/receita`"},"receita_consultado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Receita Consultado Em","description":"Quando os dados da Receita foram consultados (ISO 8601, UTC)"},"fora_do_simples":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Fora Do Simples","description":"Preenchido quando a Receita mostrou que a empresa saiu do Simples Nacional (`desde`, `conferido_em`, `fonte`): a emissão fica parada (422 `EMPRESA_FORA_DO_SIMPLES`) até o \"Conferir na Receita\" mostrar que ela voltou"},"emissao_parada":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emissao Parada","description":"A frase pronta quando a emissão está parada por regime; `null` quando emite"},"pendencia_da_ativacao":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Pendencia Da Ativacao","description":"Por que a última validação não ativou a empresa: `codigo` (o do erro de `POST /companies/{id}/validate` — `INSCRICAO_MUNICIPAL_OBRIGATORIA`, `CERTIFICADO_AUSENTE`, `VALIDACAO_REPROVADA`…), `mensagem`, `em`, `cidade` (Cidade/UF, na inscrição municipal) e `checks` (`cnpj_confere`, `dentro_da_validade`, `handshake_govbr`, na validação reprovada). Some quando a empresa é ativada; `null` quando nunca reprovou"},"receita_aviso_regime":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Receita Aviso Regime","description":"A reconferência mensal viu no cadastro da Receita uma mudança de regime que ainda não parou nada: `tipo` (`saiu`, a empresa não é mais optante do Simples; `saida_marcada`, a saída marcada para uma data futura; `deixou_mei`, o MEI que virou ME/EPP), `data` (a da saída, `AAAA-MM-DD`) e `mes` (o do cadastro, `AAAA-MM`). Só avisa: a emissão para quando a saída se confirma na Receita do dia. Some quando a conferência não mostra mais a mudança; `null` quando não há"}},"type":"object","required":["id","cnpj","razao_social","status","serie_padrao","criado_em"],"title":"CompanyOut"},"CompanyStatusOut":{"properties":{"company":{"$ref":"#/components/schemas/CompanyOut","description":"O cadastro da empresa"},"certificate":{"anyOf":[{"$ref":"#/components/schemas/CertificateOut"},{"type":"null"}],"description":"O certificado A1 mais recente da empresa; `null` quando nenhum foi enviado"},"importacao":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Importacao","description":"Estado da importação automática das notas do Sistema Nacional: `ultima` (a última rodada, com `em`, `status` e contagens), `em_andamento` e `progresso`, `pode_importar` e `motivo` (por que não dá), `automatica` (se a rodada diária está ligada e quando volta) e `legado` (notas do sistema antigo do município: `disponiveis` × `no_painel`). Vem com `indisponivel: true` quando não deu para apurar"}},"type":"object","required":["company"],"title":"CompanyStatusOut"},"CompetenciaPropostaOut":{"properties":{"data":{"type":"string","title":"Data","description":"AAAA-MM-DD. Com histórico, o mesmo dia do mês da última nota ativa; se esse dia ainda não chegou, o do mês anterior (nunca no futuro). Sem histórico, hoje — no horário de Brasília"},"origem":{"type":"string","title":"Origem","description":"`ultima_nota` (a régua do histórico) ou `hoje`"}},"type":"object","required":["data","origem"],"title":"CompetenciaPropostaOut","description":"A data da prestação a propor para a próxima nota deste tomador."},"ConsultaCepOut":{"properties":{"CEP":{"type":"string","title":"Cep","description":"CEP consultado, 8 dígitos sem hífen"},"xLgr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xlgr","description":"Logradouro; `null` em CEP de município inteiro"},"xCpl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xcpl","description":"Complemento devolvido pelos Correios, quando houver"},"xBairro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xbairro","description":"Bairro; `null` em CEP de município inteiro"},"municipio_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Municipio Nome","description":"Nome do município"},"uf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uf","description":"Sigla da UF, 2 letras"},"cMun":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cmun","description":"Código IBGE do município (7 dígitos) — é este o valor que vai na nota"}},"additionalProperties":true,"type":"object","required":["CEP","cMun"],"title":"ConsultaCepOut","description":"Endereço de um CEP, com os nomes de campo que a emissão de NFS-e usa."},"ConsultaCnpjOut":{"properties":{"tipo":{"type":"string","const":"CNPJ","title":"Tipo","description":"Sempre `CNPJ` nesta rota"},"documento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Documento","description":"CNPJ consultado, sem pontuação (14 caracteres; pode ter letras nas 12 primeiras)"},"nome":{"type":"string","title":"Nome","description":"Razão social"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia, quando houver"},"abertura":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Abertura","description":"Data de abertura (AAAA-MM-DD)"},"situacao":{"$ref":"#/components/schemas/SituacaoCnpjOut","description":"Situação cadastral — confira antes de emitir para a empresa"},"cnae_principal":{"anyOf":[{"$ref":"#/components/schemas/CodigoDescricaoOut"},{"type":"null"}],"description":"CNAE da atividade principal"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail do cadastro na Receita, em minúsculas"},"fone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fone","description":"Telefone só dígitos, com DDD e o 9º dígito já completado"},"endereco":{"$ref":"#/components/schemas/EnderecoReceitaOut","description":"Endereço pronto para o cadastro de empresa ou de tomador"},"receita":{"$ref":"#/components/schemas/ReceitaOut","description":"Demais dados cadastrais (o QSA só vem com `completo=true`)"},"fonte":{"type":"string","enum":["serpro","gerecnpj"],"title":"Fonte","description":"Origem do dado, sempre a Receita Federal: `gerecnpj` = o cadastro mensal (Dados Abertos do CNPJ, publicado uma vez por mês — pode estar algumas semanas atrás); `serpro` = a consulta em tempo real (o CNPJ que ainda não está no cadastro do mês, o `fresco` e quando o cadastro mensal não responde)"},"mes_referencia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mes Referencia","description":"Com `fonte` `gerecnpj`: o mês do cadastro (AAAA-MM). Cite a fonte onde terceiros veem"},"data_extracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Extracao","description":"Com `fonte` `gerecnpj`: o dia em que a Receita extraiu os dados (AAAA-MM-DD)"},"regime_sugerido":{"anyOf":[{"$ref":"#/components/schemas/RegimeSugeridoOut"},{"type":"null"}],"description":"Só presente quando a chamada usou `completo=true`"},"consulta_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Consulta Id","description":"Identificador desta consulta guardada na conta; `null` se não foi possível guardar"},"de_cache":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"De Cache","description":"`true` quando a resposta veio do cache — o mesmo CNPJ no mesmo mês do cadastro mensal, ou consultado em tempo real nos últimos 7 dias, por qualquer conta —, sem ir à Receita e sem consumir cota. Ausente quando a consulta foi mesmo feita agora"},"consultado_em":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Consultado Em","description":"Quando a consulta em cache foi originalmente feita (ISO 8601); só vem com `de_cache`"}},"additionalProperties":true,"type":"object","required":["tipo","nome","situacao","endereco","receita","fonte"],"title":"ConsultaCnpjOut","description":"O cadastro de um CNPJ na Receita, normalizado."},"ConsultaCpfOut":{"properties":{"tipo":{"type":"string","const":"CPF","title":"Tipo","description":"Sempre `CPF` nesta rota"},"documento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Documento","description":"CPF consultado, só números"},"nome":{"type":"string","title":"Nome","description":"Nome da pessoa"},"nome_social":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Social","description":"Nome social, quando registrado"},"situacao":{"$ref":"#/components/schemas/SituacaoCpfOut","description":"Situação cadastral do CPF"},"nascimento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nascimento","description":"Data de nascimento confirmada pela Receita (AAAA-MM-DD)"},"fonte":{"type":"string","const":"serpro","title":"Fonte","description":"Origem do dado: a Receita Federal, via SERPRO"},"consulta_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Consulta Id","description":"Identificador desta consulta guardada na conta"},"de_cache":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"De Cache","description":"`true` quando a resposta veio do cache (o mesmo CPF e a mesma data de nascimento, consultados pela conta nas últimas 24 h), sem consumir cota"},"consultado_em":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Consultado Em","description":"Quando a consulta em cache foi originalmente feita (ISO 8601)"}},"additionalProperties":true,"type":"object","required":["tipo","nome","situacao","fonte"],"title":"ConsultaCpfOut","description":"O cadastro de um CPF na Receita, normalizado. Não traz endereço nem telefone."},"ConsultaMunicipioOut":{"properties":{"cMun":{"type":"string","title":"Cmun","description":"Código IBGE do município, 7 dígitos"},"nome":{"type":"string","title":"Nome","description":"Nome oficial do município, na grafia do IBGE"},"uf":{"type":"string","title":"Uf","description":"Sigla da UF informada na busca, em maiúsculas"}},"additionalProperties":true,"type":"object","required":["cMun","nome","uf"],"title":"ConsultaMunicipioOut","description":"Um município identificado pelo nome + UF."},"ContagensDoLoteOut":{"properties":{"itens":{"type":"integer","title":"Itens","description":"Quantas linhas viraram notas propostas"},"por_estado":{"additionalProperties":{"type":"integer"},"type":"object","title":"Por Estado","description":"As linhas por situação: `proposto` (pronta), `precisa_dados`, `ja_tem_nota`, `repetida`, `ignorada`, `pronto` (na fila), `emitindo`, `emitida`, `recusada`, `incerta` e `cancelada`"},"total_incluido":{"type":"string","title":"Total Incluido","description":"A soma das linhas incluídas (prontas, na fila e emitidas), em reais"}},"additionalProperties":true,"type":"object","required":["itens","por_estado","total_incluido"],"title":"ContagensDoLoteOut"},"CotaDeNotasOut":{"properties":{"usadas":{"type":"integer","title":"Usadas","description":"Quantas foram usadas no mês corrente"},"cota":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cota","description":"Limite do mês; `null` = sem bloqueio por cota"},"upgrade":{"anyOf":[{"$ref":"#/components/schemas/UpgradeOut"},{"type":"null"}],"description":"Só para o dono da conta, e só quando o próximo item não cabe no plano: o plano mais barato em que ele cabe, com o preço e o link para assinar — o mesmo `upgrade` dos erros de limite. Ausente quando nenhum plano resolve (o Plano Escritório no teto); a chave de API nunca é do dono e não o recebe"}},"additionalProperties":true,"type":"object","required":["usadas"],"title":"CotaDeNotasOut","description":"Notas emitidas no mês contra a cota do plano."},"CotaOut":{"properties":{"usadas":{"type":"integer","title":"Usadas","description":"Quantas foram usadas no mês corrente"},"cota":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cota","description":"Limite do mês; `null` = sem bloqueio por cota"}},"additionalProperties":true,"type":"object","required":["usadas"],"title":"CotaOut","description":"Consumo do mês corrente contra a cota do plano."},"DataIn":{"properties":{"modo":{"type":"string","enum":["linha","emissao","outra"],"title":"Modo"},"outra":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outra"}},"type":"object","required":["modo"],"title":"DataIn"},"DeclaracaoPgdasDetalheOut":{"properties":{"pa":{"type":"string","title":"Pa","description":"Período de apuração, `AAAAMM`"},"versao":{"type":"string","title":"Versao","description":"`001` = original; `002`+ = retificadora (os 3 últimos dígitos do nº da declaração)"},"numero_declaracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Declaracao","description":"Nº da declaração no PGDAS-D"},"retificadora":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Retificadora","description":"True quando a declaração se diz retificadora"},"regime_apuracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regime Apuracao","description":"`caixa` ou `competencia` (seção 1 do PDF)"},"data_abertura":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Abertura","description":"Data de abertura no CNPJ (`AAAA-MM-DD`)"},"impedido_iss_no_das":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Impedido Iss No Das","description":"Impedida de recolher ICMS/ISS no DAS (sublimite estourado — seção 2.7)"},"rpa_competencia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rpa Competencia","description":"Receita bruta do PA por competência (R$) — o faturado no mês; é ela que forma a RBT12 e a alíquota, nos dois regimes"},"rpa_caixa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rpa Caixa","description":"Receita bruta do PA por caixa (R$) — o recebido no mês, base do DAS no regime de caixa; `null` na empresa de competência"},"rbt12":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rbt12","description":"Receita bruta dos 12 meses anteriores ao PA, do mercado interno (R$)"},"rbt12p":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rbt12P","description":"RBT12 proporcionalizada (início de atividade), do mercado interno, quando houver"},"rba":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rba","description":"Receita bruta acumulada no ano corrente, do mercado interno (R$)"},"rbaa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rbaa","description":"Receita bruta acumulada no ano anterior, do mercado interno (R$)"},"p_tot_trib_sn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Tot Trib Sn","description":"Efetiva total declarada (%) — débito ÷ base da seção 2.7"},"p_aliq_iss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Aliq Iss","description":"ISS efetivo declarado (%)"},"iss_retido_no_pa":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Iss Retido No Pa","description":"Toda a receita do PA teve ISS retido (ISS zerado no DAS)"},"anexo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Anexo","description":"Anexo do Simples que reproduz a efetiva declarada (III, IV ou V)"},"faixa":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Faixa","description":"Faixa (1–6) da RBT12 nesse anexo"},"anexo_confere":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Anexo Confere","description":"A efetiva total E o ISS declarados saem da tabela com a RBT12 declarada"},"anexo_ambiguo":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Anexo Ambiguo","description":"III e V empatam (6ª faixa) — anexo indeterminado por este PDF"},"efetiva_motivo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Efetiva Motivo","description":"Por que a efetiva total não saiu desta declaração: `mais_de_um_anexo` (atividades de anexos diferentes — a soma não bate com anexo nenhum; a de cada anexo está em `por_anexo`, no detalhe) ou `leiaute` (a seção 2.7 não foi lida, ver `falhas_leitura`)"},"fator_r_declarado":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fator R Declarado","description":"Seção 2.4: o fator r que a declaração traz (`0.31` = 31 %), só quando há atividade sujeita ao fator r declarada; com 0,28 ou mais, essa atividade fica no Anexo III, abaixo, no V"},"fator_r_motivo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fator R Motivo","description":"Por que `fator_r_declarado` é nulo: `nao_se_aplica` (a 2.4 diz \"Não se aplica\" — nenhuma atividade sujeita ao fator r declarada), `ilegivel` (formato desconhecido: o número não é lido) ou `ausente`"},"cpp_declarada":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cpp Declarada","description":"Seção 2.8 (Total Geral da Empresa, Total do Débito Declarado), coluna INSS/CPP: a contribuição patronal paga dentro do DAS no PA (R$) — conta como folha no fator r"},"falhas_leitura":{"items":{"type":"string"},"type":"array","title":"Falhas Leitura","description":"Seções que a leitura não reconheceu, por código (`identificacao` = 1 (o período de apuração); `receitas_2_1` = 2.1 (o discriminativo de receitas: RPA, RBT12, RBA); `receitas_2_2` = 2.2 (as receitas brutas anteriores, mês a mês); `folha_2_3` = 2.3 (a folha de salários, mês a mês); `fator_r_2_4` = 2.4 (o fator r); `impedimento_2_7` = 2.7 (o impedimento de recolher o ISS no DAS); `atividades_2_7` = 2.7 (as atividades e os débitos por tributo); `total_2_8` = 2.8 (o total geral da empresa: a CPP); `leitura` = a leitura parou no meio (erro do leitor)). O número dessas seções fica nulo, nunca errado, e a operação do GereNota é avisada; com uma seção da conta (1, 2.1, 2.2, o impedimento ou as atividades da 2.7), esta declaração não muda a alíquota"},"meses_retificados":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Meses Retificados","description":"Meses cuja receita mudou em relação ao histórico anterior (`AAAA-MM` → {antes, depois}) — PA retificado"},"transmitida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Transmitida Em","description":"Data e hora da transmissão (seção 3), em UTC"},"consultado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Consultado Em","description":"Quando a plataforma consultou/arquivou"},"fonte":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fonte","description":"`sync` (consulta) · `backfill_s3` / `historico_s3` (texto já arquivado)"},"tem_pdf":{"type":"boolean","title":"Tem Pdf","description":"O PDF está arquivado (`…/declaracoes/{pa}/pdf`)","default":false},"receitas_mensais":{"additionalProperties":{"type":"string"},"type":"object","title":"Receitas Mensais","description":"Seção 2.2: receita por competência de cada mês desde janeiro do ano anterior até M−1 (`AAAA-MM` → R$)"},"folhas_mensais":{"additionalProperties":{"type":"string"},"type":"object","title":"Folhas Mensais","description":"Seção 2.3: a folha de salários de cada mês dos 12 anteriores ao PA (`AAAA-MM` → R$), só quando há atividade sujeita ao fator r declarada (senão a declaração diz \"Nenhuma\" e vem vazio)"},"total_geral":{"additionalProperties":{"type":"string"},"type":"object","title":"Total Geral","description":"Seção 2.8: o total do débito declarado da empresa por tributo (R$), pelo nome da coluna, como em `atividades[].tributos`"},"por_anexo":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Por Anexo","description":"As atividades da 2.7 separadas por anexo (`III`, `IV`, `V`): `atividades` (quantas), `receita`, `debitos` por tributo, `p_tot_trib_sn` e `p_aliq_iss` do grupo, `iss_retido_no_pa`, `faixa` e `confere` (a efetiva do grupo sai da tabela desse anexo com a RBT12 declarada)"},"atividades":{"items":{"$ref":"#/components/schemas/gerenota_api__integra_contador__AtividadeOut"},"type":"array","title":"Atividades","description":"Seção 2.7: por atividade, a receita informada, os débitos por tributo e a classe"},"versoes":{"items":{"$ref":"#/components/schemas/VersaoDeclaracaoOut"},"type":"array","title":"Versoes","description":"Todas as versões deste PA, da mais nova para a mais antiga"},"pdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdf","description":"Caminho do PDF arquivado desta versão, quando houver"}},"type":"object","required":["pa","versao"],"title":"DeclaracaoPgdasDetalheOut","description":"A declaração inteira como dado: o resumo mais a tabela mensal, as atividades, as versões e o PDF."},"DeclaracaoPgdasOut":{"properties":{"pa":{"type":"string","title":"Pa","description":"Período de apuração, `AAAAMM`"},"versao":{"type":"string","title":"Versao","description":"`001` = original; `002`+ = retificadora (os 3 últimos dígitos do nº da declaração)"},"numero_declaracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Declaracao","description":"Nº da declaração no PGDAS-D"},"retificadora":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Retificadora","description":"True quando a declaração se diz retificadora"},"regime_apuracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regime Apuracao","description":"`caixa` ou `competencia` (seção 1 do PDF)"},"data_abertura":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Abertura","description":"Data de abertura no CNPJ (`AAAA-MM-DD`)"},"impedido_iss_no_das":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Impedido Iss No Das","description":"Impedida de recolher ICMS/ISS no DAS (sublimite estourado — seção 2.7)"},"rpa_competencia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rpa Competencia","description":"Receita bruta do PA por competência (R$) — o faturado no mês; é ela que forma a RBT12 e a alíquota, nos dois regimes"},"rpa_caixa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rpa Caixa","description":"Receita bruta do PA por caixa (R$) — o recebido no mês, base do DAS no regime de caixa; `null` na empresa de competência"},"rbt12":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rbt12","description":"Receita bruta dos 12 meses anteriores ao PA, do mercado interno (R$)"},"rbt12p":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rbt12P","description":"RBT12 proporcionalizada (início de atividade), do mercado interno, quando houver"},"rba":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rba","description":"Receita bruta acumulada no ano corrente, do mercado interno (R$)"},"rbaa":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rbaa","description":"Receita bruta acumulada no ano anterior, do mercado interno (R$)"},"p_tot_trib_sn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Tot Trib Sn","description":"Efetiva total declarada (%) — débito ÷ base da seção 2.7"},"p_aliq_iss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Aliq Iss","description":"ISS efetivo declarado (%)"},"iss_retido_no_pa":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Iss Retido No Pa","description":"Toda a receita do PA teve ISS retido (ISS zerado no DAS)"},"anexo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Anexo","description":"Anexo do Simples que reproduz a efetiva declarada (III, IV ou V)"},"faixa":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Faixa","description":"Faixa (1–6) da RBT12 nesse anexo"},"anexo_confere":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Anexo Confere","description":"A efetiva total E o ISS declarados saem da tabela com a RBT12 declarada"},"anexo_ambiguo":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Anexo Ambiguo","description":"III e V empatam (6ª faixa) — anexo indeterminado por este PDF"},"efetiva_motivo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Efetiva Motivo","description":"Por que a efetiva total não saiu desta declaração: `mais_de_um_anexo` (atividades de anexos diferentes — a soma não bate com anexo nenhum; a de cada anexo está em `por_anexo`, no detalhe) ou `leiaute` (a seção 2.7 não foi lida, ver `falhas_leitura`)"},"fator_r_declarado":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fator R Declarado","description":"Seção 2.4: o fator r que a declaração traz (`0.31` = 31 %), só quando há atividade sujeita ao fator r declarada; com 0,28 ou mais, essa atividade fica no Anexo III, abaixo, no V"},"fator_r_motivo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fator R Motivo","description":"Por que `fator_r_declarado` é nulo: `nao_se_aplica` (a 2.4 diz \"Não se aplica\" — nenhuma atividade sujeita ao fator r declarada), `ilegivel` (formato desconhecido: o número não é lido) ou `ausente`"},"cpp_declarada":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cpp Declarada","description":"Seção 2.8 (Total Geral da Empresa, Total do Débito Declarado), coluna INSS/CPP: a contribuição patronal paga dentro do DAS no PA (R$) — conta como folha no fator r"},"falhas_leitura":{"items":{"type":"string"},"type":"array","title":"Falhas Leitura","description":"Seções que a leitura não reconheceu, por código (`identificacao` = 1 (o período de apuração); `receitas_2_1` = 2.1 (o discriminativo de receitas: RPA, RBT12, RBA); `receitas_2_2` = 2.2 (as receitas brutas anteriores, mês a mês); `folha_2_3` = 2.3 (a folha de salários, mês a mês); `fator_r_2_4` = 2.4 (o fator r); `impedimento_2_7` = 2.7 (o impedimento de recolher o ISS no DAS); `atividades_2_7` = 2.7 (as atividades e os débitos por tributo); `total_2_8` = 2.8 (o total geral da empresa: a CPP); `leitura` = a leitura parou no meio (erro do leitor)). O número dessas seções fica nulo, nunca errado, e a operação do GereNota é avisada; com uma seção da conta (1, 2.1, 2.2, o impedimento ou as atividades da 2.7), esta declaração não muda a alíquota"},"meses_retificados":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Meses Retificados","description":"Meses cuja receita mudou em relação ao histórico anterior (`AAAA-MM` → {antes, depois}) — PA retificado"},"transmitida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Transmitida Em","description":"Data e hora da transmissão (seção 3), em UTC"},"consultado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Consultado Em","description":"Quando a plataforma consultou/arquivou"},"fonte":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fonte","description":"`sync` (consulta) · `backfill_s3` / `historico_s3` (texto já arquivado)"},"tem_pdf":{"type":"boolean","title":"Tem Pdf","description":"O PDF está arquivado (`…/declaracoes/{pa}/pdf`)","default":false}},"type":"object","required":["pa","versao"],"title":"DeclaracaoPgdasOut","description":"Uma declaração PGDAS-D arquivada (resumo) — uma linha por PA × versão; nunca sobrescrita."},"DossieAliquotasOut":{"properties":{"empresa":{"additionalProperties":true,"type":"object","title":"Empresa","description":"id, nome, op_simp_nac, tributacao_modo (auto | manual), pgdas_autorizado, regime_apuracao (caixa | competencia) com regime_apuracao_fonte (rfb = opção registrada na Receita Federal, consultada no Integra Contador; pgdas = item 1 da declaração do próprio ano; lei = a partir de 2027 só há competência; padrao = nenhuma opção registrada no ano, vale a regra geral, competência), regimes_apuracao (ano → regime, todas as opções efetivadas), regime_consultado_em, regime_apuracao_divergencia (quando a declaração e a opção registrada discordam) e regime_apuracao_ate"},"mes":{"additionalProperties":true,"type":"object","title":"Mes","description":"A alíquota em vigor: mes, defasada, p_tot_trib_sn, p_aliq_iss, iss_fora_do_das, fonte (pgdas | estimada | proporcionalizada | inicio_atividade | manual), conta, rbt12, anexo, faixa, janela, meses_estimados, tabela, explicacao"},"proxima":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Proxima","description":"A do mês seguinte (a_partir_de, p_tot_trib_sn, p_aliq_iss, conta, explicacao)"},"pelo_pgdas_seria":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Pelo Pgdas Seria","description":"Modo manual: o que a conta pelo PGDAS-D daria para o mês"},"pelo_pgdas":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Pelo Pgdas","description":"Modo manual: o registro da última conta (mes, atual, proxima, calculada_em)"},"conferencia":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conferencia","description":"A última conferência: pa, mes, aliquota (veredito, declarada, aplicada, hipotese), receita (veredito, declarada, notas, diferenca, pct, avisar — qualquer diferença acima de R$ 1 é alerta —, notas_apos_transmissao, regime_apuracao, rpa_caixa, transmitida_em, frase_titulo + frase + detalhes = o texto pronto para o cliente, doze_meses = notas × RBT12 dos 12 meses quando o histórico de notas cobre a janela), retificados, corrigida, nova, notas_afetadas, explicacao"},"payload_divergencia":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Divergencia","description":"Notas do mês que vieram com alíquota própria diferente da calculada"},"casos":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Casos","description":"Os casos relevantes: tipo, gravidade (acao | atencao | info), titulo, texto"},"historico":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Historico","description":"A alíquota que valeu em cada mês, com a conta e a conferência (até 24 meses)"},"receita_por_mes":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Receita Por Mes","description":"O faturamento declarado × as notas, mês a mês (mais novo primeiro; os 13 PAs mais recentes e os meses ainda sem declaração): mes, pa, notas (as ativas) e quantidade, declarada, rpa_caixa, transmitida_em, versao, rbt12, p_tot_trib_sn e p_aliq_iss da declaração, corrigida_na / informada_na (o PA da declaração mais nova de onde veio o valor, quando a do próprio mês foi corrigida depois ou não o trouxe), grupos (no_mes, seguinte e depois — as notas emitidas até o fim do mês, no mês seguinte até a transmissão e depois dela: soma, quantidade, ativas, de, ate), situacao (em_aberto | sem_notas | sem_rpa | bateu | depois | abaixo | acima), atencao (a diferença é 10 % ou mais das notas, nas duas leituras: as do dia da declaração e as ativas de hoje), faltam e pct, fecha + entraram (a combinação de grupos que dá o declarado no centavo; null quando nenhuma dá) e nao_entraram (soma e quantidade)"},"receita_abaixo":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Receita Abaixo","description":"Os meses que pedem atenção (meses: mes, pa, notas, declarada, faltam, pct, fecha, nao_entraram), quanto falta neles (faltam) e a alíquota se eles fossem declarados pelas notas (corrigida: mes, meses, p_tot_trib_sn, p_aliq_iss, rbt12 e a atual) — null quando nada muda"},"declaracoes":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Declaracoes","description":"As declarações PGDAS-D arquivadas (resumo; o detalhe está em …/pgdas/declaracoes/{pa}): por PA, a receita do mês por competência (`rpa_competencia`, o faturado — forma a RBT12 e a alíquota) e, no regime de caixa, por caixa (`rpa_caixa`, o recebido — base do DAS)"},"base_legal":{"type":"string","title":"Base Legal","description":"A regra da alíquota da nota (Res. CGSN 140/2018, art. 27)"},"meses":{"items":{"type":"string"},"type":"array","title":"Meses","description":"Abreviaturas dos meses, para montar rótulos"}},"type":"object","required":["empresa","mes","base_legal"],"title":"DossieAliquotasOut","description":"O dossiê das alíquotas do Simples de uma empresa — a mesma fonte que a ficha do painel e o MCP leem."},"EditarItemIn":{"properties":{"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"manter_email":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Manter Email"},"endereco":{"anyOf":[{"$ref":"#/components/schemas/EnderecoLinhaIn"},{"type":"null"}]},"usar_cadastro":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Usar Cadastro"},"codigo_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo Servico"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao"},"valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor"},"data_linha":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Linha"},"manter_data_citada":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Manter Data Citada"},"incluir":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Incluir"},"atualizar_cadastro":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Atualizar Cadastro"}},"type":"object","title":"EditarItemIn"},"EmailDoCliente":{"properties":{"documento":{"type":"string","maxLength":18,"minLength":11,"title":"Documento","description":"O CPF ou o CNPJ do cliente, com ou sem pontuação"},"email":{"type":"string","maxLength":254,"minLength":3,"title":"Email","description":"O e-mail que recebe as notas dele neste lote"},"itens":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":200},{"type":"null"}],"title":"Itens","description":"Só estas linhas do cliente (o `id` em `GET …/itens`); sem o campo, todas as que estão sem entrega"}},"type":"object","required":["documento","email"],"title":"EmailDoCliente"},"Endereco":{"properties":{"cMun":{"type":"string","title":"Cmun"},"CEP":{"type":"string","title":"Cep"},"xLgr":{"type":"string","title":"Xlgr"},"nro":{"type":"string","title":"Nro"},"xBairro":{"type":"string","title":"Xbairro"},"xCpl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xcpl"}},"type":"object","required":["cMun","CEP","xLgr","nro","xBairro"],"title":"Endereco"},"EnderecoIn":{"properties":{"cMun":{"type":"string","title":"Cmun","description":"Código IBGE do município, 7 dígitos (ex.: 2408102 = Natal/RN)"},"CEP":{"type":"string","title":"Cep","description":"CEP só com dígitos (ex.: 59020000)"},"xLgr":{"type":"string","title":"Xlgr","description":"Logradouro (rua, avenida…)"},"nro":{"type":"string","title":"Nro","description":"Número; use \"S/N\" quando não houver"},"xBairro":{"type":"string","title":"Xbairro","description":"Bairro"},"xCpl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xcpl","description":"Complemento (sala, andar, bloco…)"}},"type":"object","required":["cMun","CEP","xLgr","nro","xBairro"],"title":"EnderecoIn","description":"Endereço nacional (do tomador) — os nomes são os do leiaute do gov.br."},"EnderecoLinhaIn":{"properties":{"cMun":{"type":"string","title":"Cmun"},"CEP":{"type":"string","title":"Cep"},"xLgr":{"type":"string","title":"Xlgr"},"nro":{"type":"string","title":"Nro"},"xBairro":{"type":"string","title":"Xbairro"},"xCpl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xcpl"}},"type":"object","required":["cMun","CEP","xLgr","nro","xBairro"],"title":"EnderecoLinhaIn"},"EnderecoReceitaOut":{"properties":{"xLgr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xlgr","description":"Logradouro, com o tipo junto (ex.: RUA EXEMPLO)"},"nro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nro","description":"Número"},"xCpl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xcpl","description":"Complemento, quando houver"},"xBairro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xbairro","description":"Bairro"},"CEP":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cep","description":"CEP com 8 dígitos, sem hífen"},"municipio_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Municipio Nome","description":"Nome do município"},"uf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uf","description":"Sigla da UF, 2 letras"},"cMun":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cmun","description":"Código IBGE do município (7 dígitos). Pode vir `null` quando não foi possível determiná-lo pelo CEP — nesse caso resolva com `/consultas/municipio`, nunca deduza o código"}},"additionalProperties":true,"type":"object","title":"EnderecoReceitaOut","description":"Endereço do CNPJ, já com os nomes de campo que a emissão de NFS-e usa."},"EnderecoTomador":{"properties":{"cMun":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cmun"},"CEP":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cep"},"xLgr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xlgr"},"nro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nro"},"xBairro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xbairro"},"xCpl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xcpl"},"municipio_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Municipio Nome"},"uf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uf"}},"type":"object","title":"EnderecoTomador","description":"Endereço do tomador — parcial é aceitável: o SERPRO não devolve código IBGE\n(o cMun vem do ViaCEP pelo CEP) e a varredura só preenche o que o XML trouxer."},"EntregaRecusada":{"properties":{"documento":{"type":"string","title":"Documento"},"email":{"type":"string","title":"Email"},"codigo":{"type":"string","title":"Codigo","description":"`email_invalido`, `email_para_conferir` (com `sugestao`), `email_da_empresa` ou `email_em_outro_cliente` (o mesmo e-mail para dois clientes no pedido)"},"detalhe":{"type":"string","title":"Detalhe"},"sugestao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sugestao"}},"type":"object","required":["documento","email","codigo","detalhe"],"title":"EntregaRecusada"},"EntregarIn":{"properties":{"emails":{"items":{"$ref":"#/components/schemas/EmailDoCliente"},"type":"array","maxItems":200,"minItems":1,"title":"Emails"},"guardar_no_cadastro":{"type":"boolean","title":"Guardar No Cadastro","description":"Grava o e-mail no cadastro do cliente que ainda não tem; troca só o endereço que o provedor devolveu (nunca sobrescreve outro e-mail cadastrado)","default":true}},"type":"object","required":["emails"],"title":"EntregarIn"},"EntregarOut":{"properties":{"a_enviar":{"type":"integer","title":"A Enviar","description":"Quantas notas foram para a fila de entrega"},"clientes":{"type":"integer","title":"Clientes","description":"De quantos clientes"},"recusados":{"items":{"$ref":"#/components/schemas/EntregaRecusada"},"type":"array","title":"Recusados","description":"Os e-mails recusados pelas travas da revisão do lote"},"sem_linha":{"items":{"type":"string"},"type":"array","title":"Sem Linha","description":"Os documentos sem linha a entregar neste lote (já enviada, de outro lote ou digitado errado)"}},"type":"object","required":["a_enviar","clientes","recusados","sem_linha"],"title":"EntregarOut"},"EnviarEmailIn":{"properties":{"para":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Para","description":"E-mail do destinatário. Omita para usar o e-mail cadastrado do tomador da nota — se não houver nenhum, a resposta é 422 EMAIL_OBRIGATORIO"},"salvar_no_tomador":{"type":"boolean","title":"Salvar No Tomador","description":"true grava este endereço no cadastro do cliente quando ele ainda não tem e-mail (nunca sobrescreve um e-mail já cadastrado)","default":false}},"type":"object","title":"EnviarEmailIn","description":"Para quem mandar a nota. Sem `para`, o destino é o e-mail do cadastro do cliente."},"EnviarEmailOut":{"properties":{"para":{"type":"string","title":"Para","description":"Endereço para onde o e-mail foi enviado"},"enviado_em":{"type":"string","format":"date-time","title":"Enviado Em","description":"Data/hora (UTC) do envio"},"danfse_source":{"type":"string","title":"Danfse Source","description":"De onde veio o PDF anexado"},"suprimido":{"type":"boolean","title":"Suprimido","description":"true quando o ambiente não entrega e-mail de verdade (chaves de teste)","default":false}},"additionalProperties":true,"type":"object","required":["para","enviado_em","danfse_source"],"title":"EnviarEmailOut","description":"O resultado do envio da nota ao cliente por e-mail."},"ErroOut":{"properties":{"code":{"type":"string","title":"Code","description":"Código estável em MAIÚSCULAS — programe por ele (ex.: EMPRESA_NAO_ENCONTRADA)"},"message":{"type":"string","title":"Message","description":"Frase em português, para mostrar a uma pessoa"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field","description":"Campo do corpo relacionado ao erro, quando houver"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hint","description":"Como resolver, quando houver"},"erros":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Erros","description":"Detalhe por campo (422): loc, type, msg"},"volta_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Volta Em","description":"Num limite que volta sozinho, quando ele volta (ISO 8601, UTC): a 0h de Brasília do dia seguinte nos limites do dia; a do dia 1º nas cotas do mês"},"upgrade":{"anyOf":[{"$ref":"#/components/schemas/UpgradeOut"},{"type":"null"}],"description":"Num limite do plano, o plano que resolve, com o preço e o link para assinar — só para o dono da conta, e só quando um plano resolve (o Plano Escritório no teto não tem: o `hint` diz como falar com a gente)"}},"type":"object","required":["code","message"],"title":"ErroOut","description":"Todo erro da API (4xx/5xx) volta neste envelope."},"EventoDaContaOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador do evento (evt_…) — serve em `GET /nfse/{nfse_id}/eventos/{id}/xml`"},"nfse_id":{"type":"string","title":"Nfse Id","description":"A nota que mudou de situação"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial da nota (nNFSe)"},"chave":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chave","description":"Chave de acesso da nota, 50 dígitos"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Empresa emissora da nota"},"codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo","description":"Código oficial do evento: 101101 cancelamento, 105102 substituição, 105104 cancelamento deferido por análise fiscal, 305101 cancelamento por ofício; com `todos=true`, também os que só registram histórico"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao","description":"Nome oficial do evento, como \"Cancelamento por ofício\""},"muda_situacao":{"type":"boolean","title":"Muda Situacao","description":"Se o evento tirou a nota de ativa; só vem `false` com `todos=true`","default":true},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Situação da nota hoje: `cancelada` ou `substituida` (com `todos=true`, também `ativa`)"},"substituida_por":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Substituida Por","description":"Na substituição, o id da nota que entrou no lugar"},"dh":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Dh","description":"Data/hora (UTC) OFICIAL do evento — a que vale para a contabilidade; pode ser de ontem nos que chegam pela importação do Sistema Nacional"},"cursor":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Cursor","description":"Quando o evento entrou nesta plataforma. É ISTO que vai em `desde` na próxima chamada: a hora oficial não serve de cursor, porque o cancelamento feito pela prefeitura chega depois com data anterior"},"xml_disponivel":{"type":"boolean","title":"Xml Disponivel","description":"Se `GET /nfse/{nfse_id}/eventos/{id}/xml` devolve o XML do evento"}},"type":"object","required":["id","nfse_id","xml_disponivel"],"title":"EventoDaContaOut","description":"Uma mudança de situação na conta: a nota, o evento e quando aconteceu."},"ExportCriadoOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da exportação (prefixo `exp_`) — use em `GET /api/v1/exports/{export_id}`"},"status":{"type":"string","title":"Status","description":"Sempre `pendente` aqui: o pacote começa a ser montado logo depois da resposta"}},"additionalProperties":true,"type":"object","required":["id","status"],"title":"ExportCriadoOut","description":"O recibo do pedido: a exportação entrou na fila."},"ExportIn":{"properties":{"competencia_de":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competencia De","description":"Primeira competência do pacote, `AAAA-MM`. Ausente = desde a primeira nota"},"competencia_ate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competencia Ate","description":"Última competência do pacote, `AAAA-MM`. Ausente = até a nota mais recente"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Restringe a uma empresa. Ausente = todas as empresas do seu acesso"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Só notas neste status: `ativa`, `cancelada` ou `substituida`. Ausente = todos"},"incluir_pdf":{"type":"boolean","title":"Incluir Pdf","description":"Inclui o DANFSE em PDF de cada nota. `false` deixa o pacote só com os XMLs e o CSV","default":true},"periodo_por":{"anyOf":[{"type":"string","pattern":"^(competencia|emissao|evento)$"},{"type":"null"}],"title":"Periodo Por","description":"Campo da faixa `de`/`ate`: `competencia` (padrão), `emissao` (data de autorização) ou `evento` (quando a nota saiu de ativa: cancelamento ou substituição)"},"de":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$"},{"type":"null"}],"title":"De","description":"Início da faixa, `AAAA-MM` (mês inteiro) ou `AAAA-MM-DD`; bordas no horário de Brasília. Alternativa a `competencia_de` — não misture os dois jeitos"},"ate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}(-\\d{2})?$"},{"type":"null"}],"title":"Ate","description":"Fim da faixa (inclusivo), no mesmo formato de `de`. Alternativa a `competencia_ate`"}},"type":"object","title":"ExportIn","description":"O recorte de notas que entra no pacote."},"ExportOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da exportação (prefixo `exp_`)"},"status":{"type":"string","title":"Status","description":"`pendente` (na fila), `processando` (montando o ZIP), `concluido` (pronto para baixar) ou `erro`"},"total_notas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Notas","description":"Quantas notas entraram no pacote; só tem significado com `status: concluido`"},"total_no_recorte":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total No Recorte","description":"Sempre igual a `total_notas` — o campo nasceu para dizer que o teto cortou, e não há mais corte: acima do tamanho do volume o pacote sai em `volumes`. Mantido pela compatibilidade"},"volumes":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Volumes","description":"Quando o recorte passa do tamanho do volume (2.000 notas só com XML, 1.000 com os PDFs) o pacote sai em VOLUMES — um por mês no eixo do recorte; mês grande parte em `(1 de N)`; se a contagem do período não pôde ser feita, partes de até um volume na ordem de numeração — e nunca cortado. O primeiro item é o `resumo` (`relatorio.html` do período inteiro + `relatorio.csv` completo); os demais trazem `rotulo`, `de`, `ate`, `total_notas`, `ativas`, `valor_ativas` e `bytes`. Baixe cada um em `GET …/download?volume=resumo|1|2|…`; sem o parâmetro vem o resumo. Ausente ou com um item só = pacote de um arquivo, como sempre"},"incluir_pdf":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Incluir Pdf","description":"Se o pacote inclui os PDFs (DANFSE)"},"filtros":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filtros","description":"O filtro aplicado, já com o recorte de empresas do seu acesso"},"erro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Erro","description":"Motivo em português quando `status` é `erro`"},"criado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Criado Em","description":"Quando a exportação foi pedida, em UTC (ISO 8601)"},"concluido_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Concluido Em","description":"Quando o pacote ficou pronto, em UTC (ISO 8601)"}},"additionalProperties":true,"type":"object","required":["id","status"],"title":"ExportOut","description":"O estado de uma exportação."},"HealthOut":{"properties":{"status":{"type":"string","title":"Status","description":"`ok` ou `degraded` (o HTTP é 200 nos dois casos)"},"api":{"type":"string","title":"Api","description":"Versão da API"},"core":{"type":"string","title":"Core","description":"Versão do núcleo de emissão"},"env":{"type":"string","title":"Env","description":"Ambiente que respondeu (ex.: `producao`)"},"scheduler_ha_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Scheduler Ha S","description":"Há quantos segundos o agendador deu sinal; acima de 300 vira `degraded`"},"mongo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mongo","description":"Presente só quando o banco não respondeu"}},"additionalProperties":true,"type":"object","required":["status","api","core","env"],"title":"HealthOut","description":"Resposta do /health — o que um monitor externo lê."},"InformacoesAdicionaisOut":{"properties":{"optante_simples":{"type":"boolean","title":"Optante Simples","description":"A Receita marca a empresa como optante pelo Simples Nacional"},"optante_mei":{"type":"boolean","title":"Optante Mei","description":"A Receita marca a empresa como MEI"},"periodos_simples":{"items":{"$ref":"#/components/schemas/PeriodoSimplesOut"},"type":"array","title":"Periodos Simples","description":"Entradas e saídas do Simples. Na consulta em tempo real (`fonte` `serpro`), o histórico; no cadastro mensal (`gerecnpj`), só o período mais recente"}},"additionalProperties":true,"type":"object","required":["optante_simples","optante_mei"],"title":"InformacoesAdicionaisOut","description":"O que a Receita informa sobre Simples Nacional e MEI."},"ItemDoLoteOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da linha (lti_…)"},"linha":{"type":"integer","title":"Linha","description":"A linha no arquivo (1 é a primeira)"},"estado":{"type":"string","title":"Estado","description":"A situação da linha (veja `contagens.por_estado` no lote)"},"incluir":{"type":"boolean","title":"Incluir","description":"A linha entra no lote (as repetidas e as que já têm nota ficam fora)"},"tomador":{"additionalProperties":true,"type":"object","title":"Tomador","description":"O cliente da nota: `tipo`, `documento`, `nome`, `email` e `endereco`"},"servico":{"additionalProperties":true,"type":"object","title":"Servico","description":"O serviço: `cTribNac`, `descricao` e de onde veio o código"},"valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor","description":"O valor da nota, em reais"},"pendencias":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Pendencias","description":"O que falta para a linha seguir: `campo` e `motivo`"},"nfse_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nfse Id","description":"A nota emitida pela linha (nfse_…), quando saiu"}},"additionalProperties":true,"type":"object","required":["id","linha","estado","incluir","tomador","servico","pendencias"],"title":"ItemDoLoteOut","description":"Uma linha do arquivo: a nota proposta, a situação e o que falta."},"ItemIn":{"properties":{"descricao":{"type":"string","title":"Descricao","description":"O que foi feito nesta linha"},"quantidade":{"type":"string","title":"Quantidade","description":"Quantidade como string decimal, maior que zero (ex.: \"2\")"},"valor_unitario":{"type":"string","title":"Valor Unitario","description":"Valor unitário em reais, string decimal (ex.: \"750.00\")"}},"type":"object","required":["descricao","quantidade","valor_unitario"],"title":"ItemIn","description":"Uma linha do detalhamento do serviço (a nota continua sendo de um serviço só)."},"ItensDoLoteOut":{"properties":{"itens":{"items":{"$ref":"#/components/schemas/ItemDoLoteOut"},"type":"array","title":"Itens"},"total":{"type":"integer","title":"Total","description":"Quantas linhas casam com o filtro"},"pagina":{"type":"integer","title":"Pagina"}},"type":"object","required":["itens","total","pagina"],"title":"ItensDoLoteOut"},"LinhaIn":{"properties":{"documento":{"type":"string","title":"Documento","description":"CPF ou CNPJ do cliente, com ou sem pontuação"},"valor":{"type":"string","title":"Valor","description":"Valor da nota (\"180,00\", \"1.234,56\" ou \"1234.56\")"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Nome do cliente — obrigatório no CPF"},"data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data","description":"Data da prestação (dd/mm/aaaa ou aaaa-mm-dd)"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao","description":"O texto do serviço na nota"},"codigo_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo Servico","description":"Código de tributação nacional (04.16.01 ou 041601)"},"nbs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nbs","description":"Código NBS, quando o município exige"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail do cliente: a nota vai para ele"},"endereco":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endereco","description":"Endereço em texto (rua, número, bairro)"},"cep":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cep","description":"CEP do endereço"}},"type":"object","required":["documento","valor"],"title":"LinhaIn","description":"Uma linha do lote pela API: os mesmos campos da planilha (texto, como numa célula)."},"LinkDoPacoteOut":{"properties":{"url":{"type":"string","title":"Url","description":"O link do arquivo no armazenamento, válido por 5 minutos. Abra ou baixe SEM cabeçalho de autenticação (o link já é a autorização); o arquivo vem como anexo, com o nome de `arquivo`"},"expira_em":{"type":"string","format":"date-time","title":"Expira Em","description":"Quando o link deixa de valer (UTC)"},"arquivo":{"type":"string","title":"Arquivo","description":"O nome com que o arquivo é baixado (ex.: \"gerenota-2026-06-a-2026-06.zip\")"}},"type":"object","required":["url","expira_em","arquivo"],"title":"LinkDoPacoteOut","description":"O link temporário do arquivo de uma exportação."},"ListaDeLotesOut":{"properties":{"lotes":{"items":{"$ref":"#/components/schemas/LoteOut"},"type":"array","title":"Lotes","description":"Os lotes da empresa, do mais novo para o mais antigo (90 dias)"},"pode_montar":{"type":"boolean","title":"Pode Montar","description":"O acesso em uso monta lotes (o dono, o operador e a contabilidade)"},"pode_emitir":{"type":"boolean","title":"Pode Emitir","description":"O acesso em uso confirma lotes: o dono, o operador e a contabilidade com \"Pode emitir notas\""}},"additionalProperties":true,"type":"object","required":["lotes","pode_montar","pode_emitir"],"title":"ListaDeLotesOut"},"LocalPrestacaoOut":{"properties":{"cMun":{"type":"string","title":"Cmun","description":"Código IBGE do município (7 dígitos)"},"municipio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Municipio","description":"Nome do município"},"uf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uf","description":"UF do município"}},"type":"object","required":["cMun"],"title":"LocalPrestacaoOut","description":"O município onde o serviço da nota foi prestado."},"LoteDaNotaOut":{"properties":{"lote_id":{"type":"string","title":"Lote Id","description":"O lote (lot_…), em GET /companies/{company_id}/lotes/{lote_id}"},"linha":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Linha","description":"A linha do arquivo (1 é a primeira)"},"arquivo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arquivo","description":"O nome do arquivo do lote"}},"type":"object","required":["lote_id"],"title":"LoteDaNotaOut","description":"S-LT (mockup G3): a nota que saiu de um lote — o arquivo e a linha dele."},"LoteDeLinhasIn":{"properties":{"linhas":{"items":{"$ref":"#/components/schemas/LinhaIn"},"type":"array","maxItems":200,"minItems":1,"title":"Linhas"},"nome":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Nome","description":"Um nome para reconhecer o lote"}},"type":"object","required":["linhas"],"title":"LoteDeLinhasIn"},"LoteOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador do lote (lot_…)"},"company_id":{"type":"string","title":"Company Id","description":"A empresa emissora do lote"},"origem":{"type":"string","title":"Origem","description":"\"painel\", \"api\" (as linhas em JSON), \"conector\" (as linhas pela IA conectada) ou \"lote_anterior\""},"arquivo":{"$ref":"#/components/schemas/ArquivoDoLoteOut"},"estado":{"type":"string","title":"Estado","description":"`lendo` → `em_revisao` (o formato conhecido) ou `aprendendo` → `entendi_assim` (o formato novo, que o painel confere) → `em_revisao` → `pronto_para_confirmar` (enviado a quem emite) → `confirmado` → `emitindo` → `concluido`, `parcial` (alguém cancelou o que faltava) ou `cancelado`. Também: `duvida` (uma pergunta sobre a planilha), `equipe` (a planilha foi à equipe), `acima_do_limite` (mais de 200 linhas), `invalido` (o arquivo não se lê) e `pausado`"},"contagens":{"anyOf":[{"$ref":"#/components/schemas/ContagensDoLoteOut"},{"additionalProperties":true,"type":"object"}],"title":"Contagens","description":"As linhas por situação; vazio enquanto o lote lê"},"criado_em":{"type":"string","format":"date-time","title":"Criado Em"},"atualizado_em":{"type":"string","format":"date-time","title":"Atualizado Em"}},"additionalProperties":true,"type":"object","required":["id","company_id","origem","arquivo","estado","contagens","criado_em","atualizado_em"],"title":"LoteOut","description":"Um lote: o arquivo, o estado e as contagens das linhas."},"MeOut":{"properties":{"account_id":{"type":"string","title":"Account Id","description":"Conta (tenant) a que a chave pertence"},"user_id":{"type":"string","title":"User Id","description":"Usuário dono da chave"},"role":{"type":"string","title":"Role","description":"Papel efetivo: `owner`, `operador`, `contabilidade` ou `leitor`"},"escopo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Escopo","description":"Escopo da chave de API em uso: `emissao` (emite, cancela, substitui) ou `leitura` (só consulta); nulo quando a sessão é de login no painel"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Nome do usuário, quando cadastrado"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail do usuário, quando cadastrado"},"telefone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telefone","description":"Telefone do usuário, só dígitos, quando cadastrado"},"telefone_verificado":{"type":"boolean","title":"Telefone Verificado","description":"Se o telefone já foi confirmado por código"},"empresas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Empresas","description":"Quantas empresas próprias a conta tem"},"compartilhadas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Compartilhadas","description":"Quantas empresas de outras contas foram compartilhadas com este usuário"},"plano_escritorio":{"type":"boolean","title":"Plano Escritorio","description":"`true` quando a conta está no Plano Escritório (o painel abre a Carteira para quem cuida de muitas empresas)","default":false},"empresa_padrao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Empresa Padrao","description":"`company_id` da empresa que o painel abre por padrão, quando há uma"},"billing":{"anyOf":[{"$ref":"#/components/schemas/BillingFlagsOut"},{"type":"null"}],"description":"Sinais de cobrança da conta"},"plano":{"anyOf":[{"$ref":"#/components/schemas/PlanoOut"},{"type":"null"}],"description":"Plano com uso × teto; `null` quando não foi possível apurar (não é erro)"},"importacao_auto":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Importacao Auto","description":"Se a importação automática de notas do Sistema Nacional está ligada no serviço"}},"additionalProperties":true,"type":"object","required":["account_id","user_id","role","telefone_verificado"],"title":"MeOut","description":"Identidade da chave em uso, com plano e sinais de cobrança."},"MinhaEmpresaOut":{"properties":{"id":{"type":"string","title":"Id","description":"Id da empresa: é o `company_id` das outras rotas"},"razao_social":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razao Social","description":"Razão social"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia, quando cadastrado"},"cnpj":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cnpj","description":"CNPJ, sem pontuação (pode ter letras nas 12 primeiras posições)"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"`ativa` (pode emitir), `cadastrada` (sem certificado validado) ou `inativa`"},"propria":{"type":"boolean","title":"Propria","description":"True = da sua conta; False = compartilhada por outra conta (aí vem `account_id` da dona)","default":true},"papel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Papel","description":"Seu papel efetivo nesta empresa: `owner`, `operador`, `contabilidade` ou `leitor`"},"pode_emitir":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Pode Emitir","description":"`true` quando você emite nota por esta empresa: o dono, o operador e a contabilidade com a opção \"Pode emitir notas\" que o dono liga no compartilhamento"},"municipio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Municipio","description":"Município/UF da sede, como `Natal/RN`"},"cert_bloqueado":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Cert Bloqueado","description":"True quando não há certificado válido: a emissão está bloqueada"},"emissao_parada":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emissao Parada","description":"A frase pronta quando a emissão está parada porque a empresa saiu do Simples Nacional; `null` quando ela emite"},"estado_aliquotas":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estado Aliquotas","description":"Situação das alíquotas do Simples: confirmadas para a competência ou pendentes"},"aliquota_atual":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Atual","description":"Percentual total de tributos do Simples em uso (pTotTribSN)"},"aliquota_iss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Iss","description":"Alíquota de ISS em uso, quando informada"},"aliquota_iss_fora_do_das":{"type":"boolean","title":"Aliquota Iss Fora Do Das","description":"A empresa está impedida de recolher o ISS no Simples (sublimite) — pela declaração PGDAS-D ou pelo cadastro (`regime.reg_ap_trib_sn` 2 ou 3): sem `aliquota_iss`, e nas notas com retenção vale a alíquota do município","default":false},"aliquota_competencia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Competencia","description":"Competência (AAAA-MM) para a qual as alíquotas foram confirmadas"},"tributacao_modo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tributacao Modo","description":"`auto` (do PGDAS) ou `manual`"},"receita_resumo":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Receita Resumo","description":"Resumo dos dados da Receita: `cnae_principal`, `porte`, `consultado_em`; nulo se nunca consultada"},"account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id","description":"Conta dona, presente nas empresas compartilhadas"}},"additionalProperties":true,"type":"object","required":["id"],"title":"MinhaEmpresaOut","description":"Uma empresa que a chave pode usar — própria da conta ou compartilhada com ela."},"MunicipioOut":{"properties":{"id":{"type":"string","title":"Id","description":"Código IBGE do município consultado, 7 dígitos"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Nome do município com a UF, na grafia do IBGE (ex.: \"Natal - RN\")"},"emite_pelo_sistema_nacional":{"type":"boolean","title":"Emite Pelo Sistema Nacional","description":"O município emite pelo Sistema Nacional (a prefeitura aderiu). Até 31/10/2026, a ME e a EPP sediadas num município com `false` ficam na lista de espera; o MEI emite em qualquer município e, a partir de 1º/11/2026, a ME e a EPP também"},"participa_do_ambiente_nacional":{"type":"boolean","title":"Participa Do Ambiente Nacional","description":"O município aceita notas com a prestação do serviço no território dele. É o campo que decide se você pode usar este município como local da prestação, e NÃO é o mesmo que emitir por aqui"},"aderente_emissor_nacional":{"type":"integer","title":"Aderente Emissor Nacional","description":"O valor cru do gov.br por trás de `emite_pelo_sistema_nacional` (0 ou 1)"},"aderente_ambiente_nacional":{"type":"integer","title":"Aderente Ambiente Nacional","description":"O valor cru do gov.br por trás de `participa_do_ambiente_nacional` (0 ou 1)"},"situacao_emissao_padrao":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Situacao Emissao Padrao","description":"Situação de emissão padrão dos contribuintes, como o gov.br informa"},"aderente_man":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Aderente Man","description":"Adesão ao Módulo de Apuração Nacional, como o gov.br informa"},"permite_aproveitamento_creditos":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"null"}],"title":"Permite Aproveitamento Creditos","description":"Se o município permite aproveitamento de créditos; repassado como o gov.br devolve (a chave do ADN é grafada `permiteAproveitametoDeCreditos`, sem o n — é assim que o gov.br manda)"},"fonte":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fonte","description":"De onde vieram os dados; hoje sempre `adn` (o gov.br)"},"verificado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Verificado Em","description":"Quando a informação foi buscada no gov.br (UTC, ISO 8601). O dado vale por 24 h"}},"additionalProperties":true,"type":"object","required":["id","emite_pelo_sistema_nacional","participa_do_ambiente_nacional","aderente_emissor_nacional","aderente_ambiente_nacional"],"title":"MunicipioOut","description":"Como um município está no Sistema Nacional da NFS-e, segundo o gov.br."},"NaoAchadoNaReceitaOut":{"properties":{"mes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mes","description":"O mês do cadastro em que o CNPJ não apareceu (`AAAA-MM`)"}},"type":"object","title":"NaoAchadoNaReceitaOut","description":"S-GC: o CNPJ que o cadastro da Receita do mês ainda não tem."},"NfseAgregadoOut":{"properties":{"total":{"type":"integer","title":"Total","description":"Quantidade de notas que casam com o filtro"},"valor_total":{"type":"string","title":"Valor Total","description":"Soma dos valores de serviço de TODAS as notas do filtro, string decimal com 2 casas (ex.: \"6821.40\") — inclui canceladas e substituídas; o faturamento válido é `por_status.ativa`"},"por_status":{"additionalProperties":{"$ref":"#/components/schemas/NfseAgregadoSituacaoOut"},"type":"object","title":"Por Status","description":"Detalhe por situação (\"ativa\", \"cancelada\", \"substituida\"), só as que aparecem no filtro"},"com_problema":{"anyOf":[{"$ref":"#/components/schemas/NfseAgregadoSituacaoOut"},{"type":"null"}],"description":"Quantas notas do filtro têm algum problema (`alertas`) e quanto somam — o número da aba \"Com problema\" da tela Notas; para listá-las, `com_problema=true` em `GET /nfse`"}},"additionalProperties":true,"type":"object","required":["total","valor_total"],"title":"NfseAgregadoOut","description":"O total do filtro atual — quantas notas e quanto somam, no geral e por situação."},"NfseAgregadoSituacaoOut":{"properties":{"total":{"type":"integer","title":"Total","description":"Quantidade de notas nesta situação"},"valor_total":{"type":"string","title":"Valor Total","description":"Soma dos valores de serviço nesta situação, string decimal com 2 casas"}},"type":"object","required":["total","valor_total"],"title":"NfseAgregadoSituacaoOut","description":"Quantidade e soma de uma situação dentro do filtro."},"NfseDetalheOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da nota nesta API (nfse_…)"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Empresa emissora da nota (cmp_…)"},"chave":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chave","description":"Chave de acesso da NFS-e, 50 dígitos"},"dps_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dps Id","description":"Identificador da DPS assinada; vazio em nota importada"},"serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serie","description":"Série da DPS"},"ndps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ndps","description":"Número sequencial da DPS (na listagem este mesmo dado se chama nDPS)"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial da NFS-e (nNFSe), o do DANFSE"},"dCompet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dcompet","description":"Competência (AAAA-MM-DD)"},"valor_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor Servico","description":"Valor do serviço em reais, string decimal"},"descricao_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao Servico","description":"Descrição do serviço impressa na nota"},"informacoes_complementares":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Informacoes Complementares","description":"Informações complementares da nota"},"tomador_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tomador Nome","description":"Nome do cliente, quando a nota tem tomador"},"tomador_documento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tomador Documento","description":"CNPJ ou CPF do cliente, sem pontuação: o CPF com 11 números; o CNPJ com 14 caracteres (letras A–Z só nas 12 primeiras posições, em maiúsculas)"},"cTribNac":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ctribnac","description":"Código de tributação nacional do serviço (6 dígitos)"},"cNBS":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cnbs","description":"Código NBS do serviço, quando informado"},"tribISSQN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tribissqn","description":"Tributação do ISSQN declarada (1 a 4)"},"tpRetISSQN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tpretissqn","description":"Retenção do ISSQN aplicada: 1, 2 ou 3"},"pAliq":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paliq","description":"Alíquota do ISSQN DECLARADA na emissão, em %, quando houve retenção"},"vISSQN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vissqn","description":"ISSQN apurado na nota pelo Sistema Nacional, em reais; `null` em notas antigas"},"vBC":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vbc","description":"Base de cálculo do ISSQN que o município usou, em reais; `null` em notas sem retenção e nas gravadas antes do campo existir"},"pAliqAplic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paliqaplic","description":"Alíquota que o município APLICOU, em %. Compare com `pAliq` (a declarada): diferente quer dizer que o município calculou por outra régua, e quem manda é esta"},"tot_trib_tipo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tot Trib Tipo","description":"\"pTotTribSN\" ou \"indTotTrib\""},"tot_trib_valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tot Trib Valor","description":"Percentual aproximado de tributos, quando pTotTribSN"},"vDescIncond":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vdescincond","description":"Desconto incondicionado"},"vDescCond":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vdesccond","description":"Desconto condicionado"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"\"ativa\", \"cancelada\" ou \"substituida\""},"origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origem","description":"\"plataforma\" (emitida pelo GereNota) ou \"importada\" (emitida fora do GereNota e trazida do Sistema Nacional)"},"lote":{"anyOf":[{"$ref":"#/components/schemas/LoteDaNotaOut"},{"type":"null"}],"description":"A nota saiu de um lote: o arquivo e a linha dele"},"fora_depois_da_entrada":{"type":"boolean","title":"Fora Depois Da Entrada","description":"true na nota emitida FORA do GereNota (`origem` importada) depois que a empresa entrou — outro sistema ainda emitindo pela empresa; false no histórico da entrada e nas notas do GereNota","default":false},"alertas":{"items":{"$ref":"#/components/schemas/AlertaNotaOut"},"type":"array","title":"Alertas","description":"Os problemas da nota, cada um com o que fazer — o último e-mail ao cliente que voltou, foi recusado ou marcado como spam; a retida com o ISS de outro mês; o município que aplicou outra alíquota; o cancelamento por ofício; e a nota que parece ter saído em dobro (a do GereNota e uma de fora, mesmo cliente, competência e valor, as duas ativas). Vazio na nota sem problema. Revistos quando o fato acontece e uma vez por dia"},"local_prestacao":{"anyOf":[{"$ref":"#/components/schemas/LocalPrestacaoOut"},{"type":"null"}],"description":"Onde o serviço foi prestado, como a nota declarou — é o local que a substituição mantém quando o pedido não traz `servico.cMunPrestacao`. `null` quando não foi possível ler o local agora (na nota antiga, ele vem do XML autorizado)"},"ambiente":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ambiente","description":"\"producao\" ou \"teste\""},"substitui_chave":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Substitui Chave","description":"Chave da nota que esta substituiu, se for o caso"},"substituida_por":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Substituida Por","description":"Id da nota que substituiu esta, se for o caso"},"cancelada_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Cancelada Em","description":"Quando a nota foi cancelada (UTC, hora oficial do evento); só em status cancelada"},"substituida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Substituida Em","description":"Quando a nota foi substituída (UTC): o dhEvento do e105102 ou a autorização da substituta, o que vier primeiro; só em status substituida"},"emitida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Emitida Em","description":"Data/hora (UTC) da autorização da nota"}},"additionalProperties":true,"type":"object","required":["id"],"title":"NfseDetalheOut","description":"A nota inteira como ficou guardada, com tributação, descontos e situação."},"NfseEmitIn":{"properties":{"dCompet":{"type":"string","title":"Dcompet","description":"Competência no formato AAAA-MM-DD: a data da prestação do serviço. Não pode ser futura"},"servico":{"$ref":"#/components/schemas/ServicoIn","description":"O serviço prestado"},"valores":{"$ref":"#/components/schemas/ValoresIn","description":"Os valores da nota"},"tributacao":{"$ref":"#/components/schemas/TributacaoIn","description":"Tributação do ISSQN — omita para o caso comum (tributado no município, sem retenção)","default":{"tribISSQN":"1","tpRetISSQN":"1"}},"tomador":{"anyOf":[{"$ref":"#/components/schemas/gerenota_api__emissions__TomadorIn"},{"type":"null"}],"description":"O cliente. Opcional: a nota pode sair sem tomador identificado"},"ambiente":{"type":"string","enum":["producao","teste"],"title":"Ambiente","description":"\"producao\" (padrão) emite a nota valendo. \"teste\" valida tudo no ambiente restrito do gov.br sem efeito fiscal: não consome cota, não aparece nas listagens e é descartada em 24 h","default":"producao"}},"type":"object","required":["dCompet","servico","valores"],"title":"NfseEmitIn","description":"O pedido de emissão (a DPS). Série, número, alíquota e regime saem do cadastro da empresa."},"NfseEventoOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador do evento nesta API (evt_…)"},"nfse_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nfse Id","description":"A nota a que o evento pertence"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Empresa emissora da nota"},"chave":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chave","description":"Chave de acesso da nota, 50 dígitos"},"tipo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo","description":"\"cancelamento\", \"substituicao\" ou \"dfe:<código>\" para eventos espelhados do Sistema Nacional"},"codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo","description":"Código oficial do evento no leiaute nacional: 101101 cancelamento, 105102 substituição, 105104 cancelamento deferido por análise fiscal e 305101 cancelamento por ofício tiram a nota de ativa; os demais (análise fiscal pedida ou indeferida, bloqueio e desbloqueio por ofício, confirmação e rejeição) só registram histórico"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao","description":"Nome oficial do evento, como \"Cancelamento por ofício\" ou \"Rejeição do tomador\""},"muda_situacao":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Muda Situacao","description":"Se o evento tirou a nota de ativa (cancelamento ou substituição, por qualquer via); os outros só registram histórico"},"detalhe":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Detalhe","description":"Dados do evento: no cancelamento, cMotivo e xMotivo; na substituição, cMotivo e o id da nota que substituiu"},"dh":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Dh","description":"Data/hora (UTC) oficial do evento: o dhEvento do XML nos espelhados do gov.br, o registro nesta API nos feitos aqui — é a data que vale para a contabilidade"},"xml_disponivel":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Xml Disponivel","description":"Se `GET /nfse/{nfse_id}/eventos/{id}/xml` devolve o XML deste evento"}},"additionalProperties":true,"type":"object","required":["id"],"title":"NfseEventoOut","description":"Um evento na linha do tempo da nota (cancelamento, substituição, eventos do gov.br)."},"NfseOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da nota nesta API (nfse_…) — use nas rotas /nfse/{nfse_id}"},"chave_acesso":{"type":"string","title":"Chave Acesso","description":"Chave de acesso da NFS-e no Sistema Nacional, 50 dígitos"},"serie":{"type":"string","title":"Serie","description":"Série da DPS, do cadastro da empresa"},"nDPS":{"type":"string","title":"Ndps","description":"Número sequencial da DPS dentro da série"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial da NFS-e (nNFSe) atribuído pelo gov.br — é este que sai no DANFSE e o que o cliente enxerga"},"dps_id":{"type":"string","title":"Dps Id","description":"Identificador da DPS assinada que gerou a nota"},"valor_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor Servico","description":"Valor do serviço em reais, string decimal (ex.: \"1500.00\")"},"status":{"type":"string","title":"Status","description":"Situação da nota: \"ativa\" logo após a emissão"},"ndps_ressincronizado":{"type":"boolean","title":"Ndps Ressincronizado","description":"true quando o número da DPS foi realinhado com o servidor porque outro emissor usava a série","default":false},"elapsed_ms":{"type":"integer","title":"Elapsed Ms","description":"Tempo da conversa com o Sistema Nacional, em milissegundos"},"substitui_chave":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Substitui Chave","description":"Chave da nota substituída, quando esta nota saiu de uma substituição"},"avisos":{"anyOf":[{"items":{"$ref":"#/components/schemas/AvisoOut"},"type":"array"},{"type":"null"}],"title":"Avisos","description":"O que vale conferir numa nota que saiu — hoje, o ISS retido por um tomador de fora do município do ISS (`RETENCAO_COM_TOMADOR_DE_OUTRO_MUNICIPIO`); nulo quando não há nada"}},"type":"object","required":["id","chave_acesso","serie","nDPS","dps_id","valor_servico","status","elapsed_ms"],"title":"NfseOut","description":"A nota autorizada pelo Sistema Nacional — a resposta da emissão e da substituição."},"NfseResumoOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da nota nesta API (nfse_…)"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial da NFS-e (nNFSe), o do DANFSE"},"nDPS":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ndps","description":"Número sequencial da DPS dentro da série"},"serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serie","description":"Série da DPS"},"chave":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chave","description":"Chave de acesso da NFS-e, 50 dígitos"},"dCompet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dcompet","description":"Competência (AAAA-MM-DD)"},"valor_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor Servico","description":"Valor do serviço em reais, string decimal"},"descricao_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao Servico","description":"Descrição do serviço impressa na nota"},"cTribNac":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ctribnac","description":"Código de tributação nacional do serviço (6 dígitos)"},"tomador_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tomador Nome","description":"Nome do cliente, quando a nota tem tomador"},"tomador_documento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tomador Documento","description":"CNPJ ou CPF do cliente, sem pontuação: o CPF com 11 números; o CNPJ com 14 caracteres (letras A–Z só nas 12 primeiras posições, em maiúsculas)"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"\"ativa\", \"cancelada\" ou \"substituida\""},"cancelada_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Cancelada Em","description":"Quando a nota foi cancelada (UTC, hora oficial do evento); só em status cancelada"},"substituida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Substituida Em","description":"Quando a nota foi substituída (UTC): o dhEvento do e105102 ou a autorização da substituta, o que vier primeiro; só em status substituida"},"substituida_por":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Substituida Por","description":"Id da nota que substituiu esta, se for o caso"},"substituida_por_numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Substituida Por Numero","description":"Número oficial da nota que substituiu esta, para citar sem outra chamada"},"evento_situacao":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Evento Situacao","description":"O evento que tirou a nota de ativa, `{\"codigo\", \"descricao\"}`: 101101 cancelamento, 105102 substituição, 105104 cancelamento deferido por análise fiscal ou 305101 cancelamento por ofício; `null` nas ativas"},"substitui_chave":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Substitui Chave","description":"Chave da nota que esta substituiu, se for o caso"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Empresa emissora da nota (cmp_…)"},"emitida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Emitida Em","description":"Data/hora (UTC) da autorização da nota"},"tpRetISSQN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tpretissqn","description":"Retenção do ISSQN aplicada: 1, 2 ou 3"},"pAliq":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paliq","description":"Alíquota do ISSQN DECLARADA na emissão, em %, quando houve retenção"},"vISSQN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vissqn","description":"ISSQN apurado na nota pelo Sistema Nacional, em reais; `null` em notas antigas"},"vBC":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vbc","description":"Base de cálculo do ISSQN que o município usou, em reais; `null` em notas sem retenção e nas gravadas antes do campo existir"},"pAliqAplic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paliqaplic","description":"Alíquota que o município APLICOU, em %. Compare com `pAliq` (a declarada): diferente quer dizer que o município calculou por outra régua, e quem manda é esta"},"tot_trib_tipo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tot Trib Tipo","description":"Como os tributos foram informados: \"pTotTribSN\" ou \"indTotTrib\""},"tot_trib_valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tot Trib Valor","description":"Percentual aproximado de tributos, quando pTotTribSN"},"vDescIncond":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vdescincond","description":"Desconto incondicionado"},"vDescCond":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vdesccond","description":"Desconto condicionado"},"origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origem","description":"\"plataforma\" (emitida pelo GereNota) ou \"importada\" (emitida fora do GereNota — pelo portal do Emissor Nacional, por outro sistema ou pela prefeitura — e trazida do Sistema Nacional)"},"lote":{"anyOf":[{"$ref":"#/components/schemas/LoteDaNotaOut"},{"type":"null"}],"description":"A nota saiu de um lote: o arquivo e a linha dele"},"fora_depois_da_entrada":{"type":"boolean","title":"Fora Depois Da Entrada","description":"true na nota emitida FORA do GereNota (`origem` importada) depois que a empresa entrou — outro sistema ainda emitindo pela empresa; false no histórico da entrada e nas notas do GereNota","default":false},"alertas":{"items":{"$ref":"#/components/schemas/AlertaNotaOut"},"type":"array","title":"Alertas","description":"Os problemas da nota, cada um com o que fazer — o último e-mail ao cliente que voltou, foi recusado ou marcado como spam; a retida com o ISS de outro mês; o município que aplicou outra alíquota; o cancelamento por ofício; e a nota que parece ter saído em dobro (a do GereNota e uma de fora, mesmo cliente, competência e valor, as duas ativas). Vazio na nota sem problema. Revistos quando o fato acontece e uma vez por dia"}},"additionalProperties":true,"type":"object","required":["id"],"title":"NfseResumoOut","description":"Uma nota na listagem: o resumo que alimenta tabelas, conferências e relatórios."},"NfseSubstituirIn":{"properties":{"dCompet":{"type":"string","title":"Dcompet","description":"Competência no formato AAAA-MM-DD: a data da prestação do serviço. Não pode ser futura"},"servico":{"$ref":"#/components/schemas/ServicoIn","description":"O serviço prestado"},"valores":{"$ref":"#/components/schemas/ValoresIn","description":"Os valores da nota"},"tributacao":{"$ref":"#/components/schemas/TributacaoIn","description":"Tributação do ISSQN — omita para o caso comum (tributado no município, sem retenção)","default":{"tribISSQN":"1","tpRetISSQN":"1"}},"tomador":{"anyOf":[{"$ref":"#/components/schemas/gerenota_api__emissions__TomadorIn"},{"type":"null"}],"description":"O cliente. Opcional: a nota pode sair sem tomador identificado"},"ambiente":{"type":"string","enum":["producao","teste"],"title":"Ambiente","description":"\"producao\" (padrão) emite a nota valendo. \"teste\" valida tudo no ambiente restrito do gov.br sem efeito fiscal: não consome cota, não aparece nas listagens e é descartada em 24 h","default":"producao"},"motivo":{"$ref":"#/components/schemas/SubstituicaoMotivoIn","description":"A justificativa fiscal da substituição"}},"type":"object","required":["dCompet","servico","valores","motivo"],"title":"NfseSubstituirIn","description":"A nota CORRIGIDA (mesmo corpo da emissão) mais o motivo da substituição."},"PedidoIn":{"properties":{"recado":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Recado","description":"O recado a quem é dono (até 500 caracteres; no WhatsApp, até 200 e sem link)"}},"type":"object","title":"PedidoIn"},"PedidoOut":{"properties":{"id":{"type":"string","title":"Id","description":"O id do pedido (`cpd_…`)"},"company_id":{"type":"string","title":"Company Id"},"empresa":{"type":"string","title":"Empresa","description":"O nome da empresa"},"email":{"type":"string","title":"Email","description":"O e-mail do acesso de quem pediu: se quem é dono liberar, o link vai para ele"},"estado":{"type":"string","enum":["aberto","liberado","recusado","vencido"],"title":"Estado"},"recado":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recado"},"criado_em":{"type":"string","format":"date-time","title":"Criado Em"},"vence_em":{"type":"string","format":"date-time","title":"Vence Em","description":"O pedido vence 7 dias depois de criado"}},"type":"object","required":["id","company_id","empresa","email","estado","criado_em","vence_em"],"title":"PedidoOut"},"PendenciaDaReceitaOut":{"properties":{"desde":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Desde","description":"Desde quando a ficha espera (UTC, ISO 8601)"}},"type":"object","title":"PendenciaDaReceitaOut","description":"S-GC: a ficha que espera a atualização pela Receita."},"PeriodoSimplesOut":{"properties":{"dataInicio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Datainicio","description":"Início da opção (AAAA-MM-DD)"},"dataFim":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Datafim","description":"Fim da opção; vazio (`\"\"`) quando o período segue em aberto, isto é, optante hoje"}},"additionalProperties":true,"type":"object","title":"PeriodoSimplesOut","description":"Um período de opção pelo Simples Nacional, como a Receita devolve."},"PgdasSyncIn":{"properties":{"aceite":{"type":"boolean","title":"Aceite","description":"Consentimento explícito na 1ª sincronização — o termo assinado é o instrumento. Só o dono da conta.","default":false},"forcar":{"type":"boolean","title":"Forcar","description":"Ignora o cache mensal (a consulta é PAGA — R$ 0,24 por PA pedido)","default":false},"pa":{"anyOf":[{"type":"string","pattern":"^\\d{6}$"},{"type":"null"}],"title":"Pa","description":"Só este PA (`AAAAMM`) — uma consulta paga. Omitido: M−1, M−2 e M−3 na ordem do calendário (antes do dia 21, M−2 primeiro), parando na primeira declaração encontrada"}},"type":"object","title":"PgdasSyncIn"},"PgdasSyncOut":{"properties":{"periodo_apuracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Periodo Apuracao","description":"PA (período de apuração, `AAAAMM`) da declaração mais recente da empresa"},"p_tot_trib_sn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Tot Trib Sn","description":"Efetiva total declarada nesse PA (%)"},"p_aliq_iss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Aliq Iss","description":"ISS efetivo declarado nesse PA (%)"},"regime_apuracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regime Apuracao","description":"`caixa` ou `competencia` — o regime do ANO CORRENTE (o de cada declaração está em `declaracao.regime_apuracao`); ver `regime_apuracao_fonte`"},"regime_apuracao_fonte":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Regime Apuracao Fonte","description":"De onde vem `regime_apuracao`: `rfb` = opção registrada na Receita Federal (Integra Contador, REGIMEAPURACAO); `pgdas` = item 1 da última declaração, do próprio ano; `padrao` = consultado e sem opção registrada (competência, a regra geral); `lei` = a partir de 2027 só há competência"},"regimes_apuracao":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Regimes Apuracao","description":"Opções registradas na Receita Federal, ano → `caixa` | `competencia`"},"regime_consultado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Regime Consultado Em","description":"Última consulta à Receita (REGIMEAPURACAO)"},"regime_apuracao_divergencia":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Regime Apuracao Divergencia","description":"Quando a declaração e a opção registrada discordam no mesmo ano: {ano, pa, rfb, declaracao}"},"rbt12":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rbt12","description":"RBT12 declarada nesse PA (R$)"},"consultado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Consultado Em","description":"Quando a consulta foi feita"},"fonte":{"type":"string","title":"Fonte","description":"`pgdas` (consultou agora) ou `cache` (já consultado neste mês, sem nova consulta)"},"aliquota":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Aliquota","description":"O que a conta deu: `atual` (a alíquota do mês, aplicada ou não), `proxima`, `aplicada`, `mudou_atual`"},"conferencia":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conferencia","description":"A conferência da declaração contra o mês que ela prova: aliquota (veredito), receita (veredito, declarada, notas, diferenca, avisar e as frases prontas frase_titulo + frase + detalhes; doze_meses quando o histórico de notas cobre a janela), retificados"},"principal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Principal","description":"False quando a declaração consultada é mais antiga que a atual (só histórico)"},"pa_consultado":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pa Consultado","description":"O PA que esta chamada consultou ou devolveu (`AAAAMM`)"},"declaracao":{"anyOf":[{"$ref":"#/components/schemas/DeclaracaoPgdasOut"},{"type":"null"}],"description":"A declaração do PA consultado, como no histórico; se for mais antiga que a mais recente da empresa, a ficha e a alíquota não mudam"}},"additionalProperties":true,"type":"object","required":["fonte"],"title":"PgdasSyncOut","description":"O resumo da ficha (a declaração mais recente da empresa) mais o que a conta e a conferência deram e,\nquando um PA foi pedido, a declaração desse PA. Campos além destes vêm no mesmo objeto (RBT12p/RBA/RBAA,\nversão, transmissão, ISS retido no PA)."},"PlanoOut":{"properties":{"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Nome comercial do plano (ex.: Individual)"},"empresas":{"anyOf":[{"$ref":"#/components/schemas/UsoTetoOut"},{"type":"null"}],"description":"Empresas cadastradas × teto do plano"},"automacoes":{"anyOf":[{"$ref":"#/components/schemas/UsoTetoOut"},{"type":"null"}],"description":"Automações × teto do plano"},"acessos":{"anyOf":[{"$ref":"#/components/schemas/UsoTetoOut"},{"type":"null"}],"description":"Acessos compartilhados × teto do plano"},"notas":{"anyOf":[{"$ref":"#/components/schemas/CotaDeNotasOut"},{"type":"null"}],"description":"Notas emitidas no mês × cota do plano"},"relatorios":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Relatorios","description":"Se o plano inclui relatórios agendados"},"api_mcp":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Api Mcp","description":"Se o plano inclui o uso desta API"},"consultas":{"anyOf":[{"$ref":"#/components/schemas/CotaOut"},{"type":"null"}],"description":"Consultas pagas de CNPJ/CPF feitas no mês × cota do plano"},"upgrade_relatorios":{"anyOf":[{"$ref":"#/components/schemas/UpgradeOut"},{"type":"null"}],"description":"Só para o dono da conta, quando o plano não inclui relatórios agendados: o primeiro plano que inclui, com o preço e o link para assinar"},"upgrade_api_mcp":{"anyOf":[{"$ref":"#/components/schemas/UpgradeOut"},{"type":"null"}],"description":"Só para o dono da conta, quando o plano não inclui esta API: o primeiro plano que inclui, com o preço e o link para assinar"}},"additionalProperties":true,"type":"object","title":"PlanoOut","description":"Plano da conta com uso × teto — a mesma régua que a API aplica ao barrar."},"PlanoQueResolveOut":{"properties":{"id":{"type":"string","title":"Id","description":"Id do plano (ex.: plan_solo)"},"nome":{"type":"string","title":"Nome","description":"Nome do plano na vitrine (ex.: Individual)"},"rotulo":{"type":"string","title":"Rotulo","description":"Como citar o plano num texto (ex.: \"Plano Individual\")"},"preco_base":{"type":"string","title":"Preco Base","description":"Preço do mês em reais, como texto (ex.: \"19.90\")"},"preco_anual":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preco Anual","description":"Preço do ciclo anual em reais, quando o plano tem"}},"type":"object","required":["id","nome","rotulo","preco_base"],"title":"PlanoQueResolveOut","description":"O plano que resolve um limite, com os nomes da vitrine (`GET /billing/plans`)."},"PularIn":{"properties":{"ocorrencia":{"type":"string","format":"date-time","title":"Ocorrencia","description":"A nota que não deve sair: o `proxima_execucao` que a automação mostra agora, em ISO 8601"}},"type":"object","required":["ocorrencia"],"title":"PularIn"},"ReceitaDoCadastroOut":{"properties":{"consultada":{"type":"boolean","title":"Consultada","description":"`true`: o cadastro saiu da Receita"},"de_cache":{"type":"boolean","title":"De Cache","description":"`true` quando a busca saiu do cache (o mesmo CNPJ no mesmo mês do cadastro mensal, ou consultado em tempo real nos últimos 7 dias): não gastou a cota"},"situacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Situacao","description":"Situação cadastral em minúsculas: `ativa`, `suspensa`, `inapta`, `baixada` ou `nula`"},"situacao_desde":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Situacao Desde","description":"Desde quando vale a situação (AAAA-MM-DD)"},"ativa":{"type":"boolean","title":"Ativa","description":"`false` quando o CNPJ não está ativo — confira com o cliente antes de emitir"},"razao_social":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Razao Social","description":"A razão social na Receita (é o `nome` do cadastro)"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"O nome fantasia na Receita, quando houver"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"O e-mail da Receita. NÃO entra no cadastro como e-mail de entrega (costuma ser o do contador): para usá-lo, mande-o em `PATCH /tomadores/{id}`"}},"type":"object","required":["consultada","de_cache","ativa"],"title":"ReceitaDoCadastroOut","description":"S-TR: o que a busca automática na Receita trouxe, quando o cadastro foi feito só com o CNPJ."},"ReceitaDoCampoOut":{"properties":{"origem":{"type":"string","enum":["espelho","cliente"],"title":"Origem","description":"`espelho`: veio da Receita e ninguém editou — acompanha o cadastro todo mês (com a atualização automática da conta ligada); `cliente`: digitado, preenchido pelo link, vindo da nota ou editado — a Receita só sugere"},"mes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mes","description":"O mês do cadastro da Receita da última comparação (`AAAA-MM`)"}},"type":"object","required":["origem"],"title":"ReceitaDoCampoOut","description":"S-GC: de onde veio um campo da ficha do cliente CNPJ, na comparação com o cadastro da Receita."},"ReceitaOut":{"properties":{"situacao_cadastral":{"anyOf":[{"$ref":"#/components/schemas/SituacaoCnpjOut"},{"type":"null"}],"description":"Situação cadastral e sua data"},"data_abertura":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Abertura","description":"Data de abertura do CNPJ (AAAA-MM-DD)"},"cnae_principal":{"anyOf":[{"$ref":"#/components/schemas/CodigoDescricaoOut"},{"type":"null"}],"description":"CNAE da atividade principal"},"cnaes_secundarios":{"items":{"$ref":"#/components/schemas/CodigoDescricaoOut"},"type":"array","title":"Cnaes Secundarios","description":"CNAEs secundários; lista vazia quando não há"},"natureza_juridica":{"anyOf":[{"$ref":"#/components/schemas/CodigoDescricaoOut"},{"type":"null"}],"description":"Natureza jurídica da empresa"},"porte":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Porte","description":"Código do porte informado pela Receita (ex.: \"ME\")"},"porte_descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Porte Descricao","description":"Porte por extenso"},"capital_social_centavos":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Capital Social Centavos","description":"Capital social em CENTAVOS, exatamente como a Receita devolve"},"capital_social":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capital Social","description":"O mesmo capital social convertido para reais (ex.: 5000.0)"},"tipo_estabelecimento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Estabelecimento","description":"MATRIZ ou FILIAL"},"tipo_estabelecimento_descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Estabelecimento Descricao","description":"Tipo de estabelecimento por extenso"},"municipio_jurisdicao":{"anyOf":[{"$ref":"#/components/schemas/CodigoDescricaoOut"},{"type":"null"}],"description":"Município da jurisdição na Receita. ATENÇÃO: este código é interno da Receita e NÃO é o código IBGE — para o IBGE use `endereco.cMun`"},"situacao_especial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Situacao Especial","description":"Situação especial, quando houver"},"data_situacao_especial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Situacao Especial","description":"Data da situação especial (AAAA-MM-DD)"},"informacoes_adicionais":{"anyOf":[{"$ref":"#/components/schemas/InformacoesAdicionaisOut"},{"type":"null"}],"description":"Simples Nacional e MEI; só vem na consulta completa (`completo=true`)"},"qsa":{"anyOf":[{"items":{"$ref":"#/components/schemas/SocioOut"},"type":"array"},{"type":"null"}],"title":"Qsa","description":"Quadro societário; só vem na consulta completa (`completo=true`)"},"fonte":{"anyOf":[{"type":"string","enum":["serpro","gerecnpj"]},{"type":"null"}],"title":"Fonte","description":"De onde veio o bloco: `gerecnpj` (o cadastro mensal) ou `serpro` (em tempo real)"},"mes_referencia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mes Referencia","description":"No cadastro mensal: o mês da publicação da Receita (AAAA-MM)"},"data_extracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Extracao","description":"No cadastro mensal: o dia em que a Receita extraiu os dados (AAAA-MM-DD)"},"atualizando":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Atualizando","description":"`true` nos minutos em que o mês novo é aplicado: o dado pode misturar os dois meses e não fica guardado no cache"}},"additionalProperties":true,"type":"object","title":"ReceitaOut","description":"Tudo o que a consulta ao CNPJ traz além do cadastro básico. Campos que a Receita não\ndevolveu (ou que só existem na consulta completa) vêm `null` ou lista vazia."},"RecorrenteIn":{"properties":{"tomador_documento":{"type":"string","title":"Tomador Documento"},"dia":{"type":"integer","maximum":28.0,"minimum":1.0,"title":"Dia"},"valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor"},"cTribNac":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ctribnac"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao"},"nome":{"type":"string","title":"Nome","default":""},"avisos":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Avisos"},"entrega_tomador":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Entrega Tomador"},"tributacao":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tributacao"}},"type":"object","required":["tomador_documento","dia"],"title":"RecorrenteIn","description":"Criação manual (mockup tela 4). O serviço vem da ÚLTIMA nota do tomador —\no mesmo caminho do aceite de sugestão, sem recriar o seletor fiscal do Emitir."},"RegimeSugeridoOut":{"properties":{"op_simp_nac":{"type":"string","title":"Op Simp Nac","description":"Valor pronto para o campo `opSimpNac` da NFS-e: `1` (não optante), `2` (MEI) ou `3` (Simples)"},"optante_simples":{"type":"boolean","title":"Optante Simples","description":"A Receita marca a empresa como optante pelo Simples"},"optante_mei":{"type":"boolean","title":"Optante Mei","description":"A Receita marca a empresa como MEI"},"periodo_em_aberto":{"type":"boolean","title":"Periodo Em Aberto","description":"Há um período do Simples valendo hoje (o início já passou e o fim, se houver, ainda não) — é o que prova optante HOJE. Uma empresa que já saiu do Simples aparece como optante no histórico, mas com o período fechado"},"periodos_simples":{"items":{"$ref":"#/components/schemas/PeriodoSimplesOut"},"type":"array","title":"Periodos Simples","description":"Entradas e saídas do Simples (no cadastro mensal, só o período mais recente). O fim no futuro vem como `\"\"` (ainda optante) e a data vai para `exclusao_marcada`"},"exclusao_marcada":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exclusao Marcada","description":"A saída do Simples já marcada para uma data futura (AAAA-MM-DD): até lá, segue optante"},"nao_optante_explicito":{"type":"boolean","title":"Nao Optante Explicito","description":"A Receita, em tempo real, diz NÃO ao Simples e ao MEI — a prova que recusa o cadastro e para a emissão (a GereNota atende só Simples Nacional e MEI). O cadastro mensal nunca marca esta prova, e o `op_simp_nac` 1 sem ela é só sugestão","default":false},"fonte":{"anyOf":[{"type":"string","enum":["serpro","gerecnpj"]},{"type":"null"}],"title":"Fonte","description":"De onde veio o regime"}},"additionalProperties":true,"type":"object","required":["op_simp_nac","optante_simples","optante_mei","periodo_em_aberto"],"title":"RegimeSugeridoOut","description":"O regime tributário deduzido do cadastro da Receita — só na consulta completa."},"RegimeTributario":{"properties":{"op_simp_nac":{"type":"string","enum":["1","2","3"],"title":"Op Simp Nac","description":"Opção pelo Simples Nacional: 2 = MEI · 3 = ME/EPP. A GereNota atende só Simples Nacional e MEI: 1 (não optante) volta 422 `EMPRESA_FORA_DO_SIMPLES` (o SEFIN valida o regime contra o cadastro do Simples por competência — E0160)","default":"3"},"reg_ap_trib_sn":{"anyOf":[{"type":"string","enum":["1","2","3"]},{"type":"null"}],"title":"Reg Ap Trib Sn","description":"Só ME/EPP (op_simp_nac=3): 1 = tudo no DAS · 2 = ISS por fora (sublimite estourado) · 3 = ISS e ICMS por fora","default":"1"},"reg_esp_trib":{"type":"string","enum":["0","1","2","3","4","5","6","9"],"title":"Reg Esp Trib","description":"Regime especial de tributação: 0 = nenhum · 1 = cooperativa · 2 = estimativa · 3 = ME municipal · 4 = notário · 5 = autônomo · 6 = sociedade de profissionais · 9 = outros","default":"0"},"p_tot_trib_sn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Tot Trib Sn","description":"Efetiva total do Simples (%) — o `pTotTribSN` das notas. Informado aqui é alíquota MANUAL do dono; no modo automático vem do PGDAS-D mês a mês. ME/EPP sem valor não emite (422 ALIQUOTA_NAO_CONFIRMADA)"},"p_aliq_iss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Aliq Iss","description":"ISS efetivo (%) — a `pAliq` das notas COM retenção. Mesma regra do p_tot_trib_sn"},"ibs_cbs_no_das":{"anyOf":[{"type":"string","enum":["dentro","fora"]},{"type":"null"}],"title":"Ibs Cbs No Das","description":"2027: IBS/CBS recolhidos DENTRO do DAS ou por fora (regime híbrido) — a opção de setembro/2026. Registro; a composição do DAS de 2027 é modelagem futura"},"aliquota_confirmada_para":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Confirmada Para","description":"Mês (AAAA-MM) para o qual a alíquota vale — confirmada (no painel, pelo WhatsApp ou pela API) ou calculada pela plataforma (automático). None = nunca confirmada"},"aliquota_fonte":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Fonte","description":"De onde veio a alíquota em vigor: manual (confirmada manualmente — painel, WhatsApp, MCP) · detectada (a mais usada nas notas importadas) · calculada (pela RBT12 informada, em chamada direta à API) · pgdas · estimada · proporcionalizada · inicio_atividade"},"aliquota_detectada":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Detectada","description":"Moda do pTotTribSN nas notas importadas — sugestão de 1 clique, nunca aplicada sozinha"},"aliquota_conta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Conta","description":"A conta aberta da alíquota do mês (modo automático): «13,79 % (ISS 4,48 %): RBT12 R$ 1.616.078 = Σ set/25..ago/26 do PGDAS 202608 — Anexo III, 4ª faixa»"},"aliquota_rbt12":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Rbt12","description":"A RBT12 usada na conta (R$)"},"aliquota_anexo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aliquota Anexo","description":"Anexo do Simples usado na conta (III, IV ou V)"},"aliquota_faixa":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Aliquota Faixa","description":"Faixa (1–6) usada na conta"},"aliquota_meses_estimados":{"items":{"type":"string"},"type":"array","title":"Aliquota Meses Estimados","description":"Meses (AAAA-MM) cuja receita veio das notas, não da declaração — alíquota `estimada`"},"aliquota_iss_fora_do_das":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Aliquota Iss Fora Do Das","description":"True quando a empresa está impedida de recolher o ISS no DAS (sublimite): sem p_aliq_iss — vale a alíquota do município"},"aliquota_calculada_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Aliquota Calculada Em","description":"Quando a conta do mês foi feita"},"proxima":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Proxima","description":"A alíquota do mês seguinte, já calculada: {mes, p_tot_trib_sn, p_aliq_iss, a_partir_de, conta, …}"},"pelo_pgdas":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Pelo Pgdas","description":"Modo MANUAL: o que a conta pelo PGDAS-D daria para o mês ({mes, atual, proxima, calculada_em}) — só para comparar na ficha; nunca aplicado"},"conferencia":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Conferencia","description":"A última conferência (declaração × alíquota aplicada, receita × notas, retificações, notas com retenção afetadas por uma correção)"},"payload_divergencia":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Divergencia","description":"Régua (c): notas do mês que vieram com alíquota própria diferente da calculada — {mes, mandada, calculada, notas, avisada_em, aviso_entregue}"},"receita_abaixo":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Receita Abaixo","description":"Os meses em que o contador declarou menos do que as notas a ponto de pedir atenção (a diferença é 10 % ou mais das notas — as do dia da declaração e as de hoje) — {meses: [{mes, pa, notas, declarada, faltam, pct, fecha, nao_entraram}], faltam, corrigida (a alíquota se esses meses fossem declarados pelas notas), calculado_em}; refeito na conferência de cada declaração e uma vez por dia"}},"type":"object","title":"RegimeTributario","description":"O regime como fica gravado e como sai na ficha: o que o dono informou mais o que a plataforma calcula —\nestes campos são só de leitura para quem usa a API."},"RegimeTributarioIn":{"properties":{"op_simp_nac":{"type":"string","enum":["1","2","3"],"title":"Op Simp Nac","description":"Opção pelo Simples Nacional: 2 = MEI · 3 = ME/EPP. A GereNota atende só Simples Nacional e MEI: 1 (não optante) volta 422 `EMPRESA_FORA_DO_SIMPLES` (o SEFIN valida o regime contra o cadastro do Simples por competência — E0160)","default":"3"},"reg_ap_trib_sn":{"anyOf":[{"type":"string","enum":["1","2","3"]},{"type":"null"}],"title":"Reg Ap Trib Sn","description":"Só ME/EPP (op_simp_nac=3): 1 = tudo no DAS · 2 = ISS por fora (sublimite estourado) · 3 = ISS e ICMS por fora","default":"1"},"reg_esp_trib":{"type":"string","enum":["0","1","2","3","4","5","6","9"],"title":"Reg Esp Trib","description":"Regime especial de tributação: 0 = nenhum · 1 = cooperativa · 2 = estimativa · 3 = ME municipal · 4 = notário · 5 = autônomo · 6 = sociedade de profissionais · 9 = outros","default":"0"},"p_tot_trib_sn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Tot Trib Sn","description":"Efetiva total do Simples (%) — o `pTotTribSN` das notas. Informado aqui é alíquota MANUAL do dono; no modo automático vem do PGDAS-D mês a mês. ME/EPP sem valor não emite (422 ALIQUOTA_NAO_CONFIRMADA)"},"p_aliq_iss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"P Aliq Iss","description":"ISS efetivo (%) — a `pAliq` das notas COM retenção. Mesma regra do p_tot_trib_sn"},"ibs_cbs_no_das":{"anyOf":[{"type":"string","enum":["dentro","fora"]},{"type":"null"}],"title":"Ibs Cbs No Das","description":"2027: IBS/CBS recolhidos DENTRO do DAS ou por fora (regime híbrido) — a opção de setembro/2026. Registro; a composição do DAS de 2027 é modelagem futura"}},"type":"object","title":"RegimeTributarioIn","description":"O que o dono informa do regime: a opção pelo Simples, o regime especial e, se quiser, os percentuais.\nOs campos que a plataforma calcula (a conta da alíquota, a próxima, a conferência) só aparecem na leitura e\nnunca são aceitos na entrada. O Sistema Nacional confere a opção pelo Simples contra o cadastro do Simples mês a\nmês: valor fora da tabela devolve 422, e divergência com o cadastro real volta como erro explicado."},"RelatorioCompetenciaOut":{"properties":{"competencia":{"type":"string","title":"Competencia","description":"Mês de competência `AAAA-MM`; `—` quando a nota não tem competência gravada"},"quantidade":{"type":"integer","title":"Quantidade","description":"Notas com essa competência, em qualquer status"},"valor_ativas":{"type":"number","title":"Valor Ativas","description":"Soma do valor do serviço só das notas ativas do mês, em reais"},"canceladas":{"type":"integer","title":"Canceladas","description":"Quantas notas do mês foram canceladas"},"substituidas":{"type":"integer","title":"Substituidas","description":"Quantas notas do mês foram substituídas"}},"additionalProperties":true,"type":"object","required":["competencia","quantidade","valor_ativas","canceladas","substituidas"],"title":"RelatorioCompetenciaOut","description":"Uma linha do fechamento mês a mês."},"RelatorioNfseOut":{"properties":{"filtros":{"additionalProperties":true,"type":"object","title":"Filtros","description":"O filtro efetivamente aplicado, já com o recorte de empresas do seu acesso — serve de conferência"},"totais":{"$ref":"#/components/schemas/RelatorioTotaisOut","description":"Totais do período inteiro"},"por_competencia":{"items":{"$ref":"#/components/schemas/RelatorioCompetenciaOut"},"type":"array","title":"Por Competencia","description":"Fechamento mês a mês, em ordem crescente de competência"},"notas":{"items":{"$ref":"#/components/schemas/RelatorioNotaOut"},"type":"array","title":"Notas","description":"As notas do período, até o `limite` pedido, ordenadas por competência e depois por nDPS"}},"additionalProperties":true,"type":"object","required":["filtros","totais","por_competencia","notas"],"title":"RelatorioNfseOut","description":"O relatório em JSON (`formato=json`)."},"RelatorioNotaOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador da nota (prefixo `nfse_`) — use em `GET /api/v1/nfse/{nfse_id}`"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Empresa emissora da nota"},"chave":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chave","description":"Chave de acesso da NFS-e (50 dígitos)"},"serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serie","description":"Série da DPS"},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial (nNFSe) impresso no DANFSE; `null` em notas antigas"},"ndps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ndps","description":"Sequência interna da DPS — use `numero` para falar com o cliente"},"dCompet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dcompet","description":"Competência da nota, no formato `AAAA-MM-DD`"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"`ativa`, `cancelada` ou `substituida`"},"origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origem","description":"`plataforma` (emitida aqui) ou `importada` (trazida do Sistema Nacional)"},"valor_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor Servico","description":"Valor do serviço em reais, como texto (ex.: `1500.00`)"},"vDescIncond":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vdescincond","description":"Desconto incondicionado, como texto"},"vDescCond":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vdesccond","description":"Desconto condicionado, como texto"},"descricao_servico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao Servico","description":"Descrição do serviço prestado"},"informacoes_complementares":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Informacoes Complementares","description":"Texto complementar impresso na nota"},"cTribNac":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ctribnac","description":"Código de tributação nacional do serviço"},"cNBS":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cnbs","description":"Código NBS do serviço, quando informado"},"tribISSQN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tribissqn","description":"Tributação do ISSQN declarada na nota"},"tpRetISSQN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tpretissqn","description":"`1` = ISS não retido, `2` = retido pelo tomador"},"pAliq":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paliq","description":"Alíquota do ISSQN DECLARADA na emissão. No JSON ela vem como está na nota; a coluna `Alíquota do ISS (%)` do CSV mostra a que VALE — `pAliqAplic` quando existe, esta quando não"},"vBC":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vbc","description":"Base de cálculo do ISSQN que o município usou; `null` em nota sem retenção e nas gravadas antes do campo existir"},"pAliqAplic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paliqaplic","description":"A alíquota que o município APLICOU, quando a nota a trouxe — é ela que manda quando difere da declarada"},"vISSQN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vissqn","description":"ISSQN apurado na nota pelo Sistema Nacional, em reais; `null` nas notas gravadas antes de a plataforma guardar esse valor"},"tot_trib_tipo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tot Trib Tipo","description":"`pTotTribSN` ou `indTotTrib` — qual regra de totais foi usada"},"tot_trib_valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tot Trib Valor","description":"Valor ou percentual dos tributos totais, como texto"},"tomador_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tomador Nome","description":"Nome do cliente"},"tomador_documento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tomador Documento","description":"CPF ou CNPJ do cliente, sem pontuação (o CNPJ pode ter letras)"},"emitida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Emitida Em","description":"Quando a nota foi emitida, em UTC (ISO 8601)"},"cancelada_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Cancelada Em","description":"Quando a nota foi cancelada (UTC, hora oficial do evento); só em status cancelada"},"substituida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Substituida Em","description":"Quando a nota foi substituída (UTC): o dhEvento do e105102 ou a autorização da substituta, o que vier primeiro; só em status substituida"},"substituida_por":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Substituida Por","description":"Id da nota que substituiu esta, se for o caso"}},"additionalProperties":true,"type":"object","required":["id"],"title":"RelatorioNotaOut","description":"Uma nota do relatório — as mesmas colunas do CSV, mais o `id` e os campos de cadastro.\n\nO objeto carrega também campos internos de armazenamento que não fazem parte do contrato;\nprograme pelos campos descritos aqui."},"RelatorioStatusOut":{"properties":{"quantidade":{"type":"integer","title":"Quantidade","description":"Quantas notas estão nesse status"},"valor_total":{"type":"number","title":"Valor Total","description":"Soma do valor do serviço dessas notas, em reais"}},"additionalProperties":true,"type":"object","required":["quantidade","valor_total"],"title":"RelatorioStatusOut","description":"Quantas notas e quanto valor há em um status, dentro do período pedido."},"RelatorioTotaisOut":{"properties":{"quantidade":{"type":"integer","title":"Quantidade","description":"Total de notas do período, somando todos os status"},"valor_total":{"type":"number","title":"Valor Total","description":"Soma do valor do serviço de TODAS as notas do período, inclusive canceladas e substituídas"},"tomadores_distintos":{"type":"integer","title":"Tomadores Distintos","description":"Quantos clientes diferentes aparecem no período"},"por_status":{"additionalProperties":{"$ref":"#/components/schemas/RelatorioStatusOut"},"type":"object","title":"Por Status","description":"Quebra por status — chaves `ativa`, `cancelada` e `substituida`, só as que existem no período"}},"additionalProperties":true,"type":"object","required":["quantidade","valor_total","tomadores_distintos"],"title":"RelatorioTotaisOut","description":"Os totais do período inteiro — não da fatia devolvida em `notas`."},"RepresentanteLegalOut":{"properties":{"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Nome do representante"},"qualificacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qualificacao","description":"Código da qualificação do representante"},"qualificacao_descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qualificacao Descricao","description":"Qualificação por extenso"}},"additionalProperties":true,"type":"object","title":"RepresentanteLegalOut","description":"Representante legal de um sócio, quando o sócio não é pessoa física brasileira residente."},"RetencaoHistoricoOut":{"properties":{"amostra":{"type":"integer","title":"Amostra","description":"Quantas das notas analisadas trouxeram a informação de retenção"},"retido":{"type":"boolean","title":"Retido","description":"`true` quando TODAS as notas da amostra tiveram o ISS retido pelo tomador"},"oscilante":{"type":"boolean","title":"Oscilante","description":"`true` quando a amostra mistura notas com e sem retenção — confirme com o usuário antes de emitir"},"pAliq":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paliq","description":"Alíquota de ISS da última nota retida, em % com ponto decimal (ex.: \"5.00\"); `null` se não houver"}},"additionalProperties":true,"type":"object","required":["amostra","retido","oscilante"],"title":"RetencaoHistoricoOut","description":"O que as últimas notas deste tomador dizem sobre retenção de ISS."},"RodarIn":{"properties":{"ocorrencia":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ocorrencia","description":"Para ANTECIPAR uma emissão recorrente: o `proxima_execucao` que a automação mostra agora (ISO 8601). A nota dessa ocorrência sai agora e a ocorrência fica feita. Sem o campo, roda na hora como sempre"}},"type":"object","title":"RodarIn"},"ServicoIn":{"properties":{"cMunPrestacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cmunprestacao","description":"Código IBGE do município onde o serviço foi prestado. Omita para usar o município da empresa emissora — só informe quando prestou em outra cidade"},"cTribNac":{"type":"string","title":"Ctribnac","description":"Código de tributação nacional do serviço, 6 dígitos (ex.: 010501). É o item da lista nacional; sem pontos"},"descricao":{"type":"string","title":"Descricao","description":"Descrição do serviço que sai impressa na nota"},"cNBS":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cnbs","description":"Código NBS (9 dígitos), quando o município o exigir"},"informacoes_complementares":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Informacoes Complementares","description":"Texto livre impresso no campo de informações complementares da nota"},"itens":{"anyOf":[{"items":{"$ref":"#/components/schemas/ItemIn"},"type":"array"},{"type":"null"}],"title":"Itens","description":"Detalhamento opcional. Com itens, o valor do serviço pode ser omitido: o total é a soma de quantidade × valor unitário e o detalhe vai nas informações complementares"}},"type":"object","required":["cTribNac","descricao"],"title":"ServicoIn","description":"O serviço prestado: o código nacional, o texto que sai na nota e o detalhamento opcional."},"SituacaoCnpjOut":{"properties":{"codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo","description":"Código da situação (ex.: \"2\" = Ativa)"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao","description":"Situação por extenso: Nula, Ativa, Suspensa, Inapta ou Baixada"},"data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data","description":"Data em que a situação passou a valer (AAAA-MM-DD)"}},"additionalProperties":true,"type":"object","title":"SituacaoCnpjOut","description":"Situação cadastral do CNPJ na Receita."},"SituacaoCpfOut":{"properties":{"codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo","description":"Código da situação (ex.: \"0\" = Regular)"},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao","description":"Situação por extenso: Regular, Suspensa, Titular falecido, Pendente de regularização, Cancelada por multiplicidade, Nula ou Cancelada de ofício"}},"additionalProperties":true,"type":"object","title":"SituacaoCpfOut","description":"Situação cadastral do CPF na Receita."},"SituacaoNaReceitaOut":{"properties":{"codigo":{"type":"string","title":"Codigo","description":"`1` nula, `3` suspensa, `4` inapta ou `8` baixada"},"descricao":{"type":"string","title":"Descricao","description":"`Nula`, `Suspensa`, `Inapta` ou `Baixada`"},"data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data","description":"Desde quando (`AAAA-MM-DD`), quando a Receita informa"}},"type":"object","required":["codigo","descricao"],"title":"SituacaoNaReceitaOut","description":"S-GC: a situação cadastral irregular do CNPJ na Receita."},"SocioOut":{"properties":{"tipo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo","description":"Código do tipo de sócio (pessoa física, jurídica, estrangeiro)"},"tipo_descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipo Descricao","description":"Tipo de sócio por extenso"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Nome ou razão social do sócio"},"qualificacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qualificacao","description":"Código da qualificação do sócio"},"qualificacao_descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qualificacao Descricao","description":"Qualificação por extenso (ex.: Administrador)"},"pais":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pais","description":"País do sócio"},"representante_legal":{"anyOf":[{"$ref":"#/components/schemas/RepresentanteLegalOut"},{"type":"null"}],"description":"Representante legal do sócio; `null` quando não há (e sempre no sócio menor)"},"menor":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Menor","description":"`true` no sócio menor de idade, que vem sem nome"}},"additionalProperties":true,"type":"object","title":"SocioOut","description":"Um integrante do quadro societário (QSA): o nome e a qualificação. O sócio menor de idade vem como \"Sócio\nmenor\", sem nome e sem documento. Esta rota nunca devolve o documento dos sócios."},"SubstituicaoMotivoIn":{"properties":{"cMotivo":{"type":"string","pattern":"^(0[1-5]|99)$","title":"Cmotivo","description":"01 = desenquadramento do Simples Nacional · 02 = enquadramento no Simples Nacional · 03 = inclusão retroativa de imunidade/isenção · 04 = exclusão retroativa de imunidade/isenção · 05 = rejeição pelo tomador (ou intermediário responsável) · 99 = outros (erro de valor, de serviço ou de tomador)"},"xMotivo":{"anyOf":[{"type":"string","maxLength":255,"minLength":15},{"type":"null"}],"title":"Xmotivo","description":"Explicação em texto livre, de 15 a 255 caracteres; obrigatória no 99"}},"type":"object","required":["cMotivo"],"title":"SubstituicaoMotivoIn","description":"Por que a nota está sendo substituída (justificativa fiscal oficial)."},"SugerirIn":{"properties":{"descricao":{"type":"string","maxLength":500,"minLength":3,"title":"Descricao"},"limit":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Limit","default":5}},"type":"object","required":["descricao"],"title":"SugerirIn"},"SugestaoBaseOut":{"properties":{"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","description":"Número oficial da NFS-e (nNFSe); `null` em notas antigas importadas"},"ndps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ndps","description":"Número da DPS que originou a nota-modelo"},"serie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serie","description":"Série da DPS da nota-modelo"},"dCompet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dcompet","description":"Competência da nota-modelo (AAAA-MM-DD)"},"origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origem","description":"`plataforma` (emitida pelo GereNota) ou `importada` (trazida do histórico do município)"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Empresa emissora da nota-modelo — emita pela mesma para repetir o serviço"},"empresa_nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Empresa Nome","description":"Razão social dessa empresa, para exibir sem uma segunda consulta"}},"additionalProperties":true,"type":"object","title":"SugestaoBaseOut","description":"A nota anterior que serviu de modelo para a sugestão."},"SugestaoCodigoOut":{"properties":{"cTribNac":{"type":"string","title":"Ctribnac","description":"Código de tributação nacional, 6 dígitos — é o que vai em `servico.cTribNac`"},"descricao":{"type":"string","title":"Descricao","description":"Nome oficial do serviço na lista nacional (anexo B do leiaute)"},"score":{"type":"number","title":"Score","description":"Semelhança entre a sua descrição e o item (0 a 1); os candidatos vêm do maior para o menor"},"iss_no_local":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Iss No Local","description":"True quando o ISS é devido no local da prestação (exceções da LC 116): mande `servico.cMunPrestacao`"},"familia_local":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Familia Local","description":"Família do serviço: `local`, `obra`, `evento`, `tomador` ou `rateio` (`obra` e `evento` também nos códigos em que o Sistema Nacional pede o grupo da obra ou do evento, Anexo I regras 340 e 357); nulo nos demais"},"tomador_pj_responsavel":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tomador Pj Responsavel","description":"True nos subitens em que a LC 116 (art. 6º, § 2º, II) faz a pessoa jurídica tomadora responsável pelo ISS onde quer que ela esteja — ali, a retenção por um tomador de outro município não pede aviso"}},"additionalProperties":true,"type":"object","required":["cTribNac","descricao","score"],"title":"SugestaoCodigoOut","description":"Um candidato a código de serviço para a descrição informada."},"SugestaoDaReceitaOut":{"properties":{"campo":{"type":"string","enum":["nome","nome_fantasia","endereco","email","fone"],"title":"Campo","description":"O campo da ficha"},"atual":{"title":"Atual","description":"O valor de hoje na ficha (o endereço vem inteiro, como `endereco`)"},"receita":{"title":"Receita","description":"O valor do cadastro da Receita"},"mes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mes","description":"O mês do cadastro da Receita (`AAAA-MM`)"},"muda_municipio":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Muda Municipio","description":"No endereço: `true` quando o município muda — o que muda o ISS e a retenção, e o que a NT 009 da reforma, prevista para 2027, vai conferir"},"um_a_um":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Um A Um","description":"No e-mail e no telefone de um MEI: o contato da Receita é o pessoal do dono — aceite um a um"}},"type":"object","required":["campo"],"title":"SugestaoDaReceitaOut","description":"S-GC: o que o cadastro da Receita tem de diferente num campo da ficha."},"SugestaoServicoOut":{"properties":{"descricao":{"type":"string","title":"Descricao","description":"Descrição do serviço da nota-modelo"},"cTribNac":{"type":"string","title":"Ctribnac","description":"Código de tributação nacional do serviço (6 dígitos, sem pontos)"},"nome_codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Codigo","description":"Denominação oficial do `cTribNac`, para o usuário conferir o código"},"cNBS":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cnbs","description":"Código NBS do serviço, quando a nota-modelo trouxe"},"valor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valor","description":"Valor sugerido em reais com ponto decimal (ex.: \"350.00\"). `null` quando as duas últimas notas não concordam no valor — nesse caso pergunte ao usuário em vez de arbitrar"},"informacoes_complementares":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Informacoes Complementares","description":"Texto complementar impresso na nota-modelo"}},"additionalProperties":true,"type":"object","required":["descricao","cTribNac"],"title":"SugestaoServicoOut","description":"O serviço sugerido: os campos para montar a próxima emissão."},"SugestaoTomadorOut":{"properties":{"tem_historico":{"type":"boolean","title":"Tem Historico","description":"`false` quando não há nota anterior: só `email_cadastro` acompanha e os demais campos não vêm"},"email_cadastro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Cadastro","description":"E-mail do cadastro do tomador — vem mesmo sem histórico de notas"},"cadastrado":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Cadastrado","description":"`true` quando o documento está no cadastro de clientes da conta — vem mesmo sem histórico"},"situacao_na_receita":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Situacao Na Receita","description":"S-GC: o cliente do cadastro com o CNPJ baixado, inapto, suspenso ou nulo na Receita (`descricao`, `data` — desde quando — e `mes`, o do cadastro conferido). Só aviso: a nota sai mesmo assim — diga ao cliente antes de emitir. Ausente quando o CNPJ está regular ou ainda não foi conferido"},"retencao_historico":{"anyOf":[{"$ref":"#/components/schemas/RetencaoHistoricoOut"},{"type":"null"}],"description":"Como o ISS foi retido nas notas recentes; ausente quando não há histórico"},"base_cancelada":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Base Cancelada","description":"`true` quando a nota-modelo não está mais ativa: o serviço ainda serve de modelo, o valor não"},"base_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Base Status","description":"Situação da nota-modelo: `ativa`, `cancelada` ou `substituida`"},"baseada_em":{"anyOf":[{"$ref":"#/components/schemas/SugestaoBaseOut"},{"type":"null"}],"description":"Identificação da nota-modelo"},"sugestao":{"anyOf":[{"$ref":"#/components/schemas/SugestaoServicoOut"},{"type":"null"}],"description":"Os campos do serviço a repetir"},"valores_recentes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Valores Recentes","description":"Até 6 valores das notas mais recentes, do mais novo para o mais antigo (reais com ponto decimal)"},"total_notas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Notas","description":"Quantas notas entraram na análise (no máximo 12)"},"competencia_proposta":{"anyOf":[{"$ref":"#/components/schemas/CompetenciaPropostaOut"},{"type":"null"}],"description":"A data da prestação a propor para a próxima nota, já calculada — vem com e sem histórico"}},"additionalProperties":true,"type":"object","required":["tem_historico"],"title":"SugestaoTomadorOut","description":"Sugestão de emissão montada a partir do histórico de notas do tomador."},"TomadorCriadoOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador do tomador nesta conta — use em `PATCH` e `DELETE /tomadores/{id}`"},"documento":{"type":"string","title":"Documento","description":"CNPJ (14 caracteres; letras A–Z só nas 12 primeiras posições) ou CPF (11 números), sem pontuação"},"tipo":{"type":"string","enum":["CNPJ","CPF"],"title":"Tipo","description":"Natureza do documento"},"nome":{"type":"string","title":"Nome","description":"Razão social (CNPJ) ou nome da pessoa (CPF)"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia, quando houver (só existe em CNPJ)"},"origem":{"type":"string","enum":["importado","manual","link","serpro"],"title":"Origem","description":"De onde veio o cadastro: `importado` (varredura das notas antigas do município), `manual`, `link` (formulário público preenchido pelo próprio cliente) ou `serpro` (autocompletar pela Receita)"},"ultima_nota_em":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultima Nota Em","description":"Competência (AAAA-MM-DD) da nota mais recente emitida para este tomador; `null` se nunca houve. Para quem tem recorte (membro recortado ou empresa compartilhada), a das empresas do seu acesso"},"inscricao_municipal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inscricao Municipal","description":"Inscrição municipal do tomador, se informada"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail para o envio da nota, se informado"},"fone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fone","description":"Telefone só dígitos, com DDD (celular no formato antigo ganha o 9º dígito ao ser gravado)"},"endereco":{"anyOf":[{"$ref":"#/components/schemas/EnderecoTomador"},{"type":"null"}],"description":"Endereço, possivelmente parcial; `null` quando o cadastro não tem endereço"},"criado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Criado Em","description":"Quando o cadastro foi criado (UTC, ISO 8601)"},"atualizado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Atualizado Em","description":"Quando o cadastro foi alterado pela última vez (UTC, ISO 8601); `null` se nunca"},"receita_campos":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/ReceitaDoCampoOut"},"type":"object"},{"type":"null"}],"title":"Receita Campos","description":"Nos clientes CNPJ comparados com o cadastro da Receita, a origem de cada campo que acompanha a Receita (`nome`, `nome_fantasia`, `endereco`). Ausente nos demais"},"receita_sugestoes":{"anyOf":[{"items":{"$ref":"#/components/schemas/SugestaoDaReceitaOut"},"type":"array"},{"type":"null"}],"title":"Receita Sugestoes","description":"O que o cadastro da Receita tem de diferente nesta ficha, para aceitar ou dispensar no painel (Tomadores → Sugestões da Receita). E-mail e telefone só aparecem quando a ficha não tem. Ausente quando não há"},"receita_situacao":{"anyOf":[{"$ref":"#/components/schemas/SituacaoNaReceitaOut"},{"type":"null"}],"description":"O CNPJ baixado, inapto, suspenso ou nulo na Receita: só aviso, a nota sai. Some sozinho quando a Receita volta a dizer ativo. Ausente nos demais"},"receita_pendente":{"anyOf":[{"$ref":"#/components/schemas/PendenciaDaReceitaOut"},{"type":"null"}],"description":"A ficha espera a atualização pela Receita (o cadastro não respondeu): ela se atualiza sozinha quando ele voltar. Ausente nos demais"},"receita_nao_achado":{"anyOf":[{"$ref":"#/components/schemas/NaoAchadoNaReceitaOut"},{"type":"null"}],"description":"O CNPJ ainda não aparece no cadastro da Receita do mês (pode ser recente): a ficha fica com os dados das notas, e a comparação se repete no mês seguinte. Ausente nos demais"},"receita_mes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Receita Mes","description":"O mês do cadastro da Receita da última comparação desta ficha (`AAAA-MM`)"},"receita":{"anyOf":[{"$ref":"#/components/schemas/ReceitaDoCadastroOut"},{"type":"null"}],"description":"O resumo da busca na Receita; `null` quando o nome veio no pedido"}},"additionalProperties":true,"type":"object","required":["id","documento","tipo","nome","origem"],"title":"TomadorCriadoOut","description":"O tomador recém-cadastrado; `receita` vem quando o cadastro saiu da Receita (só com o CNPJ)."},"TomadorDaBuscaOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador do tomador nesta conta — use em `PATCH` e `DELETE /tomadores/{id}`"},"documento":{"type":"string","title":"Documento","description":"CNPJ (14 caracteres; letras A–Z só nas 12 primeiras posições) ou CPF (11 números), sem pontuação"},"tipo":{"type":"string","enum":["CNPJ","CPF"],"title":"Tipo","description":"Natureza do documento"},"nome":{"type":"string","title":"Nome","description":"Razão social (CNPJ) ou nome da pessoa (CPF)"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia, quando houver (só existe em CNPJ)"},"origem":{"type":"string","enum":["importado","manual","link","serpro"],"title":"Origem","description":"De onde veio o cadastro: `importado` (varredura das notas antigas do município), `manual`, `link` (formulário público preenchido pelo próprio cliente) ou `serpro` (autocompletar pela Receita)"},"ultima_nota_em":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultima Nota Em","description":"Competência (AAAA-MM-DD) da nota mais recente emitida para este tomador; `null` se nunca houve. Para quem tem recorte (membro recortado ou empresa compartilhada), a das empresas do seu acesso"},"inscricao_municipal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inscricao Municipal","description":"Inscrição municipal do tomador, se informada"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail para o envio da nota, se informado"},"fone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fone","description":"Telefone só dígitos, com DDD (celular no formato antigo ganha o 9º dígito ao ser gravado)"},"endereco":{"anyOf":[{"$ref":"#/components/schemas/EnderecoTomador"},{"type":"null"}],"description":"Endereço, possivelmente parcial; `null` quando o cadastro não tem endereço"},"criado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Criado Em","description":"Quando o cadastro foi criado (UTC, ISO 8601)"},"atualizado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Atualizado Em","description":"Quando o cadastro foi alterado pela última vez (UTC, ISO 8601); `null` se nunca"},"receita_campos":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/ReceitaDoCampoOut"},"type":"object"},{"type":"null"}],"title":"Receita Campos","description":"Nos clientes CNPJ comparados com o cadastro da Receita, a origem de cada campo que acompanha a Receita (`nome`, `nome_fantasia`, `endereco`). Ausente nos demais"},"receita_sugestoes":{"anyOf":[{"items":{"$ref":"#/components/schemas/SugestaoDaReceitaOut"},"type":"array"},{"type":"null"}],"title":"Receita Sugestoes","description":"O que o cadastro da Receita tem de diferente nesta ficha, para aceitar ou dispensar no painel (Tomadores → Sugestões da Receita). E-mail e telefone só aparecem quando a ficha não tem. Ausente quando não há"},"receita_situacao":{"anyOf":[{"$ref":"#/components/schemas/SituacaoNaReceitaOut"},{"type":"null"}],"description":"O CNPJ baixado, inapto, suspenso ou nulo na Receita: só aviso, a nota sai. Some sozinho quando a Receita volta a dizer ativo. Ausente nos demais"},"receita_pendente":{"anyOf":[{"$ref":"#/components/schemas/PendenciaDaReceitaOut"},{"type":"null"}],"description":"A ficha espera a atualização pela Receita (o cadastro não respondeu): ela se atualiza sozinha quando ele voltar. Ausente nos demais"},"receita_nao_achado":{"anyOf":[{"$ref":"#/components/schemas/NaoAchadoNaReceitaOut"},{"type":"null"}],"description":"O CNPJ ainda não aparece no cadastro da Receita do mês (pode ser recente): a ficha fica com os dados das notas, e a comparação se repete no mês seguinte. Ausente nos demais"},"receita_mes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Receita Mes","description":"O mês do cadastro da Receita da última comparação desta ficha (`AAAA-MM`)"},"fora_do_recorte":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Fora Do Recorte","description":"`true` no cadastro de fora do seu acesso que só a busca pelo documento inteiro acha (membro recortado ou empresa compartilhada): vêm o `id`, o documento, o tipo, o nome e a origem, sem os contatos, o endereço e a data da última nota. Ausente nos demais"},"de_outras_empresas":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"De Outras Empresas","description":"`true`, para quem tem recorte (membro recortado ou empresa compartilhada), no cliente do seu acesso que a conta também atende por uma empresa de fora dele: o e-mail, o telefone, a inscrição e o endereço valem para as notas e a entrega dessas empresas também, e por isso só o dono da conta os muda ou exclui o cadastro (`PATCH` e `DELETE` devolvem 403 `TOMADOR_DE_OUTRA_EMPRESA`). Ausente nos demais"}},"additionalProperties":true,"type":"object","required":["id","documento","tipo","nome","origem"],"title":"TomadorDaBuscaOut","description":"Um tomador da lista ou da busca; o cadastro de fora do seu acesso vem reduzido (S-LA R2.3b)."},"TomadorOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador do tomador nesta conta — use em `PATCH` e `DELETE /tomadores/{id}`"},"documento":{"type":"string","title":"Documento","description":"CNPJ (14 caracteres; letras A–Z só nas 12 primeiras posições) ou CPF (11 números), sem pontuação"},"tipo":{"type":"string","enum":["CNPJ","CPF"],"title":"Tipo","description":"Natureza do documento"},"nome":{"type":"string","title":"Nome","description":"Razão social (CNPJ) ou nome da pessoa (CPF)"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia, quando houver (só existe em CNPJ)"},"origem":{"type":"string","enum":["importado","manual","link","serpro"],"title":"Origem","description":"De onde veio o cadastro: `importado` (varredura das notas antigas do município), `manual`, `link` (formulário público preenchido pelo próprio cliente) ou `serpro` (autocompletar pela Receita)"},"ultima_nota_em":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ultima Nota Em","description":"Competência (AAAA-MM-DD) da nota mais recente emitida para este tomador; `null` se nunca houve. Para quem tem recorte (membro recortado ou empresa compartilhada), a das empresas do seu acesso"},"inscricao_municipal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inscricao Municipal","description":"Inscrição municipal do tomador, se informada"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail para o envio da nota, se informado"},"fone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fone","description":"Telefone só dígitos, com DDD (celular no formato antigo ganha o 9º dígito ao ser gravado)"},"endereco":{"anyOf":[{"$ref":"#/components/schemas/EnderecoTomador"},{"type":"null"}],"description":"Endereço, possivelmente parcial; `null` quando o cadastro não tem endereço"},"criado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Criado Em","description":"Quando o cadastro foi criado (UTC, ISO 8601)"},"atualizado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Atualizado Em","description":"Quando o cadastro foi alterado pela última vez (UTC, ISO 8601); `null` se nunca"},"receita_campos":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/ReceitaDoCampoOut"},"type":"object"},{"type":"null"}],"title":"Receita Campos","description":"Nos clientes CNPJ comparados com o cadastro da Receita, a origem de cada campo que acompanha a Receita (`nome`, `nome_fantasia`, `endereco`). Ausente nos demais"},"receita_sugestoes":{"anyOf":[{"items":{"$ref":"#/components/schemas/SugestaoDaReceitaOut"},"type":"array"},{"type":"null"}],"title":"Receita Sugestoes","description":"O que o cadastro da Receita tem de diferente nesta ficha, para aceitar ou dispensar no painel (Tomadores → Sugestões da Receita). E-mail e telefone só aparecem quando a ficha não tem. Ausente quando não há"},"receita_situacao":{"anyOf":[{"$ref":"#/components/schemas/SituacaoNaReceitaOut"},{"type":"null"}],"description":"O CNPJ baixado, inapto, suspenso ou nulo na Receita: só aviso, a nota sai. Some sozinho quando a Receita volta a dizer ativo. Ausente nos demais"},"receita_pendente":{"anyOf":[{"$ref":"#/components/schemas/PendenciaDaReceitaOut"},{"type":"null"}],"description":"A ficha espera a atualização pela Receita (o cadastro não respondeu): ela se atualiza sozinha quando ele voltar. Ausente nos demais"},"receita_nao_achado":{"anyOf":[{"$ref":"#/components/schemas/NaoAchadoNaReceitaOut"},{"type":"null"}],"description":"O CNPJ ainda não aparece no cadastro da Receita do mês (pode ser recente): a ficha fica com os dados das notas, e a comparação se repete no mês seguinte. Ausente nos demais"},"receita_mes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Receita Mes","description":"O mês do cadastro da Receita da última comparação desta ficha (`AAAA-MM`)"}},"additionalProperties":true,"type":"object","required":["id","documento","tipo","nome","origem"],"title":"TomadorOut","description":"Um tomador (cliente) da conta, como a API devolve."},"TomadorUpdate":{"properties":{"nome":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Nome","description":"Novo nome ou razão social"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Novo nome fantasia"},"inscricao_municipal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inscricao Municipal","description":"Nova inscrição municipal"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Novo e-mail para receber a nota"},"fone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fone","description":"Novo telefone com DDD; celular de 8 dígitos ganha o 9º ao ser gravado"},"endereco":{"anyOf":[{"$ref":"#/components/schemas/EnderecoTomador"},{"type":"null"}],"description":"Novo endereço (substitui o anterior por inteiro). Pode ser parcial; `cMun`, se vier, precisa ser um código IBGE existente"}},"type":"object","title":"TomadorUpdate"},"TributacaoIn":{"properties":{"tribISSQN":{"type":"string","enum":["1","2","3","4"],"title":"Tribissqn","description":"1 = tributável no município (único aceito hoje) · 2 = imunidade · 3 = exportação · 4 = não incidência","default":"1"},"tpRetISSQN":{"type":"string","enum":["1","2","3"],"title":"Tpretissqn","description":"Retenção do ISSQN: 1 = não retido (padrão) · 2 = retido pelo tomador · 3 = retido pelo intermediário (ainda não suportado)","default":"1"},"pAliq":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paliq","description":"Alíquota do ISSQN em %, string decimal até 5.00 (ex.: \"4.53\"). Informe SOMENTE quando há retenção (tpRetISSQN=2); sem retenção, a alíquota parametrizada do município é aplicada pelo sistema"}},"type":"object","title":"TributacaoIn","description":"Tributação do ISSQN. Os defaults cobrem o caso comum: serviço tributado no município, sem retenção."},"UpgradeOut":{"properties":{"plano":{"$ref":"#/components/schemas/PlanoQueResolveOut","description":"O plano mais barato, acima do atual, em que o uso de hoje cabe"},"limite_no_plano":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limite No Plano","description":"O limite deste recurso no plano que resolve; null = sem limite (ex.: as notas dos planos pagos) ou recurso incluído (relatórios automáticos, API e MCP)"},"link":{"type":"string","title":"Link","description":"A página Cobrança do painel, que abre com o plano que resolve já marcado e o motivo do limite (os dois vão na URL: `…/billing?plano=…&motivo=…`)"}},"type":"object","required":["plano","link"],"title":"UpgradeOut","description":"O plano que resolve o limite batido e o caminho para assiná-lo."},"UsoTetoOut":{"properties":{"uso":{"type":"integer","title":"Uso","description":"Quantos itens a conta usa hoje"},"teto":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Teto","description":"Máximo do plano, extras já somados; `null` = ilimitado"},"upgrade":{"anyOf":[{"$ref":"#/components/schemas/UpgradeOut"},{"type":"null"}],"description":"Só para o dono da conta, e só quando o próximo item não cabe no plano: o plano mais barato em que ele cabe, com o preço e o link para assinar — o mesmo `upgrade` dos erros de limite. Ausente quando nenhum plano resolve (o Plano Escritório no teto); a chave de API nunca é do dono e não o recebe"}},"additionalProperties":true,"type":"object","required":["uso"],"title":"UsoTetoOut","description":"Quanto a conta já usa de um recurso contável e quanto o plano permite."},"ValidarIn":{"properties":{"itens":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1},{"type":"null"}],"title":"Itens","description":"Só estas linhas (o \"Validar as 2 de novo\"); sem elas, as prontas sem a marca \"aceita no teste\""}},"type":"object","title":"ValidarIn"},"ValoresIn":{"properties":{"vServ":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vserv","description":"Valor do serviço em reais (ex.: \"1500.00\"). Obrigatório, salvo quando servico.itens traz o detalhamento — aí o total é calculado"},"vDescIncond":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vdescincond","description":"Desconto incondicionado — abate a base de cálculo do ISSQN"},"vDescCond":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vdesccond","description":"Desconto condicionado — não abate a base de cálculo"},"pTotTribSN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ptottribsn","description":"Percentual aproximado de tributos (Lei 12.741) para optante do Simples. Omita: ME/EPP usa a alíquota da empresa (a do mês pelo PGDAS-D, ou a confirmada no painel) — sem alíquota nenhuma a emissão para em 422 ALIQUOTA_NAO_CONFIRMADA. O MEI não leva o percentual (o Sistema Nacional o recusa para o MEI, E0710): a nota sai com indTotTrib 0, e mandado volta 422 MEI_NAO_INFORMA_PTOTTRIBSN. Mandado diferente da calculada, a nota da ME/EPP sai como veio e o dono é avisado uma vez por mês"}},"type":"object","title":"ValoresIn","description":"Os valores da nota, sempre como string decimal com ponto (`\"1500.00\"`) — nunca número."},"VersaoDeclaracaoOut":{"properties":{"versao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Versao","description":"`001` = original; `002`+ = retificadora"},"numero_declaracao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero Declaracao","description":"Nº da declaração no PGDAS-D"},"retificadora":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Retificadora","description":"True quando a declaração se diz retificadora"},"transmitida_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Transmitida Em","description":"Transmissão (seção 3), em UTC"},"consultado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Consultado Em","description":"Quando a plataforma a arquivou"},"tem_pdf":{"type":"boolean","title":"Tem Pdf","description":"O PDF desta versão está arquivado","default":false}},"type":"object","title":"VersaoDeclaracaoOut","description":"Uma versão do mesmo PA — a original e as retificadoras, cada uma um documento."},"gerenota_api__atividades__AtividadeOut":{"properties":{"id":{"type":"string","title":"Id","description":"Identificador do evento (prefixo `atv_`)"},"tipo":{"type":"string","title":"Tipo","description":"Tipo do evento, ex.: `nfse_emitida`, `nfse_cancelada`, `export`, `automacao_emitida`"},"texto":{"type":"string","title":"Texto","description":"Frase pronta para exibir, já em português"},"quem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quem","description":"Quem fez: nome do membro, e-mail, `WhatsApp` ou `Chave de API`. `null` quando foi o próprio sistema"},"papel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Papel","description":"Papel de quem fez no momento do evento (`owner`, `operador`, `contabilidade`, `leitor`) ou `automação`"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id","description":"Empresa do evento. `null` nos eventos da conta inteira (membros, cobrança, entrada por link)"},"criado_em":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Criado Em","description":"Quando aconteceu, em UTC (ISO 8601)"}},"additionalProperties":true,"type":"object","required":["id","tipo","texto"],"title":"AtividadeOut","description":"Um evento da trilha: alguém (ou o próprio sistema) fez alguma coisa na conta."},"gerenota_api__emissions__TomadorIn":{"properties":{"tipo":{"type":"string","pattern":"^(CNPJ|CPF|NIF|naoNIF)$","title":"Tipo","description":"Tipo do documento: CNPJ, CPF, NIF (tomador no exterior) ou naoNIF"},"documento":{"type":"string","title":"Documento","description":"CNPJ (14) ou CPF (11) — pontuação é aceita e removida; para NIF, o número como veio"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","description":"Razão social ou nome do cliente. Obrigatório, exceto no CNPJ: só com o `documento`, a emissão usa o cadastro da conta e, se o CNPJ é novo, busca na Receita e cadastra (pelo cadastro mensal, sem cota; o CNPJ que ainda não está nele vai à consulta em tempo real, da cota do plano). O cliente cadastrado fora do seu acesso (membro recortado ou empresa compartilhada) também sai pela Receita"},"inscricao_municipal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inscricao Municipal","description":"Inscrição municipal do tomador, se houver"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail do cliente (usado no envio da nota por e-mail)"},"fone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fone","description":"Telefone com DDD, só dígitos"},"endereco":{"anyOf":[{"$ref":"#/components/schemas/EnderecoIn"},{"type":"null"}],"description":"Endereço completo — obrigatório quando o ISSQN é retido pelo tomador (tributacao.tpRetISSQN=2) ou quando o serviço é tributado no município do tomador"}},"type":"object","required":["tipo","documento"],"title":"TomadorIn","description":"O cliente da nota. O bloco inteiro é opcional (nota sem tomador identificado é válida)."},"gerenota_api__integra_contador__AtividadeOut":{"properties":{"descricao":{"type":"string","title":"Descricao","description":"A atividade como o PGDAS-D a descreve"},"receita":{"type":"string","title":"Receita","description":"Receita informada na atividade (R$)"},"iss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Iss","description":"ISS devido na atividade (R$); nulo quando a tabela de débitos não foi lida"},"total":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Total","description":"Total dos débitos da atividade (R$); nulo quando a tabela de débitos não foi lida"},"tributos":{"additionalProperties":{"type":"string"},"type":"object","title":"Tributos","description":"Os débitos da atividade por tributo (R$), pelo nome da coluna do PGDAS-D: `irpj`, `csll`, `cofins`, `pis`, `cpp` (INSS/CPP), `icms`, `ipi`, `iss` e `total`; a partir de 2027, `cbs` e `ibs` no lugar de `cofins` e `pis`. Vazio nas declarações lidas antes de 12/10/2026"},"classe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classe","description":"A atividade pela descrição do PGDAS-D: `fator_r` (sujeita ao fator r — Anexo III ou V), `anexo_iii` (não sujeita, tributada pelo Anexo III), `anexo_iv`, `contabil_iss_fixo` (escritório contábil com ISS em valor fixo), `construcao_anexo_iii`/`construcao_anexo_iv` (7.02 e 7.05), `transporte_municipal` (16.01), `locacao_bens_moveis`; nulo para as demais (comércio, indústria) e nas declarações lidas antes de 12/10/2026"},"c_atv_sn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"C Atv Sn","description":"O código da atividade no catálogo do Simples de 2027 (`cAtvSN` da NT 009): `07` só Anexo III, `08` contábil com ISS fixo, `09` sujeita ao fator r, `10` transporte municipal, `11` locação de bens móveis, `12`/`13` construção (III/IV), `14` Anexo IV; nulo para o exterior e para as classes sem código"},"anexo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Anexo","description":"O anexo da atividade (III, IV ou V); na sujeita ao fator r, pelo fator r da 2.4 (0,28 ou mais, III); nulo quando não dá para saber"},"retencao_iss":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Retencao Iss","description":"Com (true) ou sem (false) retenção/substituição tributária de ISS"},"iss_devido_a":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Iss Devido A","description":"Sem retenção, a quem o ISS é devido: `proprio` (o município do estabelecimento) ou `outro` (outro município)"},"exterior":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Exterior","description":"Prestação de serviços para o exterior (exportação)"}},"type":"object","required":["descricao","receita"],"title":"AtividadeOut","description":"Uma linha da seção 2.7: a receita informada, os débitos por tributo e a classe daquela atividade."},"gerenota_api__tomadores__TomadorIn":{"properties":{"tipo":{"type":"string","pattern":"^(CNPJ|CPF)$","title":"Tipo","description":"Natureza do documento: `CNPJ` (padrão) ou `CPF`","default":"CNPJ"},"documento":{"type":"string","title":"Documento","description":"CNPJ ou CPF do tomador. Aceita com ou sem pontuação (a máscara é removida) e os dígitos verificadores são conferidos; o CNPJ pode ter letras nas 12 primeiras posições (minúscula vira maiúscula). Gravado e devolvido sem pontuação"},"nome":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Nome","description":"Razão social (CNPJ) ou nome da pessoa (CPF). Obrigatório no CPF. No CNPJ, sem ele a plataforma busca o cadastro na Receita (pelo cadastro mensal, sem cota; o CNPJ que ainda não está nele usa a cota do plano — veja `POST /tomadores`)"},"nome_fantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome Fantasia","description":"Nome fantasia, quando houver (só em CNPJ)"},"inscricao_municipal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inscricao Municipal","description":"Inscrição municipal do tomador, se houver"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"E-mail para receber a nota emitida"},"fone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fone","description":"Telefone com DDD, com ou sem máscara; celular no formato antigo (8 dígitos) ganha o 9º"},"endereco":{"anyOf":[{"$ref":"#/components/schemas/EnderecoTomador"},{"type":"null"}],"description":"Endereço do tomador. Pode ser parcial; se mandar `cMun`, ele precisa ser um código IBGE existente (use `/consultas/cep/{cep}` ou `/consultas/municipio` para obtê-lo, nunca chute)"},"origem":{"type":"string","pattern":"^(manual|serpro)$","title":"Origem","description":"Informativo: `manual` (digitado) ou `serpro` (preenchido a partir de uma consulta à Receita)","default":"manual"}},"type":"object","required":["documento"],"title":"TomadorIn"}},"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"gnk_live_…","description":"Chave de API criada em Painel → Integrações (escopo emissão ou leitura). Cabeçalho: `Authorization: Bearer gnk_live_…`."}}},"tags":[{"name":"conta","description":"Quem sou eu: identidade, plano e cotas da chave em uso."},{"name":"empresas","description":"As empresas emissoras da conta: listar, cadastrar, enviar o certificado A1 e validar."},{"name":"aliquotas","description":"Alíquotas do Simples (ME/EPP): o dossiê da empresa (a alíquota do mês com a conta e a explicação, a próxima, a conferência, os casos relevantes), as declarações PGDAS-D arquivadas como dado (13 PAs na entrada, uma por mês depois, versões) e a consulta paga ao Integra Contador."},{"name":"notas","description":"Emitir (teste ou valendo), listar, consultar, XML, PDF (DANFSE) e envio por e-mail."},{"name":"lotes","description":"Emitir em lote: uma planilha (XLSX ou CSV) ou as linhas em JSON viram notas propostas, uma por linha; você confere e confirma, e a fila emite uma nota por vez pelo Sistema Nacional."},{"name":"eventos","description":"Cancelar, substituir e ler os eventos de uma nota."},{"name":"tomadores","description":"Os clientes (tomadores) da conta e a sugestão pela última nota."},{"name":"consultas","description":"CNPJ na Receita (pelo cadastro mensal, sem cota; em tempo real, com cota), CPF (com cota), CEP e município (grátis) e a adesão do município ao Sistema Nacional."},{"name":"servicos","description":"Código de serviço (cTribNac): sugerir pela descrição e conferir um código no catálogo nacional."},{"name":"relatorios","description":"Relatório por período e exportação em ZIP (XMLs, PDFs e CSV)."},{"name":"automacoes","description":"Emissões recorrentes e agendadas: criar, editar, pausar, rodar agora e ver as execuções."},{"name":"atividades","description":"A trilha de quem fez o quê na conta."},{"name":"meta","description":"Saúde do serviço."}],"security":[{"ApiKeyBearer":[]}]}