OpenParable
Skip to content
← Back to skills

Govbr Integrator

Apps & Automation
govbr-integrator

Govbr Integrator is an Agent Skill for apps & automation published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Integração Gov.br (Login Único + APIs Conecta)

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/integration/govbr-integrator/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/govbr-integrator, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Integração com o ecossistema Gov.br: Login Único (OAuth 2.0/OpenID Connect), APIs do Conecta Gov.br e princípio "once-only".

Contexto

  • 166 milhões de usuários no Gov.br (2025)
  • Contas Ouro (biometria) superaram Bronze pela primeira vez
  • Conecta Gov.br: 1,1 bilhão de transações de dados em 2025
  • Princípio: "Não pedir ao cidadão dado que o governo já tem" (Lei 13.726/2018)

Login Único (OAuth 2.0 / OpenID Connect)

Fluxo de Autenticação

Cidadão → Tá na Mão → Redireciona Gov.br → Login → Callback → Token → Dados

1. Registro da Aplicação

Portal: https://acesso.gov.br/roteiro-tecnico/
Tipo: Web Application
Redirect URI: https://api.tanamao.com.br/auth/callback
Scopes: openid profile email govbr_confiabilidades

2. Iniciar Login

# backend/app/routers/auth.py
from authlib.integrations.starlette_client import OAuth

oauth = OAuth()
oauth.register(
    name="govbr",
    client_id=settings.GOVBR_CLIENT_ID,
    client_secret=settings.GOVBR_CLIENT_SECRET,
    server_metadata_url="https://sso.acesso.gov.br/.well-known/openid-configuration",
    client_kwargs={"scope": "openid profile email govbr_confiabilidades"},
)

@router.get("/auth/login")
async def login(request: Request):
    redirect_uri = request.url_for("auth_callback")
    return await oauth.govbr.authorize_redirect(request, redirect_uri)

3. Callback e Token

@router.get("/auth/callback")
async def auth_callback(request: Request):
    token = await oauth.govbr.authorize_access_token(request)
    userinfo = token.get("userinfo", {})

    # Dados retornados pelo Gov.br
    cpf = userinfo.get("sub")  # CPF é o "sub" no Gov.br
    nome = userinfo.get("name")
    email = userinfo.get("email")
    phone = userinfo.get("phone_number")
    nivel = userinfo.get("govbr_confiabilidades")  # bronze/prata/ouro

    # Criar ou atualizar sessão
    session = await create_session(cpf=cpf, nome=nome, nivel=nivel)
    return RedirectResponse(url=f"/dashboard?session={session.id}")

4. Níveis de Confiabilidade

class NivelGovBr(str, Enum):
    BRONZE = "bronze"   # Cadastro básico (CPF + validação facial)
    PRATA = "prata"     # Validação com banco ou biometria DENATRAN
    OURO = "ouro"       # Biometria TSE ou certificado digital

# Funcionalidades por nível
PERMISSOES_POR_NIVEL = {
    NivelGovBr.BRONZE: ["consultar_beneficios", "ver_checklist", "buscar_cras"],
    NivelGovBr.PRATA: ["consultar_cadunico", "gerar_carta", "pedir_medicamento"],
    NivelGovBr.OURO: ["assinar_documento", "atualizar_cadastro", "portabilidade"],
}

APIs Conecta Gov.br

Catálogo de APIs Disponíveis

Base URL: https://api.conectagov.estaleiro.serpro.gov.br

APIs relevantes:
├── /api-cadunico-servicos/v1/        → CadÚnico (situação cadastral)
├── /api-cadunico-servicos-dados/v1/  → CadÚnico (dados familiares)
├── /api-cpf-light/v2/               → Validação CPF (nome, nascimento)
├── /api-cep/v1/                     → Consulta CEP
└── /api-cnpj/v2/                    → Consulta CNPJ (cooperativas)

Autenticação nas APIs

# backend/app/services/conecta_govbr.py
import httpx

class ConectaGovBrService:
    def __init__(self):
        self.base_url = settings.CONECTA_GOVBR_URL
        self.client_id = settings.CONECTA_GOVBR_CLIENT_ID
        self.client_secret = settings.CONECTA_GOVBR_CLIENT_SECRET
        self._token = None
        self._token_expires = None

    async def _get_token(self) -> str:
        """Obtém ou renova token OAuth2 client_credentials."""
        if self._token and datetime.now() < self._token_expires:
            return self._token

        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/oauth2/jwt-token",
                data={"grant_type": "client_credentials"},
                auth=(self.client_id, self.client_secret),
            )
            data = response.json()
            self._token = data["access_token"]
            self._token_expires = datetime.now() + timedelta(seconds=data["expires_in"] - 60)
            return self._token

    async def get(self, endpoint: str, params: dict = None) -> dict:
        """GET autenticado em qualquer API do Conecta."""
        token = await self._get_token()
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"{self.base_url}{endpoint}",
                headers={"Authorization": f"Bearer {token}"},
                params=params,
            )
            response.raise_for_status()
            return response.json()

Princípio "Once-Only"

Auto-preenchimento de Formulários

async def auto_preencher_perfil(cpf: str, token_govbr: str) -> dict:
    """
    Preenche automaticamente dados do cidadão usando APIs Gov.br.
    Cidadão não precisa digitar o que o governo já sabe.
    """
    conecta = ConectaGovBrService()

    # CPF → nome, data nascimento
    dados_cpf = await conecta.get(f"/api-cpf-light/v2/{cpf}")

    # CadÚnico → renda, composição familiar
    dados_cadunico = await conecta.get(
        f"/api-cadunico-servicos-dados/v1/dp/dadosFamiliar/{cpf}"
    )

    return {
        "nome": dados_cpf.get("nome"),
        "nascimento": dados_cpf.get("nascimento"),
        "renda_per_capita": dados_cadunico.get("rendaFamiliarPerCapita"),
        "membros_familia": dados_cadunico.get("quantidadeMembros"),
        "municipio": dados_cadunico.get("municipio"),
        "uf": dados_cadunico.get("uf"),
        "fonte": "govbr_conecta",
    }

Variáveis de Ambiente

# .env
GOVBR_CLIENT_ID=seu_client_id_login_unico
GOVBR_CLIENT_SECRET=seu_client_secret_login_unico
GOVBR_REDIRECT_URI=https://api.tanamao.com.br/auth/callback
CONECTA_GOVBR_URL=https://api.conectagov.estaleiro.serpro.gov.br
CONECTA_GOVBR_CLIENT_ID=seu_client_id_conecta
CONECTA_GOVBR_CLIENT_SECRET=seu_client_secret_conecta

Arquivos Relacionados

  • backend/app/routers/auth.py - Rotas de autenticação
  • backend/app/services/conecta_govbr.py - Serviço Conecta Gov.br
  • backend/app/core/config.py - Configurações
  • backend/app/models/user.py - Modelo de usuário

Segurança

  • Tokens Gov.br NUNCA em logs
  • Sessão com TTL curto (Redis)
  • PKCE obrigatório para fluxo mobile
  • Validar state parameter contra CSRF
  • Nível mínimo Bronze para qualquer operação

Referências