Documentação da API

Referência completa para integrar com o Gyn Fiscal

Versão 12.05.26

Início Rápido

A API do Gyn Fiscal permite emitir, cancelar e consultar documentos fiscais eletrônicos como NF-e, NFC-e, NFS-e, MDF-e e CT-e de forma programática.

# Base URL

https://gynfiscal.up.railway.app/api/v1

Todas as requisições e respostas utilizam application/json.

1

Crie sua conta

2

Cadastre uma empresa e gere a API Key

3

Faça sua primeira emissão

Autenticação

Todas as requisições fiscais requerem os seguintes headers obrigatórios:

x-api-key: sua_api_key_aqui obrigatório

x-tenant-id: id_da_empresa obrigatório

Content-Type: application/json

Importante

A API key e o Client ID (x-tenant-id) são gerados por empresa e por ambiente (produção/homologação). Ao gerar a chave no painel, você receberá ambos os valores. Use a chave e o ID corretos nos headers. Mantenha-os em segredo e nunca exponha no frontend.

Endpoints públicos (não requerem API key): /auth/login, /auth/register, /planos

Endpoints protegidos: Todos os demais requerem x-api-key + x-tenant-id (ambiente correto).

Demo de autenticação

Headers viram código no terminal

Headers obrigatórios

x-api-key:

123456

x-tenant-id:

123456

node integration demo

Terminal preparado para Node.js

$const BASE_URL = 'https://gynfiscal.up.railway.app/api/v1';

>const apiKey = '123456';

>const tenantId = '123456';

>const res = await fetch(`${BASE_URL}/fiscal/nfe/status`, {

> headers: { 'x-api-key': apiKey, 'x-tenant-id': tenantId }

>});

>console.log("operacional");

Testar Conexão

Use este endpoint para validar suas credenciais (API Key + Client ID) e verificar a comunicação com a SEFAZ.

GET/api/v1/fiscal/nfe/status

Testar conexão e validar credenciais. Retorna status da SEFAZ e ambiente da API key.🔒

NF-e (Nota Fiscal Eletrônica)

GET/api/v1/fiscal/nfe

Listar NF-e com paginação e filtros por emitente, referência, ambiente, chave e série.🔒

GET/api/v1/fiscal/nfe/lotes

Listar lotes de NF-e ordenados por criação, com documentos e recibo.🔒

GET/api/v1/fiscal/nfe/lotes/:id

Consultar um lote específico de NF-e pelo ID retornado na emissão ou listagem.🔒

POST/api/v1/fiscal/nfe/emitir

Emitir NF-e (async). Retorna jobId para acompanhamento.🔒

POST/api/v1/fiscal/nfe/cancelar

Cancelar NF-e (async). Retorna jobId. Requer chave, protocolo e justificativa.🔒

POST/api/v1/fiscal/nfe/inutilizar

Inutilizar faixa de numeração não utilizada.🔒

GET/api/v1/fiscal/nfe/consultar/:chave

Consultar situação de NF-e pela chave de acesso (44 dígitos).🔒

GET/api/v1/fiscal/nfe/status

Verificar disponibilidade do serviço SEFAZ para o estado configurado.🔒

GET/api/v1/fiscal/nfe/job/:jobId

Consultar status de processamento assíncrono pelo jobId.🔒

GET/api/v1/fiscal/nfe/:id/xml

Baixar o XML da nota (nfeProc) salvo no job de emissão.🔒

GET/api/v1/fiscal/nfe/:id/xml/contingencia

Baixar o XML assinado salvo localmente quando a NF-e entrou em contingência.🔒

GET/api/v1/fiscal/nfe/eventos/:id/xml

Baixar o XML do evento (procEventoNFe) salvo no job de cancelamento ou CC-e.🔒

POST/api/v1/fiscal/nfe/danfe

Gerar PDF DANFE a partir do XML autorizado. Retorna application/pdf.🔒

POST/api/v1/fiscal/nfe/danfe-evento

Gerar PDF de evento (cancelamento / CC-e). DANFE com carimbo "CANCELADA" ou comprovante.🔒

DF-e (Distribuição de Documentos Fiscais)

POST/api/v1/fiscal/nfe/distribuicao/chave

Buscar DF-e por chave de acesso. Uso típico para recuperar XML de NF-e recebida.🔒

GET/api/v1/fiscal/nfe/distribuicao/nsu

Buscar DF-e por NSU específico ou distribuir a partir de um NSU inicial.🔒

GET/api/v1/fiscal/nfe/distribuicao/ult-nsu

Continuar a distribuição a partir do último NSU conhecido para o destinatário.🔒

POST/api/v1/fiscal/nfe/distribuicao/nfe

Criar uma distribuição genérica informando o tipo de consulta no body.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe

Listar distribuições já persistidas para o destinatário e ambiente.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe/:id

Consultar uma distribuição específica com documentos retornados pela SEFAZ.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe/manifestacoes

Listar manifestações do destinatário já registradas para as NF-e recebidas.🔒

POST/api/v1/fiscal/nfe/distribuicao/nfe/manifestacoes

Registrar ciência, confirmação, desconhecimento ou operação não realizada.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe/manifestacoes/:id

Consultar o detalhe de uma manifestação específica.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe/notas-sem-manifestacao

Listar NF-e distribuídas que ainda não possuem manifestação ou manifestação conclusiva.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe/documentos

Listar documentos distribuídos com filtros por tipo, chave, NSU e resumo/completo.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe/documentos/:id

Consultar o detalhe de um documento distribuído.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe/documentos/:id/xml

Baixar o XML armazenado do documento distribuído.🔒

GET/api/v1/fiscal/nfe/distribuicao/nfe/documentos/:id/pdf

Gerar PDF do documento distribuído quando houver XML completo da NF-e.🔒

MDF-e (Manifesto Eletrônico de Documentos Fiscais)

GET/api/v1/fiscal/mdfe

Listar MDF-e com paginação e filtros por referência e ambiente.🔒

GET/api/v1/fiscal/mdfe/lotes

Listar lotes lógicos de MDF-e ordenados por criação.🔒

POST/api/v1/fiscal/mdfe/emitir

Emitir MDF-e (async) usando o contrato JSON em português, no ambiente da API key.🔒

GET/api/v1/fiscal/mdfe/:id

Consultar um manifesto MDF-e já persistido pelo ID do backend.🔒

GET/api/v1/fiscal/mdfe/eventos/:id

Consultar evento MDF-e por ID.🔒

GET/api/v1/fiscal/mdfe/eventos/:id/pdf

Baixar PDF do evento MDF-e.🔒

GET/api/v1/fiscal/mdfe/eventos/:id/xml

Baixar XML do evento MDF-e.🔒

GET/api/v1/fiscal/mdfe/nao-encerrados

Consultar MDF-e ainda abertos para a empresa.🔒

GET/api/v1/fiscal/mdfe/sefaz/status

Consultar status do serviço MDF-e na SEFAZ autorizadora em produção.🔒

GET/api/v1/fiscal/mdfe/:id/cancelamento

Consultar o cancelamento do MDF-e.🔒

POST/api/v1/fiscal/mdfe/:id/cancelar

Cancelar um MDF-e autorizado pelo ID do manifesto.🔒

GET/api/v1/fiscal/mdfe/:id/cancelamento/pdf

Baixar PDF do cancelamento do MDF-e.🔒

GET/api/v1/fiscal/mdfe/:id/cancelamento/xml

Baixar XML do cancelamento do MDF-e.🔒

GET/api/v1/fiscal/mdfe/:id/encerramento

Consultar encerramento do MDF-e.🔒

POST/api/v1/fiscal/mdfe/:id/encerrar

Encerrar um MDF-e autorizado.🔒

GET/api/v1/fiscal/mdfe/:id/encerramento/pdf

Baixar PDF do encerramento do MDF-e.🔒

GET/api/v1/fiscal/mdfe/:id/encerramento/xml

Baixar XML do encerramento do MDF-e.🔒

POST/api/v1/fiscal/mdfe/:id/condutores

Incluir um condutor em um MDF-e autorizado.🔒

POST/api/v1/fiscal/mdfe/:id/documentos

Incluir um DF-e em um MDF-e autorizado.🔒

GET/api/v1/fiscal/mdfe/:id/damdfe

Baixar PDF do DAMDFE.🔒

POST/api/v1/fiscal/mdfe/:id/sincronizar

Sincronizar dados do MDF-e a partir da SEFAZ.🔒

GET/api/v1/fiscal/mdfe/:id/xml

Baixar XML do MDF-e processado salvo no backend.🔒

GET/api/v1/fiscal/mdfe/:id/xml/contingencia

Baixar o XML assinado salvo localmente quando o MDF-e entrou em contingência.🔒

GET/api/v1/fiscal/mdfe/:id/xml/manifesto

Baixar XML do manifesto MDF-e.🔒

GET/api/v1/fiscal/mdfe/:id/xml/protocolo

Baixar XML do protocolo da SEFAZ.🔒

GET/api/v1/fiscal/mdfe/exemplo

Obter JSON de exemplo do MDF-e em português, no ambiente da API key.🔒

POST/api/v1/fiscal/mdfe/validar

Validar payload do MDF-e sem transmitir, no ambiente da API key.🔒

GET/api/v1/fiscal/mdfe/status

Consultar status do serviço MDF-e em produção.🔒

GET/api/v1/fiscal/mdfe/consultar/:chave

Consultar MDF-e pela chave de acesso.🔒

GET/api/v1/fiscal/mdfe/job/:jobId

Consultar job assíncrono do MDF-e.🔒

CT-e (Conhecimento de Transporte Eletrônico)

GET/api/v1/fiscal/cte

Listar CT-e com situação, paginação e filtros.🔒

POST/api/v1/fiscal/cte/emitir

Emitir CT-e 4.00 (async) com o contrato JSON em português, no ambiente da API key.🔒

POST/api/v1/fiscal/cte/validar

Validar o JSON do CT-e sem transmitir para a SEFAZ.🔒

GET/api/v1/fiscal/cte/exemplo

Obter JSON de exemplo do CT-e rodoviário com os dados da empresa.🔒

GET/api/v1/fiscal/cte/endpoints

Consultar autorizador e URLs da SEFAZ do CT-e.🔒

GET/api/v1/fiscal/cte/status

Consultar status do serviço de CT-e na SEFAZ.🔒

GET/api/v1/fiscal/cte/consultar/:chave

Consultar CT-e na SEFAZ pela chave de acesso.🔒

GET/api/v1/fiscal/cte/job/:jobId

Acompanhar emissão ou evento assíncrono do CT-e.🔒

POST/api/v1/fiscal/cte/cancelar

Cancelar CT-e pela chave de acesso.🔒

POST/api/v1/fiscal/cte/desacordo

Registrar prestação de serviço em desacordo (tomador).🔒

GET/api/v1/fiscal/cte/eventos/:id

Consultar evento do CT-e.🔒

GET/api/v1/fiscal/cte/eventos/:id/xml

Baixar XML do evento do CT-e.🔒

GET/api/v1/fiscal/cte/eventos/:id/pdf

Baixar PDF do evento do CT-e.🔒

GET/api/v1/fiscal/cte/:id

Consultar CT-e emitido pelo ID.🔒

GET/api/v1/fiscal/cte/:id/xml

Baixar XML autorizado do CT-e (cteProc).🔒

GET/api/v1/fiscal/cte/:id/xml/protocolo

Baixar protocolo de autorização do CT-e.🔒

GET/api/v1/fiscal/cte/:id/dacte

Baixar DACTE em PDF.🔒

GET/api/v1/fiscal/cte/:id/eventos

Listar eventos do CT-e.🔒

GET/api/v1/fiscal/cte/:id/cancelamento

Consultar cancelamento do CT-e.🔒

POST/api/v1/fiscal/cte/:id/cancelar

Cancelar CT-e autorizado pelo ID (até 168 horas).🔒

POST/api/v1/fiscal/cte/:id/carta-correcao

Enviar carta de correção do CT-e.🔒

POST/api/v1/fiscal/cte/:id/sincronizar

Sincronizar CT-e com a SEFAZ.🔒

NFC-e (Nota Fiscal ao Consumidor)

GET/api/v1/fiscal/nfce

Listar NFC-e com paginação e filtros por emitente, referência, ambiente, chave e série.🔒

GET/api/v1/fiscal/nfce/lotes

Listar lotes de NFC-e ordenados por criação, com documentos e recibo.🔒

GET/api/v1/fiscal/nfce/lotes/:id

Consultar um lote específico de NFC-e pelo ID retornado na emissão ou listagem.🔒

POST/api/v1/fiscal/nfce/emitir

Emitir NFC-e (async). Mesmo fluxo assíncrono da NF-e.🔒

POST/api/v1/fiscal/nfce/cancelar

Cancelar NFC-e (async). Retorna jobId. Requer chave, protocolo e justificativa.🔒

GET/api/v1/fiscal/nfce/status

Verificar disponibilidade do serviço SEFAZ para NFC-e.🔒

GET/api/v1/fiscal/nfce/consultar/:chave

Consultar situação de NFC-e pela chave de acesso.🔒

GET/api/v1/fiscal/nfce/job/:jobId

Consultar status de processamento assíncrono pelo jobId.🔒

GET/api/v1/fiscal/nfce/:id/xml

Baixar o XML da NFC-e (nfeProc) salvo no job de emissão.🔒

GET/api/v1/fiscal/nfce/:id/xml/contingencia

Baixar o XML assinado salvo localmente quando a NFC-e entrou em contingência offline.🔒

GET/api/v1/fiscal/nfce/eventos/:id/xml

Baixar o XML do evento de cancelamento (procEventoNFe) salvo no job de cancelamento.🔒

POST/api/v1/fiscal/nfce/danfe

Gerar PDF DANFE NFC-e (cupom fiscal) a partir do XML autorizado.🔒

POST/api/v1/fiscal/nfce/danfe-evento

Gerar PDF de cancelamento NFC-e. Cupom com carimbo "CANCELADA" ou comprovante.🔒

NFS-e (Nota Fiscal de Serviço)

NFS-e — Nota Fiscal de Serviço Eletrônica

Emitida pela Prefeitura (não pela SEFAZ). Processamento síncrono — o resultado vem na mesma requisição. Suporta 19 municípios de GO via ISSNet/NotaControl (padrão ABRASF 2.04). O PDF da NFS-e é gerado pela prefeitura e pode ser consultado no portal municipal usando o código de verificação.

POST/api/v1/fiscal/nfse/emitir

Emitir NFS-e (síncrono). Suporta 19 municípios de GO (Goiânia, Aparecida, Anápolis e outros).🔒

POST/api/v1/fiscal/nfse/cancelar

Cancelar NFS-e. Goiânia: apenas via processo administrativo. Demais: via API.🔒

GET/api/v1/fiscal/nfse/consultar/rps/:numero/:serie/:tipo

Consultar NFS-e pelo número do RPS.🔒

GET/api/v1/fiscal/nfse/job/:jobId

Consultar status do job NFS-e.🔒

GET/api/v1/fiscal/nfse/municipios

Listar municípios suportados para emissão de NFS-e.🔒

IBPT (Tributos Aproximados)

GET/api/v1/fiscal/ibpt/status

Ver se o IBPT está ligado, regime, token cadastrado e a tabela usada nas notas da empresa.🔒

GET/api/v1/fiscal/ibpt/versoes

Listar as versões de tabela do IBPT (gerais e da empresa), com vigência e qual está ativa.🔒

GET/api/v1/fiscal/ibpt/consulta

Consultar os percentuais do IBPT de um NCM e calcular os tributos aproximados de um valor.🔒

Autenticação

POST/api/v1/auth/register

Registrar novo usuário na plataforma.

Empresas (Tenants)

GET/api/v1/empresa

Listar todas as empresas vinculadas ao usuário autenticado.🔒

POSTPOST /api/v1/empresa

Criar nova empresa (tenant). Requer CNPJ, razão social e e-mail.🔒

POST/api/v1/empresa/:id/api-keys

Gerar nova API Key (produção ou homologação) para a empresa.🔒

Consultas (CEP & CNPJ)

GET/api/v1/cep/:cep

Consultar endereço pelo CEP. Aceita ?modelo=1|2|3|4 para escolher provedor.🔒

POST/api/v1/cep

Consultar CEP via POST. Body: { cep, modelo? }. Modelo seleciona o provedor.🔒

GET/api/v1/cnpj/:cnpj

Consultar dados de empresa pelo CNPJ. Aceita ?modelo=1|2|3|4 para escolher provedor.🔒

POST/api/v1/cnpj

Consultar CNPJ via POST. Body: { cnpj, modelo? }. Modelo seleciona o provedor.🔒

GET/api/v1/consultas/provedores

Listar provedores disponíveis para CEP e CNPJ com seus números de modelo.🔒

Certificados Digitais

GET/api/v1/certificados

Listar certificados digitais ativos do usuário/empresa.🔒

POST/api/v1/certificados/upload

Upload de certificado A1 (.pfx). Criptografado com AES-256 no servidor.🔒

DELETE/api/v1/certificados/:id

Desativar (soft delete) um certificado digital.🔒

GET/api/v1/certificados/:id/status

Verificar validade e dias restantes do certificado.🔒

Planos & Consumo

GET/api/v1/planos

Listar planos disponíveis com limites e preços.

GET/api/v1/billing/consumo?ambiente=homologation|production

Consultar consumo mensal e limite por ambiente.🔒

GET/api/v1/billing/historico?ambiente=homologation|production

Consultar histórico de consumo por ambiente.🔒

Fluxo Assíncrono

A emissão de notas é processada de forma assíncrona para garantir alta disponibilidade.

1

Envie o JSON para /nfe/emitir ou /nfce/emitir

A API valida o payload e enfileira o processamento.

2

Receba jobId (202 Accepted)

Use este ID para consultar o status.

3

Consulte /nfe/job/:jobId ou aguarde o webhook

Polling recomendado: a cada 2 segundos, máximo 30 tentativas.

4

Receba o XML autorizado e protocolo SEFAZ

O XML assinado e o número do protocolo ficam disponíveis no job concluído.

Contingência

A API não troca automaticamente uma emissão normal por contingência. Se o seu sistema quiser usar contingência, ele precisa enviar a emissão já com formaEmissao de contingência no payload.

Depois que a emissão entra em contingência, o restante do trabalho fica com o backend: ele assina o XML, salva o XML local, marca o job como contingencia_pendente e tenta regularizar automaticamente na SEFAZ conforme a configuração enviada em contingencia.

O que o integrador faz

Envie o documento com o modo correto:

NF-e: formaEmissao: "contingencia"
NFC-e: formaEmissao: "contingencia_offline"
MDF-e: formaEmissao: "contingencia"

Como consultar

Continue consultando o job normalmente.

Se estiver processando, o status segue em andamento.
Se entrou em contingência, o job passa para contingencia_pendente.
Quando regularizar, o mesmo job passa para concluido com protocolo da SEFAZ.

Como baixar o XML

Use um endpoint diferente em cada fase.

Durante contingência: /xml/contingencia
Depois da autorização: /xml
Eventos como cancelamento continuam em /eventos/:id/xml

Códigos de Erro e Demais Retornos

Use esta seção para interpretar tanto o resultado HTTP quanto os campos fiscais extras que aparecem nos retornos de consulta e listagem de NF-e/NFC-e.

Para os códigos devolvidos pela própria SEFAZ (rejeição 204, 539, 725, 608 e outras), consulte a lista de erros e rejeições da SEFAZ, com o significado e a correção de cada um.

200Sucesso

Vem com o resultado solicitado. Exemplo: consulta retornou dados, XML foi baixado ou status da SEFAZ respondeu normalmente.

202Aceito — processamento assíncrono iniciado

A requisição foi aceita, mas o processamento ainda vai acontecer em background. Exemplo: emissão de NF-e/NFC-e retornando jobId.

400Requisição inválida — verifique o body JSON

Pode ser body malformado, JSON inválido, tipo incorreto ou estrutura enviada diferente do esperado pelo endpoint.

401Não autorizado — API key inválida ou ausente

Acontece quando x-api-key não foi enviada, está errada, expirou ou não pertence ao tenant informado.

403Proibido — sem permissão para este recurso

A credencial existe, mas não tem acesso ao recurso. Exemplo: recurso bloqueado por plano, ambiente ou regra de permissão.

404Recurso não encontrado

Usado quando o item consultado não existe ou não pertence à empresa. Exemplo: documento, job, manifestação ou certificado inexistente.

422Erro de validação — campos obrigatórios faltando

Pode ser campo obrigatório ausente, chave inválida, ambiente divergente, schema incompatível ou regra fiscal rejeitando a entrada.

VALIDATION_ERRORFalha de validação de negócio/fiscal

Além do HTTP, a API pode devolver este código semântico quando o JSON está estruturalmente válido, mas viola uma regra fiscal ou de contrato. Nesses casos, confira também o array campos quando existir.

429Rate limit excedido — aguarde antes de tentar novamente

O cliente enviou requisições demais em pouco tempo. O ideal é aguardar e repetir com retry/backoff.

500Erro interno do servidor

Erro inesperado no backend ou em biblioteca interna. Exemplo: falha ao gerar PDF, processar XML ou concluir uma rotina interna.

NF-e/NFC-e: diferenca entre status do job e situacao do documento

Depois da atualizacao do backend, o frontend deve preferir situacao ou situacaoLabel para mostrar se a nota esta ativa ou cancelada. O campo status continua por compatibilidade e pode permanecer como processado mesmo quando a situacao fiscal correta do documento e cancelado.

statusprocessado

Campo legado de compatibilidade. Em listagens, ele continua representando principalmente o andamento do job e nao deve ser usado sozinho para decidir se o documento esta ativo ou cancelado.

statusJobprocessado

Explicita o status operacional do job assíncrono: pendente, processado ou erro.

situacaoativo

Situacao fiscal do documento. Para NF-e/NFC-e os valores mais comuns agora sao ativo, cancelado, inutilizado, pendente, erro ou contingencia.

situacaoLabelAtivo

Versao pronta para exibicao em tela da situacao fiscal do documento.

canceladafalse

Booleano auxiliar. Quando true, o backend ja identificou evento autorizado de cancelamento para a chave do documento.

codigoStatus100

Codigo bruto da SEFAZ para consulta/status do documento. Exemplos: 100 autorizado, 101 cancelado, 135 ou 155 evento registrado/cancelamento homologado.

motivoStatusAutorizado o uso da NF-e

Motivo textual devolvido pela SEFAZ para o codigoStatus.

protocoloCancelamento / dataCancelamento135260000123456 / 2026-05-13T11:42:00-03:00

Quando existirem, indicam que o backend localizou um job de cancelamento concluido para a mesma chave de acesso.

Rate Limits

A API utiliza rate limiting por tenant para garantir estabilidade e uso justo dos recursos. O limite de requisições por minuto depende do plano contratado.

A contagem é feita em janelas de 1 minuto, com reset automático ao final de cada janela. O controle é por tenant (identificado via x-tenant-id ou x-api-key), não por IP.

Headers de resposta

Header	Descrição
`X-RateLimit-Limit`	Máximo de requisições permitidas na janela atual
`X-RateLimit-Remaining`	Requisições restantes na janela atual
`X-RateLimit-Reset`	Timestamp Unix (segundos) de quando a janela expira

Ao exceder o limite, a API retorna 429 Too Many Requests com o código RATE_LIMIT_EXCEEDED. Monitore o header X-RateLimit-Remaining e implemente retry com backoff exponencial.