Documentação da API
Emita, cancele e consulte NF-e, NFC-e, NFS-e, MDF-e e CT-e por REST. Todas as requisições e respostas utilizam application/json.
Versão 30.10.26
Início rápido
- 1
Crie sua conta
No painel do Gyn Fiscal.
- 2
Cadastre uma empresa e gere a API Key
A chave e o Client ID são gerados por empresa e por ambiente.
- 3
Faça sua primeira emissão
Antes, valide as credenciais com o exemplo ao lado.
Base URL
https://gynfiscal.up.railway.app/api/v1curl https://gynfiscal.up.railway.app/api/v1/fiscal/nfe/status \
-H "x-api-key: gfk_sua_api_key_aqui" \
-H "x-tenant-id: seu_client_id_aqui"
{
"sucesso": true,
"dados": {
"status": "operacional",
"codigoStatus": 107,
"motivo": "Servico em Operacao",
"ambienteApiKey": "homologation",
"ambienteLabel": "Homologação"
}
}Autenticação
Todas as requisições fiscais requerem os seguintes headers:
x-api-keysua_api_key_aquiobrigatóriox-tenant-idid_da_empresaobrigatórioContent-Typeapplication/jsonImportante
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).
const BASE_URL = 'https://gynfiscal.up.railway.app/api/v1';
const res = await fetch(`${BASE_URL}/fiscal/nfe/status`, {
headers: {
'x-api-key': 'sua_api_key_aqui',
'x-tenant-id': 'id_da_empresa',
},
});Testar conexão
Use este endpoint para validar suas credenciais (API Key + Client ID) e verificar a comunicação com a SEFAZ.
/api/v1/fiscal/nfe/statusTestar conexão e validar credenciais. Retorna status da SEFAZ e ambiente da API key.
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
concluidocom 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
NF-e
Nota Fiscal Eletrônica/api/v1/fiscal/nfeListar NF-e por período de emissão (data_inicio/data_fim), chave ou referência, com paginação. Sem data: últimos 10 dias.
/api/v1/fiscal/nfe/lotesListar lotes de NF-e por período de emissão, chave ou referência, com documentos e recibo. Sem data: últimos 10 dias.
/api/v1/fiscal/nfe/lotes/:idConsultar um lote específico de NF-e pelo ID retornado na emissão ou listagem.
/api/v1/fiscal/nfe/emitirEmitir NF-e (async). Retorna jobId para acompanhamento.
/api/v1/fiscal/nfe/cancelarCancelar NF-e (async). Retorna jobId. Requer chave, protocolo e justificativa.
/api/v1/fiscal/nfe/inutilizarInutilizar faixa de numeração não utilizada.
/api/v1/fiscal/nfe/consultar/:chaveConsultar situação de NF-e pela chave de acesso (44 dígitos).
/api/v1/fiscal/nfe/statusVerificar disponibilidade do serviço SEFAZ para o estado configurado.
/api/v1/fiscal/nfe/job/:jobIdConsultar status de processamento assíncrono pelo jobId.
/api/v1/fiscal/nfe/:id/xmlBaixar o XML da nota (nfeProc) salvo no job de emissão.
/api/v1/fiscal/nfe/:id/xml/contingenciaBaixar o XML assinado salvo localmente quando a NF-e entrou em contingência.
/api/v1/fiscal/nfe/conciliacao-financeiraConciliação financeira (ECONF): informar o pagamento recebido depois da NF-e autorizada (boleto, crediário). Async.
/api/v1/fiscal/nfe/conciliacao-financeira/cancelarCancelar um ECONF registrado. Async.
/api/v1/fiscal/nfe/conciliacao-financeiraListar as conciliações e cancelamentos de uma NF-e pela chave.
/api/v1/fiscal/nfe/eventos/:id/xmlBaixar o XML do evento (procEventoNFe) salvo no job de cancelamento, CC-e ou conciliação.
/api/v1/fiscal/nfe/danfeGerar PDF DANFE a partir do XML autorizado. Retorna application/pdf.
/api/v1/fiscal/nfe/danfe-eventoGerar PDF de evento (cancelamento / CC-e). DANFE com carimbo "CANCELADA" ou comprovante.
NFC-e
Nota Fiscal ao Consumidor/api/v1/fiscal/nfceListar NFC-e por período de emissão (data_inicio/data_fim), chave ou referência, com paginação. Sem data: últimos 10 dias.
/api/v1/fiscal/nfce/lotesListar lotes de NFC-e por período de emissão, chave ou referência, com documentos e recibo. Sem data: últimos 10 dias.
/api/v1/fiscal/nfce/lotes/:idConsultar um lote específico de NFC-e pelo ID retornado na emissão ou listagem.
/api/v1/fiscal/nfce/emitirEmitir NFC-e (async). Mesmo fluxo assíncrono da NF-e.
/api/v1/fiscal/nfce/cancelarCancelar NFC-e (async). Retorna jobId. Requer chave, protocolo e justificativa.
/api/v1/fiscal/nfce/inutilizarInutilizar até 10.000 números não utilizados por pedido (modelo 65). Retorna jobId; confira protocolo e XML após o processamento.
/api/v1/fiscal/nfce/statusVerificar disponibilidade do serviço SEFAZ para NFC-e.
/api/v1/fiscal/nfce/consultar/:chaveConsultar situação de NFC-e pela chave de acesso.
/api/v1/fiscal/nfce/job/:jobIdConsultar status de processamento assíncrono pelo jobId.
/api/v1/fiscal/nfce/:id/xmlBaixar o XML da NFC-e (nfeProc) salvo no job de emissão.
/api/v1/fiscal/nfce/:id/xml/contingenciaBaixar o XML assinado salvo localmente quando a NFC-e entrou em contingência offline.
/api/v1/fiscal/nfce/conciliacao-financeiraConciliação financeira (ECONF): informar o pagamento recebido depois da NFC-e autorizada. Async.
/api/v1/fiscal/nfce/conciliacao-financeira/cancelarCancelar um ECONF registrado. Async.
/api/v1/fiscal/nfce/conciliacao-financeiraListar as conciliações e cancelamentos de uma NFC-e pela chave.
/api/v1/fiscal/nfce/eventos/:id/xmlBaixar XML do cancelamento ou da conciliação (procEventoNFe), ou comprovante de inutilização (procInutNFe).
/api/v1/fiscal/nfce/danfeGerar PDF DANFE NFC-e (cupom fiscal) a partir do XML autorizado.
/api/v1/fiscal/nfce/danfe-eventoGerar PDF de cancelamento NFC-e. Cupom com carimbo "CANCELADA" ou comprovante.
NFS-e
Nota Fiscal de ServiçoNota de serviço autorizada pelo Sistema Nacional NFS-e ou pela prefeitura (não pela SEFAZ). Processamento síncrono: o resultado vem na mesma requisição.
Como funciona
- Você envia o JSON em português para POST /emitir com a API key da empresa.
- O Gyn escolhe o caminho, monta o XML (DPS 1.01 do Sistema Nacional ou ABRASF 2.04 da prefeitura), confere no XSD oficial e assina com o certificado A1 da empresa.
- A resposta já traz o resultado: autorizada (com número e chave de acesso) ou rejeitada (com o código e a mensagem do emissor).
Dois caminhos, escolhidos automaticamente
- Sistema Nacional NFS-e (Sefin Nacional da Receita): MEI de qualquer município e empresas de municípios que aderiram ao Emissor Nacional.
- Webservice da prefeitura (ISSNet ABRASF 2.04): Anápolis, para ME/EPP e não optantes. Goiânia aderiu ao Emissor Nacional em 2026 e só usa o ISSNet com o caminho forçado na tela.
- A adesão do município é consultada ao vivo no Sistema Nacional (cache de 6 horas). Confira qualquer município em GET /municipios/:codigoIbge/situacao.
- O regime vem de Empresas > Serviços > NFS-e ou de regimeTributario no JSON. O caminho pode ser forçado na mesma tela (MEI sempre vai pelo Sistema Nacional).
Numeração: RPS, DPS e número da NFS-e
- RPS (prefeitura) e DPS (Sistema Nacional) são o pedido de nota que o seu sistema envia. O número deles é seu: vai em rps.numero e rps.serie e não pode repetir na mesma série do CNPJ.
- O número da NFS-e é dado pela prefeitura ou pelo Sistema Nacional quando a nota é autorizada. Ele volta em numeroNfse, com codigoVerificacao (prefeitura) ou chaveAcesso de 50 dígitos (Sistema Nacional), e é o que vai no PDF e o tomador vê.
- O RPS/DPS identifica o envio: se a conexão cair, consulte a nota por ele em GET /consultar/rps/:numero/:serie/1 em vez de mandar outro número.
- Número repetido é recusado pela prefeitura ou pelo Sistema Nacional, não pelo Gyn, porque só o emissor conhece os números usados por outros sistemas. No Sistema Nacional, se a nota que já existe for da mesma prestação (mesmo valor e tomador), o Gyn devolve essa nota com o alerta DPS_JA_EMITIDA em vez do erro.
- Sem rps no JSON, o Gyn usa a série e o próximo número de Empresas > Serviços > NFS-e e soma 1 sozinho: no Sistema Nacional ao reservar a DPS, antes do envio; na prefeitura, depois da nota autorizada. Com rps.numero, vale o número enviado e o contador passa para depois dele. Use um jeito só: sempre enviar ou nunca enviar.
- Empresa começando no Gyn pelo Sistema Nacional: notas feitas no portal ou no aplicativo estão nas séries 70000 e 50000 e não atrapalham. Comece na série 1, número 1. Só se o CNPJ já emitiu por outro sistema próprio (série de 1 a 49999), veja em GET /distribuicao/:nsu a série usada e escolha outra, ou continue do número seguinte. Na prefeitura, use a série que ela definiu e continue do RPS seguinte ao último. Antes da primeira nota, confira em GET /consultar/rps/:numero/:serie/1, com a API key de produção, que o número está livre.
- Homologação tem sequência própria: nota de teste não gasta número de produção.
- Buraco na numeração do RPS/DPS não abre buraco na NFS-e, que é numerada pelo emissor.
Regras de numeração: o que pode e o que não pode
- DPS (Sistema Nacional): o número vai de 1 a 999999999999999 e só não pode repetir um que já virou nota na mesma série, município e CNPJ (E0014). DPS recusada não vira nota, então o número dela fica livre, e pular número é aceito. O Gyn reserva o número antes do envio: se o Sistema Nacional recusar, o próximo envio usa o seguinte e sobra um buraco, o que é permitido.
- Série da DPS: de 1 a 49999 para quem emite por sistema próprio, como o Gyn. 50000 a 69999 é do aplicativo, 70000 a 79999 do emissor web do portal e 80000 a 89999 da transcrição manual (E0010). Por isso a nota feita no portal nunca usa o mesmo número do Gyn. Se a empresa também emite por outro sistema próprio, use uma série diferente da dele.
- Número da NFS-e (Sistema Nacional): é sempre dado pelo Sistema Nacional, e a NT 007/2026 avisa que ele pode pular. O número é reservado antes da nota ser gravada, e uma falha interna deixa o número sem nota. Esse buraco não é irregularidade da empresa e não tem o que fazer.
- RPS (prefeitura): pela legislação municipal, o RPS segue em ordem crescente em cada série e não pode repetir. O Gyn só soma 1 depois da nota autorizada, então RPS recusado é reaproveitado no próximo envio e não abre buraco.
- Inutilização não existe na NFS-e, nem no Sistema Nacional nem na prefeitura. Na NF-e e na NFC-e ela existe porque o número da nota é da empresa; na NFS-e, o número da nota é do emissor, e buraco na DPS é aceito.
Série e número na prática (Sistema Nacional)
- A série não é um número alto ou baixo: é uma faixa que mostra por onde a nota saiu. "DPS 50000/16" quer dizer DPS nº 16 da série 50000, que é a do aplicativo. "70000/5" é a 5ª DPS do emissor web do portal.
- No Gyn vale qualquer série de 1 a 49999, como 1/1, 2/1 ou 1000/1. Cada série tem a própria sequência, que começa no 1, e não é preciso continuar a numeração do portal ou do aplicativo.
- Pode: começar em 1/1; usar 1000/1 para separar sistemas, por exemplo o Gyn na série 1 e outro sistema próprio na série 1000; trocar de série depois, recomeçando do 1 na nova; pular números.
- Não pode: emitir pelo Gyn em série de 50000 a 89999, como 50000/17 ou 70000/6 (E0010); repetir série e número que já viraram nota, como 1/5 de novo (E0014); usar série 0 ou com letra.
- O número que o cliente vê é o da NFS-e. Ele é um só para o CNPJ e continua a sequência, venha a nota do portal, do aplicativo ou do Gyn. Não dá para escolher, reduzir nem reiniciar, porque quem dá é o Sistema Nacional.
- Exemplo: a empresa emitiu pelo aplicativo até a NFS-e 21 (DPS 50000/16) e passa a usar o Gyn com série 1, número 1. A primeira nota pelo Gyn vai como DPS 1/1 e sai como NFS-e 22. A próxima vai como DPS 1/2 e sai como NFS-e 23, ou mais se o aplicativo emitir no meio.
- Na prefeitura (Anápolis) não é assim: a série é a que a prefeitura definiu (8), e o RPS segue em ordem crescente, sem escolher à vontade.
Corrigir uma nota: substituição
- A NFS-e não tem carta de correção. Para corrigir valor, descrição, tomador ou tributos, emita a nota certa em POST /emitir com substituicao: { jobId (ou chaveAcesso) da nota errada, codigoMotivo, motivo }.
- No mesmo envio o Sistema Nacional autoriza a nota nova e cancela a antiga por substituição (evento e105102). A nota nova leva um número de DPS novo e recebe outro número de NFS-e.
- O que dá para mudar depende do regime. MEI e ME/EPP corrigem descrição, código do serviço e dados do tomador, mas não mudam o valor nem trocam o tomador (E0061); a nota antiga sem tomador pode ganhar um. Não optante corrige valor e tributos, mas não muda o código do serviço nem o local da prestação (E0060). Nos dois casos a competência é a da nota antiga, e o Gyn preenche sozinho. Para mudar o que a substituição trava, cancele e emita outra.
- O Gyn lê a nota antiga (do próprio Gyn ou no Sistema Nacional, pela chave) e recusa essas mudanças antes de gastar número.
- No Gyn, a antiga passa a ter cancelada true e substituidaPor (chave da nova), sai com a marca SUBSTITUÍDA no PDF, e o webhook dela recebe nfse.cancelada com substituidaPor.
- Só no Sistema Nacional, para nota do mesmo CNPJ e município (E0042), dentro do prazo da prefeitura, que vai até 2 anos (E0050). Não dá para substituir nota cancelada (E0046), nota que o tomador já confirmou (E0070) nem nota com análise fiscal pendente (E0068). Os motivos 01 e 02, de desenquadramento e enquadramento no Simples, não têm prazo.
- Na prefeitura (Anápolis), cancele a nota e emita outra.
Tributos por regime
- ME/EPP: servico.percentualTributosSimples é obrigatório. Sem ele, o Gyn barra antes de gastar número, porque o Sistema Nacional rejeitaria com E0712.
- Não optante: servico.tributosAproximados é obrigatório, com valores ou alíquotas por esfera. Na NFS-e o Gyn não calcula esses números: quem envia é o seu sistema. Sem eles, o Gyn barra antes de gastar número, porque a rejeição seria E0713.
- MEI: nenhum dos dois vai na nota. Se vierem no JSON, são ignorados e a resposta traz um alerta (E0710).
- O regime informado precisa bater com o cadastro do Simples Nacional na competência (E0160).
- PIS, COFINS e CSLL retidos (normalmente de não optante): informe servico.cstPisCofins junto com valorPis/valorCofins. O Gyn soma os três em vRetCSLL e indica quais foram retidos, como pede a NT 007/2026. Sem o CST, PIS e COFINS retidos são recusados antes do envio.
IBS e CBS (Reforma Tributária)
- Quem é obrigado: regime normal (não optante) desde 01/10/2026 na maioria dos serviços e desde 01/12/2026 em plataformas digitais, itens 1.03, 1.05, 1.09 e 16.01, locação e condomínio (Ato Conjunto RFB/CGIBS nº 4/2026). Simples Nacional, inclusive MEI, só a partir de 2027 (Anexo VI da NT 009).
- Até 31/12/2026 o Sistema Nacional não recusa nota sem o grupo IBS/CBS, mas para quem já é obrigado a nota fica em desconformidade e sujeita às sanções do Ato Conjunto. Se você informar o grupo, ele precisa estar completo e certo.
- Você envia só a classificação em ibsCbs (cst, cClassTrib, cIndOp). O Sistema Nacional calcula base, alíquotas e valores e grava na nota; o PDF mostra o bloco TRIBUTAÇÃO IBS / CBS. Em 2026 as alíquotas são de teste: 0,1% de IBS e 0,9% de CBS.
- Com ibsCbs, servico.codigoNbs é obrigatório (E0322). Os códigos de cada serviço estão no Anexo VIII do portal da NFS-e (item da LC 116 × NBS × cIndOp × cClassTrib).
- O Gyn confere antes de gastar número: formato dos códigos, cClassTrib do mesmo CST, NBS, tipo de operação e NFS-e referenciadas. Se o cIndOp diz que o imposto é do município do tomador, ele precisa ter CNPJ/CPF e endereço (E0239), e a resposta avisa.
- Testado na Produção Restrita em 03/11/2026: NFS-e MEI de R$ 30 com CST 000, cClassTrib 000001 e cIndOp 050101 foi autorizada, com IBS de R$ 0,03 e CBS de R$ 0,27.
- Na prefeitura (Anápolis, ABRASF 2.04) não há campos de IBS/CBS: ibsCbs é ignorado com um aviso.
Alíquota do ISS
- ME/EPP com ISS pelo Simples: só vai com ISS retido. Com retenção é obrigatória, de 1,8% a 5% (E0621 e E0628); sem retenção, é ignorada (E0625 e E0631).
- Não optante e ME/EPP com ISS fora do Simples: com o município de incidência ativo no Sistema Nacional, a alíquota vem da parametrização dele e a informada é ignorada (E0617 e E0635). Fora dele, é obrigatória (E0619 e E0640).
- MEI, serviço imune e regime especial de tributação: nunca vai na nota.
- Quando a alíquota depende do município e o Sistema Nacional não responde, ela segue como veio no JSON.
Cadastro do prestador
- Inscrição municipal no Sistema Nacional: com cadastro complementar no CNC do município, é obrigatória (E0116); sem ele, não pode ir na nota (E0120).
- ME/EPP e não optante só emitem pelo Sistema Nacional se o município estiver parametrizado para os emissores nacionais (E0039). Nota aprovada em homologação não prova isso em produção.
Homologação
- Use a API key de homologação: no Sistema Nacional a nota vai para a Produção Restrita, com o mesmo certificado A1 e sem valor fiscal; na prefeitura, para o ambiente de homologação do ISSNet.
- O JSON é o mesmo da produção; só a API key muda.
- Na Produção Restrita, nem todo município tem convênio para quem não é MEI. Em 02/11/2026, Aparecida de Goiânia aceitava só MEI: ME/EPP de lá voltava E0037 ("município emissor inexistente no cadastro de convênio"), embora em produção Aparecida tenha aderido. Goiânia aceitou ME/EPP na Produção Restrita em 01/11/2026.
- Nos testes, o regime precisa ser o verdadeiro do CNPJ: o Sistema Nacional confere com o cadastro do Simples (E0160). Um MEI não serve para testar nota de ME/EPP.
Síncrono, sem fila
- A NFS-e não passa pela fila (Redis/worker) da NF-e: o emissor responde na mesma conexão, em poucos segundos, e o limite é de 30 segundos.
- Se a conexão cair antes da resposta, consulte GET /job/:jobId (o idDps fica gravado antes do envio) ou GET /consultar/rps/:numero/:serie/1. No Sistema Nacional também dá para reenviar com o mesmo rps.numero: a API devolve a NFS-e já gerada em vez de duplicar. Na prefeitura, o reenvio de um RPS que já virou nota é recusado.
- Com webhookUrl no JSON, a API também avisa os eventos nfse.emitida, nfse.rejeitada e nfse.cancelada (também na substituição, com substituidaPor).
Notas emitidas fora do Gyn
- GET /distribuicao/:nsu traz do Sistema Nacional (ADN) as NFS-e em que a empresa é prestadora, tomadora ou intermediária, inclusive as emitidas no portal nacional, em outro sistema ou no sistema próprio do município. Os 19 municípios de GO da lista compartilham as notas com o ADN.
- Serve para montar o cadastro de tomadores e serviços a partir do histórico e para achar o último número de DPS antes de começar a emitir pelo Gyn.
- GET /consultar/chave/:chave/eventos mostra se a nota foi cancelada e se o tomador confirmou ou rejeitou.
- Os serviços favoritos e os cadastros do portal nacional não têm API: ficam só no site.
O que fica gravado (auditoria)
- Firestore, job (fiscal_jobs): JSON recebido, caminho, ambiente, idDps, série e número, resultado completo e marcação de cancelada, substituída (substituidaPor) ou com análise fiscal pedida.
- Firestore, log (fiscal_logs): cada tentativa, com o JSON recebido, o XML assinado enviado e o retorno do emissor. Erros de conexão e rejeições também ficam.
- Firebase Storage: xmls/{empresa}/NFSE/{chave}.xml (nota autorizada), cancelamento_{chave}.xml (evento de cancelamento) e analise_fiscal_{chave}.xml (pedido de análise fiscal registrado).
PDF, cancelamento e inutilização
- PDF: GET /:id/pdf. No Sistema Nacional, é o DANFSe v2.0 da NT 008/2026, com QR Code de consulta, gerado pelo Gyn em uma página. Em homologação traz "NFS-e SEM VALIDADE JURÍDICA"; nota cancelada pelo Gyn traz a marca CANCELADA, e nota substituída, a marca SUBSTITUÍDA.
- Cancelamento: POST /cancelar com chaveAcesso ou jobId, código 1 (erro na emissão), 2 (serviço não prestado) ou 9 (outros) e motivo de 15 a 255 caracteres. Notas de Goiânia emitidas pela prefeitura são canceladas no processo administrativo da Secretaria de Finanças.
- Prazo de cancelamento: cada prefeitura define o seu, e não há API para consultar. Fora do prazo vem E0822. Nesse caso, reenvie com analiseFiscal true para pedir à prefeitura (e101103), ou corrija por substituição se a nota só estiver errada.
- Inutilização não existe na NFS-e: veja "Regras de numeração".
Municípios de GO
MEI emite pelo Sistema Nacional em qualquer município do Brasil. Para ME/EPP e não optantes, o caminho depende do município. Lista de referência de 02/11/2026: na emissão vale a consulta ao vivo, que pode ser diferente desta tabela. Para conferir qualquer município: GET /municipios/:codigoIbge/situacao.
| Município | MEI | ME/EPP e não optante |
|---|---|---|
| Aparecida de Goiânia | Sistema Nacional | Sistema Nacional |
| Águas Lindas de Goiás | Sistema Nacional | Sistema Nacional |
| Catalão | Sistema Nacional | Sistema Nacional |
| Formosa | Sistema Nacional | Sistema Nacional |
| Goianésia | Sistema Nacional | Sistema Nacional |
| Luziânia | Sistema Nacional | Sistema Nacional |
| Planaltina | Sistema Nacional | Sistema Nacional |
| Valparaíso de Goiás | Sistema Nacional | Sistema Nacional |
| Goiânia | Sistema Nacional | Sistema Nacional |
| Jataí | Sistema Nacional | Sistema Nacional |
| Trindade | Sistema Nacional | Sistema Nacional |
| Anápolis | Sistema Nacional | Webservice da prefeitura |
| Caldas Novas, Goianira, Inhumas, Itumbiara, Novo Gama, Rio Verde, Senador Canedo | Sistema Nacional | Indisponível (só MEI) |
/api/v1/fiscal/nfse/emitirEmitir NFS-e (síncrono). MEI de qualquer município e municípios que aderiram ao Emissor Nacional (Goiânia e Aparecida inclusive) pelo Sistema Nacional; Anápolis pelo webservice da prefeitura. Com substituicao, corrige uma nota do Sistema Nacional.
/api/v1/fiscal/nfse/cancelarCancelar NFS-e. Sistema Nacional: pela chave de acesso ou jobId; fora do prazo do município, com analiseFiscal. Goiânia (prefeitura): apenas via processo administrativo.
/api/v1/fiscal/nfse/:id/pdfBaixar o PDF da NFS-e (DANFSe v2.0 gerado pelo Gyn a partir do XML autorizado).
/api/v1/fiscal/nfse/:id/xmlBaixar o XML da NFS-e autorizada (ou do evento, no job de cancelamento).
/api/v1/fiscal/nfse/listarListar emissões e cancelamentos de NFS-e da empresa, com paginação e filtros.
/api/v1/fiscal/nfse/consultar/chave/:chaveConsultar NFS-e do Sistema Nacional pela chave de acesso.
/api/v1/fiscal/nfse/consultar/chave/:chave/eventosEventos da NFS-e no Sistema Nacional: cancelamento, confirmação ou rejeição do tomador, bloqueio e outros.
/api/v1/fiscal/nfse/distribuicao/:nsuNFS-e da empresa no Sistema Nacional (ADN) depois do NSU: emitidas e recebidas, pelo Gyn ou fora dele.
/api/v1/fiscal/nfse/consultar/rps/:numero/:serie/:tipoConsultar NFS-e pelo número do RPS (no Sistema Nacional, pela DPS de mesma série e número).
/api/v1/fiscal/nfse/job/:jobIdConsultar status do job NFS-e.
/api/v1/fiscal/nfse/municipiosListar os municípios de GO conhecidos e o caminho de emissão de cada um (público).
/api/v1/fiscal/nfse/municipios/:codigoIbge/situacaoConsultar ao vivo, no Sistema Nacional, se o município aderiu ao Emissor Nacional e por onde a sua empresa vai emitir.
MDF-e
Manifesto Eletrônico de Documentos Fiscais/api/v1/fiscal/mdfeListar MDF-e com paginação e filtros por referência e ambiente.
/api/v1/fiscal/mdfe/lotesListar lotes lógicos de MDF-e ordenados por criação.
/api/v1/fiscal/mdfe/emitirEmitir MDF-e (async) usando o contrato JSON em português, no ambiente da API key.
/api/v1/fiscal/mdfe/:idConsultar um manifesto MDF-e já persistido pelo ID do backend.
/api/v1/fiscal/mdfe/eventos/:idConsultar evento MDF-e por ID.
/api/v1/fiscal/mdfe/eventos/:id/pdfBaixar PDF do evento MDF-e.
/api/v1/fiscal/mdfe/eventos/:id/xmlBaixar XML do evento MDF-e.
/api/v1/fiscal/mdfe/nao-encerradosConsultar MDF-e ainda abertos para a empresa.
/api/v1/fiscal/mdfe/sefaz/statusConsultar status do serviço MDF-e na SEFAZ autorizadora em produção.
/api/v1/fiscal/mdfe/:id/cancelamentoConsultar o cancelamento do MDF-e.
/api/v1/fiscal/mdfe/:id/cancelarCancelar um MDF-e autorizado pelo ID do manifesto.
/api/v1/fiscal/mdfe/:id/cancelamento/pdfBaixar PDF do cancelamento do MDF-e.
/api/v1/fiscal/mdfe/:id/cancelamento/xmlBaixar XML do cancelamento do MDF-e.
/api/v1/fiscal/mdfe/:id/encerramentoConsultar encerramento do MDF-e.
/api/v1/fiscal/mdfe/:id/encerrarEncerrar um MDF-e autorizado.
/api/v1/fiscal/mdfe/:id/encerramento/pdfBaixar PDF do encerramento do MDF-e.
/api/v1/fiscal/mdfe/:id/encerramento/xmlBaixar XML do encerramento do MDF-e.
/api/v1/fiscal/mdfe/:id/condutoresIncluir um condutor em um MDF-e autorizado.
/api/v1/fiscal/mdfe/:id/documentosIncluir um DF-e em um MDF-e autorizado.
/api/v1/fiscal/mdfe/:id/damdfeBaixar PDF do DAMDFE.
/api/v1/fiscal/mdfe/:id/sincronizarSincronizar dados do MDF-e a partir da SEFAZ.
/api/v1/fiscal/mdfe/:id/xmlBaixar XML do MDF-e processado salvo no backend.
/api/v1/fiscal/mdfe/:id/xml/contingenciaBaixar o XML assinado salvo localmente quando o MDF-e entrou em contingência.
/api/v1/fiscal/mdfe/:id/xml/manifestoBaixar XML do manifesto MDF-e.
/api/v1/fiscal/mdfe/:id/xml/protocoloBaixar XML do protocolo da SEFAZ.
/api/v1/fiscal/mdfe/exemploObter JSON de exemplo do MDF-e em português, no ambiente da API key.
/api/v1/fiscal/mdfe/validarValidar o MDF-e sem transmitir: regras de negócio e XML contra o XSD oficial, no ambiente da API key.
/api/v1/fiscal/mdfe/statusConsultar status do serviço MDF-e em produção.
/api/v1/fiscal/mdfe/consultar/:chaveConsultar MDF-e pela chave de acesso.
/api/v1/fiscal/mdfe/job/:jobIdConsultar job assíncrono do MDF-e.
CT-e
Conhecimento de Transporte Eletrônico/api/v1/fiscal/cteListar CT-e com situação, paginação e filtros.
/api/v1/fiscal/cte/emitirEmitir CT-e 4.00 (async) com o contrato JSON em português, no ambiente da API key.
/api/v1/fiscal/cte/validarValidar o JSON do CT-e sem transmitir para a SEFAZ.
/api/v1/fiscal/cte/exemploObter JSON de exemplo do CT-e rodoviário com os dados da empresa.
/api/v1/fiscal/cte/endpointsConsultar autorizador e URLs da SEFAZ do CT-e.
/api/v1/fiscal/cte/statusConsultar status do serviço de CT-e na SEFAZ.
/api/v1/fiscal/cte/consultar/:chaveConsultar CT-e na SEFAZ pela chave de acesso.
/api/v1/fiscal/cte/job/:jobIdAcompanhar emissão ou evento assíncrono do CT-e.
/api/v1/fiscal/cte/cancelarCancelar CT-e pela chave de acesso.
/api/v1/fiscal/cte/desacordoRegistrar prestação de serviço em desacordo (tomador).
/api/v1/fiscal/cte/eventos/:idConsultar evento do CT-e.
/api/v1/fiscal/cte/eventos/:id/xmlBaixar XML do evento do CT-e.
/api/v1/fiscal/cte/eventos/:id/pdfBaixar PDF do evento do CT-e.
/api/v1/fiscal/cte/:idConsultar CT-e emitido pelo ID.
/api/v1/fiscal/cte/:id/xmlBaixar XML autorizado do CT-e (cteProc).
/api/v1/fiscal/cte/:id/xml/protocoloBaixar protocolo de autorização do CT-e.
/api/v1/fiscal/cte/:id/dacteBaixar DACTE em PDF.
/api/v1/fiscal/cte/:id/eventosListar eventos do CT-e.
/api/v1/fiscal/cte/:id/cancelamentoConsultar cancelamento do CT-e.
/api/v1/fiscal/cte/:id/cancelarCancelar CT-e autorizado pelo ID (até 168 horas).
/api/v1/fiscal/cte/:id/carta-correcaoEnviar carta de correção do CT-e.
/api/v1/fiscal/cte/:id/sincronizarSincronizar CT-e com a SEFAZ.
DF-e
Distribuição de Documentos Fiscais/api/v1/fiscal/nfe/distribuicao/chaveBuscar DF-e por chave de acesso. Uso típico para recuperar XML de NF-e recebida.
/api/v1/fiscal/nfe/distribuicao/nsuBuscar DF-e por NSU específico ou distribuir a partir de um NSU inicial.
/api/v1/fiscal/nfe/distribuicao/ult-nsuContinuar a distribuição a partir do último NSU conhecido para o destinatário.
/api/v1/fiscal/nfe/distribuicao/nfeCriar uma distribuição genérica informando o tipo de consulta no body.
/api/v1/fiscal/nfe/distribuicao/nfeListar distribuições já persistidas para o destinatário e ambiente.
/api/v1/fiscal/nfe/distribuicao/nfe/:idConsultar uma distribuição específica com documentos retornados pela SEFAZ.
/api/v1/fiscal/nfe/distribuicao/nfe/manifestacoesListar manifestações do destinatário já registradas para as NF-e recebidas.
/api/v1/fiscal/nfe/distribuicao/nfe/manifestacoesRegistrar ciência, confirmação, desconhecimento ou operação não realizada.
/api/v1/fiscal/nfe/distribuicao/nfe/manifestacoes/:idConsultar o detalhe de uma manifestação específica.
/api/v1/fiscal/nfe/distribuicao/nfe/notas-sem-manifestacaoListar NF-e distribuídas que ainda não possuem manifestação ou manifestação conclusiva.
/api/v1/fiscal/nfe/distribuicao/nfe/documentosListar documentos distribuídos com filtros por tipo, chave, NSU e resumo/completo.
/api/v1/fiscal/nfe/distribuicao/nfe/documentos/:idConsultar o detalhe de um documento distribuído.
/api/v1/fiscal/nfe/distribuicao/nfe/documentos/:id/xmlBaixar o XML armazenado do documento distribuído.
/api/v1/fiscal/nfe/distribuicao/nfe/documentos/:id/pdfGerar PDF do documento distribuído quando houver XML completo da NF-e.
Autenticação
/api/v1/auth/loginAutenticar usuário. Retorna token JWT válido por 24h.
/api/v1/auth/registerRegistrar novo usuário na plataforma.
Empresas
Tenants/api/v1/empresaListar todas as empresas vinculadas ao usuário autenticado.
/api/v1/empresaCriar nova empresa (tenant). Requer CNPJ, razão social e e-mail.
/api/v1/empresa/:id/api-keysGerar nova API Key (produção ou homologação) para a empresa.
Certificados Digitais
/api/v1/certificadosListar certificados digitais ativos do usuário/empresa.
/api/v1/certificados/uploadUpload de certificado A1 (.pfx). Criptografado com AES-256 no servidor.
/api/v1/certificados/:idDesativar (soft delete) um certificado digital.
/api/v1/certificados/:id/statusVerificar validade e dias restantes do certificado.
Planos & Consumo
/api/v1/planosListar planos disponíveis com limites e preços.
/api/v1/billing/consumo?ambiente=homologation|productionConsultar consumo mensal e limite por ambiente.
/api/v1/billing/historico?ambiente=homologation|productionConsultar histórico de consumo por ambiente.
Consultas
CEP & CNPJ/api/v1/cep/:cepConsultar endereço pelo CEP. Aceita ?modelo=1|2|3|4 para escolher provedor.
/api/v1/cepConsultar CEP via POST. Body: { cep, modelo? }. Modelo seleciona o provedor.
/api/v1/cnpj/:cnpjConsultar dados de empresa pelo CNPJ. Aceita ?modelo=1|2|3|4 para escolher provedor.
/api/v1/cnpjConsultar CNPJ via POST. Body: { cnpj, modelo? }. Modelo seleciona o provedor.
/api/v1/consultas/provedoresListar provedores disponíveis para CEP e CNPJ com seus números de modelo.
IBPT
Tributos Aproximados/api/v1/fiscal/ibpt/statusVer se o IBPT está ligado, regime, token cadastrado e a tabela usada nas notas da empresa.
/api/v1/fiscal/ibpt/versoesListar as versões de tabela do IBPT (gerais e da empresa), com vigência e qual está ativa.
/api/v1/fiscal/ibpt/consultaConsultar os percentuais do IBPT de um NCM e calcular os tributos aproximados de um valor.
Pagamentos
Maquininhas Mercado Pago e Pix/api/v1/pagamentos/maquininhasListar as Points da empresa no ambiente da API key, com situação e última cobrança.
/api/v1/pagamentos/maquininhas/:maquininhaIdConsultar uma Point e o total aprovado nela hoje.
/api/v1/pagamentos/cobrancasCobrar na maquininha (crédito, débito ou vale). A mesma referência não cobra duas vezes.
/api/v1/pagamentos/pixGerar Pix (QR Code dinâmico) pelo Mercado Pago.
/api/v1/pagamentos/cobrancasListar cobranças por período, maquininha, status, referência ou sem nota.
/api/v1/pagamentos/cobrancas/:cobrancaIdConsultar uma cobrança, com a nota em que ela entrou.
/api/v1/pagamentos/cobrancas/:cobrancaId/cancelarCancelar cobrança ainda não paga e liberar a Point.
/api/v1/pagamentos/cobrancas/:cobrancaId/estornarEstornar o valor total de uma cobrança aprovada (não cancela a nota).
/api/v1/pagamentos/resumoFechamento do dia: total aprovado, sem nota e totais por maquininha, forma e bandeira.
Maquininhas e Pix integrados
A IN 1.608/2025 da SEFAZ-GO exige que cartão, Pix e outros pagamentos eletrônicos cheguem ao XML da NF-e e da NFC-e com os dados da transação, vindos do sistema de venda, sem digitação. Com o Mercado Pago (Point e Pix), o Gyn cobra pela maquininha e preenche a nota sozinho: o seu sistema manda só o cobrancaId (veja "Pelo hub do Gyn" e a seção Pagamentos da API). Com as demais credenciadoras, o seu sistema integra com elas e manda o resultado no JSON da emissão.
Como funciona
- 1
O seu sistema manda o valor para a maquininha (ou gera o Pix dinâmico) pela integração da credenciadora.
- 2
O cliente paga. A credenciadora devolve ao seu sistema o resultado: autorização, bandeira e identificadores.
- 3
Com o pagamento aprovado, o seu sistema emite a NF-e ou NFC-e no Gyn com esses dados em pagamentos[].
- 4
O Gyn confere os dados e grava no XML como pagamento integrado (tpIntegra=1).
- 5
Pagamento que acontece depois da nota (boleto, crediário, Pix na entrega) vai pelo ECONF: POST /conciliacao-financeira.
Prazos (receita bruta de 2024)
| Acima de R$ 4,8 mi (supermercado 4711-3, combustível 4731-8, farmácia 4771-7/01) | 01/11/2025 |
| Acima de R$ 4,8 mi (demais atividades) | 01/06/2026 |
| De R$ 360 mil a R$ 4,8 mi | 01/11/2026 |
| Até R$ 360 mil | 01/02/2027 |
MEI está fora. IN 1.608/2025-GSE (SEFAZ-GO) · IN 1.644/2026 (cronograma)
Campos de pagamentos[] na emissão
| Campo do Gyn | De onde vem | Observação |
|---|---|---|
| forma | Tipo da transação | cartao_credito, cartao_debito, vale_alimentacao, vale_refeicao, pix (Pix dinâmico), boleto, transferencia... |
| valor | Valor pago, em reais (número) | Não mande em centavos. |
| integrado | true quando os dados vieram da transação | Exige cnpjCredenciadora e autorizacao (Rejeição 392). Pagamento digitado à mão: não marque. |
| cnpjCredenciadora | CNPJ da credenciadora que autorizou | O CNPJ de cada credenciadora está na seção dela, neste guia. |
| bandeira | Bandeira devolvida pela transação | Nome (visa, mastercard, elo, hipercard, amex...) ou código 01 a 27, ou 99. Código fora da tabela é recusado (Rejeição 443). |
| autorizacao | Código de autorização / identificador da transação | Até 128 caracteres. |
| cnpjBeneficiario | CNPJ da loja cadastrado na credenciadora | Opcional. Normalmente é o CNPJ do emitente. |
| terminal | Identificador da maquininha | Opcional, até 40 caracteres. |
| dataPagamento | Data da autorização | Opcional, AAAA-MM-DD ou DD/MM/AAAA. |
- Dados de transação só valem em cartao_credito (03), cartao_debito (04), vales (10 a 13), boleto (15), pix (17, dinâmico) e transferencia (18). Em outra forma o Gyn recusa antes da SEFAZ (Rejeição 963).
- Pix por QR Code impresso ou chave Pix colada na maquininha é Pix estático (forma pix_estatico, 20): o sistema não recebe a confirmação e não há dados de transação para mandar. Para o Pix ficar integrado, gere a cobrança pela integração (Pix dinâmico).
- Só emita a nota com integrado=true depois que a credenciadora aprovar. Se a emissão falhar, repita a emissão com os mesmos dados: não cobre o cliente de novo.
- Sem os campos novos, a nota sai como antes (não integrado). A SEFAZ-GO ainda aceita, mas a IN 1.608/2025 exige a integração a partir do prazo da empresa.
- MEI está fora da IN 1.608/2025.
{
"pagamentos": [
{
"forma": "cartao_credito",
"valor": 89.90,
"integrado": true,
"cnpjCredenciadora": "16501555000157",
"bandeira": "VISA",
"autorizacao": "A1B2C3",
"cnpjBeneficiario": "CNPJ da loja",
"terminal": "SERIAL-DA-MAQUININHA"
}
]
}
Stone · maquininha verde
Stone Instituição de Pagamento S.A. · CNPJ 16.501.555/0001-57 · cnpjCredenciadora "16501555000157"
App de vendas que roda na própria maquininha Android da Stone: integração por deeplink com o app de Pagamento da Stone. Sistema fora da maquininha (computador, tablet, nuvem): Connect 2.0, para parceiros cadastrados.
Atenção
Deeplink: app de vendas instalado na maquininha Android Stone
Quando usar: O seu PDV é um app Android e roda na própria maquininha smart da Stone. A Stone informa que o deeplink só existe nos POS Android que ela disponibiliza.
- 1
No AndroidManifest, declare na Activity que recebe a resposta um intent-filter (action VIEW, category DEFAULT) com o mesmo scheme que você vai mandar em return_scheme. Use launchMode singleTop ou singleTask para a resposta chegar em onNewIntent; sem isso ela chega em onCreate.
- 2
Abra payment-app://pay com Intent.ACTION_VIEW e a flag FLAG_ACTIVITY_NEW_TASK. Todos os parâmetros vão como String: return_scheme (obrigatório); amount em centavos (0 a 999999999); editable_amount (1 permite editar o valor, 0 não); transaction_type (DEBIT, CREDIT, VOUCHER, INSTANT_PAYMENT ou PIX); installment_type (MERCHANT sem juros, ISSUER com juros, NONE à vista); installment_count (2 a 99); order_id (exige habilitar a função nos Ajustes do POS). O que você não mandar, o app de Pagamento pergunta na tela.
- 3
Leia a resposta pelos parâmetros da URI: code = 0 é sucesso, qualquer outro valor é erro (veja message, reason e response_code). A Stone avisa que erros também podem chegar como Exception: trate as duas formas.
- 4
Com code = 0, emita a nota no Gyn com os campos da tabela abaixo.
| Campo do Gyn | De onde vem | Observação |
|---|---|---|
| forma | transaction_type que você enviou | CREDIT → cartao_credito; DEBIT → cartao_debito; VOUCHER → vale_alimentacao ou vale_refeicao, conforme o cartão; PIX ou INSTANT_PAYMENT → pix. Se não enviar, o retorno informa o tipo em type. |
| valor | O valor que você cobrou, em reais | O amount do deeplink é em centavos: 1500 = R$ 15,00. |
| integrado | true | |
| cnpjCredenciadora | "16501555000157" | |
| bandeira | brand | Mande como vier. No Pix, omita. |
| autorizacao | authorization_code | Recomendação do Gyn: se vier vazio (por exemplo no Pix), use o atk (chave da transação no autorizador). |
| dataPagamento | Data de authorization_date_time | Opcional. |
| cnpjBeneficiario | CNPJ da loja cadastrado na Stone | Opcional. |
| terminal | Número de série da maquininha | Opcional, até 40 caracteres. |
<activity android:name=".VendaActivity" android:launchMode="singleTask" android:exported="true">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<data android:scheme="meupdv" />
</intent-filter>
</activity>// tipo: "CREDIT", "DEBIT", "VOUCHER" ou "PIX"
fun cobrarNaStone(valorEmReais: BigDecimal, tipo: String) {
val centavos = valorEmReais.movePointRight(2).toBigIntegerExact().toString()
val uri = Uri.Builder()
.scheme("payment-app")
.authority("pay")
.appendQueryParameter("return_scheme", "meupdv")
.appendQueryParameter("amount", centavos)
.appendQueryParameter("editable_amount", "0")
.appendQueryParameter("transaction_type", tipo)
.build()
startActivity(Intent(Intent.ACTION_VIEW, uri).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
}
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
val resposta = intent.data ?: return
if (resposta.getQueryParameter("code") != "0") {
// Recusado: mostre resposta.getQueryParameter("message") e não emita a nota
return
}
val autorizacao = resposta.getQueryParameter("authorization_code")
?.takeIf { it.isNotBlank() } ?: resposta.getQueryParameter("atk")
// Monte pagamentos[] do Gyn: forma pelo tipo enviado, valor em reais,
// integrado=true, cnpjCredenciadora="16501555000157",
// bandeira=resposta.getQueryParameter("brand"), autorizacao=autorizacao
}{
"forma": "cartao_credito",
"valor": 15.00,
"integrado": true,
"cnpjCredenciadora": "16501555000157",
"bandeira": "VISA",
"autorizacao": "código authorization_code devolvido"
}Connect 2.0: sistema fora da maquininha
Quando usar: O seu PDV roda no computador, tablet ou nuvem e manda a venda para a maquininha Stone.
- 1
Cadastre o software no Programa de Parcerias da Stone (partner.stone.com.br). Sem isso não há acesso ao Connect 2.0.
- 2
O PDV cria o pedido de venda pela API Pagar.me. A maquininha recebe o pedido: no modo Pedido Direto (para caixa) ele aparece na tela com forma, tipo, parcelas e valor; no modo Pedido Listado (para delivery) o terminal lista os pedidos em aberto. O modo é definido na ativação.
- 3
O resultado da transação volta em tempo real para o PDV. Preencha os mesmos campos do Gyn com esse resultado.
| Campo do Gyn | De onde vem | Observação |
|---|---|---|
| forma | Tipo da transação (crédito, débito ou voucher) | |
| integrado | true | |
| cnpjCredenciadora | "16501555000157" | |
| bandeira / autorizacao | Campos da transação na documentação técnica do Connect 2.0 | Veja "Confirme com a credenciadora". |
Confirme com a credenciadora antes de produção
- Pela Central de Ajuda da Stone, o Connect 2.0 só está disponível nas maquininhas S920 e Q92, e o Pix ainda não está disponível nele. Confirme se o modelo do seu cliente é atendido.
- Os nomes dos campos de retorno (código de autorização e bandeira) estão na documentação técnica do Connect 2.0, que pede acesso de parceiro. Use os campos de lá; não deduza.
Se algo falhar: plano de emergência do hub
Vale para quem cobra pelo hub do Gyn (Mercado Pago Point e Pix). O seu sistema deve tratar cada caso abaixo, para o caixa não parar.
| Situação | O que fazer |
|---|---|
| O Gyn não respondeu ao POST /pagamentos/cobrancas (tempo esgotado, erro 5xx) | Olhe a Point: se o valor apareceu nela, espere o resultado. Se não, repita o POST com a mesma referencia: se o primeiro chegou, volta a mesma cobrança (reaproveitada: true) e o cliente não é cobrado duas vezes. |
| Gyn ou Mercado Pago fora por mais tempo, com cliente no caixa | Passe a Point para o modo sem integração (STANDALONE) pela própria maquininha ou pelo painel do Mercado Pago e reinicie a Point, como o Mercado Pago orienta para instabilidade. Cobre direto na Point e emita a nota com o pagamento não integrado (sem integrado=true). Isso não atende a IN 1.608/2025: use só durante a falha. Depois, no painel do Gyn, clique em Sincronizar e em "Voltar ao modo PDV" (ou volte pelo painel do Mercado Pago) e reinicie a Point. |
| Pagamento aprovado e a emissão falhou ou o Gyn caiu antes dela | A cobrança fica guardada no Gyn como aprovada. Emita depois com o mesmo cobrancaId (até 30 dias depois da aprovação). Para achar as pendentes: GET /pagamentos/cobrancas?semNota=true. |
| O webhook do Gyn não chegou ao seu sistema | O Gyn tenta o webhookUrl 3 vezes. Não dependa só dele: consulte GET /pagamentos/cobrancas/:id e, no fechamento, GET /pagamentos/cobrancas?semNota=true. |
| O aviso do Mercado Pago atrasou | O Gyn consulta sozinho as cobranças em andamento (a cada 15 s nos primeiros 10 minutos). GET /pagamentos/cobrancas/:id?atualizar=true consulta o Mercado Pago na hora. |
| A cobrança veio com acaoNecessaria "conferir_na_maquininha" | O Mercado Pago ainda não sabe se o pagamento passou, ou o Gyn reiniciou no meio do envio. Confira a tela e o histórico da Point antes de cobrar de novo. Se não passou, cobre com outra referencia. |
| O Gyn está fora na hora de emitir a nota | Guarde a venda e emita quando o Gyn voltar, com a mesma referencia: o Gyn não emite duas notas para a mesma referência. A contingência offline da NFC-e é para a SEFAZ fora do ar e é feita pelo Gyn; com o Gyn fora, a nota espera. |
| A internet do caixa caiu | O sistema não alcança o Gyn: nem cobrança integrada nem nota. Se a Point tiver sinal próprio (chip ou outro Wi-Fi), use o modo sem integração (segunda linha). A nota sai quando a internet voltar. |
Pagamento depois da nota (ECONF)
Boleto, crediário ou Pix recebido depois da nota autorizada: envie o ECONF. O Gyn assina e envia o evento (NF-e pela SVRS, NFC-e pela SEFAZ-GO) e a nota não muda. Cancelamento em POST /conciliacao-financeira/cancelar com eventoId; listagem em GET /conciliacao-financeira?chaveAcesso=. Detalhes nas seções NF-e e NFC-e.
POST /api/v1/fiscal/nfe/conciliacao-financeira (ou /nfce/...)
{
"documentoId": "jobId da emissão no Gyn",
"pagamentos": [
{
"forma": "boleto",
"valor": 150.00,
"dataPagamento": "2026-11-28",
"cnpjCredenciadora": "CNPJ do banco que liquidou",
"autorizacao": "identificação do boleto"
}
]
}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.
Sucesso
Vem com o resultado solicitado. Exemplo: consulta retornou dados, XML foi baixado ou status da SEFAZ respondeu normalmente.
Aceito — 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.
Requisição inválida — verifique o body JSON
Pode ser body malformado, JSON inválido, tipo incorreto ou estrutura enviada diferente do esperado pelo endpoint.
Nã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.
Proibido — 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.
Recurso não encontrado
Usado quando o item consultado não existe ou não pertence à empresa. Exemplo: documento, job, manifestação ou certificado inexistente.
Erro 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.
Falha 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.
Rate limit excedido — aguarde antes de tentar novamente
O cliente enviou requisições demais em pouco tempo. O ideal é aguardar e repetir com retry/backoff.
Erro 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: diferença entre status do job e situação do documento
situacao ou situacaoLabel para mostrar se a nota está ativa ou cancelada. O campo status continua por compatibilidade e pode permanecer como processado mesmo quando a situação fiscal correta do documento é cancelado.statusprocessadoCampo legado de compatibilidade. Em listagens, ele continua representando principalmente o andamento do job e não deve ser usado sozinho para decidir se o documento está ativo ou cancelado.
statusJobprocessadoExplicita o status operacional do job assíncrono: pendente, processado ou erro.
situacaoativoSituação fiscal do documento. Para NF-e/NFC-e os valores mais comuns agora são ativo, cancelado, inutilizado, pendente, erro ou contingencia.
situacaoLabelAtivoVersão pronta para exibição em tela da situação fiscal do documento.
canceladafalseBooleano auxiliar. Quando true, o backend já identificou evento autorizado de cancelamento para a chave do documento.
codigoStatus100Código 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-eMotivo textual devolvido pela SEFAZ para o codigoStatus.
protocoloCancelamento / dataCancelamento135260000123456 / 2026-05-13T11:42:00-03:00Quando existirem, indicam que o backend localizou um job de cancelamento concluído 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.