{"openapi":"3.1.0","info":{"title":"API do Fiscalo","version":"1.0.0","description":"Emissão de NFS-e no padrão nacional. Enquanto o Fiscalo emite só em produção restrita (homologação), as chaves são de teste (fsk_test_) e as notas não têm validade jurídica. Avisos de nota autorizada, rejeitada, cancelada e substituída chegam por webhook assinado (cabeçalho Fiscalo-Assinatura: t=…,v1=HMAC-SHA256 de \"t.corpo\").","contact":{"name":"Fiscalo","email":"contato@fiscalo.com.br","url":"https://fiscalo.com.br/desenvolvedores"}},"servers":[{"url":"https://api.fiscalo.com.br","description":"Produção restrita (sandbox)"}],"security":[{"chave":[]}],"components":{"securitySchemes":{"chave":{"type":"http","scheme":"bearer","description":"Authorization: Bearer fsk_test_… (crie em Configurações > API e webhooks)"}},"schemas":{"Nota":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["RASCUNHO","ENVIANDO","PENDENTE_CONFIRMACAO","AUTORIZADA","REJEITADA","CANCELADA","SUBSTITUIDA"]},"numero_nfse":{"type":["string","null"]},"chave_acesso":{"type":["string","null"],"description":"50 posições"},"competencia":{"type":"string","format":"date","examples":["2026-11-05"]},"valor":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$","examples":["1500.00"],"description":"Valor em reais, com ponto decimal"},"erros":{"type":["array","null"],"items":{"type":"object","properties":{"codigo":{"type":"string"},"descricao":{"type":"string"}}}},"calculo":{"type":"object","description":"Cálculo congelado: Simples, ISS, retenções, IBS/CBS e explicação de cada número"}}},"Erro":{"type":"object","properties":{"erro":{"type":"string"},"detalhes":{"type":"array","items":{"type":"object","properties":{"campo":{"type":"string"},"mensagem":{"type":"string"}}}}},"required":["erro"]}}},"paths":{"/v1/empresas":{"get":{"summary":"Empresas da conta","responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cnpj":{"type":"string"},"razao_social":{"type":"string"},"regime":{"type":"string","enum":["MEI","SIMPLES","LUCRO_PRESUMIDO","LUCRO_REAL"]}}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"listarEmpresas"}},"/v1/empresas/{id}/servicos":{"get":{"summary":"Serviços do catálogo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string"},"ctribnac":{"type":"string","description":"Código de tributação nacional (6 dígitos)"},"nbs":{"type":["string","null"]},"descricao":{"type":"string"}}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"listarServicos"}},"/v1/empresas/{id}/tomadores":{"get":{"summary":"Clientes (tomadores)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"documento":{"type":"string"},"nome":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}}}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"listarTomadores"},"post":{"summary":"Cadastrar cliente","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nome"],"properties":{"documento":{"type":"string","description":"CNPJ (inclusive alfanumérico) ou CPF"},"nome":{"type":"string","minLength":2},"emails":{"type":"array","items":{"type":"string","format":"email"},"maxItems":10},"endereco":{"type":"object","description":"Obrigatório para notas com IBS/CBS (a partir de 2027)","properties":{"cep":{"type":"string"},"logradouro":{"type":"string"},"numero":{"type":"string"},"complemento":{"type":"string"},"bairro":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"criarTomador"}},"/v1/empresas/{id}/calcular":{"post":{"summary":"Calcular o imposto sem criar nota","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["competencia","valor"],"properties":{"competencia":{"type":"string","format":"date","examples":["2026-11-05"]},"servicoId":{"type":"string","format":"uuid"},"cTribNac":{"type":"string"},"valor":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$","examples":["1500.00"],"description":"Valor em reais, com ponto decimal"},"issRetido":{"type":"boolean"},"tomadorPJ":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"historico":{"type":"object"},"resultado":{"type":"object"}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"calcular"}},"/v1/empresas/{id}/notas":{"get":{"summary":"Listar notas","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Situações separadas por vírgula"},{"name":"de","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}},{"name":"ate","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/Nota"}},"total":{"type":"integer"}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"listarNotas"},"post":{"summary":"Criar rascunho (cálculo congelado)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["competencia","servicoId","tomadorId","valor"],"properties":{"competencia":{"type":"string","format":"date","examples":["2026-11-05"]},"servicoId":{"type":"string","format":"uuid"},"tomadorId":{"type":"string","format":"uuid"},"valor":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$","examples":["1500.00"],"description":"Valor em reais, com ponto decimal"},"issRetido":{"type":"boolean"},"descricao":{"type":"string","minLength":3,"maxLength":2000},"emails":{"type":"array","items":{"type":"string","format":"email"},"maxItems":10,"description":"Destinatários desta nota (padrão: os do cadastro do cliente)"}}}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"RASCUNHO"},"calculo":{"type":"object"}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"criarRascunho"}},"/v1/empresas/{id}/notas/{nota}":{"get":{"summary":"Nota: situação, número, chave e cálculo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"},{"name":"nota","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Nota"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nota"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"obterNota"},"patch":{"summary":"Ajustar valor ou descrição de rascunho ou rejeitada (recalcula)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"},{"name":"nota","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Nota"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"valor":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$","examples":["1500.00"],"description":"Valor em reais, com ponto decimal"},"descricao":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"valor":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$","examples":["1500.00"],"description":"Valor em reais, com ponto decimal"}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"ajustarRascunho"}},"/v1/empresas/{id}/notas/{nota}/emitir":{"post":{"summary":"Assinar e enviar a DPS à Sefin Nacional","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"},{"name":"nota","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Nota"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"numero":{"type":["string","null"]},"chaveAcesso":{"type":["string","null"]},"erros":{"type":["array","null"]}}}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"emitirNota"}},"/v1/empresas/{id}/notas/{nota}/pdf":{"get":{"summary":"DANFSe em PDF","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"},{"name":"nota","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Nota"}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{}}}},"operationId":"baixarPdf"}},"/v1/empresas/{id}/notas/{nota}/xml":{"get":{"summary":"XML oficial da NFS-e","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"},{"name":"nota","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Nota"}],"responses":{"200":{"description":"XML","content":{"application/xml":{}}}},"operationId":"baixarXml"}},"/v1/empresas/{id}/notas/{nota}/cancelar":{"post":{"summary":"Cancelar (evento 101101)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"},{"name":"nota","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Nota"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["motivo","justificativa"],"properties":{"motivo":{"type":"integer","enum":[1,2,9],"description":"1 erro na emissão, 2 serviço não prestado, 9 outros"},"justificativa":{"type":"string","minLength":15,"maxLength":255}}}}}},"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"cancelarNota"}},"/v1/empresas/{id}/notas/{nota}/substituir":{"post":{"summary":"Substituir por uma nota corrigida","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Empresa"},{"name":"nota","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Nota"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["motivo"],"properties":{"motivo":{"type":"string","enum":["01","02","03","04","05","99"]},"justificativa":{"type":"string","minLength":15,"maxLength":255},"valor":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$","examples":["1500.00"],"description":"Valor em reais, com ponto decimal"},"descricao":{"type":"string"}}}}}},"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Dados inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não encontrado (ou de outra conta)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de 300 chamadas por minuto por chave","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"operationId":"substituirNota"}}},"webhooks":{"nota":{"post":{"summary":"Aviso de nota (nota.autorizada, nota.rejeitada, nota.cancelada, nota.substituida)","parameters":[{"name":"Fiscalo-Evento","in":"header","schema":{"type":"string"}},{"name":"Fiscalo-Assinatura","in":"header","schema":{"type":"string","examples":["t=1793900000,v1=…"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"evt_… (use para ignorar repetições)"},"tipo":{"type":"string","enum":["nota.autorizada","nota.rejeitada","nota.cancelada","nota.substituida"]},"criado_em":{"type":"string","format":"date-time"},"tentativa":{"type":"integer"},"dados":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"empresa_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"numero":{"type":["string","null"]},"chave_acesso":{"type":["string","null"]},"competencia":{"type":"string","format":"date","examples":["2026-11-05"]},"valor":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$","examples":["1500.00"],"description":"Valor em reais, com ponto decimal"},"ambiente":{"type":"integer","description":"1 produção, 2 produção restrita"},"erros":{"type":["array","null"]},"substituida_por":{"type":["string","null"]}}}}}}}},"responses":{"200":{"description":"Responda 2xx em até 10 s; senão, tentamos de novo (7 vezes, com espera crescente)"}},"operationId":"avisoDeNota"}}}}