API de governo: o caminho do cadastro até a primeira chamada com dado real

A prefeitura contratou um sistema de agendamento e, na reunião de kickoff, alguém mostra a página do catálogo do Conecta gov.br: "tem API de consulta de CPF, dá para validar o cadastro já neste sprint". O desenvolvedor encontra a documentação, copia o endereço do exemplo e, sem credencial, sem termo assinado e sem ambiente de teste, começa a planejar chamadas com o CPF dos próprios colegas para ver o retorno.

A resposta curta: documentação pública não é acesso público. APIs de governo que tratam dado de cidadão exigem que um órgão ou entidade elegível solicite o acesso, justifique a finalidade, aceite termos de uso e receba credenciais, geralmente primeiro para um ambiente de teste. Até lá, a integração se desenvolve contra um simulador seu, com dados fictícios. A credencial, quando chegar, mora no servidor, e o log nunca guarda o retorno completo.

Por que a URL não basta

O Conecta gov.br é o programa de interoperabilidade do governo federal: ele organiza um catálogo de APIs para que órgãos e entidades da administração pública compartilhem dados entre si, em vez de pedir ao cidadão o mesmo documento várias vezes. A página "quero acessar as APIs do Conecta" descreve quem pode solicitar e o caminho a seguir. Confira ali as condições vigentes antes de prometer qualquer prazo, porque elas mudam e dependem da API.

O ponto central é que o acesso é concedido a uma instituição, para uma finalidade. Uma empresa contratada não vira consumidora da API por ter um contrato com a prefeitura; ela integra em nome do órgão, com a credencial que o órgão obteve e sob as regras que o órgão aceitou. Além disso, dados como CPF e situação cadastral são dados pessoais, e a LGPD exige base legal e finalidade definida para tratá-los, inclusive pelo poder público. O cadastro não é burocracia decorativa: é o registro de quem pode ver o quê e por quê.

O que costuma fazer parte do pedido

• Identificação do órgão ou entidade solicitante e de um responsável.
• Qual API, qual finalidade e qual serviço público vai usar os dados.
• Aceite dos termos de uso, com obrigações de segurança e de sigilo.
• Credenciais emitidas para o sistema consumidor, normalmente com um ambiente de homologação antes da produção.

Os detalhes exatos (formulário, quem aprova, tipo de credencial) variam por API e mudam com o tempo. Trate o que está escrito no portal e no catálogo naquele momento como a regra, e anote no repositório a data em que você leu, como recomenda o post sobre manual de integração com data.

Como integrar enquanto o acesso não sai

1. Confirme a elegibilidade com o órgão contratante antes de estimar o prazo. Se o órgão não pode solicitar, a funcionalidade precisa de outro desenho.
2. Escreva no repositório a finalidade e os campos realmente necessários. Se o agendamento só precisa saber se o CPF existe e o nome confere, não peça endereço nem data de nascimento.
3. Desenvolva contra um simulador seu, que responde no formato documentado com dados inventados, incluindo erros e indisponibilidade.
4. Quando a credencial de homologação chegar, guarde em cofre de segredos ou variável de ambiente do servidor. Nunca no front, nunca no repositório.
5. Use só a massa de teste que o ambiente oferecer, ou CPFs fictícios válidos apenas no algoritmo. Nada de CPF de colega.
6. Registre cada consulta com quem pediu, quando e para quê, com o CPF mascarado, sem o retorno completo.
7. Passe para produção só depois de testar falhas: credencial expirada, timeout, 404 e limite de requisições.

Um cliente server-side com token e timeout

Muitas APIs governamentais publicadas atrás de um gateway usam OAuth 2.0 no fluxo client credentials: o sistema troca id e segredo por um token de acesso de curta duração. Confira no catálogo qual é o mecanismo da API que você vai usar. O exemplo abaixo, em Node.js, mostra o padrão com endereços em variáveis de ambiente e campos de retorno fictícios:

// gov-client.js (roda só no servidor)
const TOKEN_URL = process.env.GOV_TOKEN_URL;
const API_URL = process.env.GOV_API_URL;

let cache = { token: null, expiraEm: 0 };

async function obterToken() {
  if (cache.token && Date.now() < cache.expiraEm - 60_000) return cache.token;

  const credenciais = Buffer
    .from(process.env.GOV_CLIENT_ID + ':' + process.env.GOV_CLIENT_SECRET)
    .toString('base64');

  const resp = await fetch(TOKEN_URL, {
    method: 'POST',
    headers: {
      Authorization: 'Basic ' + credenciais,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({ grant_type: 'client_credentials' }),
    signal: AbortSignal.timeout(10_000)
  });
  if (!resp.ok) throw new Error('Token recusado: HTTP ' + resp.status);

  const dados = await resp.json();
  cache = { token: dados.access_token, expiraEm: Date.now() + dados.expires_in * 1000 };
  return cache.token;
}

function mascararCpf(cpf) {
  return cpf.slice(0, 3) + '.***.***-' + cpf.slice(-2);
}

export async function consultarCpf(cpf, { requestId, usuarioId, finalidade }) {
  const token = await obterToken();
  const resp = await fetch(API_URL + '/' + encodeURIComponent(cpf), {
    headers: { Authorization: 'Bearer ' + token, Accept: 'application/json' },
    signal: AbortSignal.timeout(15_000)
  });

  console.info(JSON.stringify({
    evento: 'gov.consulta_cpf',
    requestId, usuarioId, finalidade,
    cpf: mascararCpf(cpf),
    status: resp.status
  }));

  if (resp.status === 404) return null;
  if (!resp.ok) throw new Error('API respondeu HTTP ' + resp.status);

  const dados = await resp.json();
  return { nome: dados.nome, situacao: dados.situacao };
}

Três decisões estão embutidas aqui. O token é reaproveitado até um minuto antes de expirar, em vez de pedir um novo a cada consulta. Os timeouts impedem que uma API lenta segure as requisições do seu sistema indefinidamente, um assunto aprofundado em timeout antes do infinito. E a função devolve só os campos que o agendamento usa: o resto do retorno não sai dessa função, não vai para o banco e não vai para o log.

Por que a credencial nunca vai para o front

Se o navegador chama a API do governo diretamente, a credencial está no JavaScript que qualquer pessoa baixa. Com ela, alguém consulta CPFs em nome do órgão, sem limite e sem rastro no seu sistema. O front chama o seu backend, que confere se o usuário está logado e tem permissão, registra a consulta e só então chama a API. Se a credencial vazar mesmo assim, troque primeiro e investigue depois; o procedimento de troca sem derrubar o sistema está em rotação em dois passos.

Erros comuns

• Testar com CPF de pessoa real. É tratamento de dado pessoal sem finalidade legítima, feito por quem nem tinha acesso autorizado.
• Prometer a funcionalidade antes de confirmar elegibilidade. O sprint termina com a tela pronta e uma integração que o órgão não pode solicitar.
• Credencial no front ou no repositório. Qualquer pessoa consulta dados em nome do órgão, e o vazamento é do órgão.
• Logar o retorno completo "para depurar". O log vira uma cópia não controlada da base cadastral, retida sem prazo.
• Chamar a API sem timeout. Uma instabilidade do lado do governo trava as threads do seu sistema e derruba o agendamento inteiro.
• Chamar a API de "aberta" porque a página é pública. A expectativa errada se espalha para o cliente e para o prazo.

Checklist

• O órgão contratante confirmou que é elegível e quem é o responsável pelo pedido.
• A finalidade e os campos necessários estão escritos no repositório, com a data da documentação lida.
• Existe um simulador com dados fictícios, incluindo respostas de erro.
• Credenciais estão em cofre ou variável de ambiente do servidor, separadas por ambiente.
• Todas as chamadas têm timeout e tratamento de 401, 404 e limite de requisições.
• O log registra quem consultou, quando, para quê e o CPF mascarado, sem o retorno.
• Nenhum teste usa dado de pessoa real.

Procure no histórico de testes e nos logs do seu projeto um CPF que não seja fictício: a chamada de teste usou dado de uma pessoa real?