Capítulo 14 — Arquitetura de APIs e Integrações
Este capítulo estabelece as diretrizes técnicas para exposição, consumo, governança, segurança, versionamento e observabilidade das interfaces de integração da Plataforma de Relacionamento Digital com o Cidadão.
14.1 Objetivo do Capítulo
Este capítulo estabelece as diretrizes técnicas para exposição, consumo, governança, segurança, versionamento e observabilidade das interfaces de integração da Plataforma de Relacionamento Digital com o Cidadão.
As APIs não são tratadas como endpoints HTTP implementados individualmente por cada equipe. Elas constituem contratos de integração governados que conectam canais, serviços de domínio e sistemas externos de forma controlada, versionada e rastreável.
O capítulo cobre: classificação de APIs, API Gateway, padrões REST, contratos OpenAPI, versionamento, tratamento de erros, paginação, filtros, idempotência, autenticação, autorização, Tenant Context, rate limiting, integrações governamentais, Anti-Corruption Layer, resiliência e observabilidade.
14.2 Papel das APIs na Plataforma
As APIs são a principal interface síncrona entre canais, serviços e integrações que dependem de resposta imediata.
React (Portal / Painel)
React Native (App Mobile)
│
▼
API Gateway
│
▼
Serviço de Domínio (ex.: Request Service)
│
▼
Adapter de Integração (ex.: SEI Adapter)
│
▼
Sistema Externo (ex.: SEI!MG)
Comunicação síncrona é usada quando o chamador precisa de resposta dentro do fluxo corrente: autenticar, consultar catálogo, carregar solicitação, verificar disponibilidade de agenda, obter tarefas, consultar configuração.
Quando a operação pode ser executada posteriormente e de forma desacoplada, RabbitMQ é o mecanismo adequado — conforme definido no Capítulo 13.
14.3 Classificação de APIs
A plataforma classifica suas APIs em seis categorias com características, audiência e controles distintos.
| Classificação | Audiência | Autenticação | Tenant |
|---|---|---|---|
| Pública | Cidadãos, sistemas autorizados | IAM próprio, GOV.BR | Por tenant |
| Canal | Aplicações React e React Native internas | IAM + token de canal | Por tenant |
| Interna | Serviços de domínio entre si | Service-to-service | Por tenant |
| Administrativa | Gestores, administradores, PRODEMGE | IAM próprio | Por tenant ou global |
| Integração | Sistemas governamentais e corporativos externos | Credencial específica | Por tenant |
| Inteligência Artificial | AI Gateway, serviços de IA | IAM + tenant context | Por tenant obrigatório |
Cada API declara sua classificação no catálogo. A classificação determina os controles mínimos exigidos.
14.4 API Gateway
O API Gateway é o único ponto de entrada HTTP dos canais externos para o backend. Centraliza funções técnicas transversais sem implementar lógica de negócio.
Responsabilidades do Gateway:
- roteamento de requisições para serviços de domínio;
- terminação TLS;
- validação de token de autenticação;
- extração e propagação de identidade e Tenant Context;
- rate limiting por dimensão configurada;
- controle de CORS por origem autorizada;
- limite de payload;
- logging de acesso;
- coleta de métricas de entrada;
- propagação de correlationId e trace context.
Regra fundamental: o Gateway aplica controles técnicos transversais. A autorização de negócio (permissão para executar a operação no recurso específico do tenant) é sempre validada pelo serviço de domínio.
14.5 Backend for Frontend (BFF)
BFFs são adotados por canal quando há necessidade de composição de chamadas, transformação de resposta ou otimização de payload específica para React ou React Native.
Quando utilizados, BFFs: não duplicam regras de negócio; não possuem acesso direto a bancos de dados; não fazem autorização de negócio; compõem e transformam respostas de serviços de domínio.
A adoção de BFF por canal é registrada como ADR-085.
14.6 Padrões REST
14.6.1 Verbos HTTP
| Verbo | Uso |
|---|---|
| GET | Leitura de recurso ou coleção. Idempotente. Sem body. |
| POST | Criação de recurso ou execução de operação não idempotente. |
| PUT | Substituição idempotente de representação ou configuração completa. |
| PATCH | Alteração parcial de recurso. |
| DELETE | Remoção ou exclusão lógica quando o contrato adota essa semântica. |
14.6.2 Códigos HTTP
200 OK → leitura bem-sucedida
201 Created → criação bem-sucedida; Location header com URL do recurso
202 Accepted → operação assíncrona aceita; operationId para acompanhamento
204 No Content → sucesso sem corpo de resposta
400 Bad Request → requisição malformada ou inválida
401 Unauthorized → não autenticado
403 Forbidden → autenticado mas sem permissão
404 Not Found → recurso não encontrado (ou não acessível pelo tenant)
409 Conflict → conflito de estado (reutilização de Idempotency-Key com payload diferente)
412 Precondition Failed → ETag não corresponde (concorrência otimista)
422 Unprocessable Content → validação de negócio falhou
429 Too Many Requests → rate limit ou quota excedidos
500 Internal Server Error → erro interno não esperado
502 Bad Gateway → integração externa retornou erro
503 Service Unavailable → serviço temporariamente indisponível
504 Gateway Timeout → integração externa não respondeu no prazo
APIs não retornam 200 OK com { "success": false, "error": "..." } para representar falhas.
14.6.3 URLs
URLs usam substantivos que representam recursos, não verbos de operação:
✓ GET /requests/{id}
✓ POST /requests/{id}/submit
✗ GET /getRequest?id=123
✗ POST /submitRequest
URLs em kebab-case para recursos com mais de uma palavra. Identificadores em path variables. Parâmetros opcionais em query string. Extensão de arquivo nunca usada. Nomes de tabelas nunca expostos.
14.6.4 Convenção JSON
camelCase para nomes de campos em toda a plataforma. Mistura de convenções dentro do mesmo ecossistema de APIs é vedada.
{
"requestId": "uuid",
"serviceId": "uuid",
"submittedAt": "2026-07-15T10:30:00Z",
"citizenName": "João Silva"
}
14.6.5 Datas e Timestamps
Timestamps em ISO 8601 com timezone explícito UTC: 2026-07-15T10:30:00Z. Datas sem horário no formato 2026-07-15. O consumidor é responsável pela conversão para fuso local na apresentação.
14.6.6 Identificadores
Tratados como opacos pelos consumidores. O cliente não depende de sequência, tamanho ou composição interna do identificador. Quando existir identificador de negócio (protocolo, número de processo), ele é nomeado explicitamente no contrato.
14.7 Tratamento de Erros
14.7.1 Problem Details (RFC 9457)
Todas as respostas de erro seguem o padrão Problem Details:
{
"type": "https://platform.domain/problems/validation-error",
"title": "Validation failed",
"status": 422,
"code": "VALIDATION_ERROR",
"correlationId": "corr-a7f2-4b81-9c3d",
"errors": [
{ "field": "email", "code": "INVALID_FORMAT" },
{ "field": "birthDate", "code": "REQUIRED" }
]
}
APIs não expõem: stack trace, nome de tabela, SQL, caminho de arquivo, classe Java interna, segredo, URL interna ou configuração. A exceção é registrada internamente com correlationId. O consumidor recebe erro controlado com código estável.
14.8 Paginação
Por Offset
Para interfaces administrativas com navegação por página e volumes moderados:
GET /requests?page=0&size=20
{
"items": [...],
"page": 0,
"size": 20,
"totalElements": 1234,
"totalPages": 62
}
Por Cursor
Para feeds, histórico e grandes volumes:
GET /interactions?cursor=opaque-value&limit=50
{
"items": [...],
"nextCursor": "opaque-value",
"hasMore": true
}
O cursor é opaco — o consumidor não interpreta ou constrói seu valor. Limits máximos são definidos por API. Requisições com size=1000000 são rejeitadas.
14.9 Filtros e Ordenação
Filtros Simples
GET /requests?status=SUBMITTED&serviceId=abc
GET /requests?createdFrom=2026-07-01T00:00:00Z&createdTo=2026-07-31T23:59:59Z
Filtros Complexos
Quando a query string se torna inadequada:
POST /requests/search
{
"status": ["SUBMITTED", "IN_PROGRESS"],
"createdAt": { "from": "2026-07-01T00:00:00Z", "to": "2026-07-31T23:59:59Z" },
"serviceId": "abc"
}
Ordenação
GET /requests?sort=createdAt,desc&sort=status,asc
A API declara os campos ordenáveis. Nomes de colunas internas do banco nunca são aceitos como parâmetro de ordenação.
14.10 Idempotência
Idempotency-Key
Operações críticas de criação aceitam Idempotency-Key para suportar retentativas seguras em canais sujeitos a timeout ou reconexão (especialmente React Native):
POST /requests
Idempotency-Key: client-generated-uuid
Primeira requisição: processa, armazena resultado associado à chave, retorna 201. Requisição repetida com mesma chave e mesmo payload: retorna resultado armazenado. Mesma chave com payload diferente: retorna 409 Conflict.
A chave tem escopo tenant + subject + operation. Uma chave do tenant A não interfere no tenant B. O período de retenção é definido por operação.
ETag e Controle de Concorrência
APIs de atualização concorrente usam ETag ou versão explícita:
GET /requests/{id} → ETag: "18"
PATCH /requests/{id}
If-Match: "18" → 412 Precondition Failed se versão atual for 19
Evita sobrescrita silenciosa em atualizações concorrentes.
14.11 Contratos OpenAPI
Toda API governada possui contrato OpenAPI documentando: paths, métodos, parâmetros, headers, request body, responses, schemas, autenticação, exemplos e códigos de erro.
O contrato é armazenado em repositório versionado, revisado antes de publicação, e usado em testes de contrato automatizados. O pipeline detecta alterações incompatíveis entre versões.
Para APIs públicas e de canal: Design First (contrato antes da implementação). Para APIs internas de menor impacto: Code First com geração automática de OpenAPI, desde que o contrato seja governado.
Ciclo de Vida de API
Proposed → Designed → Reviewed → Implemented → Published → Active → Deprecated → Retired
O catálogo reflete o estado de cada API. APIs depreciadas publicam Sunset header com data de remoção.
14.12 Versionamento de APIs
Mudanças incompatíveis usam versionamento por URI:
/api/v1/requests
/api/v2/requests
A convenção é única em toda a plataforma. Não coexistem estratégias diferentes (/v1/, ?version=1, Accept: vnd.v1+json) sem justificativa documentada.
Mudanças compatíveis — não requerem nova versão: adicionar campo opcional; adicionar endpoint; adicionar parâmetro opcional; adicionar código de erro documentado.
Mudanças incompatíveis — requerem nova versão: remover campo; mudar tipo; mudar semântica; tornar campo opcional obrigatório; mudar formato de identificador.
Durante migração, o produtor mantém ambas as versões pelo período de depreciação acordado.
14.13 Autenticação
14.13.1 IAM Próprio
Responsável pela autenticação de usuários internos (atendentes, gestores, administradores) e de cidadãos com cadastro local. Emite tokens de acesso validados pelo API Gateway. O modelo de token e protocolo de autenticação é definido no Capítulo 17 (Segurança e Identidade).
14.13.2 Integração com GOV.BR
Fluxo OpenID Connect para autenticação federada de cidadãos:
Cidadão seleciona "Entrar com GOV.BR"
│
Plataforma redireciona para GOV.BR
│
GOV.BR autentica e retorna identidade
│
Plataforma valida resposta e vincula identidade interna
│
Plataforma emite sessão própria
│
Cidadão acessa recursos com token da plataforma
A plataforma nunca recebe ou armazena a senha GOV.BR. A identidade GOV.BR é vinculada à identidade interna por identificador estável do provedor — não por nome ou e-mail mutável. A autorização é sempre responsabilidade da plataforma.
14.13.3 Service-to-Service
Comunicação entre serviços de domínio usa autenticação mútua. As estratégias candidatas — mTLS, tokens de serviço com escopo limitado — são avaliadas e registradas como ADR-095. Serviços nunca aceitam requisições de outros serviços sem autenticação validada.
14.14 Autorização e Tenant Context
14.14.1 Modelo de Autorização
Identidade + Tenant + Perfil + Permissão + Recurso + Operação + Escopo
Autorização é verificada em dois pontos: no Gateway (validação do token e do tenant) e no serviço de domínio (permissão específica para o recurso e operação). A dupla verificação garante que configurações incorretas no gateway não concedam acesso indevido.
14.14.2 Tenant Context
O tenant não é aceito diretamente de header enviado pelo cliente como único fator. O Tenant Context é estabelecido pelo IAM a partir da identidade autenticada e seus vínculos. Se o cliente envia X-Tenant-Id: tenant-a, o backend valida se o subject autenticado tem vínculo ativo com tenant-a antes de aceitar o contexto.
O Tenant Context é propagado entre serviços via headers internos após validação no Gateway:
X-Platform-Tenant-Id: tenant-abc
X-Platform-Subject-Id: user-xyz
X-Platform-Correlation-Id: corr-123
Serviços receptores confiam nesses headers apenas quando a requisição vem de componente interno autenticado — nunca quando vêm diretamente da Internet.
14.14.3 BOLA — Broken Object Level Authorization
Toda operação em recurso específico valida se o recurso pertence ao tenant do contexto autenticado:
GET /requests/{requestId}
1. Autenticar subject
2. Resolver tenant do subject
3. Buscar Request {requestId}
4. Verificar que Request.tenantId == TenantContext.tenantId
5. Verificar que subject tem permissão REQUEST_READ
6. Retornar recurso
O passo 4 não é opcional. O ID do recurso na URL não é evidência de autorização.
14.15 Rate Limiting e Quotas
Rate limiting é aplicado em múltiplas dimensões conforme a API:
| Dimensão | Aplicação |
|---|---|
| IP | APIs públicas sem autenticação |
| Subject autenticado | APIs de canal e administrativas |
| Tenant | Todas as APIs tenant-scoped |
| Tenant + endpoint sensível | APIs de IA, criação em massa, exportação |
Resposta quando limite é excedido: 429 Too Many Requests com header Retry-After e código de erro estável (RATE_LIMIT_EXCEEDED, AI_TENANT_QUOTA_EXCEEDED).
Tenants podem ter limites distintos configurados contratualmente. As quotas de IA incluem: requisições por período, concorrência, tokens consumidos e modelos permitidos. A política de IA é aplicada na plataforma de IA, não apenas no Gateway — pois o Gateway não conhece tokens consumidos nem custo do modelo.
14.16 Catálogo Inicial de APIs por Domínio
| Domínio | Exemplos de Endpoints |
|---|---|
| Identity | POST /auth/login · POST /auth/logout · GET /auth/govbr · GET /me · POST /users |
| Tenant | GET /tenants/{id} · POST /tenants/{id}/activate · GET /tenants/{id}/modules |
| Citizen | GET /citizens/{id} · GET /citizens/{id}/360 · PUT /citizens/{id}/preferences |
| Service Catalog | GET /services · GET /services/{id} · POST /services/{id}/publish |
| Forms | GET /forms/{id}/versions/{v} · POST /forms/{id}/versions/{v}/publish |
| Request | POST /requests · POST /requests/{id}/submit · GET /protocols/{number} |
| Workflow | POST /process-instances · GET /process-instances/{id} · POST /process-instances/{id}/cancel |
| Task | GET /tasks · POST /tasks/{id}/claim · POST /tasks/{id}/complete |
| CRM | GET /interactions · POST /conversations/{id}/messages · POST /interactions/{id}/close |
| Communication | POST /communications · GET /messages · POST /templates/{id}/versions |
| Document | POST /documents · GET /documents/{id}/download · POST /documents/{id}/classify |
| Scheduling | GET /agendas/{id}/availability · POST /appointments · POST /appointments/{id}/cancel |
| Ombudsman | POST /manifestations · POST /manifestations/{id}/respond |
| Satisfaction | POST /feedback · GET /feedback/summary |
| Analytics | GET /dashboards · GET /metrics/{domain} · POST /reports/export |
| AI | POST /ai/chat · POST /ai/search · POST /ai/classify · POST /ai/knowledge-bases/{id}/search |
14.17 Anti-Corruption Layer
Integrações com sistemas externos cujos modelos diferem do domínio interno usam Anti-Corruption Layer (ACL).
Domínio da Plataforma
│
Integration Port (interface)
│
Adapter / ACL
│
Sistema Externo (SEI!MG, MG-Ouv, etc.)
O adapter traduz: Platform Request → External Model e External Response → Platform Integration Result.
Por que usar ACL: sem ACL, o Request Service acumularia conceitos específicos de cada sistema externo (seiUnidade, seiTipoProcedimento, ouvidoriaCodigo). Com ACL, o Request Service envia um ProcessRegistrationCommand e o adapter resolve a tradução para cada sistema. Sistemas externos futuros ganham adapter próprio sem alterar o domínio interno.
Implementação com Ports and Adapters:
// Port (interface do domínio)
public interface ProcessRegistrationPort {
ProcessRegistrationResult register(ProcessRegistrationCommand command);
}
// Adapter (implementação específica do SEI)
public class SeiProcessRegistrationAdapter implements ProcessRegistrationPort {
// tradução para o modelo SEI
}
14.18 Integrações Governamentais
14.18.1 GOV.BR
Autenticação federada de cidadãos via OpenID Connect. Os contratos e endpoints são os vigentes na documentação oficial do GOV.BR aplicável ao projeto. A plataforma segue o protocolo de autorização, validação de token e vínculo de identidade descritos no Capítulo 17.
14.18.2 MG API
Barramento de serviços estaduais. A plataforma consome serviços via MG API conforme autorizações e contratos disponibilizados. O adapter encapsula autenticação, base URL, headers específicos, mapeamento de erros, timeout e retry. Os contratos específicos são catalogados à medida que as integrações são implementadas.
14.18.3 SEI!MG
Integração com gestão documental governamental. Operações candidatas: registro de processo, inclusão de documento, consulta de situação. Operações que não exigem resposta imediata usam RabbitMQ com comando integration.sei.register.v1 e adapter como consumidor, beneficiando-se de retry, DLQ e absorção de indisponibilidade. O adapter isola nomenclaturas e códigos específicos do SEI do domínio da plataforma.
14.18.4 MG-Ouv
Integração com sistema estadual de ouvidoria. O adapter encapsula identificação de manifestações, classificação, protocolo, situação e mensagens específicas do MG-Ouv. A plataforma mantém seu próprio modelo de manifestação e não replica o modelo MG-Ouv como modelo central.
14.18.5 Data Lake MG
Integração para compartilhamento de dados com o repositório estadual quando formalmente estabelecida. Confirmada como necessária (ADR-103). Os datasets compartilhados, frequência, formato, autorização e política de retenção são definidos em instrumentos próprios da parceria.
14.18.6 SEG.ID
Integração com serviços de identidade e segurança estadual. O contrato e o escopo de uso são definidos conforme autorizações vigentes.
14.18.7 PRO SMTP
Envio de e-mails transacionais. O adapter encapsula conexão SMTP, autenticação, tratamento de bounces e rastreamento de entrega. O domínio de Comunicação solicita envio por contrato interno; o adapter resolve o canal.
14.19 Resiliência em Integrações Externas
Toda chamada a sistema externo aplica os seguintes controles:
Timeout
Toda chamada tem timeout configurado. Chamadas sem timeout criam dependências implícitas. O timeout é propagado (deadline propagation) em cadeias de chamadas.
Retry
Aplicado apenas a erros transitórios e operações idempotentes. Usa exponential backoff com jitter. Limitado por retry budget. Operações não idempotentes não têm retry automático.
Circuit Breaker
Isola sistemas externos degradados. Quando o limiar de falhas é excedido, o circuit breaker abre e retorna fallback sem pressionar o sistema externo. O estado é monitorado e emite métricas.
Bulkhead
Isola pools de conexão por integração. A saturação do SEI!MG não consome threads ou conexões reservadas para MG API ou GOV.BR.
Matriz de Resiliência por Integração
| Integração | Timeout | Retry | Circuit Breaker | Bulkhead | Async (RabbitMQ) |
|---|---|---|---|---|---|
| GOV.BR | ✓ | Ops idempotentes | ✓ | ✓ | — |
| MG API | ✓ | Ops idempotentes | ✓ | ✓ | Quando adequado |
| SEI!MG | ✓ | Ops idempotentes | ✓ | ✓ | Preferencial |
| MG-Ouv | ✓ | Ops idempotentes | ✓ | ✓ | Quando adequado |
| Data Lake MG | ✓ | ✓ | ✓ | ✓ | ✓ |
| SEG.ID | ✓ | Ops idempotentes | ✓ | ✓ | — |
| PRO SMTP | ✓ | ✓ | ✓ | ✓ | ✓ |
14.20 APIs de Inteligência Artificial
As APIs de IA são acessadas exclusivamente via AI Gateway. Serviços de domínio nunca chamam provedores de modelo diretamente.
O AI Gateway aplica: Tenant Context obrigatório; políticas de acesso por tenant; quotas de tokens e requisições; seleção de modelo conforme configuração; guardrails de entrada e saída; registro de métricas de consumo.
Streaming de Respostas
Chat e busca semântica podem usar streaming (Server-Sent Events ou equivalente) para que o canal apresente a resposta progressivamente. A tecnologia específica de streaming é avaliada por canal (Web vs. React Native) e registrada como ADR-107.
Endpoints de IA
POST /ai/chat → conversa com assistente
POST /ai/search → busca semântica
POST /ai/classify → classificação de texto
POST /ai/summarize → sumarização
POST /ai/knowledge-bases/{id}/search → busca na base de conhecimento do tenant
Todas requerem Tenant Context validado. Respostas incluem metadado de rastreabilidade (AI Request ID).
14.21 Webhooks e Callbacks
Webhooks para Sistemas Externos
Quando sistemas externos precisam receber notificações de eventos da plataforma, webhooks permitem entrega push. A plataforma assina cada entrega com HMAC-SHA256 usando chave por destinatário. O receptor valida a assinatura antes de processar. Reentregas seguem política de retry com backoff. Falhas persistentes são alertadas ao administrador da integração.
Callbacks Assíncronos
Operações assíncronas que retornam 202 Accepted disponibilizam endpoint de acompanhamento:
POST /admin/ai/knowledge-bases/{id}/reindex
→ 202 Accepted
{ "operationId": "op-uuid", "status": "ACCEPTED" }
GET /operations/{operationId}
→ { "status": "COMPLETED", "completedAt": "..." }
14.22 Segurança nas APIs
Princípios
- Tokens e API keys nunca em query string (aparecem em logs, histórico, proxies e traces)
- Content-Type
application/jsonexigido e validado - Responses de erro usam
Content-Type: application/problem+json - CORS configurado por ambiente com origens autorizadas explícitas —
Access-Control-Allow-Origin: *não é permitido em APIs autenticadas - Limites de payload separados: JSON API com limite pequeno; upload de documentos com rota e infraestrutura próprias
- CSRF avaliado conforme o mecanismo de autenticação final do canal Web
- Metadados de cliente (
X-Client-Platform,X-Client-Version) usados apenas para observabilidade e compatibilidade, nunca como mecanismo de autenticação
Logs de API
Logs incluem: timestamp, service, environment, correlationId, traceId, tenantId, route, method, status, duration.
Nunca registrados automaticamente em logs: token Authorization, cookies, senhas, payload integral, prompts com dados sensíveis, documentos.
14.23 Observabilidade de APIs
Métricas RED por API
Cada API emite: Rate (requisições por segundo), Errors (taxa de erros), Duration (latência P50/P95/P99).
Labels: método HTTP, template de rota (nunca ID de recurso), classe de status.
Correto: route="/requests/{requestId}"
Incorreto: route="/requests/123" ← alta cardinalidade
Rastreamento Distribuído
O trace iniciado no canal propaga-se por toda a cadeia:
Gateway [span: gateway]
│
Request Service [span: service, parent: gateway]
│
SEI Adapter [span: integration-sei, parent: service]
│
SEI!MG [chamada externa]
Trace ID e Correlation ID são propagados via W3C Trace Context (traceparent).
Métricas de Integração
Cada adapter emite métricas por operação: chamadas, sucesso, falha de negócio, falha técnica, timeout, retry, estado do circuit breaker, duração. Labels não incluem dados pessoais.
14.24 Governança de APIs
API Review
APIs públicas, administrativas críticas e integrações centrais passam por revisão antes de implementação ou exposição:
Checklist de revisão:
✓ Owner definido
✓ Classificação definida
✓ Escopo de tenant definido
✓ Autenticação definida
✓ Autorização definida
✓ OpenAPI disponível
✓ PII identificado
✓ Paginação definida
✓ Erros padronizados
✓ Idempotência avaliada
✓ Rate limit avaliado
✓ Observabilidade definida
✓ Compatibilidade avaliada
O objetivo não é burocracia para cada endpoint — é impedir divergência arquitetural em uma plataforma de grande porte com múltiplos times e múltiplos tenants.
14.25 Catálogo de Integrações
| Integração | Finalidade | Tipo | Status |
|---|---|---|---|
| GOV.BR | Identidade federada do cidadão | OIDC/OAuth2 | Confirmada |
| IAM Próprio | Identidade e perfis da plataforma | Protocolo próprio | Confirmado |
| MG API | Barramento de serviços estaduais | API REST | Contratos a levantar |
| SEI!MG | Gestão documental governamental | Adapter dedicado | Contratos a levantar |
| MG-Ouv | Ouvidoria estadual | Adapter dedicado | Contratos a levantar |
| Data Lake MG | Compartilhamento de dados | Eventos + fluxos | Confirmada |
| SEG.ID | Identidade e segurança estadual | A validar | Contratos a levantar |
| PRO SMTP | Envio de e-mail transacional | SMTP Adapter | Infraestrutura a confirmar |
| Provedores de IA | Modelos de linguagem | API via AI Gateway | Desacoplado de provedores |
| RabbitMQ | Mensageria interna | AMQP | Confirmado |
| Sistemas dos órgãos | Sistemas corporativos específicos | Adapter por órgão | Sob demanda |
14.26 Decisões Confirmadas
- APIs são a principal interface síncrona entre canais e serviços de domínio;
- o API Gateway é o único ponto de entrada HTTP dos canais externos;
- regras de negócio residem nos serviços de domínio, nunca no Gateway;
- autorização de recurso é sempre validada pelo serviço de domínio;
- Tenant Context é estabelecido por componente confiável, não por parâmetro do cliente;
- GOV.BR é o provedor de identidade federada para cidadãos (OpenID Connect);
- IAM próprio gerencia usuários internos e cidadãos com cadastro local;
- contratos HTTP são formalizados em OpenAPI;
- erros seguem Problem Details (RFC 9457);
- integrações externas são encapsuladas por adapters com Anti-Corruption Layer;
- a arquitetura de IA preserva desacoplamento de provedores via AI Gateway;
- serviços de domínio nunca dependem diretamente de provedores de LLM;
- tokens e credenciais nunca em query string ou logs;
- rate limiting é aplicado em múltiplas dimensões;
- toda chamada externa tem timeout configurado.
14.27 Benefícios da Arquitetura
- contratos claros e governados entre todos os participantes da plataforma;
- isolamento multi-tenant em todas as APIs e integrações;
- proteção dos domínios internos contra modelos externos por Anti-Corruption Layer;
- evolução controlada com versionamento e período de depreciação;
- resiliência nas integrações com timeout, retry, circuit breaker e bulkhead;
- rastreabilidade ponta a ponta por correlationId e trace context;
- desacoplamento de provedores de IA via AI Gateway;
- suporte a React e React Native com padrões específicos (CORS, Idempotency-Key, streaming);
- observabilidade integrada desde o Gateway até os sistemas externos.
14.28 Riscos e Mitigações
| Risco | Consequência | Mitigação |
|---|---|---|
| Autorização apenas no Gateway | Serviço retorna recursos de outro tenant | Autorização de negócio obrigatória no serviço de domínio |
| Tenant via header não validado | Acesso cruzado entre órgãos | Tenant Context derivado de identidade autenticada, não de header do cliente |
| Integração sem ACL | Domínio contaminado por modelo externo | Anti-Corruption Layer obrigatório para sistemas com modelo diferente |
| API sem versionamento | Breaking change quebra consumidores | Versionamento por URI, detectado no pipeline |
| Token em query string | Exposição em logs e histórico | Tokens somente em headers; validação no pipeline e code review |
| Rate limit só no Gateway | Quota de IA excedida sem controle granular | Quotas de IA aplicadas na plataforma de IA por tenant, modelo e tokens |
| Circuit breaker ausente em integração | Falha em cascata quando sistema externo degrada | Circuit breaker obrigatório em todos os adapters de integração externa |
| Streaming mal implementado em React Native | Falhas silenciosas em conexões móveis | Teste específico de streaming em condições de rede degradada |
14.29 Decisões Arquiteturais
| ADR | Tema |
|---|---|
| ADR-083 | Classificação de APIs e controles por categoria |
| ADR-084 | Produto e configuração do API Gateway |
| ADR-085 | Adoção e escopo de BFF por canal |
| ADR-086 | REST Guideline corporativo |
| ADR-087 | Convenção JSON e padrão de datas |
| ADR-088 | Estratégia de versionamento de APIs |
| ADR-089 | Problem Details — formato estendido |
| ADR-090 | Estratégia de paginação por tipo de API |
| ADR-091 | Idempotency-Key — implementação e retenção |
| ADR-092 | ETag e controle de concorrência otimista |
| ADR-093 | OpenAPI como contrato — Design First vs. Code First |
| ADR-094 | Tenant Context em HTTP — headers internos e validação |
| ADR-095 | Autenticação service-to-service (mTLS vs. tokens) |
| ADR-096 | Rate limiting — dimensões e política por categoria de API |
| ADR-097 | Anti-Corruption Layer — padrão de implementação |
| ADR-098 | Integração GOV.BR — contrato e fluxo OpenID Connect |
| ADR-099 | IAM Próprio — protocolo e modelo de tokens |
| ADR-100 | Integração MG API — catálogo e contratos |
| ADR-101 | Integração SEI!MG — protocolo e modo assíncrono |
| ADR-102 | Integração MG-Ouv — protocolo e adapter |
| ADR-103 | Integração Data Lake MG — formato e frequência |
| ADR-104 | Integração SEG.ID — escopo e protocolo |
| ADR-105 | Integração PRO SMTP — configuração e adapter |
| ADR-106 | Webhooks — política, assinatura e reentrega |
| ADR-107 | Streaming de IA — SSE vs. alternativas por canal |
| ADR-108 | Contratos das capacidades de IA no AI Gateway |
14.30 Rastreabilidade com o Anexo III
- Bloco 1 — Relacionamento e Atendimento: APIs de cidadão, CRM, comunicação, solicitações e satisfação; suporte a React e React Native; integração GOV.BR para autenticação.
- Bloco 2 — BPM: APIs de workflow, tarefas e processos; integração assíncrona com serviços externos via RabbitMQ + adapters.
- Bloco 3 — Gestão Documental: APIs de documentos com upload seguro, metadata e classificação; integração com SEI!MG via ACL.
- Bloco 4 — Dados e Inteligência: APIs de analytics e IA; integração com Data Lake MG; AI Gateway com quotas e isolamento por tenant.
- Bloco 5 — Integração e Interoperabilidade: arquitetura completa de adapters para ecossistema governamental (GOV.BR, MG API, SEI!MG, MG-Ouv, Data Lake MG, SEG.ID, SMTP); padrão ACL; webhooks para notificação externa.
- Bloco 6 — Infraestrutura, Segurança e Governança: API Gateway, Tenant Context, autenticação, autorização BOLA, rate limiting, observabilidade, OpenAPI e ciclo de vida de APIs.
14.31 Considerações Finais
A Arquitetura de APIs e Integrações estabelece os contratos que conectam todos os componentes da plataforma com canais, serviços de domínio e sistemas externos. A combinação de classificação de APIs, Tenant Context obrigatório, Anti-Corruption Layer, resiliência por camadas e observabilidade distribuída garante que a plataforma integre ecossistemas heterogêneos sem comprometer isolamento, segurança ou rastreabilidade.
O Capítulo 15 detalha a Arquitetura de Dados, Persistência e Cache, descrevendo a estratégia de banco operacional por domínio, Redis, busca vetorial e Data Lake por tenant.
14.32 Controle de Versão
| Campo | Valor |
|---|---|
| Documento | Documento Mestre — Plataforma de Relacionamento Digital com o Cidadão |
| Capítulo | 14 — Arquitetura de APIs e Integrações |
| Versão | 1.0 |
| Situação | Concluído |
| Última atualização | 15/07/2026 |
14.33 Rastreabilidade PRODEMGE
- [ANX-III] — Blocos 1 a 6 cobertos conforme seção 14.30.
- [ANX-IV] — Capacidades técnicas de API Gateway, autenticação federada, multi-tenancy, integração governamental, resiliência e IA governada.
- [ANX-V] — Sustentabilidade: OpenAPI como contrato, versionamento com período de depreciação, ACL isolando dependências externas, observabilidade integrada.
- [PNR] — Integrações confirmadas com GOV.BR, SEI!MG, MG API, MG-Ouv, Data Lake MG, SEG.ID e PRO SMTP.
- [EDITAL] — Plataforma interoperável, com APIs documentadas, integrada ao ecossistema governamental e com governança de contratos.
Capítulo 13 — Arquitetura de Eventos e Mensageria
Este capítulo apresenta a Arquitetura de Mensageria e RabbitMQ da Plataforma de Relacionamento Digital com o Cidadão.
Capítulo 15 — Arquitetura de Dados, Persistência e Cache
Este capítulo estabelece as diretrizes técnicas para armazenamento, isolamento, consistência, movimentação, retenção, auditoria, consulta e aceleração de dados da Plataforma de Relacionamento Digital com o Cidadão.