API Flow NFSe

Autenticação

Gere uma chave em Configurações > API no painel do Flow NFSe. Cada chave pertence a uma empresa e só acessa os dados dela. A chave é exibida uma única vez: guarde-a em local seguro.

curl https://flownfse.com.br/api/v1/empresa \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Também é aceito o cabeçalho X-API-Key: flw_sua_chave_aqui. Use sempre HTTPS. A API está disponível nos planos que incluem o recurso API.

Respostas e erros

Todas as respostas são JSON. Sucesso:

{ "sucesso": true, "dados": { ... } }

Erro (com código HTTP correspondente):

{ "sucesso": false, "erro": { "codigo": "nota_rejeitada", "mensagem": "[5028] MENSAGEM DO GOVERNO: ..." } }

Permissões

Ao criar a chave, escolha o que ela pode fazer. Dê a cada sistema só o necessário.

Limites

• 120 requisições por minuto por chave (resposta 429 com cabeçalho Retry-After).
• Listagens: até 100 itens por página (por_pagina).
• As notas emitidas pela API contam no limite mensal do plano, como as emitidas pelo painel. Notas rejeitadas não contam.

Fluxo de emissão recomendado

1. Consulte GET /servicos e guarde o id do serviço que você vende.
2. Emita com POST /notas enviando o tomador, o valor e a referencia_externa (id do pedido no seu sistema).
3. Se a resposta vier com status: "enviando", a prefeitura ainda está processando: consulte com GET /notas/{id} alguns minutos depois (o Flow atualiza sozinho a cada 10 minutos) ou receba o aviso por webhook.
4. Com status: "autorizada", baixe o PDF em GET /notas/{id}/pdf.

Webhooks (avisos do Flow para o seu sistema)

Em vez de consultar a nota de tempos em tempos, cadastre um endereço em Configurações > API > Webhooks. O Flow faz um POST nele quando uma nota da empresa muda de situação, inclusive as emitidas pelo painel, pela recorrência e pelas integrações.

Corpo

O campo nota tem o mesmo formato de GET /notas/{id}.

{
    "id": "evt_123",
    "evento": "nota.autorizada",
    "criado_em": "2026-11-10T10:30:31-03:00",
    "empresa": {
        "id": 7,
        "cnpj": "33013831000157",
        "razao_social": "MINHA EMPRESA LTDA"
    },
    "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"
    }
}

Cabeçalhos

Conferindo a assinatura (PHP)

$corpo = file_get_contents('php://input');
$esperada = 'sha256=' . hash_hmac('sha256', $_SERVER['HTTP_X_FLOW_TIMESTAMP'] . '.' . $corpo, 'whsec_seu_segredo');
if (!hash_equals($esperada, $_SERVER['HTTP_X_FLOW_ASSINATURA'] ?? '')) {
    http_response_code(401);
    exit;
}
$aviso = json_decode($corpo, true);
// ... atualize o pedido $aviso['nota']['referencia_externa'] ...
http_response_code(200);

Entrega e novas tentativas

• Responda com HTTP 2xx em até 10 segundos. Processe o que for demorado depois de responder.
• Sem 2xx, o Flow tenta de novo em 5 min, 15 min, 1 h, 3 h e 12 h (6 tentativas). Dá para reenviar pelo painel.
• Cada evento é avisado uma vez por nota, mas a mesma entrega pode chegar repetida numa nova tentativa: use X-Flow-Entrega.
• Somente endereços https:// públicos. Redirecionamentos não são seguidos.

GET/empresa

Dados da empresa da chave

Confirma a autenticação e retorna a empresa a que a chave pertence e as permissões da chave.

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/empresa" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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"
            ]
        }
    }
}

GET/notas notas:ler

Listar notas

Lista as NFS-e da empresa, da mais recente para a mais antiga.

Parâmetros (query string)

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/notas" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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
    }
}

POST/notas notas:emitir

Emitir nota

Cria e transmite uma NFS-e usando um serviço já cadastrado (veja GET /servicos). O 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). Use "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. Com "transmitir": false a nota fica como rascunho. Se "valor" não for informado, é usado o valor de venda cadastrado no serviço. A emissão é assíncrona na prefeitura: a resposta pode vir com status "enviando"; consulte depois com POST /notas/{id}/consultar ou GET /notas/{id}.

Exemplo

curl -X POST "https://flownfse.com.br/api/v1/notas" \
  -H "Authorization: Bearer flw_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"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}'

Corpo (JSON)

{
    "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
}

Códigos de retorno: 201 (criada) · 200 (já existia para a referência) · 422 (dados inválidos ou nota rejeitada) · 402 (limite do plano)

Resposta

{
    "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!"
    }
}

GET/notas/{id} notas:ler

Consultar uma nota

Retorna os dados da nota, incluindo status, chave e motivo do erro (se houver).

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/notas/152" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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"
    }
}

POST/notas/{id}/consultar notas:ler

Atualizar status na prefeitura

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.

Exemplo

curl -X POST "https://flownfse.com.br/api/v1/notas/152/consultar" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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!"
    }
}

POST/notas/{id}/transmitir notas:emitir

Transmitir rascunho

Transmite uma nota em rascunho (ou que teve erro) para a prefeitura.

Exemplo

curl -X POST "https://flownfse.com.br/api/v1/notas/152/transmitir" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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!"
    }
}

POST/notas/{id}/cancelar notas:cancelar

Cancelar nota

Cancela uma nota autorizada. O motivo precisa ter pelo menos 10 caracteres.

Exemplo

curl -X POST "https://flownfse.com.br/api/v1/notas/152/cancelar" \
  -H "Authorization: Bearer flw_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"motivo":"Nota emitida com valor incorreto"}'

Corpo (JSON)

{
    "motivo": "Nota emitida com valor incorreto"
}

Resposta

{
    "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"
    }
}

GET/notas/{id}/pdf notas:ler

Baixar PDF (DANFSe)

Retorna o arquivo PDF (Content-Type: application/pdf). Disponível para notas autorizadas ou canceladas.

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/notas/152/pdf" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

Arquivo application/pdf.

GET/notas/{id}/xml notas:ler

Baixar XML

Retorna o XML oficial da NFS-e (Content-Type: application/xml).

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/notas/152/xml" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

Arquivo application/xml.

GET/clientes cadastros:ler

Listar clientes

Lista os tomadores cadastrados na empresa.

Parâmetros (query string)

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/clientes" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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
    }
}

GET/clientes/{id} cadastros:ler

Consultar cliente

Retorna um cliente da empresa.

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/clientes/152" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "sucesso": true,
    "dados": {
        "id": 18,
        "documento": "12345678000199",
        "nome": "EMPRESA EXEMPLO LTDA"
    }
}

POST/clientes cadastros:escrever

Cadastrar cliente

Cadastra um tomador. Se o CPF/CNPJ já existir, devolve o cadastro existente (e completa campos vazios).

Exemplo

curl -X POST "https://flownfse.com.br/api/v1/clientes" \
  -H "Authorization: Bearer flw_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"documento":"12345678000199","nome":"EMPRESA EXEMPLO LTDA","email":"financeiro@exemplo.com.br","telefone":"11999990000","inscricao_municipal":"","endereco":{"cep":"01310100","numero":"1000","complemento":"Sala 1"}}'

Corpo (JSON)

{
    "documento": "12345678000199",
    "nome": "EMPRESA EXEMPLO LTDA",
    "email": "financeiro@exemplo.com.br",
    "telefone": "11999990000",
    "inscricao_municipal": "",
    "endereco": {
        "cep": "01310100",
        "numero": "1000",
        "complemento": "Sala 1"
    }
}

Códigos de retorno: 201 (cadastrado) · 200 (já existia)

Resposta

{
    "sucesso": true,
    "dados": {
        "criado": true,
        "cliente": {
            "id": 18,
            "documento": "12345678000199",
            "nome": "EMPRESA EXEMPLO LTDA"
        }
    }
}

GET/servicos cadastros:ler

Listar serviços

Serviços cadastrados na empresa. Use o "id" no campo "servico_id" ao emitir.

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/servicos" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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
        }
    ]
}

GET/financeiro/titulos financeiro:ler

Listar títulos (contas a receber e a pagar)

Títulos financeiros da empresa, ordenados pelo vencimento.

Parâmetros (query string)

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/financeiro/titulos" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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
    }
}

GET/financeiro/resumo financeiro:ler

Resumo do mês

Totais a receber/a pagar com vencimento no mês, valores vencidos e notas autorizadas no mês.

Parâmetros (query string)

Exemplo

curl -X GET "https://flownfse.com.br/api/v1/financeiro/resumo" \
  -H "Authorization: Bearer flw_sua_chave_aqui"

Resposta

{
    "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
        }
    }
}