{"openapi":"3.0.3","info":{"title":"Fisco API","version":"1.1.0","description":"API pública para emissão e gestão de NFS-e (São Paulo), catálogo de produtos/serviços, tomadores, notas recebidas e impostos. Autentique com sua chave: `Authorization: Bearer fisco_live_xxx` (gere/veja em Integrações)."},"servers":[{"url":"https://api.fisco.com.br/api","description":"Produção (API pública)"},{"url":"/api","description":"Mesma origem (use aqui no painel)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"NFS-e","description":"Emitir, consultar e cancelar notas de serviço."},{"name":"Recebidas","description":"Notas que sua empresa recebeu como tomadora — listar, manifestar e conciliar."},{"name":"Fornecedores","description":"Prestadores das notas recebidas — reconhecer, bloquear e gerenciar fichas."},{"name":"IBS/CBS","description":"Reforma Tributária — créditos a apropriar e apuração (débitos − créditos) do período."},{"name":"Impostos","description":"Simples Nacional — resumo do DAS da competência."},{"name":"Catálogo","description":"Produtos e serviços para agilizar a emissão."},{"name":"Tomadores","description":"Cadastro dos seus clientes (tomadores)."},{"name":"Conta","description":"Status da conta e verificação da chave."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"fisco_live_xxx"}},"responses":{"NaoAutorizado":{"description":"API Key ausente ou inválida","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"string"}}}}}}},"schemas":{"NotaEmitida":{"type":"object","properties":{"numero_nfe":{"type":"string","example":"820"},"status_nfe":{"type":"string","example":"N"},"competencia":{"type":"string","example":"06/2026"},"data_emissao":{"type":"string","example":"2026-06-15"},"valor":{"type":"number","example":5000},"discriminacao":{"type":"string"},"codigo_servico":{"type":"string","example":"04294"},"tomador_nome":{"type":"string"},"tomador_cnpj":{"type":"string"},"codigo_verificacao":{"type":"string"},"pdf_url":{"type":"string"},"numero_rps":{"type":"integer","example":820},"origem":{"type":"string","enum":["fisco","painel","api","claude","externa"],"description":"Onde a nota (ou tentativa) foi originada. 'claude' = conector MCP; 'api' = API direta; 'painel' = emissão manual.","example":"api"},"status":{"type":"string","enum":["emitida","cancelada","erro"],"description":"'erro' = emissão que FALHOU (registro da tentativa; não vira nota nem conta como receita).","example":"emitida"},"erro_mensagem":{"type":"string","nullable":true,"description":"Motivo da falha quando status = erro."},"cancelada_em":{"type":"string","nullable":true}}},"NfseEmitidaResposta":{"type":"object","properties":{"sucesso":{"type":"boolean","example":true},"numero_nfe":{"type":"string","example":"845"},"numero_rps":{"type":"integer","example":845},"codigo_verificacao":{"type":"string","example":"23GBUMXI"},"valor":{"type":"number","example":5000},"competencia":{"type":"string","example":"09/2026"},"link_pdf":{"type":"string","description":"Link PERMANENTE do PDF oficial do Fisco — envie ao tomador. Na 1ª abertura o PDF é gerado sob demanda (~40s) e fica em cache.","example":"https://app.fisco.com.br/nfse/3d24db28-6ec4-42c9-986b-def2302a11ae?k=AbC123xyz"},"link_prefeitura":{"type":"string","description":"Plano B: link oficial da Prefeitura de SP para ver/imprimir a nota.","example":"https://nfe.prefeitura.sp.gov.br/contribuinte/notaprint.aspx?nf=845&verificacao=23GBUMXI"},"instrucao_tomador":{"type":"string","example":"Envie o link_pdf ao tomador — abre o PDF oficial da NFS-e gerado pelo Fisco."}}},"ItemCatalogo":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo":{"type":"string","example":"servico"},"nome":{"type":"string","example":"Consultoria de TI"},"descricao":{"type":"string"},"codigo_servico":{"type":"string","example":"04294"},"cnae_origem":{"type":"string","example":"6204-0/00"},"valor_padrao":{"type":"number","example":5000},"aliquota_iss":{"type":"number","example":0.05},"ativo":{"type":"boolean","example":true}}},"Tomador":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string","example":"Empresa Tomadora Ltda"},"cnpj":{"type":"string","example":"12345678000199"},"email":{"type":"string","example":"financeiro@empresa.com"},"municipio":{"type":"string","example":"São Paulo"},"uf":{"type":"string","example":"SP"},"ativo":{"type":"boolean","example":true},"arquivado_em":{"type":"string","nullable":true},"created_at":{"type":"string"}}}}},"paths":{"/v1/status":{"get":{"tags":["Conta"],"summary":"Status da conta e verificação da chave","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/ccm":{"get":{"tags":["Conta"],"summary":"Consultar Inscrição Municipal (CCM) na Prefeitura de SP","description":"Descobre o(s) CCM de um CNPJ na Prefeitura de São Paulo e se está habilitado a emitir NFS-e (ConsultaCNPJ). Assinado com o certificado da sua empresa. Sem `cnpj`, consulta o CNPJ da própria conta.","parameters":[{"name":"cnpj","in":"query","required":false,"schema":{"type":"string"},"description":"CNPJ a consultar (14 dígitos). Se omitido, usa o CNPJ da sua empresa.","example":"12.321.701/0001-01"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"cnpj":{"type":"string","example":"12321701000101"},"inscricoes":{"type":"array","items":{"type":"object","properties":{"inscricao_municipal":{"type":"string","example":"41167139"},"emite_nfse":{"type":"boolean","example":true}}}}}}}}},"400":{"description":"Certificado ausente ou CNPJ inválido"},"401":{"$ref":"#/components/responses/NaoAutorizado"},"422":{"description":"Falha na consulta à Prefeitura"}}}},"/v1/nfse/emitir":{"post":{"tags":["NFS-e"],"summary":"Emitir NFS-e","description":"Emite uma NFS-e na Prefeitura de SP e devolve o `link_pdf` (link permanente do PDF oficial, para enviar ao tomador). Emissões que falham (cadastro incompleto, rejeição da Prefeitura) ficam registradas no histórico como tentativa com erro.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tomador_cnpj","tomador_nome","valor","discriminacao"],"properties":{"tomador_cnpj":{"type":"string","example":"12.345.678/0001-99"},"tomador_nome":{"type":"string","example":"Empresa Tomadora Ltda"},"tomador_email":{"type":"string","example":"financeiro@empresa.com"},"tomador_municipio":{"type":"string","example":"São Paulo"},"tomador_uf":{"type":"string","example":"SP"},"valor":{"type":"number","example":5000},"discriminacao":{"type":"string","example":"Prestação de serviços de consultoria"},"codigo_servico":{"type":"string","example":"04294"},"competencia_mes":{"type":"integer","example":6},"competencia_ano":{"type":"integer","example":2026}}}}}},"responses":{"201":{"description":"Nota emitida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseEmitidaResposta"}}}},"400":{"description":"Campos obrigatórios ausentes ou valor inválido"},"401":{"$ref":"#/components/responses/NaoAutorizado"},"403":{"description":"Cadastro incompleto (falta CCM/certificado) — tentativa registrada no histórico como erro"},"422":{"description":"Rejeição da Prefeitura — tentativa registrada no histórico como erro"}}}},"/v1/nfse":{"get":{"tags":["NFS-e"],"summary":"Listar notas emitidas","parameters":[{"name":"competencia","in":"query","schema":{"type":"string"},"example":"06/2026"},{"name":"limite","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"pagina","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Lista de notas"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/nfse/{numero}":{"get":{"tags":["NFS-e"],"summary":"Consultar nota individual (+ PDF)","parameters":[{"name":"numero","in":"path","required":true,"schema":{"type":"string"},"example":"820"}],"responses":{"200":{"description":"Detalhes da nota","content":{"application/json":{"schema":{"type":"object","properties":{"nota":{"$ref":"#/components/schemas/NotaEmitida"}}}}}},"404":{"description":"Nota não encontrada"}}},"delete":{"tags":["NFS-e"],"summary":"Cancelar nota","parameters":[{"name":"numero","in":"path","required":true,"schema":{"type":"string"},"example":"820"},{"name":"motivo","in":"query","required":false,"schema":{"type":"string"},"description":"Motivo do cancelamento (registrado na nota). Padrão: 'Cancelamento via API'.","example":"Emitida em duplicidade"}],"responses":{"200":{"description":"Cancelada"},"401":{"$ref":"#/components/responses/NaoAutorizado"},"403":{"description":"Cadastro incompleto"},"409":{"description":"Nota já cancelada"},"422":{"description":"Prazo (180 dias) expirado / sem código de verificação"}}}},"/v1/nfse/recebidas":{"get":{"tags":["Recebidas"],"summary":"Listar notas recebidas (acervo)","parameters":[{"name":"competencia","in":"query","schema":{"type":"string"},"example":"06/2026"},{"name":"de","in":"query","schema":{"type":"string"},"example":"2026-06-01"},{"name":"ate","in":"query","schema":{"type":"string"},"example":"2026-06-30"},{"name":"limite","in":"query","schema":{"type":"integer","default":50}},{"name":"pagina","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Notas recebidas (inclui status_tomador, motivo_recusa, chave)"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/nfse/recebidas/manifestar":{"post":{"tags":["Recebidas"],"summary":"Manifestar (aceitar/recusar/divergente) uma nota recebida","description":"Triagem do tomador. status: a_conferir|aceita|recusada|divergente. motivo (quando recusada): desconheco|valor_divergente|duplicada|servico_nao_prestado|outro.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["numero","status"],"properties":{"numero":{"type":"string","example":"12345"},"cnpjPrestador":{"type":"string","example":"08985446000124"},"status":{"type":"string","enum":["a_conferir","aceita","recusada","divergente"]},"motivo":{"type":"string","enum":["desconheco","valor_divergente","duplicada","servico_nao_prestado","outro"]},"observacao":{"type":"string"},"prestadorEmail":{"type":"string"},"notificarPrestador":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Manifestação registrada"},"400":{"description":"Dados inválidos"},"401":{"$ref":"#/components/responses/NaoAutorizado"},"404":{"description":"Nota não encontrada"}}}},"/v1/fornecedores-esperados":{"get":{"tags":["Fornecedores"],"summary":"Listar fornecedores reconhecidos (anti-fraude)","responses":{"200":{"description":"Lista de fornecedores esperados"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}},"post":{"tags":["Fornecedores"],"summary":"Reconhecer um fornecedor (CNPJ esperado)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cnpj"],"properties":{"cnpj":{"type":"string","example":"08985446000124"},"nome":{"type":"string"}}}}}},"responses":{"200":{"description":"Fornecedor reconhecido"},"400":{"description":"CNPJ inválido"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}},"delete":{"tags":["Fornecedores"],"summary":"Remover um fornecedor reconhecido","parameters":[{"name":"cnpj","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removido"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/creditos-ibscbs":{"get":{"tags":["IBS/CBS"],"summary":"Resumo de créditos de IBS/CBS a apropriar (Reforma)","description":"Soma IBS (UF+Mun), CBS e base das NFS-e recebidas não canceladas e não recusadas do período.","parameters":[{"name":"competencia","in":"query","schema":{"type":"string"},"example":"10/2026"},{"name":"de","in":"query","schema":{"type":"string"},"example":"2026-10-01"},{"name":"ate","in":"query","schema":{"type":"string"},"example":"2026-10-31"}],"responses":{"200":{"description":"Resumo de créditos IBS/CBS"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/inbox":{"get":{"tags":["Recebidas"],"summary":"Conciliador — documentos conciliados (Dual Check)","description":"Lista os documentos capturados por canais informais e conciliados contra o acervo SEFAZ, com status, score e o payload canônico para ERP. Retorna também o e-mail de recebimento dedicado.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"Filtra por status da conciliação."}],"responses":{"200":{"description":"Lista de documentos + endereço"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}},"post":{"tags":["Recebidas"],"summary":"Conciliar um documento de canal (Dual Check)","description":"Concilia um documento recebido por fora (e-mail/WhatsApp/upload) contra o acervo. Envie dadosExtraidos OU um xml (que será interpretado). Retorna status, score, divergência de IBS/CBS e o erp_payload canônico.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origem":{"type":"string","enum":["EMAIL","WHATSAPP","SEFAZ","PORTAL","UPLOAD"]},"dadosExtraidos":{"type":"object","properties":{"chaveNFe":{"type":"string"},"cnpjEmitente":{"type":"string"},"numeroNota":{"type":"string"},"valorTotal":{"type":"number"},"pdfUrl":{"type":"string"},"ibs":{"type":"number"},"cbs":{"type":"number"}}},"xml":{"type":"string","description":"Alternativa a dadosExtraidos: XML da NF-e/NFS-e."}}}}}},"responses":{"200":{"description":"Resultado da conciliação"},"400":{"description":"Payload inválido"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/fornecedores":{"get":{"tags":["Fornecedores"],"summary":"Fornecedores (ficha + resumo das notas recebidas)","description":"Sem parâmetros: lista os fornecedores (prestadores das notas recebidas) com status (reconhecido/a_conferir/bloqueado), contato, nº de notas, total e crédito de IBS/CBS. Com ?cnpj=: retorna as notas desse fornecedor (aceita CNPJ 14 díg. ou CPF 11 díg. — prestador PF/cartório).","parameters":[{"name":"cnpj","in":"query","required":false,"schema":{"type":"string"},"description":"CNPJ (14) ou CPF (11) — retorna as notas desse fornecedor."}],"responses":{"200":{"description":"Lista de fornecedores ou notas do fornecedor"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}},"post":{"tags":["Fornecedores"],"summary":"Reconhecer / bloquear / editar fornecedor","description":"acao: 'reconhecer' (allowlist), 'bloquear' (auto-recusa as notas dele) ou 'salvar' (edita a ficha). O campo cnpj aceita CNPJ (14 díg.) ou CPF (11 díg., prestador PF/cartório).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cnpj"],"properties":{"cnpj":{"type":"string"},"acao":{"type":"string","enum":["reconhecer","bloquear","salvar"]},"nome":{"type":"string"},"email":{"type":"string"},"telefone":{"type":"string"},"observacao":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"CNPJ inválido"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}},"delete":{"tags":["Fornecedores"],"summary":"Remover a ficha do fornecedor","parameters":[{"name":"cnpj","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removido"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/apuracao-ibscbs":{"get":{"tags":["IBS/CBS"],"summary":"Apuração de IBS/CBS (débitos − créditos = a recolher)","description":"Débitos das notas emitidas de saída menos créditos das recebidas aceitas, no período. Valores negativos = saldo credor.","parameters":[{"name":"competencia","in":"query","schema":{"type":"string"},"example":"10/2026"},{"name":"de","in":"query","schema":{"type":"string"},"example":"2026-10-01"},{"name":"ate","in":"query","schema":{"type":"string"},"example":"2026-10-31"}],"responses":{"200":{"description":"Apuração IBS/CBS"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/impostos":{"get":{"tags":["Impostos"],"summary":"Resumo do Simples Nacional (DAS) da competência","parameters":[{"name":"competencia","in":"query","schema":{"type":"string"},"example":"06/2026"}],"responses":{"200":{"description":"Resumo de impostos"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}}},"/v1/produtos-servicos":{"get":{"tags":["Catálogo"],"summary":"Listar catálogo","parameters":[{"name":"ativo","in":"query","schema":{"type":"boolean"},"example":true}],"responses":{"200":{"description":"Itens do catálogo"},"401":{"$ref":"#/components/responses/NaoAutorizado"}}},"post":{"tags":["Catálogo"],"summary":"Criar item no catálogo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nome","codigo_servico"],"properties":{"nome":{"type":"string","example":"Consultoria de TI"},"codigo_servico":{"type":"string","example":"04294"},"descricao":{"type":"string"},"valor_padrao":{"type":"number","example":5000},"aliquota_iss":{"type":"number","example":0.05},"cnae_origem":{"type":"string","example":"6204-0/00"}}}}}},"responses":{"201":{"description":"Item criado","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/ItemCatalogo"}}}}}},"409":{"description":"Código já existe"}}}},"/v1/produtos-servicos/{id}":{"put":{"tags":["Catálogo"],"summary":"Atualizar item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemCatalogo"}}}},"responses":{"200":{"description":"Atualizado"},"404":{"description":"Não encontrado"}}},"delete":{"tags":["Catálogo"],"summary":"Excluir item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excluído"},"404":{"description":"Não encontrado"}}}},"/v1/tomadores":{"get":{"tags":["Tomadores"],"summary":"Listar tomadores","parameters":[{"name":"status","in":"query","description":"ativos (padrão), arquivados ou all","schema":{"type":"string","enum":["ativos","arquivados","all"],"default":"ativos"}}],"responses":{"200":{"description":"Lista de tomadores","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"tomadores":{"type":"array","items":{"$ref":"#/components/schemas/Tomador"}}}}}}},"401":{"$ref":"#/components/responses/NaoAutorizado"}}},"post":{"tags":["Tomadores"],"summary":"Criar tomador","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nome","cnpj"],"properties":{"nome":{"type":"string","example":"Empresa Tomadora Ltda"},"cnpj":{"type":"string","example":"12.345.678/0001-99"},"email":{"type":"string"},"municipio":{"type":"string","example":"São Paulo"},"uf":{"type":"string","example":"SP"}}}}}},"responses":{"201":{"description":"Tomador criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tomador"}}}}}}},"/v1/tomadores/{id}":{"put":{"tags":["Tomadores"],"summary":"Atualizar / arquivar tomador","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nome":{"type":"string"},"email":{"type":"string"},"municipio":{"type":"string"},"uf":{"type":"string"},"ativo":{"type":"boolean","description":"false = arquivar (churn); true = reativar"},"motivo_arquivamento":{"type":"string","description":"opcional, registrado ao arquivar"}}}}}},"responses":{"200":{"description":"Atualizado"},"404":{"description":"Não encontrado"}}},"delete":{"tags":["Tomadores"],"summary":"Excluir tomador","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Excluído"},"404":{"description":"Não encontrado"}}}}}}