API: GNRE (Guia Nacional de Recolhimento de Tributos Estaduais)

Crie a guia a partir do XML do CT-e (modo recomendado) ou manualmente. Suporte a receitas 100099 (ICMS frete) e 100102 (ICMS-ST por Operação).

Visão geral

Toda a tela /gnre também está disponível por API. O fluxo recomendado é enviar o XML do CT-e: extraímos os dados (chaves, partes, base de cálculo, alíquota e UF favorecida), aplicamos a configuração da UF/receita e devolvemos a guia já calculada e, opcionalmente, validada e emitida no mesmo passo.

Autenticação

Use os headers X-FreteFlow-Key (formato prefix.secret) e X-FreteFlow-Signature (HMAC-SHA256 do body cru com o segredo da chave). Veja Autenticação.

Escopos necessários

read para GET; write para POST/PATCH/DELETE.

Listar guias

GET/api/public/v1/gnre/operationsAuth: API key

Filtros via query string: status, uf, receita.

Criar a partir do CT-e (recomendado)

POST/api/public/v1/gnre/operationsAuth: API key

Quando o body contiver o campo xml, entramos no modo "from-cte". Os demais campos passam a ser opcionais e usados como override.

Campo	Tipo	Descrição
external_id	string	Identificador no seu sistema.
xmlreq	string	XML completo do CT-e (modelo 57).
receita	enum	100099 (ICMS frete, padrão) \| 100102 (ICMS-ST operação).
uf_favorecida_override	string(2)	Força UF favorecida; por padrão usa a UF de fim do CT-e.
aliquota_override	number	Decimal (ex.: 0.12). Por padrão usa pICMS do CT-e ou a config da UF.
auto_validate	boolean	Se true, executa validações em seguida.
auto_emit	boolean	Se true, emite a guia (provider manual no momento).

Exemplo

bash

curl -X POST https://freteflow.fr.com.br/api/public/v1/gnre/operations \
  -H "X-FreteFlow-Key: $KEY" \
  -H "X-FreteFlow-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "INT-2026-0001",
    "xml": "<?xml version=\"1.0\"?>...<cteProc>...</cteProc>",
    "receita": "100099",
    "auto_validate": true,
    "auto_emit": false
  }'

Criar manualmente

POST/api/public/v1/gnre/operationsAuth: API key

Quando o body não contiver xml, validamos o payload manual:

Campo	Tipo	Descrição
receitareq	enum	100099 \| 100102
uf_favorecidareq	string(2)	UF de destino do imposto.
uf_origem	string(2)	UF de origem (opcional).
cnpj_contribuintereq	string	Contribuinte (geralmente o transportador). Aceita com/sem máscara.
ie_contribuinte	string	Inscrição estadual.
razao_contribuinte	string	Razão social.
cnpj_destinatario	string	Destinatário, quando aplicável.
ie_destinatario	string
razao_destinatario	string
cte_chave	string(44)	Chave do CT-e relacionado.
cte_numero	string
cte_serie	string
cte_emissao	ISO date
valor_base_calculoreq	number	Base de cálculo do ICMS.
aliquotareq	number	Decimal (ex.: 0.12 para 12%).
valor_fcp	number	Fundo de Combate à Pobreza.
valor_juros	number
valor_multa	number
valor_atualizacao	number
valor_icms_override	number	Sobrescreve o ICMS calculado (use se já vier do CT-e).
data_vencimento	ISO date	Vencimento da guia.
observacoes	string
auto_validate	boolean
auto_emit	boolean

Resposta

json

{
  "data": {
    "id": "uuid",
    "code": "GNRE-0001",
    "status": "rascunho",
    "receita": "100099",
    "uf_favorecida": "SP",
    "valor_base_calculo": 1500.00,
    "aliquota": 0.12,
    "valor_icms": 180.00,
    "valor_total": 180.00,
    "data_vencimento": "2026-05-25"
  },
  "validation": null,
  "emission": null
}

Ações

POST/api/public/v1/gnre/operations/{id}/validateAuth: API key

Roda o motor de validação. Códigos: GNRE-CFG-*, GNRE-CTE-*, GNRE-CALC-*.

POST/api/public/v1/gnre/operations/{id}/emitAuth: API key

Emite a guia via provedor configurado (atualmente manual: gera nº interno e registra eventos para conciliação financeira).

POST/api/public/v1/gnre/operations/{id}/cancelAuth: API key

Campo	Tipo	Descrição
motivoreq	string	Mín. 3 caracteres.

POST/api/public/v1/gnre/operations/{id}/mark-paidAuth: API key

Campo	Tipo	Descrição
data_pagamentoreq	ISO date
comprovante_url	string	Link público do comprovante.
comprovante_filename	string

Webhooks

Eventos disparados:

gnre.created — guia criada (manual ou via CT-e).
gnre.status_changed — qualquer mudança de status.
gnre.paid — marcada como paga.

Roadmap

A emissão na SEFAZ via webservice (com certificado A1 e XMLDSig) está prevista para a próxima fase. Hoje a emissão grava número interno e PDF placeholder, suficiente para registrar a obrigação e conciliar o pagamento no Financeiro.