# Integração da API de emissão

> A API v1 do Flow Fiscal é assíncrona: comandos aceitos retornam HTTP 202 e são acompanhados por operação ou webhook. Comece pelo painel, autorize cada CNPJ, configure seu certificado A1 e gere uma credencial de homologação. O OpenAPI e a coleção Postman públicos são o contrato de campos e endpoints dos seis emissores.

- Produto: Flow Fiscal — API de emissão (disponível no flow fiscal)
- Página: https://fideflow.com.br/api-nota-fiscal/guias/integracao
- Atualizado em: 2026-10-21
- Publicado por: FideFlow
- Oferta: adicional de R$ 29,90/mês além do plano Flow Fiscal, com 300 autorizações em produção por contratante/ciclo mensal compartilhadas entre CNPJs; excedente automático R$ 0,50. Cancelamento posterior não estorna consumo.

## Da conta à integração
1. **Crie ou acesse sua conta.** Quem ainda não tem conta pode [cadastrar-se no Flow Fiscal](https://erp.fideflow.com.br/flowfiscal/cadastro). 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.
2. **Abra API de emissão.** No menu Fiscal, escolha API de emissão ou [abra o painel](https://erp.fideflow.com.br/flow-fiscal/emissao-api). 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.
3. **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.
4. **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.
5. **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](https://erp.fideflow.com.br/api/flow-fiscal/v1/openapi.json): rotas, schemas separados por modelo, exemplos, campos e erros.
- [Baixar coleção Postman](https://erp.fideflow.com.br/api/flow-fiscal/v1/postman.json): 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 é `homologacao` ou `producao` e deve coincidir com a credencial e o emitente.
- **Cada modelo possui seu POST:** `/documentos/nfe`, `/documentos/nfce`, `/documentos/nfse`, `/documentos/cte`, `/documentos/cte-os` e `/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.

## Fontes oficiais
- [OpenAPI v1 publicado](https://erp.fideflow.com.br/api/flow-fiscal/v1/openapi.json)
- [Coleção Postman publicada](https://erp.fideflow.com.br/api/flow-fiscal/v1/postman.json)

## Documentos relacionados
- [API de NF-e](https://fideflow.com.br/api-nota-fiscal/nfe.md): Nota fiscal de mercadorias. Emissão, cancelamento, carta de correção e inutilização.
- [API de NFC-e](https://fideflow.com.br/api-nota-fiscal/nfce.md): Nota do consumidor no PDV, com QR Code, CSC e contingência off-line somente em SP.
- [API de NFS-e](https://fideflow.com.br/api-nota-fiscal/nfse.md): Nota de serviço no padrão nacional, enviada à Sefin Nacional como DPS assinada.
- [API de CT-e](https://fideflow.com.br/api-nota-fiscal/cte.md): Transporte rodoviário de cargas, com XML, DACTE e eventos.
- [API de CT-e OS](https://fideflow.com.br/api-nota-fiscal/cte-os.md): Outros serviços de transporte rodoviário, com contrato próprio para o modelo 67.
- [API de MDF-e](https://fideflow.com.br/api-nota-fiscal/mdfe.md): Manifesto rodoviário, com XML, DAMDFE, consulta, cancelamento e encerramento.

---
No teste grátis do Flow Fiscal, a API de emissão vem completa, sem contratar; depois do teste, requer plano Flow Fiscal ativo e o opcional de emissão contratado. Exige certificado A1 válido e vínculo autorizado de cada CNPJ. CT-e, CT-e OS e MDF-e atendem o modal rodoviário; NFS-e segue o padrão nacional e os requisitos do município. Consulte as capacidades do emitente antes de transmitir.