REST API GNRE

Guia Rápido

Todas as requisições na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://api.webmania.com.br/. O prefixo /2/gnre deve ser adicionado na URL em todas as requisições.

Principais funcionalidades:

• Dois modos de emissão — por valor direto ou a partir de notas fiscais já emitidas na Webmania®
• Seleção por período ou por chaves/UUIDs de até 100 notas por requisição
• Derivação automática de receitas a partir das parcelas de imposto declaradas na NF-e
• Prévia da seleção sem emitir e sem consumir cota do plano
• Lote de até 100 guias em uma única requisição
• PIX, código de barras e linha digitável em todas as guias aprovadas
• PDF da guia disponível na consulta do lote
• Notificação por webhook no desfecho de cada guia
• Cobertura das 25 UFs que publicam receitas GNRE

A tabela abaixo lista todos os endpoints disponíveis na API:

Sempre envie o corpo da requisição no formato JSON, e o cabeçalho Content-Type deve estar definido como application/json.

A resposta da API estará sempre no formato JSON, o padrão da estrutura da resposta está disponível nesta seção da documentação.

Notificações

O webhook é o canal principal de notificação de resultado da API GNRE. Todo payload de emissão deve informar a URL de callback no parâmetro url_notificacao.

O que é o UUID? O UUID (Universally Unique Identifier) é um identificador único de 36 caracteres, no formato 8-4-4-4-12, que a Webmania® atribui a cada emissão. Ele é gerado assim que a requisição é aceita pela API da Webmania® — antes de qualquer transmissão à SEFAZ.

Uma vez gerado, o UUID é definitivo: não muda em retentativas, contingência ou reenvio. O recibo SEFAZ (provider_identifier), o número da guia e o código de barras são campos diferentes, só existem após o processamento e podem mudar — por isso o UUID, e não eles, deve ser a sua referência no banco de dados.

Quando a guia atingir um status terminal — aprovado ou rejeitado — a Webmania® envia uma requisição POST para a url_notificacao com o resultado completo.

Exemplo do payload enviado pelo webhook na emissão por valores:

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modelo": "gnre",
  "status": "aprovado",
  "ambiente": 2,
  "identificador": "12345678901234"
}

O webhook é aditivo: além dos campos base, esse mesmo payload pode receber os blocos da tabela abaixo, sem alterá-los. A presença de cada bloco depende do modo de emissão e está indicada na respectiva descrição — origem, notas[], notas_ignoradas[] e parcelas_recusadas[] aparecem apenas na emissão por notas (origem = periodo ou chaves), enquanto guias[] também está presente nas emissões por valores quando o resultado contém guias (uma ou mais). Os blocos nunca são enviados vazios — quando não há o que reportar, a chave é simplesmente omitida.

Os campos aditivos descrevem a mesma trilha exposta no endpoint de status e, quando aplicáveis, acompanham qualquer status terminal — inclusive payloads rejeitado, que além deles carregam motivos_rejeicao.

Exemplo de payload de emissão por notas (status aprovado):

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modelo": "gnre",
  "status": "aprovado",
  "ambiente": 2,
  "identificador": "12345678901234",
  "origem": "periodo",
  "notas": [
    {
      "document_key": "35210412345678000123550010000012341123456780",
      "valor_icms_st": "250.00",
      "valor_difal": "140.25",
      "motivo_ignorado": null,
      "receita": "100102"
    },
    {
      "document_key": "35210412345678000123550010000012341123456780",
      "valor_icms_st": "250.00",
      "valor_difal": "140.25",
      "motivo_ignorado": null,
      "receita": "100129"
    },
    {
      "document_key": "35210412345678000123550010000012341123456780",
      "valor_icms_st": "250.00",
      "valor_difal": "140.25",
      "motivo_ignorado": null,
      "receita": "100099"
    },
    {
      "document_key": "35210412345678000123550010000012341123456781",
      "valor_icms_st": null,
      "valor_difal": null,
      "motivo_ignorado": "st_requer_ie_substituto",
      "receita": null
    }
  ],
  "notas_ignoradas": [
    {
      "document_key": "35210412345678000123550010000012341123456781",
      "valor_icms_st": null,
      "valor_difal": null,
      "motivo_ignorado": "st_requer_ie_substituto",
      "receita": null
    }
  ],
  "guias": [
    {
      "situacao_guia": 0,
      "uf_favorecida": "MG",
      "receita": "100102",
      "codigo_barras": "85840000002 5 99990123021 1 23456789012 7",
      "codigo_barra_48": "8584000000259999012302112345678901270000000099999",
      "linha_digitavel": "85840.00000 00025.999901 23021.123456 8 9012700000000 99999",
      "qrcode_payload": "00020101021226870014br.gov.bcb.pix..."
    },
    {
      "situacao_guia": 0,
      "uf_favorecida": "MG",
      "receita": "100129",
      "codigo_barras": "85850000002 6 99990123021 0 34567890123 7",
      "codigo_barra_48": "8585000000269999012302103456789012370000000099999",
      "linha_digitavel": "85850.00000 00026.999901 23021.034567 8 9012370000000 99999",
      "qrcode_payload": "00020101021226870014br.gov.bcb.pix..."
    }
  ],
  "parcelas_recusadas": [
    {
      "document_key": "35210412345678000123550010000012341123456780",
      "receita": "100099",
      "parcela": "vST",
      "motivo": "st_requer_ie_substituto",
      "valor": "250.00"
    }
  ]
}

O identificador é o recibo SEFAZ do lote — o mesmo valor exposto em provider_identifier no endpoint de status — e pode ser usado no POST /2/gnre/consulta para obter o resultado guia a guia. Quando status é rejeitado, o payload inclui motivos_rejeicao (lista de {codigo, mensagem}) com o motivo da rejeição.

Nas emissões originadas de notas fiscais (origem periodo ou chaves), o payload inclui também o bloco notas — uma linha por combinação de nota e receita, com document_key, valor_icms_st, valor_difal, motivo_ignorado e receita — e, quando há notas não liquidadas, o bloco notas_ignoradas com as mesmas linhas que carregam motivo_ignorado.

valor_icms_st e valor_difal são totais da nota, repetidos em cada linha. Uma nota que financia mais de uma receita aparece em mais de uma linha — cada uma identificada pelo seu receita — e todas repetem os mesmos totais: não some o array. Para valores agregados por guia, use o bloco guias descrito a seguir.

Guias

Quando o processamento do lote termina e o resultado guia a guia está disponível, o payload do webhook e a resposta de GET /2/gnre/status/{uuid} incluem o bloco guias, com um registro de pagamento por guia do lote:

Diferença em relação à consulta de lote: a resposta de POST /2/gnre/consulta documenta os campos situacao_guia, dados, linha_digitavel, codigo_barras, qrcode_payload e motivos_rejeicao. Os campos codigo_barra_48, uf_favorecida e receita existem somente no webhook e no endpoint de status — não os procure na resposta da consulta.

O webhook não dispara para processando nem para erro_comunicacao. O status erro_comunicacao indica que o resultado junto à SEFAZ ficou incerto: a API não reenvia a emissão automaticamente, e a resolução é manual — consulte GET /2/gnre/status/{uuid}, que retorna uma mensagem orientando a conferência com a SEFAZ. Só reemita após confirmar que a guia não foi gerada, para evitar documento fiscal em duplicidade.

Se a comunicação com a SEFAZ falhar e a API esgotar as tentativas sem obter um identificador (recibo), a guia será marcada como rejeitada e o webhook será chamado com a mensagem explicando que houve instabilidade nos servidores da SEFAZ. Nessa situação, o integrador pode tentar emitir novamente.

Para casos em que o webhook não puder ser recebido, acompanhe GET /2/gnre/status/{uuid} como fallback de consulta manual.

A tabela abaixo resume os valores possíveis de status e o comportamento da notificação em cada um:

Dois modos de emissão

O endpoint POST /2/gnre/emissao aceita dois modos de origem, mutuamente exclusivos:

Emissão a partir de notas fiscais. Informe uma janela de emissão em periodo (data_inicio e data_fim) ou uma lista de até 100 identificadores em documentos[]. A API localiza as notas, lê as parcelas de imposto declaradas em cada uma e compõe as guias sozinha — você não precisa calcular nada nem saber qual receita usar.

"documentos": [
  "35260800000000000000550010000012341123456789",
  "8f14e45f-ceea-4d3e-a2e0-123456789012"
]

Módulos & Exemplos

Teste a REST API de GNRE sem escrever uma linha de código e acelere a sua integração com as ferramentas oficiais da Webmania®.

• Ferramentas
  • Coleção Postman (Testes instantâneos)
  • Vídeo: Testar REST API sem linha de código

Autenticação

Para acessar os recursos da API, é necessário autenticar as requisições por meio do cabeçalho HTTP (HTTP headers). A autenticação deve ser feita utilizando o cabeçalho Authorization, no seguinte formato:

Authorization: Bearer {Access-Token}

O Access-Token da API 2.0 é encontrado no painel Webmania® e deve ser incluído em todas as requisições.

Mantenha suas credenciais em segurança. Nunca publique o Access Token nem a senha do certificado no código-fonte do site, aplicativo ou sistema onde ele possa ser facilmente acessado por terceiros.

Para aplicativos móveis (iOS e Android), recomendamos que a consulta à API seja realizada no servidor (back-end). O código-fonte do aplicativo deve apenas enviar a requisição enquanto o processamento da consulta deve ocorrer no seu servidor.

Formato de resposta

Todas as respostas da API seguem um padrão e estão no formato JSON, garantindo clareza e facilidade de interpretação.

A tabela abaixo apresenta os códigos de status HTTP que a API pode retornar com suas respectivas descrições. Esses códigos indicam o resultado da operação solicitada e ajudam a entender se a requisição foi bem-sucedida ou se ocorreu alguma falha.

Legenda: ✅ a operação foi concluída · ❌ a operação não foi concluída e nada foi criado.

O código 429 (Too Many Requests) não aparece nesta tabela: ele é específico do controle de volume e está descrito em Limite de requisições.

Limite diário do modo por notas: as emissões de GNRE a partir de notas fiscais somam um limite diário de 1.000 guias por empresa. Ao atingir o teto, novas emissões por notas retornam 429 com a mensagem "Limite diário de 1000 emissões por notas atingido. Novas emissões por notas serão liberadas no próximo dia." O limite é renovado à meia-noite (horário de Brasília) e a emissão com valor direto não consome esse limite.

Códigos de erro da GNRE

Os códigos abaixo são retornados pela Fazenda dentro do campo situacao_recepcao.codigo (recepção) ou situacao_process.codigo (processamento):

Exemplo de resposta para uma requisição com erro:

{
  "error": "Parâmetro inválido: uf_favorecida. O valor XX não é uma UF válida."
}

Serviços
Emissão de GNRE

Emite um lote de guias GNRE junto à Secretaria Estadual da Fazenda (SEFAZ). A emissão é assíncrona: a API retorna imediatamente, processa o lote em background e notifica o resultado final pelo webhook informado em url_notificacao. O acompanhamento individual da guia é feito por GET /2/gnre/status/{uuid} — Saiba mais.

O que é um lote? Uma requisição de emissão envia um lote, que contém uma ou mais guias; cada guia contém um ou mais itens (documentos de origem ou receitas), e cada item carrega os valores a recolher. O lote é transmitido de uma vez à SEFAZ e recebe um recibo único; cada guia, porém, é um documento pagável independente e é contada individualmente na cobrança.

Emissão de GNRE
Informações Gerais

Parâmetros da requisição:

Emissão de GNRE
Guia Simples

Para guias do tipo 0 (simples), informe uma única guia com um único item.

Emissão de GNRE
Tipos de guia

O campo tipo_gnre define a estrutura da guia: 0 = guia simples (um item, uma receita); 1 = guia de múltiplos documentos (cada item é um documento de origem diferente, até 100 itens); 2 = guia de múltiplas receitas (cada item é uma receita diferente, até 100 itens). Todos os itens de uma guia compartilham a mesma data de vencimento e o mesmo contribuinte emitente.

Guia tipo 1 — múltiplos documentos (tipo_gnre = 1)

Para guias do tipo 1, cada item representa um documento de origem diferente que financia a mesma receita (até 100 itens por guia). Use esse tipo quando uma obrigação é composta por vários documentos — por exemplo, várias NF-e de saída recolhendo DIFAL para a mesma UF sob a mesma receita. Cada item informa o próprio documento_origem e os seus valores; os demais campos do item podem repetir-se ou variar conforme a exigência da UF.

Exemplo — estrutura de uma guia tipo 1 dentro de guias[], dois documentos sob a mesma receita 100102:

{
  "uf_favorecida": "MG",
  "tipo_gnre": 1,
  "itens": [
    { "receita": "100102", "documento_origem": { "numero": "3526071234567890123455900012345678", "tipo": "01" }, "data_vencimento": "2026-08-20", "valores": [ { "tipo": 11, "valor": 100.00 } ] },
    { "receita": "100102", "documento_origem": { "numero": "3526071234567890123455900087654321", "tipo": "01" }, "data_vencimento": "2026-08-20", "valores": [ { "tipo": 11, "valor": 250.00 } ] }
  ]
}

Guia tipo 2 — múltiplas receitas (tipo_gnre = 2)

Para guias do tipo 2, cada item representa uma receita diferente dentro da mesma guia (até 100 itens por guia). Nem toda UF aceita este tipo de guia: a lista de tipos permitidos é publicada por receita em tipos_gnre na Configuração de UF, e uma combinação não publicada é recusada com HTTP 422.

Exemplo — estrutura de uma guia tipo 2 dentro de guias[], DIFAL e FCP na mesma guia:

{
  "uf_favorecida": "GO",
  "tipo_gnre": 2,
  "itens": [
    { "receita": "100102", "data_vencimento": "2026-08-20", "valores": [ { "tipo": 11, "valor": 350.00 } ] },
    { "receita": "100129", "data_vencimento": "2026-08-20", "valores": [ { "tipo": 12, "valor": 12.30 } ] }
  ]
}

Emissão de GNRE
Itens

Cada item da guia contém a receita, o documento de origem, os valores, a referência e dados do destinatário quando exigido.

Receitas compostas por esta API. O código da receita identifica qual tributo está sendo recolhido. As receitas abaixo são as que a emissão desta API trata quando publicadas pela UF favorecida: a disponibilidade de cada código é por UF, e a relação vigente é a que a UF publica na Configuração de UF (GET /2/gnre/config-uf/{uf}) — consulte-a antes de emitir, pois ela é a lista autoritativa. O 100002 está disponível somente nas UFs que o relacionam nessa resposta; receita que a UF favorecida não publica é recusada com HTTP 422 na emissão.

As receitas "por Apuração" (100110 e 100137) nunca são derivadas automaticamente das notas: elas só entram na guia por receita_override (descrito mais abaixo) e, como qualquer substituição, continuam sujeitas à validação de configuração da UF — uma receita que a UF não publica é recusada com HTTP 422.

Emissão de GNRE
Documento de Origem

Emissão de GNRE
Valores

Cada valor é composto pelo tipo e pelo valor monetário. Os tipos de valor seguem a tabela abaixo:

Emissão de GNRE
Referência

Período de referência para pagamento do imposto.

Emissão de GNRE
Contribuinte Emitente

Dados de identificação do contribuinte emitente da guia.

Emissão de GNRE
Contribuinte Destinatário

Dados do contribuinte destinatário, obrigatório quando a UF exigir.

Emissão de GNRE
Campos Extras

Campos extras definidos pela configuração da UF, quando uma receita da UF os exige. Cada item aceita no máximo 3 campos extras; o codigo é um inteiro e o valor, uma string de até 100 caracteres. Você descobre que a UF exige campos extras pelo sinalizador exige_campos_adicionais: "S" na configuração da receita, em GET /2/gnre/config-uf/{uf}; a relação de códigos é publicada no portal nacional do GNRE.

Emissão de GNRE
Exemplo de Requisição

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/gnre/emissao

{
  "ambiente": 2,
  "url_notificacao": "https://seudominio.com.br/webhook/gnre",
  "guias": [
    {
      "uf_favorecida": "MG",
      "tipo_gnre": 0,
      "contribuinte_emitente": {
        "tipo_identificacao": 1,
        "cnpj": "12345678000195",
        "inscricao_estadual": "123456789012",
        "razao_social": "EMPRESA EXEMPLO LTDA",
        "endereco": "RUA EXEMPLO 100",
        "municipio": "35503",
        "uf": "SP",
        "cep": "01001000",
        "telefone": "11999999999"
      },
      "itens": [
        {
          "receita": "100002",
          "detalhamento_receita": "000001",
          "documento_origem": {
            "numero": "3526071234567890123455900012345678",
            "tipo": "01"
          },
          "data_vencimento": "2026-07-20",
          "valores": [
            { "tipo": 11, "valor": 100.00 }
          ],
          "referencia": {
            "periodo": 0,
            "mes": 7,
            "ano": 2026
          },
          "contribuinte_destinatario": {
            "tipo_identificacao": 1,
            "cnpj": "11222333000181",
            "inscricao_estadual": "987654321098",
            "razao_social": "DESTINATARIO EXEMPLO LTDA",
            "endereco": "RUA DESTINO 200",
            "municipio": "35503",
            "uf": "SP",
            "cep": "01002000"
          }
        }
      ],
      "data_pagamento": "2026-07-20"
    }
  ]
}

Resposta da Webmania®:

{
  "status": "processando",
  "message": "Emissão em processamento. Consulte novamente em alguns instantes.",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Emissão de GNRE
Emissão por Notas (período ou chaves)

O POST /2/gnre/emissao — o mesmo endpoint da emissão por valor direto — também aceita a origem por notas. Além do valor direto (guias), o GNRE pode ser emitido a partir de notas fiscais já emitidas, informando uma janela de emissão (periodo) ou uma lista de identificadores (documentos). Os dois modos são mutuamente exclusivos entre si e não podem ser combinados com guias.

As receitas de cada guia são derivadas das parcelas de imposto declaradas na própria NF-e — veja a derivação de receitas: uma nota que carrega DIFAL e FCP gera duas guias separadas, e cada guia é um documento pagável contado individualmente na cobrança.

Na origem por notas, o lote é composto pela API: os campos abaixo são informados na raiz da requisição e copiados para cada guia/item composto.

Parâmetros da requisição (origem por notas):

Exemplo — período de emissão:

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/gnre/emissao

{
  "ambiente": 2,
  "url_notificacao": "https://seudominio.com.br/webhook/gnre",
  "data_vencimento": "2026-08-20",
  "data_pagamento": "2026-08-20",
  "periodo": {
    "data_inicio": "2026-07-01",
    "data_fim": "2026-07-31"
  }
}

Exemplo — chaves de acesso / UUIDs, com override e convênio opcionais:

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/gnre/emissao

{
  "ambiente": 2,
  "url_notificacao": "https://seudominio.com.br/webhook/gnre",
  "data_vencimento": "2026-08-20",
  "data_pagamento": "2026-08-20",
  "documentos": [
    "35260700000000000000550010000012341123456789",
    "8f14e45f-ceea-4d3e-a2e0-123456789012"
  ],
  "convenio": "123456789012345678901234567890",
  "receita_override": { "100102": "100110" },
  "detalhamento_receita_override": { "100129": "009888" }
}

Resposta da Webmania® (emissão enfileirada — o processamento é assíncrono):

{
  "status": "processando",
  "message": "Emissão em processamento. Consulte novamente em alguns instantes.",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parcelas_recusadas": [
    {
      "document_key": "35260700000000000000550010000012441123456790",
      "receita": "100099",
      "parcela": "vST",
      "motivo": "st_requer_ie_substituto",
      "valor": "45.00",
      "mensagem": "ICMS-ST (receita 100099) não pode ser emitido por notas: depende da inscrição estadual de substituto tributário do contribuinte na UF de destino, que não consta da nota. Emita esta guia por valor direto informando a receita."
    }
  ]
}

O bloco parcelas_recusadas aparece somente quando uma nota selecionada carrega uma parcela recusada — a ausência do bloco significa que a emissão cobriu tudo o que selecionou. O resultado final chega pelo webhook em url_notificacao e pode ser acompanhado em GET /2/gnre/status/{uuid} (saiba mais).

Recusas e status da origem por notas

• 422 — vencimento ausente: Informe data_vencimento (AAAA-MM-DD) para emissão de GNRE por notas. A política de vencimento é do contribuinte e a API não arbitra um vencimento padrão.
• 422 — pagamento ausente: Informe data_pagamento (AAAA-MM-DD) para emissão de GNRE por notas. A data de pagamento é escolha do contribuinte e define a validade da guia; a API não arbitra uma data padrão.
• 422 — nenhuma nota elegível: Nenhuma nota elegível para emissão de GNRE. com notas_ignoradas listando cada nota recusada e seu motivo_ignorado.
• ICMS-ST e FCP-ST recusados com motivo próprio: notas que carregam apenas vST/vFCPST são ignoradas com st_requer_ie_substituto / fcp_st_requer_ie_substituto; quando a nota tem outras parcelas emitíveis e carrega uma parcela de ST, ela aparece em parcelas_recusadas. Em ambos os casos, emita essas parcelas por valor direto informando a receita (e o detalhamento, quando aplicável).
• SP e ES não emitem via GNRE: notas com destino SP ou ES não são selecionadas — SP não publica nenhuma receita GNRE (use a API DARE-ICMS SP, /2/dare) e ES não publica as receitas que esta API compõe, 100102/100110/100129/100137 (use a API DUA-ES, /2/dua).
• Configuração da UF validada antes da reserva: cada receita do lote é conferida contra a configuração vigente da GNRE na UF favorecida. Recusas publicadas pela UF respondem 422 nomeando UF e receita (451 receita não cadastrada, 452 receita não relacionada a esta UF, 453 UF não cadastrada no ambiente, 454 UF não habilitada no ambiente, 455 nenhuma receita habilitada — e 422 também para receita ausente da lista da UF). Se a configuração não puder ser obtida (SEFAZ indisponível, falha de certificado), a emissão responde 503: a API nunca emite sem validar.

Emissão de GNRE
Prévia de Seleção por Notas

POST /2/gnre/notas/preview antecipa, sem emitir nada, a seleção de notas que POST /2/gnre/emissao faria para a mesma origem (periodo ou documentos) e o mesmo ambiente. A prévia executa o mesmo motor de seleção, a derivação de receitas e toda a validação de configuração de UF da emissão — inclusive as mesmas recusas com as mesmas mensagens — e devolve as guias previstas antes de qualquer confirmação.

Os parâmetros de origem são os mesmos da Emissão por Notas: ambiente e a origem (periodo ou documentos, mutuamente exclusivos). O url_notificacao não se aplica a este endpoint.

Campos da resposta:

Exemplo de requisição:

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/gnre/notas/preview

{
  "ambiente": 2,
  "periodo": {
    "data_inicio": "2026-07-01",
    "data_fim": "2026-07-31"
  }
}

Exemplo de resposta:

{
  "tipo": "gnre",
  "selecionadas": [
    {
      "fiscal_document_uuid": "8f14e45f-ceea-4d3e-a2e0-123456789012",
      "document_key": "35260700000000000000550010000012341123456789",
      "valor_icms_st": "0.00",
      "valor_difal": "362.30",
      "valor_icms_st_proprio": "0.00",
      "valor_fcp_st": "0.00",
      "valor_icms_uf_dest": "350.00",
      "valor_fcp_uf_dest": "12.30",
      "uf_destino": "GO",
      "guia_indicado": "gnre"
    }
  ],
  "ignoradas": [
    {
      "fiscal_document_uuid": "9d32fa10-bb21-4e7c-9100-987654321098",
      "document_key": "35260700000000000000550010000012441123456790",
      "valor_icms_st": null,
      "valor_difal": null,
      "motivo_ignorado": "st_requer_ie_substituto",
      "mensagem": "ICMS-ST (receita 100099) não pode ser emitido por notas: depende da inscrição estadual de substituto tributário do contribuinte na UF de destino, que não consta da nota. Emita esta guia por valor direto informando a receita."
    }
  ],
  "totais": { "icms_st": "0.00", "difal": "362.30", "total": "362.30" },
  "total_encontradas": 2,
  "total_omitidas": 0,
  "limite_por_requisicao": 100,
  "guias_previstas": [
    { "uf_favorecida": "GO", "receita": "100102", "tipo_gnre": 0, "quantidade_notas": 1, "valor": "350.00" },
    { "uf_favorecida": "GO", "receita": "100129", "tipo_gnre": 0, "quantidade_notas": 1, "valor": "12.30" }
  ]
}

Derivação de receitas por nota

Para cada nota, a receita GNRE é derivada das próprias parcelas de imposto declaradas na NF-e. Uma nota que carrega as duas parcelas abaixo gera duas guias previstas separadas — nunca dois itens de uma mesma guia — e cada guia é um documento pagável: a emissão confirma 2 guias e a cobrança conta 2 (uma unidade por guia). No exemplo acima, os totais refletem essa soma: totais.difal e totais.total totalizam 350.00 + 12.30 = 362.30, exatamente a soma de guias_previstas[].valor. Quando essa mesma nota também carrega uma parcela de substituição tributária (vST/vFCPST), a parcela é recusada com motivo próprio e aparece como uma terceira linha no bloco parcelas_recusadas[] da resposta — nunca é somada às guias derivadas e nunca é descartada em silêncio:

Os códigos "por Apuração" (100110 para DIFAL e 100137 para FCP) nunca substituem os acima automaticamente; para usá-los, informe o receita_override descrito mais abaixo.

ICMS-ST e FCP-ST — diferimento com recusa explícita

As recusas aparecem em duas superfícies diferentes:

• ignoradas[], com motivo_ignorado: a nota inteira ficou de fora da seleção. É o caso da nota que só carrega as parcelas de ST — sem DIFAL nem FCP emitíveis, ela não seleciona no endpoint.
• parcelas_recusadas[], com motivo, parcela e valor: a parcela recusada pertence a uma nota selecionada — a nota emitiu suas guias derivadas e a parcela de ST ficou de fora, declarada aberta em vez de mergulhada no total. É por isso que o mesmo par pode aparecer duas vezes na resposta: uma nota com vFCPUFDest e vFCPST figura nas guias previstas sob a receita 100129 e, sob a mesma document_key e a mesma receita 100129, no bloco de recusadas — o que distingue as duas linhas é o campo parcela.

No corpo de sucesso da emissão por notas, o bloco parcelas_recusadas[] também é anexado, quando existe recusa — o total da guia não cobre essas parcelas, e a resposta é o único lugar onde você fica sabendo disso no momento da emissão.

SP e ES — dois casos diferentes

As notas cuja UF de destino é SP ou ES não são selecionadas para GNRE, e as duas recusas são fatos distintos:

• SP não publica nenhuma receita GNRE — o portal responde "Nenhuma Receita para a UF selecionada" e SP não aparece no seletor de UF favorecida nem na lista das 25 UFs disponíveis. Notas com destino SP são indicadas com guia_indicado: "dare": utilize a API DARE-ICMS SP (/2/dare).
• ES tem receitas GNRE (incluindo a 100099), mas não publica nenhuma das receitas que esta API compõe (100102/100110/100129/100137). Notas com destino ES são indicadas com guia_indicado: "dua": utilize a API DUA-ES (/2/dua).

Override de receita e de detalhamento

Duas chaves opcionais permitem substituir a composição derivada (valores de 6 dígitos), tanto na emissão quanto na prévia. A substituição nunca recria uma parcela recusada (ICMS-ST/FCP-ST) e nunca pula a validação de configuração da UF:

Serviços
Consulta de Lote

Consulta o resultado do processamento de um lote de guias GNRE a partir do número do recibo SEFAZ. Com a emissão assíncrona, o recibo não é mais retornado na resposta imediata: ele fica disponível no campo identificador do webhook e no campo provider_identifier de GET /2/gnre/status/{uuid}.

Consulta de Lote
Por Recibo

Para consultar o resultado de um lote, envie uma requisição POST para /2/gnre/consulta.

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/gnre/consulta

{
  "ambiente": 2,
  "recibo": "12345678901234",
  "incluir_pdf_guias": "S"
}

Consulta de Lote
Resultado

A resposta contém a situação do processamento e o resultado de cada guia do lote.

Exemplo de resposta:

{
  "situacao_process": {
    "codigo": 402,
    "descricao": "Lote processado com sucesso"
  },
  "guias": [
    {
      "situacao_guia": 0,
      "dados": {
        "uf_favorecida": "MG",
        "tipo_gnre": 0,
        "valor_gnre": "150.00",
        "contribuinte_emitente": {
          "identificacao": "00000000000000",
          "razao_social": "Empresa Exemplo LTDA"
        },
        "itens_gnre": {
          "item": [
            {
              "receita": "100102",
              "detalhamento_receita": "000001",
              "valor": "150.00"
            }
          ]
        },
        "identificador_guia": "100102000000000"
      },
      "linha_digitavel": "123456789012345678901234567890123456789012345678",
      "codigo_barras": "12345678901234567890123456789012345678901234",
      "qrcode_payload": "0002012658...",
      "motivos_rejeicao": []
    }
  ],
  "pdf_guias": "JVBERi0xLjQKJdPr6eEK...",
  "noticias": []
}

Consulta de Lote
PDF e PIX

Quando a guia for processada com sucesso, a consulta pode retornar:

• linha_digitavel: linha digitável de 48 posições para pagamento em qualquer banco.
• codigo_barras: código de barras de 44 posições.
• qrcode_payload: payload do PIX (copia e cola) quando a UF/receita aceitar pagamento via PIX.
• pdf_guias: guia em formato PDF codificado em base64 quando incluir_pdf_guias=S.

Serviços
Consulta de Status

Consulta o status de uma emissão GNRE pelo uuid retornado na resposta imediata da emissão. Endpoint: GET /2/gnre/status/{uuid}. Prefira a notificação por webhook — ela chega assim que o desfecho existe.

A resposta base é:

{
  "status": "processando",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider_identifier": null
}

Os campos variam conforme o status:

Além dos campos por status, a resposta inclui campos adicionais ligados à origem da emissão, quando presentes:

Exemplo — status erro_comunicacao (resultado incerto; não dispara webhook):

{
  "status": "erro_comunicacao",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider_identifier": null,
  "message": "Status incerto. A guia pode ter sido emitida antes da falha de comunicação. Consulte a SEFAZ manualmente. Não reenvie a emissão antes dessa confirmação, para evitar um documento fiscal em duplicidade."
}

Configuração de UF

Consulta as configurações de uma UF para emissão de GNRE, incluindo receitas habilitadas, campos exigidos, tipos de guia aceitos e quantidades máximas.

Para consultar a configuração de uma UF, envie uma requisição GET para /2/gnre/config-uf/{uf}.

curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
"https://api.webmania.com.br/2/gnre/config-uf/MG?ambiente=2"

Resposta:

{
  "ambiente": 2,
  "uf": "MG",
  "situacao_consulta": {
    "codigo": 450,
    "descricao": "Consulta realizada com sucesso"
  },
  "receitas": [
    {
      "codigo": "100002",
      "nome": "ICMS CONSUMIDOR FINAL NÃO CONTRIBUINTE",
      "exige_contribuinte_emitente": "S",
      "exige_detalhamento_receita": "N",
      "exige_periodo_referencia": "S",
      "valor_exigido": "P",
      "exige_documento_origem": "S",
      "tipos_documentos_origem": ["01", "02"],
      "exige_contribuinte_destinatario": "S",
      "exige_data_vencimento": "S",
      "exige_data_pagamento": "N",
      "exige_convenio": "N",
      "exige_campos_adicionais": "S",
      "aceita_pg_pix": "S",
      "tipos_gnre": [0, 1]
    }
  ],
  "qtd_maximas": {
    "guias_por_lote": 100,
    "itens_por_guia": 100,
    "itens_por_lote": 1000
  },
  "tipos_gnre_da_uf": [0, 1, 2]
}

A resposta traz a configuração completa da UF. Campos de nível superior:

Cada entrada de receitas descreve os requisitos daquela receita na UF consultada:

Legenda dos campos de exigência: S = Sim (a receita exige ou aceita o campo), N = Não — exceto exige_convenio e exige_valor_fecp, que publicam a escala N/S/O descrita na tabela acima. Valores de valor_exigido:

• P = Principal
• T = Total
• A = Ambos
• N = Nenhum
• PO = Principal ou Outros
• TO = Total ou Outros
• AO = Ambos ou Outros

tipos_gnre × tipos_gnre_da_uf: tipos_gnre (dentro de cada receita) diz quais tipos de guia aquela receita aceita; tipos_gnre_da_uf (no nível superior) é a lista de permissão da UF. Na emissão, cada guia é validada contra a união das duas listas, e o lote contra os tetos de qtd_maximas. Valores: 0 = GNRE Simples (guia com um único item)
1 = Guia Múltiplos Documentos (vários itens de origem, mesma receita)
2 = Guia Múltiplas Receitas

Consulta de Guias

Consulta guias GNRE já emitidas por código de barras, número de controle ou documento de origem.

Para realizar a consulta, envie uma requisição POST para /2/gnre/consulta-guias.

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/gnre/consulta-guias

{
  "ambiente": 2,
  "consultas": [
    {
      "uf": "MG",
      "tipo_consulta": "C",
      "cod_barras": "12345678901234567890123456789012345678901234"
    }
  ]
}

A resposta imediata confirma o recebimento do lote de consultas — ela ainda não contém o resultado de cada consulta:

{
  "status": "processando",
  "recibo": "12345678901234",
  "data_hora_recibo": "2026-08-24T14:32:10-03:00",
  "tempo_estimado_proc": 5
}

O resultado das consultas é obtido depois, com POST /2/gnre/consulta-guias-resultado — ver Consulta de Guias • Resultado.

Consulta de Guias
Resultado

Consulta o resultado do processamento de um lote de consulta de guias a partir do recibo devolvido no envio. Envie uma requisição POST para /2/gnre/consulta-guias-resultado.

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/gnre/consulta-guias-resultado

{
  "ambiente": 2,
  "recibo": "12345678901234"
}

A resposta traz situacao_process.codigo e situacao_process.descricao e, quando o lote já foi processado, resultado.guia[] com uma entrada por consulta enviada. Cada guia carrega os campos documentados na tabela de resultado da consulta de lote — situacao_guia, dados (eco da consulta), linha_digitavel, codigo_barras, qrcode_payload e motivos_rejeicao. Enquanto situacao_process.codigo for 401 (lote em processamento), o bloco resultado não é retornado.

Infraestrutura

Os servidores da Webmania® estão localizados na Amazon AWS, líder global em cloud computing, na região us-east-1 (Leste dos EUA) com ponto de presença em sa-east-1 (São Paulo). Manter a sua estrutura perto de uma dessas duas localidades, garante um menor tempo de resposta nas requisições na API.

Utilizamos uma infraestrutura na Amazon AWS anycast de alta disponibilidade, o que significa que ao se comunicar com a API da Webmania® a requisição será redirecionada para o servidor mais próximo da sua localidade. As requisições dos endpoints são gerenciadas através de IPs estáticos, caso necessite autorize no firewall a comunicação com os IPs abaixo.

• 13.248.145.90
• 76.223.17.240

• 34.196.69.38
• 44.219.142.86

Limite de requisições

A API da Webmania® aplica limites de solicitação por método HTTP para evitar o mal uso da API e a sobrecarga dos servidores. Quando o limite é excedido, a requisição retorna erro 429 (Too Many Requests). Segue abaixo as especificações para uma correta integração:

• Taxas por requisição:
  - GET: 15 requisições por segundo.
  - POST: sem limite de requisições.
  - PUT/DELETE: 5 requisições por segundo.
  - Homologação: requisições de emissão em ambiente de homologação são limitadas a 1 requisição por segundo.
  Precisa de um volume maior de requisições? Por favor, entre em contato para liberação.
• Localização do servidor: O firewall bloqueia por padrão o IP de servidores em regiões com alto índice de ataques ou de baixa reputação. Caso a sua comunicação via GET no endpoint https://webmania.com.br/api/ ou https://api.webmania.com.br retorne 403 Erro Forbidden por engano, por favor, entre em contato para liberarmos o IP do seu servidor.
• Credenciais de acesso: Os endpoints exigem as credenciais de acesso válida e correta na HEADER da requisição, o envio incorreto é atribuído como uso indevido da API.
• URL de notificação: Realize a integração para obter todos os retornos da API via URL de notificação, dessa forma todos os processos podem ser realizados ao receber o retorno, como atualizar o banco de dados e o download do PDF da guia.