APIs da Prefeitura do Rio

Referência completa das APIs municipais para integração com os sistemas da Prefeitura do Rio de Janeiro

A IplanRio mantém um conjunto de APIs padronizadas que permitem às secretarias municipais e parceiros consumir dados e serviços da Prefeitura do Rio de forma segura, rastreável e versionada.

Autenticação

Todas as APIs utilizam JWT Bearer tokens emitidos pelo Identidade Carioca (Keycloak municipal). Inclua o token em cada requisição:

Authorization: Bearer <seu-jwt-token>

Para obter um token, faça uma requisição ao endpoint de autenticação do seu realm:

curl -X POST https://identidade.carioca.rio/auth/realms/<realm>/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<client-id>" \
  -d "client_secret=<client-secret>"

Os escopos disponíveis variam por secretaria. Solicite à equipe da IplanRio os escopos adequados para o seu caso de uso.

APIs Disponíveis

Busca

Pesquisa centralizada em múltiplas coleções de dados municipais com ranking de relevância.

Catálogo

Discovery de serviços municipais com recomendação inteligente por perfil e grupo social.

RMI

Registro Municipal Integrado — dados de pessoas físicas, telefones e histórico de interações.

GO

Gestão de cursos e vagas de emprego disponibilizados pela Prefeitura.

eAi Agent

Gerenciamento de fluxos e ferramentas dos agentes de IA municipais.

Heimdall

Autenticação e autorização centralizadas para serviços municipais.

Encurtador de URLs

Encurtamento, rastreamento e gestão de URLs para campanhas municipais.

Subpav OSA SMS

Sistema Subpav OSA para gerenciamento de SMS e comunicações operacionais.

Surkai

Busca semântica avançada com embeddings para dados municipais.

Ambientes

Ambiente	Base URL	Uso
Produção	https://services.app.dados.rio	Sistemas em produção
Staging	https://services.staging.app.dados.rio	Testes e integração

Sempre use o ambiente de staging para desenvolvimento e testes. Nunca execute testes com carga ou dados de produção diretamente na produção.

Rate Limiting

As APIs aplicam rate limiting por secretaria e por cliente. Os limites são retornados nos headers de resposta:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1719446400

Ao atingir o limite, a API retorna 429 Too Many Requests. Implemente backoff exponencial nas suas integrações.

Erros Comuns

Código	Significado	Ação
401 Unauthorized	Token ausente ou expirado	Renovar o JWT
403 Forbidden	Escopo insuficiente	Solicitar escopos corretos à IplanRio
404 Not Found	Recurso não encontrado	Verificar o identificador enviado
422 Unprocessable Entity	Dados de entrada inválidos	Revisar o payload
429 Too Many Requests	Rate limit atingido	Aguardar e usar backoff exponencial
500 Internal Server Error	Erro do servidor	Contatar a IplanRio

Exemplos de Integração

Buscar um cidadão pelo CPF (RMI)

curl -X GET "https://services.app.dados.rio/rmi/api/v1/cidadao/12345678901" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Pesquisar serviços municipais (Busca)

curl -X POST "https://services.app.dados.rio/busca/api/v1/search" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "vacina infantil", "collections": ["saude", "sme"]}'

Suporte

Para dúvidas sobre APIs, acesso, escopos ou problemas técnicos:

• Discord IplanRio: Canal #suporte-apis
• Email: [e-mail]
• GitHub: prefeitura-rio