{"openapi":"3.0.3","info":{"title":"FLUXO NFE API v1","version":"1.1.0","summary":"API pública FLUXO NFE — contrato v1 congelado","description":"API para integrações (ERP, loja, app).\n\n**Estabilidade:** `frozen` desde 2026-08-06.\nMudanças breaking só em futura `/api/v2`. Campos novos são sempre aditivos.\n\nAuth: `X-Api-Key: fnfe_…` ou `Authorization: Bearer …` (API Key, OAuth ou token de integração).\n\nDocs: /docs-api.html · Changelog: /api-changelog.html","contact":{"name":"FLUXO NFE","url":"https://fluxonfe.com.br"}},"servers":[{"url":"/api/v1","description":"Relativo ao host atual"},{"url":"https://saas.fluxonfe.com.br/api/v1","description":"Produção SaaS"}],"tags":[{"name":"Meta","description":"Health, escopos, OpenAPI, changelog"},{"name":"Auth","description":"OAuth2 e identidade"},{"name":"Notas","description":"NF-e e NFS-e"},{"name":"Cadastros","description":"Clientes e produtos"},{"name":"Cobrancas","description":"Cobranças avulsas"},{"name":"Contratos","description":"Cobranças recorrentes"},{"name":"Webhooks","description":"Eventos outbound"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Chave fnfe_… criada no painel do tenant"},"IntegrationBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer fnfe_…, OAuth access_token ou token de integração"}},"schemas":{"ApiError":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"ApiSuccess":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{},"meta":{"type":"object","additionalProperties":true}}},"ScopeItem":{"type":"object","properties":{"id":{"type":"string","enum":["notas:emitir","notas:ler","notas:cancelar","cadastros:ler","cadastros:escrever","cobrancas:ler","cobrancas:criar","cobrancas:gerenciar","contratos:ler","contratos:escrever","contratos:gerar"]},"group":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}}}},"security":[{"ApiKeyAuth":[]},{"IntegrationBearer":[]}],"paths":{"/health":{"get":{"tags":["Meta"],"security":[],"summary":"Health da API v1","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}},"/scopes":{"get":{"tags":["Meta"],"security":[],"summary":"Catálogo de escopos","description":"Lista pública usada pela UI de API Keys.","responses":{"200":{"description":"Catálogo","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ScopeItem"}}}},"example":{"success":true,"data":[{"id":"notas:emitir","group":"Notas fiscais (NF-e / NFS-e)","label":"Emitir NF-e e NFS-e","description":"POST /api/v1/notas com tipo NFE ou NFSE"},{"id":"notas:ler","group":"Notas fiscais (NF-e / NFS-e)","label":"Consultar notas, XML e PDF","description":"GET /api/v1/notas, /xml, /pdf, /status"},{"id":"notas:cancelar","group":"Notas fiscais (NF-e / NFS-e)","label":"Cancelar notas","description":"POST /api/v1/notas/:id/cancelar"},{"id":"cadastros:ler","group":"Cadastros","label":"Ler clientes e produtos","description":"GET /api/v1/clientes e /api/v1/produtos"},{"id":"cadastros:escrever","group":"Cadastros","label":"Criar/atualizar clientes","description":"POST /api/v1/clientes"},{"id":"cobrancas:ler","group":"Cobranças avulsas","label":"Listar e consultar cobranças","description":"GET /api/v1/cobrancas"},{"id":"cobrancas:criar","group":"Cobranças avulsas","label":"Criar e enviar cobranças","description":"POST /api/v1/cobrancas e /:id/enviar"},{"id":"cobrancas:gerenciar","group":"Cobranças avulsas","label":"Marcar paga / cancelar","description":"POST /api/v1/cobrancas/:id/marcar-paga e /cancelar"},{"id":"contratos:ler","group":"Cobranças recorrentes (contratos)","label":"Listar contratos","description":"GET /api/v1/contratos"},{"id":"contratos:escrever","group":"Cobranças recorrentes (contratos)","label":"Criar / atualizar / desativar contratos","description":"POST/PUT/DELETE /api/v1/contratos"},{"id":"contratos:gerar","group":"Cobranças recorrentes (contratos)","label":"Gerar cobrança do contrato","description":"POST /api/v1/contratos/:id/gerar"}]}}}}}}},"/openapi.json":{"get":{"tags":["Meta"],"security":[],"summary":"Especificação OpenAPI 3","responses":{"200":{"description":"OpenAPI JSON"}}}},"/changelog":{"get":{"tags":["Meta"],"security":[],"summary":"Changelog e política de estabilidade","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}},"/oauth/token":{"post":{"tags":["Auth"],"security":[],"summary":"OAuth2 client_credentials","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string"},"client_secret":{"type":"string"}}}}}},"responses":{"200":{"description":"access_token"},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/me":{"get":{"tags":["Auth"],"summary":"Identidade da integração autenticada","x-scopes":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/notas":{"post":{"tags":["Notas"],"summary":"Emitir NF-e ou NFS-e","description":"Escopo necessário: `notas:emitir`","x-scopes":["notas:emitir"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","enum":["NFE","NFSE"],"default":"NFE"},"valor_total":{"type":"number"},"cnpj_tomador":{"type":"string"},"razao_social_tomador":{"type":"string"},"itens":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Notas"],"summary":"Listar notas","description":"Escopo necessário: `notas:ler`","x-scopes":["notas:ler"],"parameters":[{"name":"pagina","in":"query","schema":{"type":"integer"}},{"name":"limite","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"tipo","in":"query","schema":{"type":"string","enum":["NFE","NFSE"]}},{"name":"de","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"ate","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/notas/{id}":{"get":{"tags":["Notas"],"summary":"Consultar nota","description":"Escopo necessário: `notas:ler`","x-scopes":["notas:ler"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/notas/{id}/xml":{"get":{"tags":["Notas"],"summary":"Download XML","description":"Escopo necessário: `notas:ler`","x-scopes":["notas:ler"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"XML"},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/notas/{id}/pdf":{"get":{"tags":["Notas"],"summary":"Download DANFE/PDF","description":"Escopo necessário: `notas:ler`","x-scopes":["notas:ler"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"PDF"},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/notas/{id}/status":{"get":{"tags":["Notas"],"summary":"Status da nota","description":"Escopo necessário: `notas:ler`","x-scopes":["notas:ler"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/notas/{id}/cancelar":{"post":{"tags":["Notas"],"summary":"Cancelar nota","description":"Escopo necessário: `notas:cancelar`","x-scopes":["notas:cancelar"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["motivo"],"properties":{"motivo":{"type":"string","minLength":15}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/clientes":{"get":{"tags":["Cadastros"],"summary":"Listar clientes","description":"Escopo necessário: `cadastros:ler`","x-scopes":["cadastros:ler"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}},"post":{"tags":["Cadastros"],"summary":"Criar/atualizar cliente","description":"Escopo necessário: `cadastros:escrever`","x-scopes":["cadastros:escrever"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/clientes/busca/{documento}":{"get":{"tags":["Cadastros"],"summary":"Buscar cliente por CPF/CNPJ","description":"Escopo necessário: `cadastros:ler`","x-scopes":["cadastros:ler"],"parameters":[{"name":"documento","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/produtos":{"get":{"tags":["Cadastros"],"summary":"Listar produtos fiscais","description":"Escopo necessário: `cadastros:ler`","x-scopes":["cadastros:ler"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}},"/produtos/{id}":{"get":{"tags":["Cadastros"],"summary":"Consultar produto","description":"Escopo necessário: `cadastros:ler`","x-scopes":["cadastros:ler"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/cobrancas":{"get":{"tags":["Cobrancas"],"summary":"Listar cobranças avulsas","description":"Escopo necessário: `cobrancas:ler`","x-scopes":["cobrancas:ler"],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"cliente_id","in":"query","schema":{"type":"integer"}},{"name":"pagina","in":"query","schema":{"type":"integer"}},{"name":"limite","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}},"post":{"tags":["Cobrancas"],"summary":"Criar cobrança avulsa","description":"Escopo necessário: `cobrancas:criar`","x-scopes":["cobrancas:criar"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cliente_id","valor","meio"],"properties":{"cliente_id":{"type":"integer"},"descricao":{"type":"string"},"valor":{"type":"number"},"meio":{"type":"string","enum":["pix","boleto","cartao"]},"vencimento_em":{"type":"string","format":"date"},"enviar_gateway":{"type":"boolean","default":true},"enviar_whatsapp":{"type":"boolean","description":"Manda a cobrança ao WhatsApp do cliente assim que o link do gateway retorna. Se omitido, usa o padrão configurado pela empresa."},"emitir_nf":{"type":"boolean"},"tipo_nf":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/cobrancas/{id}":{"get":{"tags":["Cobrancas"],"summary":"Consultar cobrança","description":"Escopo necessário: `cobrancas:ler`","x-scopes":["cobrancas:ler"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/cobrancas/{id}/eventos":{"get":{"tags":["Cobrancas"],"summary":"Eventos da cobrança","description":"Escopo necessário: `cobrancas:ler`","x-scopes":["cobrancas:ler"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/cobrancas/{id}/enviar":{"post":{"tags":["Cobrancas"],"summary":"Enviar cobrança ao gateway","description":"Escopo necessário: `cobrancas:criar`","x-scopes":["cobrancas:criar"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/cobrancas/{id}/marcar-paga":{"post":{"tags":["Cobrancas"],"summary":"Marcar cobrança como paga","description":"Escopo necessário: `cobrancas:gerenciar`","x-scopes":["cobrancas:gerenciar"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/cobrancas/{id}/cancelar":{"post":{"tags":["Cobrancas"],"summary":"Cancelar cobrança","description":"Escopo necessário: `cobrancas:gerenciar`","x-scopes":["cobrancas:gerenciar"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/contratos":{"get":{"tags":["Contratos"],"summary":"Listar contratos","description":"Escopo necessário: `contratos:ler`","x-scopes":["contratos:ler"],"parameters":[{"name":"ativo","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}},"post":{"tags":["Contratos"],"summary":"Criar contrato recorrente","description":"Escopo necessário: `contratos:escrever`","x-scopes":["contratos:escrever"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cliente_id","valor","dia_vencimento"],"properties":{"cliente_id":{"type":"integer"},"descricao":{"type":"string"},"valor":{"type":"number"},"meio":{"type":"string","enum":["pix","boleto","cartao"]},"dia_vencimento":{"type":"integer","minimum":1,"maximum":31},"antecipacao_dias":{"type":"integer"},"alerta_intervalo_horas":{"type":"integer"},"alerta_max":{"type":"integer"},"emitir_nf":{"type":"boolean"},"tipo_nf":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/contratos/{id}":{"get":{"tags":["Contratos"],"summary":"Consultar contrato","description":"Escopo necessário: `contratos:ler`","x-scopes":["contratos:ler"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"put":{"tags":["Contratos"],"summary":"Atualizar contrato","description":"Escopo necessário: `contratos:escrever`","x-scopes":["contratos:escrever"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"tags":["Contratos"],"summary":"Desativar contrato","description":"Escopo necessário: `contratos:escrever`","x-scopes":["contratos:escrever"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/contratos/{id}/gerar":{"post":{"tags":["Contratos"],"summary":"Gerar cobrança do contrato","description":"Escopo necessário: `contratos:gerar`","x-scopes":["contratos:gerar"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"competencia":{"type":"string","example":"2026-08","description":"YYYY-MM"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/webhooks/events":{"get":{"tags":["Webhooks"],"summary":"Eventos de webhook suportados","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}}},"x-fluxo-stability":{"version":"v1","openapi_version":"1.1.0","stability":"frozen","frozen_since":"2026-08-06","policy":["Rotas, métodos HTTP, escopos e formato de erro/sucesso já publicados em /api/v1 não sofrem mudanças breaking.","Campos novos em respostas são sempre opcionais (aditivos).","Remoção, renomeação ou mudança de significado de campo/rota exige uma futura /api/v2.","Escopos novos podem ser adicionados; escopos existentes mantêm o mesmo significado."],"docs":{"human":"/docs-api.html","changelog":"/api-changelog.html","openapi":"/api/v1/openapi.json","changelog_json":"/api/v1/changelog"}}}