FISCAL PRO · INTEGRAÇÃO ENTRE SISTEMAS

Seu sistema.
Nossa API fiscal.

Conecte seu ERP, loja ou plataforma ao Fiscal Pro. Envie os dados da venda e acompanhe cada documento, da criação ao arquivo fiscal.

Começar a integrar Coleção Postman ↓

URL basehttps://api.fiscalpro.com.brHTTPS · JSON

55NF-eVendas de produtos 65NFC-eVenda presencial ao consumidor NFSNFS-ePrestação de serviços

DO CADASTRO À PRIMEIRA CONSULTA

Primeiros passos

A API usa os cadastros e a configuração fiscal da empresa no Fiscal Pro. Prepare a empresa antes de enviar uma operação.

01
Configure a empresa e a aplicação
No aplicativo, acesse Configuração → Integrações por API. Selecione os modelos, o usuário responsável e o modo rascunho ou transmissão automática. Cadastre produtos, serviços e o emissor fiscal aplicável.
02
Gere uma credencial com os escopos necessários
Guarde client_id e client_secret no backend do seu sistema. O segredo é exibido uma única vez. NF-e e NFC-e precisam de habilitação e escopos explícitos.
03
Obtenha o token e consulte os cadastros
Use Client Credentials. Liste produtos ou serviços para obter os IDs da empresa e sincronize a pessoa que será o destinatário ou tomador, quando aplicável.
04
Crie e acompanhe uma operação
Envie uma chave de idempotência estável por venda. Guarde o id_operacao, consulte o resultado e baixe os arquivos disponíveis. O modo configurado pode transmitir a nota ao criar.

O ambiente fiscal é configurado no Fiscal Pro. A URL base não seleciona homologação. Antes dos testes, confira a empresa, o ambiente do emissor e o modo da aplicação. Comece em rascunho; para testar transmissão, prepare o emissor em homologação.

OAUTH 2.0 · CLIENT CREDENTIALS

Autenticação e escopos

Solicite o token em POST /integracao/oauth/token, enviando formulário URL encoded. Use Authorization: Bearer <access_token> nas rotas da integração.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request POST 'https://api.fiscalpro.com.br/integracao/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$FISCALPRO_CLIENT_ID" \
  --data-urlencode "client_secret=$FISCALPRO_CLIENT_SECRET"

O token expira em 1 hora (expires_in: 3600). Renove no backend usando a credencial; não há refresh token neste fluxo. Conceda somente os escopos usados pela aplicação.

Reutilize o token; não gere um por requisição.

Mantenha um cache protegido no backend, separado por credencial e ambiente. Calcule a expiração a partir de expires_in e renove cerca de 60 segundos antes. Coordene requisições concorrentes para apenas uma obter o próximo token; em múltiplas instâncias, use cache e coordenação compartilhados com esse mesmo isolamento.

Revogar a credencial ou desativar a aplicação bloqueia as próximas chamadas mesmo antes da expiração. Se receber 401, confira a credencial; evite ciclos de renovação sem limite. Para repetir uma criação, preserve a mesma chave de idempotência e o mesmo conteúdo.

Permissões da credencial
Escopo	Permite
`pessoas:write`	Criar e atualizar dados cadastrais de pessoas.
`servicos:read`	Consultar serviços cadastrados.
`produtos:read`	Consultar o catálogo de produtos.
`nfe:write`	Criar operações de NF-e.
`nfe:read`	Consultar NF-e e baixar XML/PDF.
`nfce:write`	Criar operações de NFC-e.
`nfce:read`	Consultar NFC-e e baixar XML/PDF.
`nfse:write`	Criar operações de NFS-e.
`nfse:read`	Consultar NFS-e e baixar PDF.

Uma credencial, uma empresa, uma aplicação.

A empresa é determinada pelo servidor a partir da credencial. Não envie tenant ou ID de empresa no corpo. Outra aplicação, mesmo da mesma empresa, não acessa suas operações. Permissões e vínculos são revalidados no servidor.

CONTRATO HTTP

Referência da API

Expanda uma operação para consultar os campos, o exemplo de requisição e o formato da resposta. Os dados dos exemplos são fictícios; substitua documentos e IDs pelos cadastros da sua empresa.

Os exemplos são para execução no seu backend. Este portal não envia requisições para a API nem recebe credenciais.

Autenticação

POST/integracao/oauth/token

Obter token de acesso

Autentique sua aplicação com OAuth 2.0 Client Credentials. O token dura 3600 segundos (1 hora). Reutilize-o no backend até perto da expiração e renove usando as mesmas credenciais; este fluxo não usa refresh token.

application/x-www-form-urlencoded

Campos do pedido 3 campos

Campos de Obter token de acesso. Obrigatoriedade de campos internos depende do envio do objeto pai.
Campo / tipo	Descrição
`grant_type`string · obrigatório no objeto	Fluxo de autenticação entre sistemas. Valores: client_credentials.
`client_id`string · obrigatório no objeto	Identificador da credencial criada no Fiscal Pro.
`client_secret`string · obrigatório no objeto	Segredo exibido uma única vez. Mantenha no backend.

Use application/x-www-form-urlencoded. O servidor também aceita client_id e client_secret via HTTP Basic.
Cadastre e revogue credenciais no aplicativo. Este portal não solicita nem armazena seus segredos.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request POST 'https://api.fiscalpro.com.br/integracao/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$FISCALPRO_CLIENT_ID" \
  --data-urlencode "client_secret=$FISCALPRO_CLIENT_SECRET"

Resposta de sucesso200 OK

{
  "access_token": "TOKEN_DE_EXEMPLO",
  "token_type": "Bearer",
  "expires_in": 3600
}

Cadastros

PUT/integracao/v1/pessoas/{cpf_cnpj}

Sincronizar pessoa

Crie ou atualize os dados cadastrais do cliente/tomador. O documento numérico válido vai no caminho. Inscrições e indicadores fiscais existentes são preservados.

Escopo: pessoas:write

Campos do pedido 11 campos

Campos de Sincronizar pessoa. Obrigatoriedade de campos internos depende do envio do objeto pai.
Campo / tipo	Descrição
`razao_social`string · obrigatório no objeto	Nome ou razão social, de 1 a 60 caracteres.
`nome_fantasia`string · opcional	Nome fantasia, opcional.
`email`string · opcional	E-mail válido, opcional.
`telefone`string · opcional	Telefone com 6 a 15 dígitos, opcional.
`endereco`object · obrigatório no objeto	Confira o exemplo e o schema OpenAPI.
`endereco.cep`string · obrigatório no objeto	CEP com 8 dígitos.
`endereco.logradouro`string · obrigatório no objeto	Logradouro, até 60 caracteres.
`endereco.numero`string · opcional	Número, até 60 caracteres.
`endereco.complemento`string · opcional	Complemento, até 60 caracteres.
`endereco.bairro`string · obrigatório no objeto	Bairro, até 60 caracteres.
`endereco.codigo_municipio`integer · obrigatório no objeto	Código IBGE de 7 dígitos.

201 para cadastro novo; 200 para atualização. Novas pessoas são cadastradas como não contribuintes; revise os dados fiscais no Fiscal Pro quando necessário.
Não envie inscrição estadual, municipal ou indicadores fiscais neste corpo.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request PUT 'https://api.fiscalpro.com.br/integracao/v1/pessoas/52998224725' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "razao_social": "Cliente de exemplo",
  "email": "cliente@example.com",
  "endereco": {
    "cep": "01001000",
    "logradouro": "Praça de exemplo",
    "numero": "100",
    "bairro": "Centro",
    "codigo_municipio": 3550308
  }
}'

Resposta de sucesso201 criação · 200 repetição/atualização

{
  "id_pessoa": 1,
  "cpf_cnpj": "52998224725",
  "criada": true
}

201 confirma a criação da operação ou cadastro. Para documentos fiscais, confira status; criação não significa autorização.

GET/integracao/v1/servicos

Listar serviços

Consulte os serviços da empresa e use id_servico para preparar a NFS-e. Confira o indicador ativo e a configuração do serviço no Fiscal Pro.

Escopo: servicos:read

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request GET 'https://api.fiscalpro.com.br/integracao/v1/servicos' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN"

Resposta de sucesso200 OK

[
  {
    "id_servico": 1,
    "nome": "Serviço de exemplo",
    "ativo": true
  }
]

GET/integracao/v1/produtos

Listar produtos

Consulte produtos cadastrados para NF-e e NFC-e. A API permite leitura do catálogo; a manutenção fiscal dos produtos acontece no Fiscal Pro.

Escopo: produtos:read

Parâmetros de consulta
Parâmetro	Descrição
`apos_id`	Cursor inicial 0; depois use proximo_id.
`limite`	De 1 a 100 produtos por página; padrão 50.

Enquanto houver proximo_id, use esse valor como apos_id na próxima chamada. IDs de produtos são específicos da empresa autenticada.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request GET 'https://api.fiscalpro.com.br/integracao/v1/produtos?apos_id=0&limite=50' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN"

Resposta de sucesso200 OK

{
  "itens": [
    {
      "id_produto": 1,
      "descricao": "Produto de exemplo",
      "codigo": "PROD-001",
      "unidade": "UN"
    }
  ],
  "proximo_id": 1
}

NF-e

POST/integracao/v1/nfe

Criar NF-e

Envie os dados comerciais. A configuração da aplicação determina rascunho ou transmissão automática; empresa, ambiente, numeração e parâmetros fiscais vêm do Fiscal Pro.

Escopo: nfe:writeExige Idempotency-Key (até 200 caracteres)

Campos do pedido 33 campos

Campos de Criar NF-e. Obrigatoriedade de campos internos depende do envio do objeto pai.
Campo / tipo	Descrição
`cpf_cnpj`string · obrigatório no objeto	Documento numérico válido de pessoa sincronizada. Na NFC-e, somente CPF; pode ser omitido quando a identificação for dispensável.
`destinacao`string · obrigatório no objeto	Finalidade comercial declarada. Valores: consumo_final, revenda, industrializacao.
`presenca`string · obrigatório no objeto	Modalidade da venda direta. Valores: presencial, internet, teleatendimento, outros.
`itens`array · obrigatório no objeto	Produtos já cadastrados no Fiscal Pro.
`itens[].id_produto`integer · obrigatório no objeto	ID obtido na listagem de produtos da empresa.
`itens[].quantidade`string · obrigatório no objeto	Quantidade positiva, até 4 casas decimais. Envie como texto decimal, com ponto.
`itens[].valor`string · obrigatório no objeto	Valor unitário positivo, até 10 casas decimais. Envie como texto decimal, com ponto.
`itens[].desconto`string · opcional	Desconto total do item, até 2 casas decimais; opcional. Envie como texto decimal, com ponto.
`pagamentos`array · obrigatório no objeto	Devem corresponder ao total calculado, inclusive acréscimos aplicáveis. Sem troco neste contrato.
`pagamentos[].meio`string · obrigatório no objeto	Código do meio de pagamento. Exemplos: 01 dinheiro, 03 crédito, 04 débito, 17 Pix, 99 outros.
`pagamentos[].valor`string · obrigatório no objeto	Valor do pagamento, até 2 casas decimais. Envie como texto decimal, com ponto.
`pagamentos[].descricao`string · opcional	Descrição obrigatória para meio 99.
`pagamentos[].a_prazo`boolean · opcional	Indica pagamento a prazo.
`pagamentos[].cartao`object · opcional	Confira o exemplo e o schema OpenAPI.
`pagamentos[].cartao.integrado`boolean · obrigatório no objeto	Indica integração com o pagamento.
`pagamentos[].cartao.cnpj_instituicao`string · opcional	CNPJ real da instituição, quando aplicável.
`pagamentos[].cartao.bandeira`string · opcional	Código da bandeira, quando aplicável.
`pagamentos[].cartao.autorizacao`string · opcional	Autorização real, quando aplicável.
`pagamentos[].cartao.cnpj_recebedor`string · opcional	CNPJ real do recebedor, quando aplicável.
`pagamentos[].cartao.terminal`string · opcional	Identificação real do terminal, quando aplicável.
`frete`object · opcional	Confira o exemplo e o schema OpenAPI.
`frete.valor`string · obrigatório no objeto	Valor total do frete, até 2 casas decimais; rateado pelo backend. Envie como texto decimal, com ponto.
`frete.responsabilidade`string · obrigatório no objeto	Responsabilidade do transporte. Valores: emitente, destinatario, terceiros, proprio_emitente, proprio_destinatario.
`entrega`object · opcional	Confira o exemplo e o schema OpenAPI.
`entrega.cpf_cnpj`string · obrigatório no objeto	Documento do local de entrega.
`entrega.nome`string · obrigatório no objeto	Nome do recebedor.
`entrega.endereco`object · obrigatório no objeto	Confira o exemplo e o schema OpenAPI.
`entrega.endereco.cep`string · obrigatório no objeto	CEP com 8 dígitos.
`entrega.endereco.logradouro`string · obrigatório no objeto	Logradouro, até 60 caracteres.
`entrega.endereco.numero`string · opcional	Número, até 60 caracteres.
`entrega.endereco.complemento`string · opcional	Complemento, até 60 caracteres.
`entrega.endereco.bairro`string · obrigatório no objeto	Bairro, até 60 caracteres.
`entrega.endereco.codigo_municipio`integer · obrigatório no objeto	Código IBGE de 7 dígitos.

De 1 a 250 itens e de 1 a 20 pagamentos. valor é unitário; desconto é o desconto total daquele item. Decimais são strings.
Os valores são ilustrativos: pagamentos devem corresponder ao total efetivamente calculado, inclusive acréscimos tributários. Use IDs reais da sua empresa.
Informe destinacao e presenca. Frete e entrega são opcionais; a entrega não altera o cadastro do cliente. Cartão exige dados reais quando aplicáveis.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request POST 'https://api.fiscalpro.com.br/integracao/v1/nfe' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-erp-0001' \
  --data '{
  "cpf_cnpj": "52998224725",
  "destinacao": "consumo_final",
  "presenca": "internet",
  "itens": [
    {
      "id_produto": 1,
      "quantidade": "1",
      "valor": "10.00"
    }
  ],
  "pagamentos": [
    {
      "meio": "01",
      "valor": "10.00",
      "a_prazo": false
    }
  ]
}'

Resposta de sucesso201 criação · 200 repetição/atualização

{
  "id_operacao": "operacao_exemplo",
  "modelo": 55,
  "status": "rascunho",
  "pendente_confirmacao": false,
  "tentativas_consulta": 0,
  "requer_acao_manual": false,
  "xml_disponivel": false,
  "pdf_disponivel": false
}

201 confirma a criação da operação ou cadastro. Para documentos fiscais, confira status; criação não significa autorização.

GET/integracao/v1/nfe/{id_operacao}

Consultar NF-e

Consulte pelo id_operacao retornado na criação, usando a mesma aplicação. A consulta de uma pendência pode atualizar o resultado fiscal sem retransmitir o documento.

Escopo: nfe:read

Respeite proxima_consulta_em quando informado. Se requer_acao_manual for true, acompanhe a operação no Fiscal Pro; não crie outra venda.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request GET 'https://api.fiscalpro.com.br/integracao/v1/nfe/operacao_exemplo' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN"

Resposta de sucesso200 OK

{
  "id_operacao": "operacao_exemplo",
  "modelo": 55,
  "status": "rascunho",
  "pendente_confirmacao": false,
  "tentativas_consulta": 0,
  "requer_acao_manual": false,
  "xml_disponivel": false,
  "pdf_disponivel": false
}

GET/integracao/v1/nfe/{id_operacao}/xml

Baixar XML da NF-e

Receba o arquivo binário autenticado, vinculado à empresa e à aplicação. Disponível para operação autorizada ou cancelada, quando o arquivo existir. Confira os indicadores de disponibilidade na consulta.

Escopo: nfe:read

404 pode indicar operação inacessível ou arquivo ainda indisponível. Consulte a operação e tente o download mais tarde, sem repetir a emissão.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail --request GET 'https://api.fiscalpro.com.br/integracao/v1/nfe/operacao_exemplo/xml' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --output documento.xml

Resposta de sucesso200 OK

Arquivo binário application/xml. Salve o corpo da resposta diretamente em arquivo.

GET/integracao/v1/nfe/{id_operacao}/pdf

Baixar PDF da NF-e

Escopo: nfe:read

404 pode indicar operação inacessível ou arquivo ainda indisponível. Consulte a operação e tente o download mais tarde, sem repetir a emissão.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail --request GET 'https://api.fiscalpro.com.br/integracao/v1/nfe/operacao_exemplo/pdf' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --output documento.pdf

Resposta de sucesso200 OK

Arquivo binário application/pdf. Salve o corpo da resposta diretamente em arquivo.

NFC-e

POST/integracao/v1/nfce

Criar NFC-e

Envie os dados comerciais. A configuração da aplicação determina rascunho ou transmissão automática; empresa, ambiente, numeração e parâmetros fiscais vêm do Fiscal Pro.

Escopo: nfce:writeExige Idempotency-Key (até 200 caracteres)

Campos do pedido 20 campos

Campos de Criar NFC-e. Obrigatoriedade de campos internos depende do envio do objeto pai.
Campo / tipo	Descrição
`cpf_cnpj`string · opcional	Documento numérico válido de pessoa sincronizada. Na NFC-e, somente CPF; pode ser omitido quando a identificação for dispensável.
`destinacao`string · opcional	Esta versão aceita consumo final; padrão quando omitido. Valores: consumo_final.
`presenca`string · opcional	Esta versão aceita venda presencial; padrão quando omitido. Valores: presencial.
`itens`array · obrigatório no objeto	Produtos já cadastrados no Fiscal Pro.
`itens[].id_produto`integer · obrigatório no objeto	ID obtido na listagem de produtos da empresa.
`itens[].quantidade`string · obrigatório no objeto	Quantidade positiva, até 4 casas decimais. Envie como texto decimal, com ponto.
`itens[].valor`string · obrigatório no objeto	Valor unitário positivo, até 10 casas decimais. Envie como texto decimal, com ponto.
`itens[].desconto`string · opcional	Desconto total do item, até 2 casas decimais; opcional. Envie como texto decimal, com ponto.
`pagamentos`array · obrigatório no objeto	Devem corresponder ao total calculado, inclusive acréscimos aplicáveis. Sem troco neste contrato.
`pagamentos[].meio`string · obrigatório no objeto	Código do meio de pagamento. Exemplos: 01 dinheiro, 03 crédito, 04 débito, 17 Pix, 99 outros.
`pagamentos[].valor`string · obrigatório no objeto	Valor do pagamento, até 2 casas decimais. Envie como texto decimal, com ponto.
`pagamentos[].descricao`string · opcional	Descrição obrigatória para meio 99.
`pagamentos[].a_prazo`boolean · opcional	Indica pagamento a prazo.
`pagamentos[].cartao`object · opcional	Confira o exemplo e o schema OpenAPI.
`pagamentos[].cartao.integrado`boolean · obrigatório no objeto	Indica integração com o pagamento.
`pagamentos[].cartao.cnpj_instituicao`string · opcional	CNPJ real da instituição, quando aplicável.
`pagamentos[].cartao.bandeira`string · opcional	Código da bandeira, quando aplicável.
`pagamentos[].cartao.autorizacao`string · opcional	Autorização real, quando aplicável.
`pagamentos[].cartao.cnpj_recebedor`string · opcional	CNPJ real do recebedor, quando aplicável.
`pagamentos[].cartao.terminal`string · opcional	Identificação real do terminal, quando aplicável.

De 1 a 250 itens e de 1 a 20 pagamentos. valor é unitário; desconto é o desconto total daquele item. Decimais são strings.
Os valores são ilustrativos: pagamentos devem corresponder ao total efetivamente calculado, inclusive acréscimos tributários. Use IDs reais da sua empresa.
Venda presencial para consumo final. Sem frete/entrega. CPF pode ser omitido quando a identificação for dispensável; para CNPJ, use NF-e. A autorização depende das validações do emissor.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request POST 'https://api.fiscalpro.com.br/integracao/v1/nfce' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-erp-0001' \
  --data '{
  "itens": [
    {
      "id_produto": 1,
      "quantidade": "1",
      "valor": "10.00"
    }
  ],
  "pagamentos": [
    {
      "meio": "01",
      "valor": "10.00",
      "a_prazo": false
    }
  ]
}'

Resposta de sucesso201 criação · 200 repetição/atualização

{
  "id_operacao": "operacao_exemplo",
  "modelo": 65,
  "status": "rascunho",
  "pendente_confirmacao": false,
  "tentativas_consulta": 0,
  "requer_acao_manual": false,
  "xml_disponivel": false,
  "pdf_disponivel": false
}

201 confirma a criação da operação ou cadastro. Para documentos fiscais, confira status; criação não significa autorização.

GET/integracao/v1/nfce/{id_operacao}

Consultar NFC-e

Consulte pelo id_operacao retornado na criação, usando a mesma aplicação. A consulta de uma pendência pode atualizar o resultado fiscal sem retransmitir o documento.

Escopo: nfce:read

Respeite proxima_consulta_em quando informado. Se requer_acao_manual for true, acompanhe a operação no Fiscal Pro; não crie outra venda.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request GET 'https://api.fiscalpro.com.br/integracao/v1/nfce/operacao_exemplo' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN"

Resposta de sucesso200 OK

{
  "id_operacao": "operacao_exemplo",
  "modelo": 65,
  "status": "rascunho",
  "pendente_confirmacao": false,
  "tentativas_consulta": 0,
  "requer_acao_manual": false,
  "xml_disponivel": false,
  "pdf_disponivel": false
}

GET/integracao/v1/nfce/{id_operacao}/xml

Baixar XML da NFC-e

Escopo: nfce:read

404 pode indicar operação inacessível ou arquivo ainda indisponível. Consulte a operação e tente o download mais tarde, sem repetir a emissão.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail --request GET 'https://api.fiscalpro.com.br/integracao/v1/nfce/operacao_exemplo/xml' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --output documento.xml

Resposta de sucesso200 OK

Arquivo binário application/xml. Salve o corpo da resposta diretamente em arquivo.

GET/integracao/v1/nfce/{id_operacao}/pdf

Baixar PDF da NFC-e

Escopo: nfce:read

404 pode indicar operação inacessível ou arquivo ainda indisponível. Consulte a operação e tente o download mais tarde, sem repetir a emissão.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail --request GET 'https://api.fiscalpro.com.br/integracao/v1/nfce/operacao_exemplo/pdf' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --output documento.pdf

Resposta de sucesso200 OK

Arquivo binário application/pdf. Salve o corpo da resposta diretamente em arquivo.

NFS-e

POST/integracao/v1/nfse

Criar NFS-e

Envie os dados comerciais. A configuração da aplicação determina rascunho ou transmissão automática; empresa, ambiente, numeração e parâmetros fiscais vêm do Fiscal Pro.

Escopo: nfse:writeExige Idempotency-Key (até 200 caracteres)

Campos do pedido 5 campos

Campos de Criar NFS-e. Obrigatoriedade de campos internos depende do envio do objeto pai.
Campo / tipo	Descrição
`cpf_cnpj`string · obrigatório no objeto	CPF ou CNPJ válido de pessoa sincronizada.
`itens`array · obrigatório no objeto	Serviços cadastrados e configurados na empresa.
`itens[].id_servico`integer · obrigatório no objeto	ID obtido na listagem de serviços.
`itens[].quantidade`string · obrigatório no objeto	Quantidade positiva, até 6 casas decimais. Envie como texto decimal, com ponto.
`itens[].valor`string · obrigatório no objeto	Valor unitário positivo, até 2 casas decimais. Envie como texto decimal, com ponto.

De 1 a 50 itens. O tomador deve estar sincronizado e os serviços configurados. Não envie tributos, município, série ou ambiente no payload.
O contrato comercial da integração não representa todos os campos da emissão manual. Confira a aplicabilidade dos cadastros antes de transmitir.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request POST 'https://api.fiscalpro.com.br/integracao/v1/nfse' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-erp-0001' \
  --data '{
  "cpf_cnpj": "52998224725",
  "itens": [
    {
      "id_servico": 1,
      "quantidade": "1",
      "valor": "100.00"
    }
  ]
}'

Resposta de sucesso201 criação · 200 repetição/atualização

{
  "id_operacao": "operacao_exemplo",
  "referencia_externa": "pedido-erp-0001",
  "cpf_cnpj": "52998224725",
  "status": "rascunho"
}

201 confirma a criação da operação ou cadastro. Para documentos fiscais, confira status; criação não significa autorização.

GET/integracao/v1/nfse/{id_operacao}

Consultar NFS-e

Consulte pelo id_operacao retornado na criação, usando a mesma aplicação. A consulta de uma pendência pode atualizar o resultado fiscal sem retransmitir o documento.

Escopo: nfse:read

NFS-e possui resposta própria: numero é texto e id_nfse é o ID interno. Não presuma os campos xml_disponivel e pdf_disponivel de NF-e/NFC-e.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail-with-body --request GET 'https://api.fiscalpro.com.br/integracao/v1/nfse/operacao_exemplo' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN"

Resposta de sucesso200 OK

{
  "id_operacao": "operacao_exemplo",
  "referencia_externa": "pedido-erp-0001",
  "cpf_cnpj": "52998224725",
  "status": "rascunho"
}

GET/integracao/v1/nfse/{id_operacao}/pdf

Baixar PDF da NFS-e

Receba o arquivo binário autenticado, vinculado à empresa e à aplicação. O PDF exige NFS-e autorizada; arquivo ainda indisponível retorna 404.

Escopo: nfse:read

404 pode indicar operação inacessível ou arquivo ainda indisponível. Consulte a operação e tente o download mais tarde, sem repetir a emissão.
A API de integração não oferece uma rota de XML de NFS-e nesta versão.

# Shell POSIX (Bash) · credenciais em variáveis de ambiente
curl --fail --request GET 'https://api.fiscalpro.com.br/integracao/v1/nfse/operacao_exemplo/pdf' \
  --header "Authorization: Bearer $FISCALPRO_ACCESS_TOKEN" \
  --output documento.pdf

Resposta de sucesso200 OK

Arquivo binário application/pdf. Salve o corpo da resposta diretamente em arquivo.

Baixar schemas completos em OpenAPI 3.0.3 →

UMA VENDA, UMA REFERÊNCIA

Idempotência e recuperação

Envie Idempotency-Key em toda criação de documento. A chave tem até 200 caracteres e deve permanecer vinculada à venda no seu sistema.

Como tratar repetições
Situação	Comportamento
Primeiro pedido válido	`201` e uma nova operação.
Mesma chave e mesmo conteúdo	`200` e a operação existente.
Mesma chave e conteúdo diferente	`409`. Não altere a venda silenciosamente.
Timeout ou conexão interrompida	Consulte o ID já recebido. Se não recebeu um ID, preserve a mesma chave e o mesmo conteúdo ao recuperar o pedido.

Não troque a chave para contornar um timeout.

Uma chave nova representa outra operação e pode duplicar uma venda. NF-e e NFC-e compartilham a unicidade por empresa e aplicação, incluindo o modelo. Repetir um rascunho não o transmite porque a configuração da aplicação mudou.

ACOMPANHAMENTO DO DOCUMENTO

Status e consultas

Persista o ID da operação, a chave da venda e o modelo. Use a consulta correspondente até obter o resultado ou a indicação de intervenção no Fiscal Pro.

Estados retornados pela integração
Status	Como interpretar
`processando`	A operação de NFS-e está em preparação. Acompanhe pelo ID.
`rascunho`	Registrada no Fiscal Pro. A criação não transmitiu a nota.
`pendente`	Resultado ainda não confirmado. Consulte a mesma operação.
`autorizada`	Autorização registrada. Confira os dados e arquivos disponíveis.
`rejeitada`	Confira o motivo e revise o cadastro ou a operação no Fiscal Pro.
`cancelada`	Cancelamento registrado. A API não oferece cancelamento nesta versão.
`erro`	Confira a mensagem e o estado da operação antes de qualquer nova tentativa.

Na NF-e e NFC-e, acompanhe pendente_confirmacao, proxima_consulta_em, requer_acao_manual, xml_disponivel e pdf_disponivel. Respeite o intervalo informado para consultar.

A NFS-e tem resposta própria, com id_nfse, provider_status e numero textual quando disponíveis. Consultar uma NFS-e pendente pode atualizar seu resultado; a consulta não retransmite a nota. O PDF exige nota autorizada e arquivo disponível.

Os arquivos são binários e autenticados. Não use id_nfe ou id_nfse no lugar de id_operacao no caminho da consulta.

RESPOSTAS HTTP

Erros e recuperação

Erros normalmente retornam JSON com erro e, quando disponível, codigo. Uma falha na criação de NFS-e também pode retornar a própria operação: preserve o ID se estiver presente.

Códigos HTTP e próximos passos
HTTP	Tratamento
`400`Pedido inválido	Confira campos, formato e Idempotency-Key. Campos desconhecidos são recusados; o corpo JSON aceita até 64 KiB.
`401`Não autenticado	Confira as credenciais ou obtenha outro token se expirou. Não registre o segredo em logs.
`403`Acesso negado	Confira escopos, vínculo do responsável, permissões e bloqueios da empresa.
`404`Não encontrado	Confira aplicação e ID da operação. O arquivo também pode estar indisponível.
`409`Conflito	A mesma chave foi reutilizada com outro conteúdo ou modelo. Recupere a venda original antes de decidir outra operação.
`422`Configuração pendente	Revise pessoa, serviço, produto ou configuração fiscal no Fiscal Pro.
`500`Falha interna	Preserve a referência e o ID retornado. Consulte a operação antes de repetir uma criação.
`502`Arquivo indisponível	O PDF de NFS-e não pôde ser entregue como arquivo válido. Consulte a operação e tente o download mais tarde.
`503`Serviço indisponível	A autorização empresarial está indisponível. Aguarde antes de tentar novamente, preservando a chave da venda.

Em falhas de comunicação, evite repetição automática de criações com outra chave. Registre a referência comercial, o ID da operação e o código HTTP, preservando segredos e dados pessoais.

PLANEJE SUA INTEGRAÇÃO

Escopo desta versão

O contrato atual cobre dados comerciais de vendas diretas e serviços cadastrados. Cálculos, classificação e configuração fiscal pertencem ao Fiscal Pro; a API recusa campos extras no pedido.

Não envie empresa/tenant, certificado, CSC, ambiente, série, numeração, CFOP, CST ou alíquotas no corpo da venda.
Mantenha os parâmetros fiscais nos cadastros. Valores ausentes não equivalem a zero; valores manuais e zeros explícitos devem ser conferidos na configuração.
Sem cancelamento pela API, webhooks, devoluções, remessas, exportação, intermediadores/marketplaces, contingência offline ou escrita no catálogo de produtos nesta versão.
A emissão depende dos modelos habilitados, escopos, permissões, situação da empresa, cadastros e validações do emissor. O modo da aplicação pode transmitir ao receber o pedido.

OpenAPI 3.0.3 ↓Contrato, campos e respostas Coleção Postman ↓Requisições com variáveis locais

Para usar a coleção, importe o JSON no Postman e preencha client_id e client_secret como variáveis locais secretas. Execute “Obter token de acesso” e copie o token para access_token. Preencha cpf_cnpj, id_operacao e a chave da venda conforme a requisição, revisando os corpos de exemplo.

Pronto para conectar?

Configure sua aplicação e use os cadastros da empresa para começar.

Acessar o Fiscal Pro ↗

Para configuração e suporte, consulte a Central de Ajuda.

Seu sistema.Nossa API fiscal.

Primeiros passos

Configure a empresa e a aplicação

Gere uma credencial com os escopos necessários

Obtenha o token e consulte os cadastros

Crie e acompanhe uma operação

Autenticação e escopos

Referência da API

Autenticação

Obter token de acesso

Cadastros

Sincronizar pessoa

Listar serviços

Listar produtos

NF-e

Criar NF-e

Consultar NF-e

Baixar XML da NF-e

Baixar PDF da NF-e

NFC-e

Criar NFC-e

Consultar NFC-e

Baixar XML da NFC-e

Baixar PDF da NFC-e

NFS-e

Criar NFS-e

Consultar NFS-e

Baixar PDF da NFS-e

Idempotência e recuperação

Status e consultas

Erros e recuperação

Escopo desta versão

Pronto para conectar?

Seu sistema.
Nossa API fiscal.