Radar de Débitos¶

Serviço de consulta dos débitos de um cliente apurados na Situação Fiscal. Há duas formas de consulta:

Agrupada — um resumo por código de receita (quantidade e totais);
Detalhada — cada débito individualmente.


Base URL	`https://integracao.gob.com.br/api/v1/services`
Formato	JSON (`Content-Type: application/json`)
Autenticação	Cabeçalho `X-Api-Key` (a mesma chave da API de dados)

Referência interativa deste serviço

É uma consulta, mas usa POST

Os dois endpoints não alteram nada: apenas consultam. Eles usam o método POST porque os parâmetros vão no corpo da requisição, em JSON.

Método	Rota	O que faz
POST	`/radar-debito-agrupado`	Débitos agrupados por código de receita
POST	`/radar-debito`	Débitos detalhados, um a um

As rotas são relativas à Base URL: /radar-debito significa https://integracao.gob.com.br/api/v1/services/radar-debito.

Conceitos¶

Protocolo de avaliação: Cada avaliação da Situação Fiscal de um cliente gera um protocolo. Os débitos são consultados para um cliente e um protocolo.
Origem dos dados: Os débitos são os registrados na avaliação identificada pelo protocolo — não é uma consulta em tempo real à Receita a cada chamada. Para obter uma posição mais atual, use o protocolo da avaliação mais recente do cliente. Você pode repetir a consulta sempre que precisar.
Débitos em aberto (PDCC): Débitos devedores ou a vencer.
Débitos com exigibilidade suspensa (EXCC): Débitos cuja cobrança está suspensa.

Cliente sem débitos

Muitos clientes simplesmente não têm débitos. Nesse caso a consulta funciona normalmente e as listas vêm vazias ([]) — isso não é um erro.

Obtendo os parâmetros¶

O corpo das duas consultas leva o id do cliente e o protocolo de avaliação. Ambos vêm da API de dados, com a mesma API key:

Id do cliente (/api/v1/Account)Protocolo (/api/v1/SituacaoFiscalFederal)

O account_id é o id da entidade Account. Para achar pelo CNPJ/CPF (campo sicCode, somente números):

const searchParams = {
  select: ["id", "name", "sicCode"],
  where: [{ type: "equals", attribute: "sicCode", value: "12345678000199" }]
};
const url = `https://integracao.gob.com.br/api/v1/Account?searchParams=${encodeURIComponent(JSON.stringify(searchParams))}`;

O protocolo_id é o campo protocoloAvaliacao da entidade SituacaoFiscalFederal. Para pegar o mais recente de um cliente, ordene pela data da análise (dataHoraAnalise):

const searchParams = {
  select: ["id", "protocoloAvaliacao", "dataHoraAnalise"],
  where: [{ type: "equals", attribute: "accountId", value: "5f8e7d6c5b4a39281" }],
  orderBy: "dataHoraAnalise",
  order: "desc",
  maxSize: 1
};
const url = `https://integracao.gob.com.br/api/v1/SituacaoFiscalFederal?searchParams=${encodeURIComponent(JSON.stringify(searchParams))}`;

Campos-chave de `SituacaoFiscalFederal`¶

Campo	Descrição
`accountId`	Id do cliente — é o `account_id` do Radar
`accountName`	Nome do cliente
`protocoloAvaliacao`	Protocolo da avaliação — é o `protocolo_id` do Radar
`dataHoraAnalise`	Data e hora da análise (`AAAA-MM-DD HH:MM:SS`)
`status`	Resultado da avaliação: `regular`, `irregular` ou `regularizado`

Clientes sem avaliação e status da avaliação

Um cliente sem registro em SituacaoFiscalFederal não tem protocolo e, portanto, não pode ser consultado no Radar.
O status irregular não garante débitos no Radar: um cliente irregular pode vir com as listas vazias.

Consultar vários clientes¶

Para trazer os débitos de todos os clientes, liste SituacaoFiscalFederal uma única vez (em páginas), fique com o protocolo mais recente de cada cliente e chame o Radar para cada um:

PythonJavaScript (Node 18+)

import json, os, time, requests

BASE = "https://integracao.gob.com.br/api/v1"
HEADERS = {"X-Api-Key": os.environ["GOB_API_KEY"], "Accept": "application/json"}


def protocolos_mais_recentes():
    """Um protocolo (o mais recente) por cliente, lendo SituacaoFiscalFederal em páginas."""
    por_cliente, offset = {}, 0
    while True:
        sp = {"select": ["accountId", "accountName", "protocoloAvaliacao", "dataHoraAnalise"],
              "orderBy": "dataHoraAnalise", "order": "desc", "maxSize": 200, "offset": offset}
        r = requests.get(f"{BASE}/SituacaoFiscalFederal", params={"searchParams": json.dumps(sp)}, headers=HEADERS)
        r.raise_for_status()
        dados = r.json()
        for s in dados["list"]:
            por_cliente.setdefault(s["accountId"], s)  # vem do mais recente para o mais antigo
        offset += len(dados["list"])
        if not dados["list"] or offset >= dados["total"]:
            return list(por_cliente.values())


def radar_agrupado(account_id, protocolo_id):
    corpo = {"account_id": account_id, "protocolo_id": protocolo_id}
    for espera in (5, 15, 60, None):  # novas tentativas só para erros temporários
        r = requests.post(f"{BASE}/services/radar-debito-agrupado", headers=HEADERS, json=corpo)
        if r.status_code not in (500, 502, 503, 504) or espera is None:
            return r
        time.sleep(espera)


for s in protocolos_mais_recentes():
    r = radar_agrupado(s["accountId"], s["protocoloAvaliacao"])
    if r.status_code != 200:
        print(f"{s['accountName']}: erro {r.status_code} {r.text[:120]}")
        continue
    grupos = r.json()["Agrupamento"]
    aberto = sum(g["SaldoDevedorTotal"] for g in grupos["PDCC"])
    suspenso = sum(g["SaldoDevedorTotal"] for g in grupos["EXCC"])
    print(f"{s['accountName']}: em aberto R$ {aberto:.2f} | suspenso R$ {suspenso:.2f}")

const BASE = "https://integracao.gob.com.br/api/v1";
const headers = { "X-Api-Key": process.env.GOB_API_KEY, "Accept": "application/json" };
const esperar = (s) => new Promise((ok) => setTimeout(ok, s * 1000));

// Um protocolo (o mais recente) por cliente, lendo SituacaoFiscalFederal em páginas
async function protocolosMaisRecentes() {
  const porCliente = new Map();
  let offset = 0;
  while (true) {
    const sp = { select: ["accountId", "accountName", "protocoloAvaliacao", "dataHoraAnalise"],
                 orderBy: "dataHoraAnalise", order: "desc", maxSize: 200, offset };
    const r = await fetch(`${BASE}/SituacaoFiscalFederal?searchParams=${encodeURIComponent(JSON.stringify(sp))}`, { headers });
    if (!r.ok) throw new Error(`${r.status}: ${r.headers.get("X-Status-Reason")}`);
    const dados = await r.json();
    for (const s of dados.list) if (!porCliente.has(s.accountId)) porCliente.set(s.accountId, s);
    offset += dados.list.length;
    if (!dados.list.length || offset >= dados.total) return [...porCliente.values()];
  }
}

async function radarAgrupado(accountId, protocoloId) {
  const body = JSON.stringify({ account_id: accountId, protocolo_id: protocoloId });
  for (const espera of [5, 15, 60, null]) {  // novas tentativas só para erros temporários
    const r = await fetch(`${BASE}/services/radar-debito-agrupado`, {
      method: "POST", headers: { ...headers, "Content-Type": "application/json" }, body
    });
    if (![500, 502, 503, 504].includes(r.status) || espera === null) return r;
    await esperar(espera);
  }
}

for (const s of await protocolosMaisRecentes()) {
  const r = await radarAgrupado(s.accountId, s.protocoloAvaliacao);
  if (r.status !== 200) {
    console.log(`${s.accountName}: erro ${r.status} ${(await r.text()).slice(0, 120)}`);
    continue;
  }
  const { PDCC, EXCC } = (await r.json()).Agrupamento;
  const soma = (lista) => lista.reduce((t, g) => t + g.SaldoDevedorTotal, 0);
  console.log(`${s.accountName}: em aberto R$ ${soma(PDCC).toFixed(2)} | suspenso R$ ${soma(EXCC).toFixed(2)}`);
}

Corpo da requisição¶

Igual nas duas consultas:

{
  "account_id": "5f8e7d6c5b4a39281",
  "protocolo_id": "20260101.0001.12345678000199"
}

Campo	Tipo	Descrição
`account_id`	string	Obrigatório. Id do cliente (1 a 60 caracteres)
`protocolo_id`	string	Obrigatório. Protocolo de avaliação da Situação Fiscal (1 a 60 caracteres)

Envie os identificadores exatamente como retornados pela API de dados, sem espaços nem outros caracteres.

Débitos agrupados¶

POST /radar-debito-agrupado

Um resumo por código de receita: quantos débitos, valor original total e saldo devedor total, separados em débitos em aberto e com exigibilidade suspensa.

Linux / macOSWindows (PowerShell)

curl -i -X POST "https://integracao.gob.com.br/api/v1/services/radar-debito-agrupado" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  --data-raw '{"account_id": "5f8e7d6c5b4a39281", "protocolo_id": "20260101.0001.12345678000199"}'

$body = @{
  account_id   = "5f8e7d6c5b4a39281"
  protocolo_id = "20260101.0001.12345678000199"
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "https://integracao.gob.com.br/api/v1/services/radar-debito-agrupado" `
  -Headers @{ "X-Api-Key" = "SUA_CHAVE_AQUI"; "Accept" = "application/json" } `
  -ContentType "application/json; charset=utf-8" `
  -Body $body

Dicas para o PowerShell

Para ver a resposta inteira, acrescente | ConvertTo-Json -Depth 6 — a exibição padrão trunca objetos aninhados.
Em erros (4xx/5xx), o Invoke-RestMethod lança uma exceção; o corpo com o detail fica em $_.ErrorDetails.Message.

Resposta¶

{
  "NI": "12345678000199",
  "Agrupamento": {
    "PDCC": [
      {
        "CodigoReceita": "5440",
        "Tributo": "MAED - DCTFWEB",
        "ValorOriginalTotal": 1200.0,
        "SaldoDevedorTotal": 1200.0,
        "Quantidade": 4
      },
      {
        "CodigoReceita": "1708",
        "Tributo": "IRRF",
        "ValorOriginalTotal": 8.5,
        "SaldoDevedorTotal": 8.5,
        "Quantidade": 2
      }
    ],
    "EXCC": [
      {
        "CodigoReceita": "1082",
        "Tributo": "CP-SEGUR.",
        "ValorOriginalTotal": 10000.0,
        "SaldoDevedorTotal": 9800.0,
        "Quantidade": 1
      }
    ]
  }
}

Campo	Descrição
`NI`	CNPJ/CPF do cliente, somente números
`Agrupamento.PDCC`	Grupos de débitos em aberto
`Agrupamento.EXCC`	Grupos de débitos com exigibilidade suspensa
`CodigoReceita`	Código de receita do grupo (sem a variação; ex.: `1708`). Vem vazio (`""`) no grupo do Simples Nacional
`Tributo`	Nome do tributo
`ValorOriginalTotal`	Soma dos valores originais do grupo — número, até 2 casas decimais
`SaldoDevedorTotal`	Soma dos saldos devedores do grupo — número, até 2 casas decimais
`Quantidade`	Quantos débitos compõem o grupo

Cada lista vem ordenada por SaldoDevedorTotal, do maior para o menor.
Se não houver débitos em uma das origens, a lista correspondente vem vazia ([]).

Débitos detalhados¶

POST /radar-debito

Cada débito individualmente, com as duas origens reunidas numa única lista.

Linux / macOSWindows (PowerShell)

curl -i -X POST "https://integracao.gob.com.br/api/v1/services/radar-debito" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  --data-raw '{"account_id": "5f8e7d6c5b4a39281", "protocolo_id": "20260101.0001.12345678000199"}'

$body = @{
  account_id   = "5f8e7d6c5b4a39281"
  protocolo_id = "20260101.0001.12345678000199"
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "https://integracao.gob.com.br/api/v1/services/radar-debito" `
  -Headers @{ "X-Api-Key" = "SUA_CHAVE_AQUI"; "Accept" = "application/json" } `
  -ContentType "application/json; charset=utf-8" `
  -Body $body

Resposta¶

{
  "resultado": {
    "NI": "12345678000199",
    "DEBITOS": [
      {
        "tabela": "PDCC",
        "tributo": "IRRF",
        "codRec": "1708-06",
        "dtVenc": "20/01/2026",
        "vlOrig": "4,25",
        "vlSlDec": "4,25",
        "tipoPA": "5",
        "dtPAEx": "12/2025",
        "paramDarfNum": "AQIDBAUGBwgJCgsMDQ4PEA...",
        "paramDarf": null,
        "paramDASN": null,
        "situacao": "DEVEDOR"
      },
      {
        "tabela": "EXCC",
        "tributo": "CP-SEGUR.",
        "codRec": "1082-01",
        "dtVenc": "20/02/2026",
        "vlOrig": "10.000,00",
        "vlSlDec": "9.800,00",
        "tipoPA": "5",
        "dtPAEx": "01/2026",
        "paramDarfNum": "AQIDBAUGBwgJCgsMDQ4PEB...",
        "paramDarf": null,
        "paramDASN": null,
        "situacao": "AVENCER"
      }
    ]
  }
}

Campo	Descrição
`resultado.NI`	CNPJ/CPF do cliente, somente números
`resultado.DEBITOS`	Lista de débitos (em aberto e com exigibilidade suspensa juntos)
`tabela`	Origem do débito: `PDCC` (em aberto) ou `EXCC` (exigibilidade suspensa)
`tributo`	Nome do tributo
`codRec`	Código de receita com a variação (ex.: `1708-06`). Vem vazio (`""`) nos débitos do Simples Nacional
`dtPAEx`	Período de apuração / exercício (ex.: `06/2026` ou `01/08/2025`)
`dtVenc`	Data de vencimento (`DD/MM/AAAA`)
`vlOrig`	Valor original
`vlSlDec`	Saldo devedor
`situacao`	Situação do débito (ex.: `DEVEDOR`, `AVENCER`)
`tipoPA`	Tipo do período de apuração, como informado pela Receita
`paramDarfNum`, `paramDarf`, `paramDASN`	Parâmetros de emissão da guia, quando existirem: `paramDarfNum`/`paramDarf` para DARF, `paramDASN` para débitos do Simples Nacional

Valores vêm como texto, no formato brasileiro

No detalhado, vlOrig e vlSlDec são texto com ponto de milhar e vírgula decimal (ex.: "10.000,00"). Converta antes de calcular — um parseFloat("10.000,00") direto resulta em 10. Exemplo em JavaScript:

const valor = Number("10.000,00".replace(/\./g, "").replace(",", "."));  // 10000

Já no agrupado, os totais vêm como número.

Datas e demais valores vêm como informados pela Receita.
Campos sem informação vêm como null.
Se o cliente não tiver débitos, DEBITOS vem vazio ([]).

Erros¶

Os erros vêm com corpo JSON no formato:

{ "detail": "mensagem" }

A exceção é o 401 de autenticação, que vem sem corpo.

Status	Quando acontece	Mensagem (`detail`)
401	Chave ausente, inválida ou desativada	Sem corpo
404	Cliente inexistente ou sem permissão para a chave	`"Account não encontrada ou sem permissão"`
404	Protocolo não encontrado para o cliente informado	`"Protocolo não encontrado para esta conta"`
422	Campo faltando, vazio ou com tipo errado	`"Corpo da requisição inválido: protocolo_id ausente ou inválido"` (ou `account_id`)
422	Campo com mais de 60 caracteres ou com caracteres inválidos	`"Corpo da requisição inválido: account_id e protocolo_id são obrigatórios, devem ter entre 1 e 60 caracteres e não podem conter caracteres inválidos."` — se o campo inválido for o `account_id`: `"Corpo da requisição inválido: account_id ausente ou inválido"`
422	Corpo que não é um JSON válido	`"Corpo da requisição inválido: JSON malformado"`
500	Erro inesperado ao consultar	`"Erro ao consultar débitos"` (detalhado) / `"Erro ao consultar débitos consolidados"` (agrupado) / `"Erro interno do servidor"`
502	Falha em serviço do qual a consulta depende	`"Erro em serviço externo"` / `"Serviço temporariamente indisponível. Tente novamente mais tarde."`
503	Serviço temporariamente indisponível	`"Serviço indisponível no momento. Tente novamente mais tarde."`
504	Tempo esgotado ao validar o acesso	`"Timeout ao validar acesso"`

Como tratar¶

404 e 422: não repita a chamada sem corrigir os dados enviados.
401: confira a chave; se estiver correta, fale com o suporte.
500, 502, 503 e 504: erro temporário. Tente novamente mais tarde, de preferência com espera crescente entre as tentativas (ex.: 5 s, 15 s, 60 s). Se persistir, acione o suporte.
Um cliente que a sua chave não pode acessar responde 404, igual a um cliente que não existe. O mesmo vale para um protocolo de outro cliente.

Dados sensíveis nas respostas

As respostas trazem o CNPJ/CPF do cliente e os parâmetros de emissão de guias. Evite registrá-las em logs ou expô-las fora do seu sistema.

Radar de Débitos¶

Conceitos¶

Obtendo os parâmetros¶

Campos-chave de SituacaoFiscalFederal¶

Consultar vários clientes¶

Corpo da requisição¶

Débitos agrupados¶

Resposta¶

Débitos detalhados¶

Resposta¶

Erros¶

Como tratar¶

Campos-chave de `SituacaoFiscalFederal`¶