{"openapi":"3.0.3","info":{"title":"API - Conota","description":"API para emissao de documentos fiscais eletronicos (NF-e, NFC-e, NFS-e), consulta de CEP/CNPJ e gestao de empresas emissoras. Autentique com X-API-Key (chave do tenant) ou Bearer (JWT do login).\n\nDominios: use `api.conota.dev` (principal). `api.conota.com.br`, `api.pluganota.com` e `api.qualyfiscal.com.br` sao aliases do MESMO servico — **nenhuma integracao existente precisa mudar**, todas seguem funcionando.\n\n**Quer testar uma chamada?** Esta pagina e para leitura. O console com \"Try it out\", onde voce dispara a requisicao com a sua propria chave, fica em [/swagger](/swagger) — mesma API, mesmos endpoints.\n\n**Assistentes de IA (MCP):** estas mesmas consultas estao disponiveis para agentes via Model Context Protocol, usando a MESMA API Key. Instrucoes de conexao e catalogo de ferramentas em [mcp.conota.dev](https://mcp.conota.dev).","version":"1.0.0"},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"Chave de API do tenant"},"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT do login"}},"schemas":{}},"paths":{"/":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/health":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/status":{"get":{"summary":"Status operacional da plataforma (para monitoramento)","tags":["Publicas"],"description":"Verifica de fato cada dependência da emissão — banco, fila, bridge fiscal e workers — e devolve o veredito no **código HTTP**: `200` quando está operacional (ou degradado em algo não essencial) e `503` quando um componente essencial está fora.\n\nEndpoint público, sem autenticação, pensado para status page e monitoramento externo. Não confunda com `GET /health`, que é a sonda de vida do processo e responde 200 mesmo com dependências fora (é o que o healthcheck do container usa).","responses":{"200":{"description":"Default Response"}}}},"/v1/auth/login":{"post":{"summary":"Login do tenant (email/senha) -> JWT","tags":["Autenticacao"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","senha"],"additionalProperties":true,"properties":{"email":{"type":"string"},"senha":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/logout":{"post":{"summary":"Logout","tags":["Autenticacao"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/ambiente":{"post":{"summary":"Trocar o ambiente da sessão do painel (produção <-> homologação)","tags":["Autenticacao"],"description":"Reemite o token da sessão ligado à API Key do ambiente escolhido. Use no painel para emitir um teste em homologação sem sair da conta. O token anterior é revogado — guarde o novo.\n\nRequer que a conta tenha uma API Key **ativa** naquele ambiente.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ambiente"],"properties":{"ambiente":{"type":"string","enum":["producao","homologacao"],"description":"Ambiente desejado para a sessão."}}}}}},"security":[{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/me":{"get":{"summary":"Perfil do usuario autenticado","tags":["Autenticacao"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/senha":{"put":{"summary":"Trocar a senha do tenant","tags":["Autenticacao"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/api-keys":{"get":{"summary":"Listar API keys do tenant","tags":["Autenticacao"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Criar API key (producao ou homologacao)","tags":["Autenticacao"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/api-keys/{id}":{"delete":{"summary":"Revogar API key","tags":["Autenticacao"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/notas":{"get":{"summary":"Listar notas do tenant (JWT — compatibilidade)","tags":["Notas"],"description":"Lista as notas fiscais do tenant, autenticada **apenas por JWT** (Bearer, do login no painel). Rota de compatibilidade — para integrações via `X-API-Key`, prefira `GET /v1/notas` (mesmo formato de retorno, com mais filtros). Filtros opcionais por tipo, situação e emitente. Ordena da mais recente para a mais antiga.","parameters":[{"schema":{"type":"string","enum":["nfe","nfse","nfce","mdfe"]},"in":"query","name":"tipo","required":false,"description":"Filtra por tipo de documento."},{"schema":{"type":"string","enum":["autorizada","cancelada","rejeitada","denegada","inutilizada"]},"in":"query","name":"status","required":false,"description":"Filtra pela situação fiscal da nota."},{"schema":{"type":"string","example":"60772432000142"},"in":"query","name":"emitente","required":false,"description":"CNPJ do emitente (com ou sem máscara)."},{"schema":{"type":"integer","default":20},"in":"query","name":"limite","required":false,"description":"Itens por página (padrão 20)."},{"schema":{"type":"integer","default":1},"in":"query","name":"pagina","required":false,"description":"Página (padrão 1)."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas":{"get":{"summary":"Listar empresas emissoras do tenant","tags":["Empresas"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Cadastrar empresa emissora","tags":["Empresas"],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/certificados":{"get":{"summary":"Listar certificados digitais do tenant (validade e status)","tags":["Empresas"],"description":"Retorna o certificado A1 ativo de cada empresa do tenant — titular, emissor, validade e status: valido | expira_em_breve (<= 30 dias) | expirado | sem_certificado.","responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/numeracao":{"get":{"summary":"Último número autorizado por empresa, tipo, série e ambiente","tags":["Empresas"],"description":"Diz **em que número cada sequência está** — o número da última nota **autorizada**, por empresa, tipo de documento, série e ambiente.\n\nHomologação e produção são sequências **independentes**, e vêm separadas. Nota rejeitada não avança a sequência: só entram autorizadas.\n\nInforme `cnpj` para trazer só uma empresa. Sem ele, vêm todas as do tenant.\n\n**Isto é consulta, não reserva.** Serve para saber onde a numeração está — não para atribuir o próximo número: entre ler e emitir há uma janela, e duas emissões simultâneas leriam o mesmo valor. Quem numera continua sendo você.","parameters":[{"schema":{"type":"string"},"in":"query","name":"cnpj","required":false,"description":"Opcional — CNPJ/CPF da empresa (com ou sem máscara)."},{"schema":{"type":"string","enum":["nfe","nfce","nfse"]},"in":"query","name":"tipo","required":false,"description":"Opcional — filtra por tipo."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/{cpf_cnpj}":{"get":{"summary":"Detalhe de uma empresa","tags":["Empresas"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Atualizar dados da empresa","tags":["Empresas"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remover empresa","tags":["Empresas"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/{cpf_cnpj}/nfe":{"put":{"summary":"Configurar parametros de NF-e da empresa","tags":["Empresas"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/{cpf_cnpj}/nfse":{"put":{"summary":"Configurar parametros de NFS-e da empresa","tags":["Empresas"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/{cpf_cnpj}/nfce":{"put":{"summary":"Configurar parametros de NFC-e da empresa (CSC, serie, ambiente)","tags":["Empresas"],"description":"Define o CSC (Codigo de Seguranca do Contribuinte) e o ID do CSC, obtidos no portal da SEFAZ do estado da empresa - necessarios para gerar o QR Code da NFC-e. ambiente: 1=producao, 2=homologacao. crt: 1=Simples Nacional, 2=Simples excesso sublimite, 3=Regime Normal, 4=MEI. Por seguranca, o CSC nao e retornado; a resposta traz apenas csc_configurado (boolean).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ambiente":{"type":"integer","enum":[1,2],"description":"1=producao, 2=homologacao"},"crt":{"type":"integer","enum":[1,2,3,4]},"serie":{"type":"string","maxLength":3},"proximo_numero":{"type":"integer","minimum":1},"csc_id":{"type":"string","maxLength":10,"description":"ID do CSC / idToken (ex: \"000001\")"},"csc":{"type":"string","maxLength":50,"description":"Codigo de Seguranca do Contribuinte (token)"}},"example":{"ambiente":2,"crt":1,"serie":"001","proximo_numero":1,"csc_id":"string","csc":"string"}}}}},"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/{cpf_cnpj}/certificado":{"put":{"summary":"Enviar/atualizar certificado digital A1 (PFX)","tags":["Empresas"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/cep/{cep}":{"get":{"summary":"Consultar endereco por CEP","tags":["CEP"],"description":"Retorna o endereco completo a partir de um CEP (8 digitos).","parameters":[{"schema":{"type":"string"},"in":"path","name":"cep","required":true,"description":"CEP (somente numeros)"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/cep":{"get":{"summary":"Buscar CEP por logradouro","tags":["CEP"],"description":"Busca CEPs a partir de logradouro / cidade / UF.","parameters":[{"schema":{"type":"string"},"in":"query","name":"logradouro","required":true},{"schema":{"type":"string"},"in":"query","name":"tipo","required":false},{"schema":{"type":"string"},"in":"query","name":"bairro","required":false},{"schema":{"type":"string"},"in":"query","name":"cidade","required":false},{"schema":{"type":"string"},"in":"query","name":"uf","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/cnpj/{cnpj}":{"get":{"summary":"Consultar dados cadastrais por CNPJ","tags":["CNPJ"],"description":"Retorna os dados cadastrais de uma empresa a partir do CNPJ.","parameters":[{"schema":{"type":"string"},"in":"path","name":"cnpj","required":true,"description":"CNPJ, com ou sem máscara. Aceita **CNPJ alfanumérico** (NT Conjunta 2025.001): 12 posições alfanuméricas + 2 dígitos verificadores, ex.: `00.000.000/E08G-12`."}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/{cpf_cnpj}/emitir":{"post":{"summary":"Emitir NFS-e (sincrono, cpf_cnpj na URL)","tags":["NFS-e"],"description":"Variante sincrona com o CNPJ do prestador no path. Prefira POST /nfse/emitir (assincrono) para producao.","parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/{cpf_cnpj}/cancelar":{"post":{"summary":"Cancelar NFS-e (sincrono, cpf_cnpj na URL)","tags":["NFS-e"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/{cpf_cnpj}/consultar":{"post":{"summary":"Consultar NFS-e (sincrono, cpf_cnpj na URL)","tags":["NFS-e"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/{cpf_cnpj}/emitir/json/sync":{"post":{"summary":"Emitir NFS-e via JSON (sincrono)","tags":["NFS-e"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/{cpf_cnpj}/consultar-rps":{"get":{"summary":"Consultar NFS-e por RPS (GovDigital)","tags":["NFS-e"],"description":"Verifica na prefeitura se um RPS ja foi emitido. Util quando a emissao deu erro mas a nota pode ter sido gerada (timeout).","parameters":[{"schema":{"type":"string"},"in":"query","name":"numero_rps","required":true,"description":"Numero do RPS"},{"schema":{"type":"string"},"in":"query","name":"serie","required":false,"description":"Serie (default \"1\")"},{"schema":{"type":"string"},"in":"query","name":"inscricao_municipal","required":false,"description":"IM do prestador (opcional)"},{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/emitir":{"post":{"summary":"Emitir NF-e (assincrono)","tags":["NF-e"],"description":"Enfileira a emissao de uma NF-e. Retorna um job_id; acompanhe via GET /nfe/consultar/{id} ou webhook.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj","nota"],"additionalProperties":true,"properties":{"cpf_cnpj":{"type":"string","description":"CNPJ/CPF do emitente. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito** — 12 posições alfanuméricas + 2 dígitos verificadores, ex.: `00.000.000/E08G-12`."},"nota":{"type":"object","additionalProperties":true,"description":"Dados da NF-e: identificacao, emitente, destinatario, produtos[], total, pagamentos[]... (veja a Referencia de Campos na documentacao). REFORMA TRIBUTARIA (IBS/CBS/IS): por item, envie o grupo produtos[].ibscbs { cst, classificacao (cClassTrib), ibs_uf/ibs_mun/cbs: {valor_bc, aliquota, valor} } e, no nivel da nota, ibscbs_total. IMPORTANTE: para itens IMUNES/isentos (ex.: livro, CST 410) envie APENAS { cst, classificacao } — SEM os sub-grupos ibs_uf/ibs_mun/cbs e SEM ibscbs_total (o CST de imunidade veda o grupo de calculo). Imposto Seletivo vai em produtos[].is_ e is_total."},"webhook_url":{"type":"string","description":"URL para notificacao ao finalizar"},"referencia_externa":{"type":"string","maxLength":120,"description":"Opcional. Id unico do seu lado (letras/numeros, ate 120 chars; ex.: UUID). Idempotente por tenant: reenviar a MESMA referencia devolve o job existente (HTTP 200, idempotente:true) em vez de reemitir a nota. Para corrigir e reemitir uma nota que falhou, use uma NOVA referencia. Tambem permite localizar a emissao depois via GET /v1/jobs/localizar?ref=... mesmo sem o job_id."}},"example":{"cpf_cnpj":"string","referencia_externa":"PEDIDO-12345","nota":{"identificacao":{"natOp":"string","mod":0,"serie":0,"nNF":0,"dhEmi":"string","tpNF":0,"idDest":0,"cMunFG":0,"tpImp":0,"tpEmis":0,"finNFe":0,"indFinal":0,"indPres":0,"procEmi":0,"verProc":"string"},"emitente":{"CNPJCPF":"string","xNome":"string","xFant":"string","CRT":0,"IE":"string","xLgr":"string","nro":"string","xBairro":"string","cMun":0,"xMun":"string","UF":"string","cUF":0,"CEP":"string","cPais":0,"xPais":"string","Fone":"string"},"destinatario":{"CNPJCPF":"string","xNome":"string","indIEDest":0,"xLgr":"string","nro":"string","xBairro":"string","cMun":0,"xMun":"string","UF":"string","CEP":"string"},"produtos":[{"cProd":"string","cEAN":"string","xProd":"string","NCM":"string","CFOP":0,"uCom":"string","qCom":0,"vUnCom":0,"vProd":0,"cEANTrib":"string","uTrib":"string","qTrib":0,"vUnTrib":0,"indTot":0,"icms":{"orig":0,"CST":"string"},"pis":{"CST":"string"},"cofins":{"CST":"string"},"ibscbs":{"cst":"string","classificacao":"string","ibs_uf":{"valor_bc":0,"aliquota":0,"valor":0},"ibs_mun":{"valor_bc":0,"aliquota":0,"valor":0},"cbs":{"valor_bc":0,"aliquota":0,"valor":0}}}],"total":{"vProd":0,"vNF":0},"ibscbs_total":{"vBCIBSCBS":0,"ibs":{"vIBS":0,"uf":{"vIBSUF":0},"mun":{"vIBSMun":0}},"cbs":{"vCBS":0}},"transportador":{"modFrete":0},"pagamentos":[{"tPag":"string","vPag":0,"indPag":0}]}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/cancelar":{"post":{"summary":"Cancelar NF-e","tags":["NF-e"],"description":"Solicita o cancelamento de uma NF-e autorizada. Informe job_id (da emissao) OU chave, e a justificativa (min. 15 caracteres).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj"],"additionalProperties":true,"properties":{"cpf_cnpj":{"type":"string"},"job_id":{"type":"string"},"chave":{"type":"string"},"justificativa":{"type":"string"},"webhook_url":{"type":"string"}},"example":{"cpf_cnpj":"string","job_id":"string","justificativa":"string"}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/consultar/{id}":{"get":{"summary":"Consultar job de NF-e","tags":["NF-e"],"description":"Retorna o status e o resultado de um job de NF-e (status, dados da nota, arquivos disponiveis).","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do job (UUID)"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/{id}/file/{tipo}":{"get":{"summary":"Baixar arquivo da NF-e","tags":["NF-e"],"description":"Download direto do arquivo (binario) de um job de NF-e.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do job"},{"schema":{"type":"string"},"in":"path","name":"tipo","required":true,"description":"xml | pdf | log | xml_cancelamento"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfce/emitir":{"post":{"summary":"Emitir NFC-e (assincrono)","tags":["NFC-e"],"description":"Enfileira a emissao de uma NFC-e (modelo 65). Requer CSC configurado (PUT /empresas/{cpf_cnpj}/nfce). O modelo (65), tpImp (4), idDest (1) e indPres (1) sao aplicados automaticamente. Retorna job_id; acompanhe via GET /nfce/consultar/{id} ou webhook.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj","nota"],"additionalProperties":true,"properties":{"cpf_cnpj":{"type":"string","description":"CNPJ/CPF do emitente. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito** — 12 posições alfanuméricas + 2 dígitos verificadores, ex.: `00.000.000/E08G-12`."},"nota":{"type":"object","additionalProperties":true,"description":"Dados da NFC-e: identificacao, emitente, produtos[], total, pagamentos[] (destinatario opcional)."},"webhook_url":{"type":"string"},"referencia_externa":{"type":"string","maxLength":120,"description":"Opcional. Id unico do seu lado (letras/numeros, ate 120 chars; ex.: UUID). Idempotente por tenant: reenviar a MESMA referencia devolve o job existente (HTTP 200, idempotente:true) em vez de reemitir a nota. Para corrigir e reemitir uma nota que falhou, use uma NOVA referencia. Tambem permite localizar a emissao depois via GET /v1/jobs/localizar?ref=... mesmo sem o job_id."}},"example":{"cpf_cnpj":"string","referencia_externa":"PEDIDO-12345","nota":{"identificacao":{"modelo":65,"serie":0,"nNF":0,"dhEmi":"string","natOp":"string","tpNF":1,"idDest":1,"cMunFG":0,"tpImp":4,"tpEmis":1,"finNFe":1,"indFinal":1,"indPres":1},"emitente":{"CNPJCPF":"string","xNome":"string","xFant":"string","CRT":0,"IE":"string","xLgr":"string","nro":"string","xBairro":"string","cMun":0,"xMun":"string","UF":"string","cUF":0,"CEP":"string"},"produtos":[{"cProd":"string","cEAN":"SEM GTIN","xProd":"string","NCM":"string","CFOP":0,"uCom":"string","qCom":0,"vUnCom":0,"vProd":0,"cEANTrib":"SEM GTIN","uTrib":"string","qTrib":0,"vUnTrib":0,"indTot":1,"icms":{"orig":0,"CST":"string"},"pis":{"CST":"string"},"cofins":{"CST":"string"}}],"total":{"vProd":0,"vNF":0},"pagamentos":[{"tPag":"string","vPag":0}]}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/nfce/cancelar":{"post":{"summary":"Cancelar NFC-e","tags":["NFC-e"],"description":"Solicita o cancelamento de uma NFC-e autorizada. Informe job_id (da emissao) OU chave, e a justificativa (min. 15 caracteres).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj"],"additionalProperties":true,"properties":{"cpf_cnpj":{"type":"string"},"job_id":{"type":"string"},"chave":{"type":"string"},"justificativa":{"type":"string"},"webhook_url":{"type":"string"}},"example":{"cpf_cnpj":"string","job_id":"string","justificativa":"string"}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/nfce/consultar/{id}":{"get":{"summary":"Consultar job de NFC-e","tags":["NFC-e"],"description":"Retorna o status e o resultado de um job de NFC-e (status, dados da nota, arquivos disponiveis).","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do job (UUID)"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfce/{id}/file/{tipo}":{"get":{"summary":"Baixar arquivo da NFC-e","tags":["NFC-e"],"description":"Download direto do arquivo (binario) de um job de NFC-e (xml | pdf | log).","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do job"},{"schema":{"type":"string"},"in":"path","name":"tipo","required":true,"description":"xml | pdf | log"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/emitir":{"post":{"summary":"Emitir NFS-e — provedor Nacional (assincrono)","tags":["NFS-e"],"description":"Enfileira a emissao de uma NFS-e no Padrao Nacional. O corpo \"nota\" usa o formato infDPS. Retorna um job_id; acompanhe via GET /nfse/consultar/{id} ou webhook.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj","nota"],"additionalProperties":true,"properties":{"cpf_cnpj":{"type":"string","description":"CNPJ/CPF do prestador. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito** — 12 posições alfanuméricas + 2 dígitos verificadores, ex.: `00.000.000/E08G-12`."},"nota":{"type":"object","additionalProperties":true,"description":"Objeto com ambiente, provedor:\"nacional\" e infDPS (veja a Referencia de Campos na documentacao)."},"webhook_url":{"type":"string","description":"URL para notificacao ao finalizar"},"referencia_externa":{"type":"string","maxLength":120,"description":"Opcional. Id unico do seu lado (letras/numeros, ate 120 chars; ex.: UUID). Idempotente por tenant: reenviar a MESMA referencia devolve o job existente (HTTP 200, idempotente:true) em vez de reemitir a nota. Para corrigir e reemitir uma nota que falhou, use uma NOVA referencia. Tambem permite localizar a emissao depois via GET /v1/jobs/localizar?ref=... mesmo sem o job_id."}},"example":{"cpf_cnpj":"string","referencia_externa":"PEDIDO-12345","nota":{"ambiente":"string","provedor":"nacional","infDPS":{"tpAmb":0,"dhEmi":"string","dCompet":"string","prest":{"CNPJ":"string","IM":"string","opSimpNac":0},"toma":{"CPF":"string","xNome":"string","end":{"endNac":{"cMun":"string","CEP":"string"},"xLgr":"string","nro":"string","xBairro":"string"}},"serv":{"locPrest":{"cLocPrestacao":"string"},"cServ":{"cTribNac":"string","xDescServ":"string","cNBS":"string"}},"valores":{"vServPrest":{"vServ":0},"trib":{"tribMun":{"tribISSQN":0,"cLocIncid":"string","vBC":0,"tpRetISSQN":0,"vLiq":0},"totTrib":{"vTotTrib":{"vTotTribFed":0,"vTotTribEst":0,"vTotTribMun":0}}}},"IBSCBS":{"finNFSe":0,"indFinal":0,"cIndOp":"string","indDest":0,"valores":{"trib":{"gIBSCBS":{"CST":"string","cClassTrib":"string"}}}}}}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/govdigital/emitir":{"post":{"summary":"Emitir NFS-e — provedor GovDigital (assincrono)","tags":["NFS-e"],"description":"Enfileira a emissao de uma NFS-e no GovDigital (Tecnos/NFe-Cidades). Mesmo formato infDPS do endpoint nacional, com provedor:\"govdigital\".","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj","nota"],"additionalProperties":true,"properties":{"cpf_cnpj":{"type":"string","description":"CNPJ/CPF do prestador. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito** — 12 posições alfanuméricas + 2 dígitos verificadores, ex.: `00.000.000/E08G-12`."},"nota":{"type":"object","additionalProperties":true,"description":"Objeto com ambiente, provedor:\"govdigital\" e infDPS (veja a Referencia de Campos na documentacao)."},"webhook_url":{"type":"string","description":"URL para notificacao ao finalizar"},"referencia_externa":{"type":"string","maxLength":120,"description":"Opcional. Id unico do seu lado (letras/numeros, ate 120 chars; ex.: UUID). Idempotente por tenant: reenviar a MESMA referencia devolve o job existente (HTTP 200, idempotente:true) em vez de reemitir a nota. Para corrigir e reemitir uma nota que falhou, use uma NOVA referencia. Tambem permite localizar a emissao depois via GET /v1/jobs/localizar?ref=... mesmo sem o job_id."}},"example":{"cpf_cnpj":"string","referencia_externa":"PEDIDO-12345","nota":{"ambiente":"string","provedor":"govdigital","infDPS":{"tpAmb":0,"dhEmi":"string","dCompet":"string","prest":{"CNPJ":"string","IM":"string","opSimpNac":0,"end":{"endNac":{"cMun":"string","CEP":"string"},"xLgr":"string","nro":"string","xBairro":"string"}},"toma":{"CPF":"string","xNome":"string","end":{"endNac":{"cMun":"string","CEP":"string"},"xLgr":"string","nro":"string","xBairro":"string"}},"serv":{"locPrest":{"cLocPrestacao":"string"},"cServ":{"cTribNac":"string","xDescServ":"string","cNBS":"string"}},"valores":{"vServPrest":{"vServ":0},"trib":{"tribMun":{"tribISSQN":0,"cLocIncid":"string","vBC":0,"pAliq":0,"vISSQN":0,"tpRetISSQN":0,"vLiq":0},"totTrib":{"vTotTrib":{"vTotTribFed":0,"vTotTribEst":0,"vTotTribMun":0}}}},"IBSCBS":{"finNFSe":0,"indFinal":0,"cIndOp":"string","indDest":0,"valores":{"trib":{"gIBSCBS":{"CST":"string","cClassTrib":"string"}}}}}}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/cancelar":{"post":{"summary":"Cancelar NFS-e","tags":["NFS-e"],"description":"Solicita o cancelamento de uma NFS-e emitida. Informe job_id (da emissao) OU numero, e a justificativa.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj"],"additionalProperties":true,"properties":{"cpf_cnpj":{"type":"string"},"job_id":{"type":"string"},"numero":{"type":"integer"},"codigo_cancelamento":{"type":"string"},"justificativa":{"type":"string"},"webhook_url":{"type":"string"}},"example":{"cpf_cnpj":"string","job_id":"string","justificativa":"string"}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/consultar/{id}":{"get":{"summary":"Consultar job de NFS-e","tags":["NFS-e"],"description":"Retorna o status e o resultado de um job de NFS-e (status, dados da nota, arquivos disponiveis).","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do job (UUID)"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/{id}/file/{tipo}":{"get":{"summary":"Baixar arquivo da NFS-e","tags":["NFS-e"],"description":"Download direto do arquivo (binario) de um job de NFS-e.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"ID do job"},{"schema":{"type":"string"},"in":"path","name":"tipo","required":true,"description":"xml | pdf | log"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfse/consultar-sefaz":{"post":{"summary":"Consultar NFS-e na SEFAZ/prefeitura (tempo real)","tags":["NFS-e"],"description":"Consulta a nota diretamente no webservice da prefeitura/SEFAZ. Informe chave_acesso, job_id ou numero.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj"],"additionalProperties":true,"properties":{"cpf_cnpj":{"type":"string"},"chave_acesso":{"type":"string"},"job_id":{"type":"string"},"numero":{"type":"integer"},"tipo_consulta":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/jobs/consultar-lote":{"post":{"summary":"Consulta o status de vários jobs de uma vez (lote)","tags":["Notas"],"description":"Envie uma lista de `job_ids` (máx. 200) e receba o status de cada um numa só chamada. Escopo por tenant: ids inexistentes ou de outro tenant retornam `status: \"nao_encontrado\"`. A ordem do retorno segue a ordem enviada.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["job_ids"],"properties":{"job_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":200,"description":"Lista de job_id (UUID) a consultar."}},"example":{"job_ids":["3fa85f64-5717-4562-b3fc-2c963f66afa6","9c8b1e2d-0a4f-4c3b-8e5a-1d2f3a4b5c6d"]}}}}},"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/jobs/erros":{"get":{"summary":"Lista jobs com erro (status failed) num período, por data","tags":["Notas"],"description":"Retorna os jobs que **falharam** (`status = failed`) num intervalo de datas, escopado por tenant. Útil para reconciliar falhas de emissão em lote (ex.: automatizar retry).\n\n- **Período**: `de`/`ate` no formato `YYYY-MM-DD` (data de criação do job, fuso de Brasília). A janela é de no **máximo 90 dias**. Se você **não** informar datas, retorna os **últimos 7 dias**; se informar só `ate`, `de` = `ate − 7 dias`.\n- **`formato=lista`** (padrão): lista paginada de jobs. **`formato=resumo`**: contagem agregada por tipo e motivo normalizado (sem listar cada job).\n- Só falhas de **job**. Notas que foram autorizadas mas **rejeitadas** pela SEFAZ/prefeitura NÃO entram aqui.\n- O campo `erro` vem saneado (sem marcadores internos); quando houve reemissão, o novo id vem em `reemitido_como`.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-18"},"in":"query","name":"de","required":false,"description":"Data inicial (YYYY-MM-DD). Default: `ate − 7 dias`."},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-06-19"},"in":"query","name":"ate","required":false,"description":"Data final (YYYY-MM-DD). Default: hoje."},{"schema":{"type":"string","enum":["nfe","nfse","nfce","mdfe"]},"in":"query","name":"tipo","required":false,"description":"Filtra por tipo de documento."},{"schema":{"type":"string"},"in":"query","name":"cpf_cnpj","required":false,"description":"Filtra por emitente (CNPJ; pode enviar com ou sem máscara)."},{"schema":{"type":"string","enum":["lista","resumo"],"default":"lista"},"in":"query","name":"formato","required":false,"description":"`lista` (paginada) ou `resumo` (agregado)."},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"pagina","required":false,"description":"Página (formato=lista)."},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"por_pagina","required":false,"description":"Itens por página (máx. 500)."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/jobs/rejeitadas":{"get":{"summary":"Lista notas rejeitadas pela SEFAZ/prefeitura num período, por data","tags":["Notas"],"description":"Retorna as notas cujo job foi processado mas o documento voltou **rejeitado** (`status = rejeitada`) num intervalo de datas, escopado por tenant. É o **par** de `GET /v1/jobs/erros`: aquela cobre jobs que **falharam** (nunca viraram nota); esta cobre notas que **foram rejeitadas** pela SEFAZ/prefeitura.\n\n- **Período**: `de`/`ate` no formato `YYYY-MM-DD` (data de criação do registro, fuso de Brasília). Janela de no **máximo 90 dias**. Sem datas → **últimos 7 dias**; só `ate` → `de` = `ate − 7 dias`.\n- **`formato=lista`** (padrão): lista paginada de notas. **`formato=resumo`**: contagem agregada por tipo e `codigo_status` (o código da SEFAZ é a chave do motivo).\n- Só `rejeitada`. Cancelamento é ação do cliente (rota própria); denegação/inutilização não entram aqui.","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-11"},"in":"query","name":"de","required":false,"description":"Data inicial (YYYY-MM-DD). Default: `ate − 7 dias`."},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-18"},"in":"query","name":"ate","required":false,"description":"Data final (YYYY-MM-DD). Default: hoje."},{"schema":{"type":"string","enum":["nfe","nfse","nfce","mdfe"]},"in":"query","name":"tipo","required":false,"description":"Filtra por tipo de documento."},{"schema":{"type":"string"},"in":"query","name":"cpf_cnpj","required":false,"description":"Filtra por emitente (CNPJ; com ou sem máscara)."},{"schema":{"type":"string","enum":["lista","resumo"],"default":"lista"},"in":"query","name":"formato","required":false,"description":"`lista` (paginada) ou `resumo` (agregado)."},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"pagina","required":false,"description":"Página (formato=lista)."},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"por_pagina","required":false,"description":"Itens por página (máx. 500)."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/jobs/localizar":{"get":{"summary":"Localizar job/emissão sem o job_id (por referência ou atributos)","tags":["Notas"],"description":"Recupera o `job_id` (ou confirma que a emissão nunca aconteceu) quando o cliente **perdeu o job_id**. Escopado por tenant. Duas formas de busca:\n\n1. **Por referência** — se você enviou `referencia_externa` no `/emitir`, basta `?ref=<sua-referencia>` (busca exata, sem precisar de período).\n2. **Por atributos** — informe um **período** (`de`/`ate`, máx. 90 dias; sem datas → últimos 7 dias) e **pelo menos um** de: `cpf_cnpj` (emitente), `destinatario_cpf_cnpj` ou valor (`valor` exato, ou faixa `valor_min`/`valor_max`). Refine com `tipo` e `status`.\n\nA busca cruza os dados do próprio job (referência, destinatário e valor denormalizados na criação) com a nota fiscal, quando existir. **0 resultados** = forte indício de que não processou (pode reemitir com segurança); **1** = é o job perdido; **N** = desambigúe por destinatário/valor/hora. Nunca retorna o payload (que carrega dados sensíveis).\n\n> Observação: destinatário/valor passam a ser gravados no job a partir de 18/07/2026; emissões anteriores são encontradas por esses campos apenas quando viraram nota (ou após backfill).","parameters":[{"schema":{"type":"string","maxLength":120,"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},"in":"query","name":"ref","required":false,"description":"A `referencia_externa` que você enviou no /emitir (busca exata). Dispensa período."},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"query","name":"de","required":false,"description":"Data inicial (YYYY-MM-DD). Default: `ate − 7 dias` (quando busca por atributos)."},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"query","name":"ate","required":false,"description":"Data final (YYYY-MM-DD). Default: hoje."},{"schema":{"type":"string"},"in":"query","name":"cpf_cnpj","required":false,"description":"CNPJ do emitente (com ou sem máscara)."},{"schema":{"type":"string"},"in":"query","name":"destinatario_cpf_cnpj","required":false,"description":"CPF/CNPJ do destinatário (com ou sem máscara)."},{"schema":{"type":"number"},"in":"query","name":"valor","required":false,"description":"Valor total exato do documento."},{"schema":{"type":"number"},"in":"query","name":"valor_min","required":false,"description":"Piso do valor (faixa)."},{"schema":{"type":"number"},"in":"query","name":"valor_max","required":false,"description":"Teto do valor (faixa)."},{"schema":{"type":"string","enum":["nfe","nfse","nfce","mdfe"]},"in":"query","name":"tipo","required":false,"description":"Filtra por tipo de documento."},{"schema":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"in":"query","name":"status","required":false,"description":"Filtra pelo status do job."},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"pagina","required":false},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"in":"query","name":"por_pagina","required":false}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/jobs/{job_id}/itens":{"get":{"summary":"Itens (produtos/serviços) de uma emissão, com os grupos tributários","tags":["Notas"],"description":"Retorna os **itens** de uma emissão a partir do `job_id`, com código, descrição, NCM, CFOP, quantidade, valores e os **grupos tributários de cada item** (ICMS, PIS, COFINS e **IBS/CBS**).\n\n### Para que serve\nResponder **\"qual produto derrubou minha nota\"** sem abrir XML. Quando o fisco rejeita apontando um item (`[nItem: N]` no motivo), a rota marca esse item com `\"rejeitado\": true` e o repete em `item_rejeitado` — o culpado sai identificado em **uma** chamada.\n\n### De onde vêm os dados\nDo **payload enviado** na emissão (`\"fonte\": \"payload_enviado\"`), não do XML autorizado. Isso é deliberado: o XML só existe para nota autorizada, enquanto o payload existe para **qualquer status** — inclusive as rejeitadas e as que falharam, que são justamente as que você precisa diagnosticar. Para notas autorizadas o conteúdo é equivalente (a SEFAZ não altera itens); se você precisa do documento com valor legal, baixe o XML em `/v1/{tipo}/{job_id}/file/xml`.\n\n### Por tipo de documento\n- **NF-e** e **NFC-e**: um item por produto, na ordem em que foram enviados (`nItem` começa em 1).\n- **NFS-e**: a DPS tem **um único serviço**, devolvido como um item só — com `codigo_tributacao_nacional`, `codigo_nbs` e o grupo `issqn`.\n\n> Nunca devolve o payload cru (que carrega certificado e senha) — apenas os itens e seus grupos fiscais.\n\n### Exemplo de uso\nUma NF-e rejeitada com *\"Aliquota do IBS da UF invalida[nItem: 2]\"* devolve `item_rejeitado` com o código e a descrição do produto, e o `ibscbs` daquele item mostra o que foi enviado (ex.: `cst: \"000\"` com alíquota `0` — contradição que o fisco recusa, já que CST 000 é tributação integral).","parameters":[{"schema":{"type":"string","example":"0fafe732-9665-4d36-8971-c8063962290c"},"in":"path","name":"job_id","required":true,"description":"ID do job retornado na emissão. Se você o perdeu, recupere em `GET /v1/jobs/localizar`."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/verificar-campos":{"post":{"summary":"Verificar campos do payload antes de emitir (não emite nada)","tags":["Notas"],"description":"Recebe **o mesmo corpo que você enviaria para `/v1/nfe/emitir`** e devolve os campos que o emissor **não reconhece** — sem emitir, sem consumir numeração e **sem debitar cota**.\n\n### O problema que isto resolve\nCampo com nome errado **não gera erro**: ele é ignorado na conversão e o campo correto sai vazio ou zerado. Um `vlrProd` no lugar de `vProd` produz uma NF-e formalmente válida com o produto valendo **R$ 0,00** — e você só descobre pela rejeição do fisco, ou não descobre.\n\n### O que a resposta traz\nPara cada campo desconhecido: o **caminho exato** dentro do payload e, quando existe algo parecido, uma **sugestão**:\n\n```json\n{ \"caminho\": \"nota.produtos[0].vlrProd\", \"campo\": \"vlrProd\", \"sugestao\": \"vProd\" }\n```\n\n### Duas camadas\n1. **Nomes de campo** — sempre, só com o payload.\n2. **Schema oficial** — quando você informa `cpf_cnpj`: monta, assina com o certificado do emitente e valida contra o XSD da NF-e, **sem transmitir**. Pega valor malformado (`NCM` de 3 dígitos, data inválida, tamanho excedido).\n\nAs duas se complementam e **nenhuma substitui a outra**: campo ignorado não chega ao XML, então o schema não o enxerga; e nome certo não garante valor válido.\n\n### Limites — leia antes de confiar\n- **Regra fiscal não é verificada** (ex.: CST 000 com alíquota zerada). Isso só o fisco avalia.\n- Sem `cpf_cnpj`, apenas a camada 1 roda — a resposta diz isso em `schema.verificado: false`.\n- Disponível para **NF-e e NFC-e**. A **NFS-e usa outro layout** e ainda não tem vocabulário próprio — pedir `tipo: \"nfse\"` é recusado em vez de acusar campos legítimos como desconhecidos.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nota"],"properties":{"nota":{"type":"object","additionalProperties":true,"description":"O mesmo objeto `nota` do /emitir."},"tipo":{"type":"string","enum":["nfe","nfce"],"default":"nfe","description":"Tipo do documento."},"cpf_cnpj":{"type":"string","description":"CNPJ do emitente. **Opcional**: informando, roda também a validação contra o schema oficial (precisa do certificado para assinar antes de validar)."}}}}}},"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/preparar":{"post":{"summary":"Preparar uma emissão para confirmação (não emite)","tags":["NF-e"],"description":"Passo 1 de 2 da emissão assistida. **Não emite nada.** Confere o payload (nomes de campo e schema oficial), monta um **resumo legível** e devolve um `token` de uso único, válido por 15 minutos.\n\nFeito para fluxos com **aprovação humana** — em especial agentes de IA, onde emitir direto é arriscado. Mostre `resumo.texto` para a pessoa e só chame `/v1/nfe/confirmar` depois do sim.\n\n**Se a conferência falhar, não há token**: o payload torto não chega a virar emissão.\n\n**Há um teto de valor** por emissão nesta rota (configurável por conta). Acima dele a preparação é recusada — a emissão direta em `/v1/nfe/emitir` não tem esse limite.\n\nA `referencia_externa` é gerada aqui e presa ao token — repetir o `confirmar` devolve o mesmo job, nunca uma segunda nota.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cpf_cnpj","nota"],"properties":{"cpf_cnpj":{"type":"string","description":"CNPJ do emitente."},"nota":{"type":"object","additionalProperties":true,"description":"O mesmo objeto `nota` do /emitir."},"referencia_externa":{"type":"string","maxLength":120,"description":"Opcional — se omitida, geramos uma."},"webhook_url":{"type":"string"}}}}}},"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/preparar-de":{"post":{"summary":"Preparar uma emissão a partir de uma nota existente","tags":["NF-e"],"description":"Passo 1 de 2, partindo de uma nota que **já existe** em vez de um payload montado do zero. Devolve `token` + `resumo` + **`alteracoes`** (o que mudou em relação à original), e só emite depois do `/v1/nfe/confirmar`.\n\nDois modos:\n\n- **`corrigir`** — a nota de origem **falhou** (rejeitada pelo fisco). Ajusta o que a SEFAZ apontou e reenvia. O número é mantido por padrão: número de nota rejeitada não foi consumido.\n- **`copiar`** — usa uma nota como modelo para uma **nova**. O número **precisa mudar**; se você não informar um, sugerimos o próximo com base nas notas emitidas por aqui — confira, porque não enxergamos o que o cliente emite por fora.\n\nO payload de origem **nunca é devolvido**: ele carrega o certificado digital. Você recebe o resumo e o diff, não a nota inteira.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["job_id","modo"],"properties":{"job_id":{"type":"string","description":"A emissão de origem."},"modo":{"type":"string","enum":["corrigir","copiar"],"description":"`corrigir` (origem rejeitada) ou `copiar` (modelo)."},"ajustes":{"type":"object","additionalProperties":true,"description":"Mudanças por caminho, ex.: `{\"identificacao.nNF\": 1235, \"produtos[0].vProd\": 5.00}`. Use `[n]` para índice de lista e `null` para remover o campo."},"referencia_externa":{"type":"string","maxLength":120},"webhook_url":{"type":"string"}}}}}},"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/confirmar":{"post":{"summary":"Confirmar e emitir uma emissão preparada","tags":["NF-e"],"description":"Passo 2 de 2. Emite o que foi preparado. **Chame apenas após a aprovação de uma pessoa.**\n\nO token é de **uso único**: repetir a chamada devolve o **mesmo** `job_id`, nunca uma segunda nota. A emissão é encaminhada para `/v1/nfe/emitir` com a sua própria credencial — cota, validação de ambiente e idempotência são exatamente as mesmas.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"O token devolvido por /v1/nfe/preparar."}}}}}},"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/jobs/{id}/arquivos":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/jobs/{id}/download/{tipo}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"tipo","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/jobs/{id}/file/{tipo}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"tipo","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/arquivos/zips":{"get":{"summary":"Listar zips mensais de XMLs disponíveis","tags":["Notas"],"description":"Lista os pacotes ZIP mensais de XMLs do tenant, gerados automaticamente no dia 1º de cada mês (um zip por tipo de documento — nfe/nfse/nfce — com todos os XMLs de emissão do mês anterior, organizados por CNPJ do emitente + manifest.json). Retenção: 15 meses. `completo: false` indica zip gerado antes do fechamento do mês (parcial; será regenerado no dia 1º). Baixe via `GET /v1/arquivos/zip-mensal`.","security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/arquivos/zip-mensal":{"get":{"summary":"Download do zip mensal de XMLs (URL assinada)","tags":["Notas"],"description":"Retorna a URL de download (válida por 1h) do ZIP mensal de XMLs do tenant para o tipo e a competência informados. Os zips são gerados no dia 1º de cada mês com os XMLs do mês anterior e mantidos por 15 meses. Use `GET /v1/arquivos/zips` para ver os disponíveis.","parameters":[{"schema":{"type":"string","enum":["nfe","nfse","nfce"],"example":"nfe"},"in":"query","name":"tipo","required":true,"description":"Tipo de documento fiscal."},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","example":"2026-07"},"in":"query","name":"competencia","required":true,"description":"Mês de referência (YYYY-MM)."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/empresas/{cpf_cnpj}/certificado/download":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"cpf_cnpj","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/notas":{"get":{"summary":"Listar notas fiscais","tags":["Notas"],"description":"Lista as notas fiscais do tenant (NF-e, NFS-e, NFC-e), da mais recente para a mais antiga (ordena por `data_emissao`, depois `criado_em`). Escopada ao tenant autenticado.\n\n- **Filtros** (todos opcionais e combináveis por E): `tipo` (tipo de documento), `status` (situação fiscal) e `cpf_cnpj` (CNPJ do **emitente**). Sem filtros, retorna todas as notas do tenant.\n- **Paginação**: `limite` (padrão 20) e `pagina` (padrão 1). A resposta traz `total` (contagem total do filtro), `pagina` e `limite`.\n- **Cada item** inclui: identificação (`tipo`, `modelo`, `serie`, `numero`, `chave_acesso`); situação (`status`, `codigo_status`, `motivo_status`, `protocolo`, `data_autorizacao`); `valor_total`, destinatário (`destinatario_nome`, `destinatario_cpf_cnpj`) e emitente (`emitente_nome`, `emitente_cpf_cnpj`); dados de cancelamento (`protocolo_cancelamento`, `data_cancelamento`, `justificativa_cancelamento`); e os ids de origem `job_emissao_id` / `job_cancelamento_id` + `ambiente`.\n- **Rotas relacionadas**: status de um job → `GET /v1/<tipo>/consultar/{id}`; documento por chave → `GET /v1/notas/{chave}`; reconciliação por período → `GET /v1/jobs/erros` e `GET /v1/jobs/rejeitadas`.","parameters":[{"schema":{"type":"string","enum":["nfe","nfse","nfce","mdfe"],"example":"nfe"},"in":"query","name":"tipo","required":false,"description":"Filtra por tipo de documento."},{"schema":{"type":"string","enum":["autorizada","cancelada","rejeitada","denegada","inutilizada"],"example":"autorizada"},"in":"query","name":"status","required":false,"description":"Filtra pela situação fiscal da nota."},{"schema":{"type":"string","example":"60772432000142"},"in":"query","name":"cpf_cnpj","required":false,"description":"CNPJ do emitente. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito** — 12 posições alfanuméricas + 2 dígitos verificadores, ex.: `00.000.000/E08G-12`."},{"schema":{"type":"integer","minimum":1,"default":20},"in":"query","name":"limite","required":false,"description":"Itens por página (padrão 20)."},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"pagina","required":false,"description":"Página, começando em 1 (padrão 1)."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/notas/rejeicoes":{"get":{"summary":"Relatório de emissões × rejeições (resumo com valores e motivos)","tags":["Notas"],"description":"Resumo consolidado do período: **emitidas com sucesso** (autorizadas + canceladas) × **com erro** (notas rejeitadas + jobs falhos), com **valores somados**, **percentuais**, classificação por **categoria** (fiscal, duplicidade, infra), os **principais motivos** e um resumo por tipo (NF-e/NFS-e). Escopado ao tenant. É a visão de topo — use `GET /v1/notas/rejeicoes/detalhe` (por código/motivo) e `GET /v1/notas/emitidas/detalhe` para o drill-down paginado. Sem datas → do 1º dia do mês corrente até hoje.","parameters":[{"schema":{"type":"string","example":"2026-07-01"},"in":"query","name":"de","required":false,"description":"Data inicial YYYY-MM-DD. Default: 1º dia do mês atual."},{"schema":{"type":"string","example":"2026-07-18"},"in":"query","name":"ate","required":false,"description":"Data final YYYY-MM-DD. Default: hoje."},{"schema":{"type":"string","enum":["nfe","nfse","nfce","mdfe"]},"in":"query","name":"tipo","required":false,"description":"Filtra por tipo de documento."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/notas/rejeicoes/detalhe":{"get":{"summary":"Detalhe paginado de rejeições/falhas (drill-down por código ou motivo)","tags":["Notas"],"description":"Drill-down paginado e buscável de um item do relatório `GET /v1/notas/rejeicoes`. Informe **`codigo`** (código numérico da SEFAZ — ex.: 225 = falha de schema, 539 = duplicidade → notas `rejeitada`) **ou** **`motivo`** (texto normalizado do erro, para falhas de **job** NFS-e/pré-SEFAZ, quando `codigo` = `-`). Um dos dois é obrigatório (senão `400`). Escopado ao tenant. Sem datas → do 1º dia do mês até hoje.","parameters":[{"schema":{"type":"string","example":"539"},"in":"query","name":"codigo","required":false,"description":"Código de status da SEFAZ (ex.: 225, 539). Use \"-\" para falhas de job (aí informe `motivo`)."},{"schema":{"type":"string","example":"Certificado vencido"},"in":"query","name":"motivo","required":false,"description":"Motivo normalizado do erro (quando `codigo` = \"-\")."},{"schema":{"type":"string","enum":["nfe","nfse","nfce","mdfe"]},"in":"query","name":"tipo","required":false,"description":"Filtra por tipo de documento."},{"schema":{"type":"string","example":"Maria"},"in":"query","name":"busca","required":false,"description":"Filtra por nome/CPF/CNPJ do destinatário ou data (DD/MM/YYYY HH:MM)."},{"schema":{"type":"string","example":"2026-07-01"},"in":"query","name":"de","required":false,"description":"Data inicial YYYY-MM-DD. Default: 1º dia do mês."},{"schema":{"type":"string","example":"2026-07-18"},"in":"query","name":"ate","required":false,"description":"Data final YYYY-MM-DD. Default: hoje."},{"schema":{"type":"integer","default":1},"in":"query","name":"pagina","required":false,"description":"Página."},{"schema":{"type":"integer","default":20},"in":"query","name":"limite","required":false,"description":"Itens por página (máx. 100)."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/notas/emitidas/detalhe":{"get":{"summary":"Detalhe paginado de notas emitidas com sucesso","tags":["Notas"],"description":"Lista paginada e buscável das notas **emitidas com sucesso** (status `autorizada` ou `cancelada`) no período — o drill-down do bloco \"emitidas\" do relatório `GET /v1/notas/rejeicoes`. Escopado ao tenant. Ordena da mais recente para a mais antiga. Sem datas → do 1º dia do mês corrente até hoje.","parameters":[{"schema":{"type":"string","example":"2026-07-01"},"in":"query","name":"de","required":false,"description":"Data inicial YYYY-MM-DD. Default: 1º dia do mês."},{"schema":{"type":"string","example":"2026-07-18"},"in":"query","name":"ate","required":false,"description":"Data final YYYY-MM-DD. Default: hoje."},{"schema":{"type":"string","enum":["nfe","nfse","nfce","mdfe"]},"in":"query","name":"tipo","required":false,"description":"Filtra por tipo de documento."},{"schema":{"type":"string","example":"Maria"},"in":"query","name":"busca","required":false,"description":"Filtra por nome/CPF/CNPJ do destinatário ou data (DD/MM/YYYY HH:MM)."},{"schema":{"type":"integer","default":1},"in":"query","name":"pagina","required":false,"description":"Página."},{"schema":{"type":"integer","default":20},"in":"query","name":"limite","required":false,"description":"Itens por página (máx. 100)."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/notas/auditoria":{"get":{"summary":"Auditoria por documento/nome, Job ID ou referência externa","tags":["Notas"],"description":"Busca notas e jobs do tenant por **um** destes critérios: `busca` (documento/nome do destinatário), `job_id` (completo ou prefixo) ou `referencia_externa` (a que você enviou no `/emitir`, correspondência exata). Sempre escopado ao tenant. Retorna as notas do período (autorizada/rejeitada/cancelada) e — em modo `job_id`/`referencia_externa` — também o job quando ainda **não virou nota** (falha/pendente), com resumo por status e valores. Datas (`de`/`ate`) são opcionais.","parameters":[{"schema":{"type":"string","example":"Maria Silva"},"in":"query","name":"busca","required":false,"description":"CPF/CNPJ ou nome do destinatário (aceita máscara)."},{"schema":{"type":"string","example":"8881bac5"},"in":"query","name":"job_id","required":false,"description":"ID do job (completo ou prefixo)."},{"schema":{"type":"string","example":"PEDIDO-12345"},"in":"query","name":"referencia_externa","required":false,"description":"Referência externa exata enviada no /emitir."},{"schema":{"type":"string","example":"2026-07-01"},"in":"query","name":"de","required":false,"description":"Data inicial YYYY-MM-DD (opcional)."},{"schema":{"type":"string","example":"2026-07-18"},"in":"query","name":"ate","required":false,"description":"Data final YYYY-MM-DD (opcional)."},{"schema":{"type":"integer","default":1},"in":"query","name":"pagina","required":false,"description":"Página."},{"schema":{"type":"integer","default":20},"in":"query","name":"limite","required":false,"description":"Itens por página (máx. 100)."}],"security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v1/notas/{chave}":{"get":{"summary":"Consultar nota por chave de acesso","tags":["Notas"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"chave","required":true,"description":"Chave de acesso (44 digitos)"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/nfe/{cpf_cnpj}/cancelar":{"post":{"summary":"Cancelar NF-e (sincrono, cpf_cnpj na URL)","tags":["NF-e"],"parameters":[{"schema":{"type":"string","example":"60772432000142"},"in":"path","name":"cpf_cnpj","required":true,"description":"CNPJ/CPF da empresa. Aceita com ou sem máscara. **CNPJ alfanumérico (NT Conjunta 2025.001) é aceito.**"}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://api.conota.dev","description":"Producao (principal)"},{"url":"https://api.conota.com.br","description":"Producao (alias)"},{"url":"https://api.pluganota.com","description":"Producao (alias anterior — segue ativo)"},{"url":"https://api.qualyfiscal.com.br","description":"Producao (alias legado — segue ativo)"}],"security":[{"apiKey":[]},{"bearer":[]}],"tags":[{"name":"NFS-e","description":"Emissao, consulta e cancelamento de NFS-e"},{"name":"NF-e","description":"Emissao, consulta e cancelamento de NF-e"},{"name":"NFC-e","description":"Emissao, consulta e cancelamento de NFC-e (modelo 65)"},{"name":"CEP","description":"Consulta de CEP"},{"name":"CNPJ","description":"Consulta de CNPJ"},{"name":"Notas","description":"Listagem, consulta e auditoria de notas"},{"name":"Empresas","description":"Cadastro e configuracao de empresas emissoras"},{"name":"Autenticacao","description":"Login e gestao de API keys"}]}