{ "openapi": "3.0.3", "info": { "title": "Flow NFSe API", "version": "1.0.0", "description": "API REST do Flow NFSe: emissão e consulta de NFS-e, clientes, serviços e financeiro. Cada chave pertence a uma empresa." }, "servers": [ { "url": "https://flownfse.com.br/api/v1" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Chave gerada em Configurações > API" } } }, "security": [ { "bearer": [] } ], "paths": { "/empresa": { "get": { "tags": [ "Empresa" ], "summary": "Dados da empresa da chave", "description": "Confirma a autenticação e retorna a empresa a que a chave pertence e as permissões da chave.", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "id": 7, "cnpj": "33013831000157", "razao_social": "MINHA EMPRESA LTDA", "nome_fantasia": "Minha Empresa", "municipio_ibge": "3550308", "regime_tributario": "simples", "ambiente_emissao": "producao", "chave": { "nome": "ERP", "permissoes": [ "notas:ler", "notas:emitir" ] } } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/notas": { "get": { "tags": [ "Notas fiscais" ], "summary": "Listar notas", "description": "Lista as NFS-e da empresa, da mais recente para a mais antiga.\n\nPermissão: `notas:ler`", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "rascunho | enviando | autorizada | cancelada | erro", "schema": { "type": "string" } }, { "name": "data_inicio", "in": "query", "required": false, "description": "Data de emissão inicial (AAAA-MM-DD)", "schema": { "type": "string" } }, { "name": "data_fim", "in": "query", "required": false, "description": "Data de emissão final (AAAA-MM-DD)", "schema": { "type": "string" } }, { "name": "cliente_id", "in": "query", "required": false, "description": "Filtra por cliente", "schema": { "type": "string" } }, { "name": "referencia_externa", "in": "query", "required": false, "description": "Busca a nota pela referência enviada na emissão", "schema": { "type": "string" } }, { "name": "pagina", "in": "query", "required": false, "description": "Página (padrão 1)", "schema": { "type": "string" } }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (padrão 25, máximo 100)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "itens": [ { "id": 152, "numero_rps": "102", "serie": "1", "numero_nfse": "3263", "status": "autorizada", "data_emissao": "2026-11-09 10:30:28", "competencia": "2026-11-09", "valor_servico": 100.0, "valor_desconto": 0.0, "valor_iss": 0.0, "valor_iss_retido": 0.0, "valor_retencoes": 0.0, "valor_liquido": 100.0, "aliquota_iss": 0.0, "codigo_lc116": "1.05", "discriminacao": "Mensalidade do sistema - novembro/2026", "cliente": { "id": 18, "nome": "EMPRESA EXEMPLO LTDA", "documento": "12345678000199" }, "servico_id": 3, "chave": "3526113301383100015790308000000102...", "codigo_verificacao": "ABC123", "link_pdf": null, "motivo_erro": null, "motivo_cancelamento": null, "origem": "api", "referencia_externa": "pedido-9981", "criado_em": "2026-11-09 10:30:25", "atualizado_em": "2026-11-09 10:30:31" } ], "pagina": 1, "por_pagina": 25, "total": 1 } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } }, "post": { "tags": [ "Notas fiscais" ], "summary": "Emitir nota", "description": "Cria e transmite uma NFS-e usando um serviço já cadastrado (veja GET /servicos).\nO tomador pode ser informado por \"cliente_id\" ou pelo objeto \"cliente\": se o CPF/CNPJ ainda não existir, ele é cadastrado (o endereço é completado pelo CEP).\nUse \"referencia_externa\" (ou o cabeçalho Idempotency-Key) com o id do pedido no seu sistema: se a mesma referência for enviada de novo, a nota existente é devolvida e nada é emitido em duplicidade.\nCom \"transmitir\": false a nota fica como rascunho.\nSe \"valor\" não for informado, é usado o valor de venda cadastrado no serviço.\nA emissão é assíncrona na prefeitura: a resposta pode vir com status \"enviando\"; consulte depois com POST /notas/{id}/consultar ou GET /notas/{id}.\n\nPermissão: `notas:emitir`", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "nota": { "id": 152, "numero_rps": "102", "serie": "1", "numero_nfse": "3263", "status": "autorizada", "data_emissao": "2026-11-09 10:30:28", "competencia": "2026-11-09", "valor_servico": 100.0, "valor_desconto": 0.0, "valor_iss": 0.0, "valor_iss_retido": 0.0, "valor_retencoes": 0.0, "valor_liquido": 100.0, "aliquota_iss": 0.0, "codigo_lc116": "1.05", "discriminacao": "Mensalidade do sistema - novembro/2026", "cliente": { "id": 18, "nome": "EMPRESA EXEMPLO LTDA", "documento": "12345678000199" }, "servico_id": 3, "chave": "3526113301383100015790308000000102...", "codigo_verificacao": "ABC123", "link_pdf": null, "motivo_erro": null, "motivo_cancelamento": null, "origem": "api", "referencia_externa": "pedido-9981", "criado_em": "2026-11-09 10:30:25", "atualizado_em": "2026-11-09 10:30:31" }, "mensagem": "NFS-e autorizada pela prefeitura!" } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "cliente": { "documento": "12345678000199", "nome": "EMPRESA EXEMPLO LTDA", "email": "financeiro@exemplo.com.br", "telefone": "11999990000", "endereco": { "cep": "01310100", "numero": "1000", "complemento": "Sala 1" } }, "servico_id": 3, "valor": 100.0, "desconto": 0, "discriminacao": "Mensalidade do sistema - novembro/2026", "data_competencia": "2026-11-09", "iss_retido": false, "retencoes": { "pis": 0, "cofins": 0, "inss": 0, "ir": 0, "csll": 0 }, "referencia_externa": "pedido-9981", "transmitir": true } } } } } }, "/notas/{id}": { "get": { "tags": [ "Notas fiscais" ], "summary": "Consultar uma nota", "description": "Retorna os dados da nota, incluindo status, chave e motivo do erro (se houver).\n\nPermissão: `notas:ler`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "id": 152, "numero_rps": "102", "serie": "1", "numero_nfse": "3263", "status": "autorizada", "data_emissao": "2026-11-09 10:30:28", "competencia": "2026-11-09", "valor_servico": 100.0, "valor_desconto": 0.0, "valor_iss": 0.0, "valor_iss_retido": 0.0, "valor_retencoes": 0.0, "valor_liquido": 100.0, "aliquota_iss": 0.0, "codigo_lc116": "1.05", "discriminacao": "Mensalidade do sistema - novembro/2026", "cliente": { "id": 18, "nome": "EMPRESA EXEMPLO LTDA", "documento": "12345678000199" }, "servico_id": 3, "chave": "3526113301383100015790308000000102...", "codigo_verificacao": "ABC123", "link_pdf": null, "motivo_erro": null, "motivo_cancelamento": null, "origem": "api", "referencia_externa": "pedido-9981", "criado_em": "2026-11-09 10:30:25", "atualizado_em": "2026-11-09 10:30:31" } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/notas/{id}/consultar": { "post": { "tags": [ "Notas fiscais" ], "summary": "Atualizar status na prefeitura", "description": "Consulta a prefeitura e atualiza uma nota que está \"enviando\" (autorizada, rejeitada ou cancelada). O Flow também faz isso sozinho a cada 10 minutos.\n\nPermissão: `notas:ler`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "nota": { "id": 152, "numero_rps": "102", "serie": "1", "numero_nfse": "3263", "status": "autorizada", "data_emissao": "2026-11-09 10:30:28", "competencia": "2026-11-09", "valor_servico": 100.0, "valor_desconto": 0.0, "valor_iss": 0.0, "valor_iss_retido": 0.0, "valor_retencoes": 0.0, "valor_liquido": 100.0, "aliquota_iss": 0.0, "codigo_lc116": "1.05", "discriminacao": "Mensalidade do sistema - novembro/2026", "cliente": { "id": 18, "nome": "EMPRESA EXEMPLO LTDA", "documento": "12345678000199" }, "servico_id": 3, "chave": "3526113301383100015790308000000102...", "codigo_verificacao": "ABC123", "link_pdf": null, "motivo_erro": null, "motivo_cancelamento": null, "origem": "api", "referencia_externa": "pedido-9981", "criado_em": "2026-11-09 10:30:25", "atualizado_em": "2026-11-09 10:30:31" }, "mensagem": "NFS-e autorizada pela prefeitura!" } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/notas/{id}/transmitir": { "post": { "tags": [ "Notas fiscais" ], "summary": "Transmitir rascunho", "description": "Transmite uma nota em rascunho (ou que teve erro) para a prefeitura.\n\nPermissão: `notas:emitir`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "nota": { "id": 152, "numero_rps": "102", "serie": "1", "numero_nfse": "3263", "status": "autorizada", "data_emissao": "2026-11-09 10:30:28", "competencia": "2026-11-09", "valor_servico": 100.0, "valor_desconto": 0.0, "valor_iss": 0.0, "valor_iss_retido": 0.0, "valor_retencoes": 0.0, "valor_liquido": 100.0, "aliquota_iss": 0.0, "codigo_lc116": "1.05", "discriminacao": "Mensalidade do sistema - novembro/2026", "cliente": { "id": 18, "nome": "EMPRESA EXEMPLO LTDA", "documento": "12345678000199" }, "servico_id": 3, "chave": "3526113301383100015790308000000102...", "codigo_verificacao": "ABC123", "link_pdf": null, "motivo_erro": null, "motivo_cancelamento": null, "origem": "api", "referencia_externa": "pedido-9981", "criado_em": "2026-11-09 10:30:25", "atualizado_em": "2026-11-09 10:30:31" }, "mensagem": "NFS-e enviada!" } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/notas/{id}/cancelar": { "post": { "tags": [ "Notas fiscais" ], "summary": "Cancelar nota", "description": "Cancela uma nota autorizada. O motivo precisa ter pelo menos 10 caracteres.\n\nPermissão: `notas:cancelar`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "nota": { "id": 152, "numero_rps": "102", "serie": "1", "numero_nfse": "3263", "status": "cancelada", "data_emissao": "2026-11-09 10:30:28", "competencia": "2026-11-09", "valor_servico": 100.0, "valor_desconto": 0.0, "valor_iss": 0.0, "valor_iss_retido": 0.0, "valor_retencoes": 0.0, "valor_liquido": 100.0, "aliquota_iss": 0.0, "codigo_lc116": "1.05", "discriminacao": "Mensalidade do sistema - novembro/2026", "cliente": { "id": 18, "nome": "EMPRESA EXEMPLO LTDA", "documento": "12345678000199" }, "servico_id": 3, "chave": "3526113301383100015790308000000102...", "codigo_verificacao": "ABC123", "link_pdf": null, "motivo_erro": null, "motivo_cancelamento": null, "origem": "api", "referencia_externa": "pedido-9981", "criado_em": "2026-11-09 10:30:25", "atualizado_em": "2026-11-09 10:30:31" }, "mensagem": "NFS-e cancelada com sucesso" } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "motivo": "Nota emitida com valor incorreto" } } } } } }, "/notas/{id}/pdf": { "get": { "tags": [ "Notas fiscais" ], "summary": "Baixar PDF (DANFSe)", "description": "Retorna o arquivo PDF (Content-Type: application/pdf). Disponível para notas autorizadas ou canceladas.\n\nPermissão: `notas:ler`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Arquivo", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/notas/{id}/xml": { "get": { "tags": [ "Notas fiscais" ], "summary": "Baixar XML", "description": "Retorna o XML oficial da NFS-e (Content-Type: application/xml).\n\nPermissão: `notas:ler`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Arquivo", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/clientes": { "get": { "tags": [ "Cadastros" ], "summary": "Listar clientes", "description": "Lista os tomadores cadastrados na empresa.\n\nPermissão: `cadastros:ler`", "parameters": [ { "name": "busca", "in": "query", "required": false, "description": "Nome, CPF/CNPJ ou e-mail", "schema": { "type": "string" } }, { "name": "documento", "in": "query", "required": false, "description": "CPF/CNPJ exato (só dígitos)", "schema": { "type": "string" } }, { "name": "pagina", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "por_pagina", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "itens": [ { "id": 18, "tipo": "pj", "documento": "12345678000199", "nome": "EMPRESA EXEMPLO LTDA", "nome_fantasia": null, "email": "financeiro@exemplo.com.br", "telefone": "11999990000", "inscricao_municipal": null, "endereco": { "cep": "01310100", "logradouro": "Avenida Paulista", "numero": "1000", "complemento": "Sala 1", "bairro": "Bela Vista", "cidade": "São Paulo", "uf": "SP", "codigo_municipio_ibge": "3550308" }, "ativo": true } ], "pagina": 1, "por_pagina": 25, "total": 1 } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } }, "post": { "tags": [ "Cadastros" ], "summary": "Cadastrar cliente", "description": "Cadastra um tomador. Se o CPF/CNPJ já existir, devolve o cadastro existente (e completa campos vazios).\n\nPermissão: `cadastros:escrever`", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "criado": true, "cliente": { "id": 18, "documento": "12345678000199", "nome": "EMPRESA EXEMPLO LTDA" } } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "documento": "12345678000199", "nome": "EMPRESA EXEMPLO LTDA", "email": "financeiro@exemplo.com.br", "telefone": "11999990000", "inscricao_municipal": "", "endereco": { "cep": "01310100", "numero": "1000", "complemento": "Sala 1" } } } } } } }, "/clientes/{id}": { "get": { "tags": [ "Cadastros" ], "summary": "Consultar cliente", "description": "Retorna um cliente da empresa.\n\nPermissão: `cadastros:ler`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "id": 18, "documento": "12345678000199", "nome": "EMPRESA EXEMPLO LTDA" } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/servicos": { "get": { "tags": [ "Cadastros" ], "summary": "Listar serviços", "description": "Serviços cadastrados na empresa. Use o \"id\" no campo \"servico_id\" ao emitir.\n\nPermissão: `cadastros:ler`", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": [ { "id": 3, "codigo_interno": "SRV-001", "valor_unitario": 100.0, "codigo_lc116": "1.05", "codigo_tributacao_nacional": "010501", "codigo_tributacao_municipio": null, "descricao": "Licenciamento de software", "discriminacao_padrao": "Mensalidade do sistema", "aliquota_iss": 2.0, "cnae": "6203100", "nbs": "115029000", "ativo": true } ] } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/financeiro/titulos": { "get": { "tags": [ "Financeiro" ], "summary": "Listar títulos (contas a receber e a pagar)", "description": "Títulos financeiros da empresa, ordenados pelo vencimento.\n\nPermissão: `financeiro:ler`", "parameters": [ { "name": "tipo", "in": "query", "required": false, "description": "receber | pagar", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "pendente | parcial | pago | cancelado | vencido", "schema": { "type": "string" } }, { "name": "vencimento_de", "in": "query", "required": false, "description": "AAAA-MM-DD", "schema": { "type": "string" } }, { "name": "vencimento_ate", "in": "query", "required": false, "description": "AAAA-MM-DD", "schema": { "type": "string" } }, { "name": "nfs_e_id", "in": "query", "required": false, "description": "Títulos de uma nota", "schema": { "type": "string" } }, { "name": "pagina", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "por_pagina", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "itens": [ { "id": 40, "tipo": "receber", "status": "pendente", "descricao": "NFS-e #102", "categoria": "Venda de Serviço", "valor": 100.0, "valor_pago": 0.0, "saldo": 100.0, "data_emissao": "2026-11-09", "data_vencimento": "2026-12-09", "data_pagamento": null, "forma_pagamento": "A definir", "nfs_e_id": 152 } ], "pagina": 1, "por_pagina": 25, "total": 1 } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } }, "/financeiro/resumo": { "get": { "tags": [ "Financeiro" ], "summary": "Resumo do mês", "description": "Totais a receber/a pagar com vencimento no mês, valores vencidos e notas autorizadas no mês.\n\nPermissão: `financeiro:ler`", "parameters": [ { "name": "mes", "in": "query", "required": false, "description": "AAAA-MM (padrão: mês atual)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "sucesso": true, "dados": { "mes": "2026-11", "receber": { "total": 5400.0, "recebido": 3200.0 }, "pagar": { "total": 1200.0, "pago": 800.0 }, "vencido": 350.0, "notas_autorizadas": { "quantidade": 42, "valor": 5400.0 } } } } } }, "default": { "description": "Erro", "content": { "application/json": { "example": { "sucesso": false, "erro": { "codigo": "codigo_do_erro", "mensagem": "Descrição do erro" } } } } } } } } } }