Gyn Fiscal

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. 1

    Crie sua conta

    No painel do Gyn Fiscal.

  2. 2

    Cadastre uma empresa e gere a API Key

    A chave e o Client ID são gerados por empresa e por ambiente.

  3. 3

    Faça sua primeira emissão

    Antes, valide as credenciais com o exemplo ao lado.

Base URL

https://gynfiscal.up.railway.app/api/v1
Testar conexão200
curl 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ório
x-tenant-idid_da_empresaobrigatório
Content-Typeapplication/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).

Exemplo em Node.js
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.

Fluxo assíncrono

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

  1. 1

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

    A API valida o payload e enfileira o processamento.

  2. 2

    Receba jobId (202 Accepted)

    Use este ID para consultar o status.

  3. 3

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

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

  4. 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

NF-e

Nota Fiscal Eletrônica

NFC-e

Nota Fiscal ao Consumidor

NFS-e

Nota Fiscal de Serviço

Nota 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ípioMEIME/EPP e não optante
Aparecida de GoiâniaSistema NacionalSistema Nacional
Águas Lindas de GoiásSistema NacionalSistema Nacional
CatalãoSistema NacionalSistema Nacional
FormosaSistema NacionalSistema Nacional
GoianésiaSistema NacionalSistema Nacional
LuziâniaSistema NacionalSistema Nacional
PlanaltinaSistema NacionalSistema Nacional
Valparaíso de GoiásSistema NacionalSistema Nacional
GoiâniaSistema NacionalSistema Nacional
JataíSistema NacionalSistema Nacional
TrindadeSistema NacionalSistema Nacional
AnápolisSistema NacionalWebservice da prefeitura
Caldas Novas, Goianira, Inhumas, Itumbiara, Novo Gama, Rio Verde, Senador CanedoSistema NacionalIndisponível (só MEI)

MDF-e

Manifesto Eletrônico de Documentos Fiscais

CT-e

Conhecimento de Transporte Eletrônico

DF-e

Distribuição de Documentos Fiscais

Autenticação

Empresas

Tenants

Certificados Digitais

Planos & Consumo

Consultas

CEP & CNPJ

IBPT

Tributos Aproximados

Pagamentos

Maquininhas Mercado Pago e Pix

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. 1

    O seu sistema manda o valor para a maquininha (ou gera o Pix dinâmico) pela integração da credenciadora.

  2. 2

    O cliente paga. A credenciadora devolve ao seu sistema o resultado: autorização, bandeira e identificadores.

  3. 3

    Com o pagamento aprovado, o seu sistema emite a NF-e ou NFC-e no Gyn com esses dados em pagamentos[].

  4. 4

    O Gyn confere os dados e grava no XML como pagamento integrado (tpIntegra=1).

  5. 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 mi01/11/2026
Até R$ 360 mil01/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 GynDe onde vemObservação
formaTipo da transaçãocartao_credito, cartao_debito, vale_alimentacao, vale_refeicao, pix (Pix dinâmico), boleto, transferencia...
valorValor pago, em reais (número)Não mande em centavos.
integradotrue quando os dados vieram da transaçãoExige cnpjCredenciadora e autorizacao (Rejeição 392). Pagamento digitado à mão: não marque.
cnpjCredenciadoraCNPJ da credenciadora que autorizouO CNPJ de cada credenciadora está na seção dela, neste guia.
bandeiraBandeira devolvida pela transaçãoNome (visa, mastercard, elo, hipercard, amex...) ou código 01 a 27, ou 99. Código fora da tabela é recusado (Rejeição 443).
autorizacaoCódigo de autorização / identificador da transaçãoAté 128 caracteres.
cnpjBeneficiarioCNPJ da loja cadastrado na credenciadoraOpcional. Normalmente é o CNPJ do emitente.
terminalIdentificador da maquininhaOpcional, até 40 caracteres.
dataPagamentoData da autorizaçãoOpcional, 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.
Exemplo
{
  "pagamentos": [
    {
      "forma": "cartao_credito",
      "valor": 89.90,
      "integrado": true,
      "cnpjCredenciadora": "16501555000157",
      "bandeira": "VISA",
      "autorizacao": "A1B2C3",
      "cnpjBeneficiario": "CNPJ da loja",
      "terminal": "SERIAL-DA-MAQUININHA"
    }
  ]
}
Logo Stone

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

O adesivo com QR Code ou chave Pix colado atrás da maquininha é Pix estático: não fica integrado. Cobre o Pix pelo app de Pagamento (transaction_type PIX).

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. 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. 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. 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. 4

    Com code = 0, emita a nota no Gyn com os campos da tabela abaixo.

Campo do GynDe onde vemObservação
formatransaction_type que você enviouCREDIT → 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.
valorO valor que você cobrou, em reaisO amount do deeplink é em centavos: 1500 = R$ 15,00.
integradotrue
cnpjCredenciadora"16501555000157"
bandeirabrandMande como vier. No Pix, omita.
autorizacaoauthorization_codeRecomendação do Gyn: se vier vazio (por exemplo no Pix), use o atk (chave da transação no autorizador).
dataPagamentoData de authorization_date_timeOpcional.
cnpjBeneficiarioCNPJ da loja cadastrado na StoneOpcional.
terminalNúmero de série da maquininhaOpcional, até 40 caracteres.
AndroidManifest.xml
<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>
Kotlin: cobrar e ler a resposta
// 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
}
Pagamento no JSON do Gyn
{
  "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. 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. 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. 3

    O resultado da transação volta em tempo real para o PDV. Preencha os mesmos campos do Gyn com esse resultado.

Campo do GynDe onde vemObservação
formaTipo da transação (crédito, débito ou voucher)
integradotrue
cnpjCredenciadora"16501555000157"
bandeira / autorizacaoCampos da transação na documentação técnica do Connect 2.0Veja "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çãoO 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 caixaPasse 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 delaA 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 sistemaO 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 atrasouO 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 notaGuarde 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 caiuO 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.

Exemplo
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.

200

Sucesso

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

202

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.

400

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.

401

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.

403

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.

404

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.

422

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.

VALIDATION_ERROR

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.

429

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.

500

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

Depois da atualização do backend, o frontend deve preferir 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.
statusprocessado

Campo 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.

statusJobprocessado

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

situacaoativo

Situação fiscal do documento. Para NF-e/NFC-e os valores mais comuns agora são ativo, cancelado, inutilizado, pendente, erro ou contingencia.

situacaoLabelAtivo

Versão pronta para exibição em tela da situação fiscal do documento.

canceladafalse

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

codigoStatus100

Có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-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 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

HeaderDescrição
X-RateLimit-LimitMáximo de requisições permitidas na janela atual
X-RateLimit-RemainingRequisições restantes na janela atual
X-RateLimit-ResetTimestamp 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.