Da conta à integração
-
Crie ou acesse sua conta
Quem ainda não tem conta pode cadastrar-se no Flow Fiscal. Conclua o onboarding e a configuração da empresa e escolha o plano Flow Fiscal adequado; o plano base é uma contratação separada do adicional.
-
Abra API de emissão
No menu Fiscal, escolha API de emissão ou abra o painel. Para uma conta existente, esse endereço preserva o destino após o login. Conta nova conclui primeiro seu cadastro e então acessa o painel pelo menu.
-
Teste e contratação
No teste grátis do Flow Fiscal, a API de emissão funciona completa sem contratar: homologação sem limite e até 300 autorizações em produção, sem cobrança. Para continuar depois do teste, confira os termos e o preço no painel e conclua a contratação. O retorno do navegador não ativa direitos sozinho: a confirmação do pagamento pelo provedor libera o opcional. A API de documentos recebidos permanece em contratação independente.
-
Autorize os CNPJs
Um contratante pode vincular múltiplos emitentes. Para um cadastro existente, solicite o consentimento do titular; para um emitente técnico novo, siga o cadastro fiscal e a autorização previstos no painel. Não é necessário criar um plano ERP completo para cada CNPJ técnico.
-
Configure e teste
Cadastre certificado A1, inscrições e séries, crie a integração, conceda vínculos e gere uma credencial com validade e escopos mínimos no ambiente de homologação. Só use produção depois de concluir os testes e conferir o credenciamento e as regras da operação.
OpenAPI, Postman e endereço base
- Baixar OpenAPI 3.1.1: rotas, schemas separados por modelo, exemplos, campos e erros.
- Baixar coleção Postman: importe a coleção e preencha ambiente, emitente e credencial de teste. Não publique esses valores.
- Base:
https://erp.fideflow.com.br/api/flow-fiscal/v1/{ambiente}/emitentes/{emitente}. O ambiente éhomologacaoouproducaoe deve coincidir com a credencial e o emitente. - Cada modelo possui seu POST:
/documentos/nfe,/documentos/nfce,/documentos/nfse,/documentos/cte,/documentos/cte-ose/documentos/mdfe. Não envie o payload de um modelo a outro.
Use Authorization: Bearer SUA_CREDENCIAL e Content-Type: application/json. Uma sessão de navegador não substitui a credencial da integração. Antes da primeira emissão, consulte GET /capacidades no contexto do emitente. O retorno informa as ações concedidas e as restrições do conector; ele não substitui a validação fiscal de cada envio.
Os exemplos das páginas de documento são extraídos do mesmo OpenAPI servido pela API. IDs de clientes, produtos, veículos e cidades são fictícios e precisam corresponder aos cadastros autorizados, ou ser informados pelos grupos inline permitidos no schema. Valores decimais seguem strings com ponto, sem separador de milhares.
Aceite, consulta e idempotência
Envie uma referencia_externa única para o documento e uma Idempotency-Key estável no comando. Repetir a mesma solicitação idempotente não cria outra emissão nem outra unidade de consumo. Reutilizar a chave com conteúdo diferente gera conflito; preserve a referência e consulte a operação para decidir o próximo passo.
HTTP 202 significa aceite durável para processamento, ainda sem autorização fiscal. Acompanhe o endereço retornado em Location, consulte os identificadores da resposta ou receba o webhook. Autorização, rejeição e resultado incerto são situações distintas. A falta de resposta de rede não prova rejeição e não autoriza criar uma nova referência para repetir a nota.
| Resposta | Tratamento |
|---|---|
| 401 / 403 | Revisar credencial, validade, ambiente, escopos, vínculo e licença. |
| 409 | Conferir idempotência, revisão ou operação em andamento antes de repetir. |
| 422 | Corrigir os campos apontados ou a capacidade solicitada. |
| 429 | Respeitar o intervalo de repetição indicado pela API. |
| Timeout ou falha após envio | Consultar a referência/operação existente e aguardar a conciliação. |
Documentos, eventos e arquivos privados
Consulte os metadados do documento e baixe XML ou PDF com as permissões apropriadas. O acervo mantém os artefatos fiscais e sua integridade, incluindo eventos e DPS quando aplicáveis. Um PDF ainda indisponível não exige retransmitir uma nota autorizada. O protocolo oficial continua sendo a evidência do resultado fiscal.
NF-e admite cancelamento, CC-e e inutilização; NFC-e, cancelamento e inutilização; CT-e e CT-e OS, cancelamento e CC-e; MDF-e, cancelamento e encerramento; NFS-e Nacional, cancelamento. As condições legais e a situação do documento são revalidadas. Substituição de NFS-e e cancelamento por substituição de NFC-e não estão habilitados nesta API.
CT-e, CT-e OS e MDF-e atendem o modal rodoviário. A contingência off-line de NFC-e está restrita a SP, com escopo, aceite e regularização posterior; outras contingências não estão habilitadas. A emissão nacional de NFS-e depende da matriz fiscal e da liberação do conector; leiautes e funcionalidades com gate próprio não são liberados pela contratação do adicional.
Recebimento seguro dos webhooks
Cadastre um destino HTTPS público com o escopo webhooks.gerir e guarde o segredo fornecido de forma privada. Configure a verificação da assinatura HMAC sobre os bytes do corpo, conforme o OpenAPI e o exemplo do painel. Não aceite um aviso somente porque ele contém um identificador conhecido.
O evento possui identificador estável e pode ser entregue novamente. Grave esse identificador para não executar o mesmo efeito duas vezes. Consulte as entregas para identificar falhas e use a reentrega prevista no contrato quando necessário. O webhook informa a mudança; consultas e downloads continuam sujeitos às credenciais e aos vínculos de cada emitente.
Cobrança mensal e dados do ERP
O adicional de R$ 29,90 por mês inclui 300 documentos autorizados em produção no ciclo mensal do contratante, compartilhados entre os seus CNPJs. Autorizações excedentes custam R$ 0,50 cada e são cobradas automaticamente. Rejeições, homologação, consultas, downloads, eventos e reentregas não geram unidades; cancelamento posterior não estorna a autorização. Consulte o consumo no painel.
A emissão registra o fiscal sem movimentar financeiro e estoque nem enviar comunicações comerciais automaticamente. O uso de dados e cadastros do ERP não autoriza novos efeitos comerciais: integrações adicionais exigem ação explícita. A API de recebidos continua no opcional atual e sua contratação não é requisito para obter XML e PDF das próprias emissões.
Perguntas frequentes
Preciso de um plano para cada CNPJ?
O contratante possui o plano Flow Fiscal e o adicional. Múltiplos CNPJs técnicos podem ser vinculados sob essa contratação, com autorização e isolamento próprios; não recebem acesso ERP completo.
A documentação pública concede acesso à API?
Não. OpenAPI, Postman e guias são públicos; as operações exigem credencial válida, ambiente, vínculo, escopos e licença correspondentes.
Como volto ao painel depois de criar uma conta?
Conclua o onboarding e a configuração do plano e da empresa. Em seguida, use API de emissão no menu Fiscal ou o endereço do painel indicado neste guia.