Relacionamento Digitalcom o Cidadão
Parte III — Arquitetura
Parte III — ArquiteturaCapítulo 14

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çãoAudiênciaAutenticaçãoTenant
PúblicaCidadãos, sistemas autorizadosIAM próprio, GOV.BRPor tenant
CanalAplicações React e React Native internasIAM + token de canalPor tenant
InternaServiços de domínio entre siService-to-servicePor tenant
AdministrativaGestores, administradores, PRODEMGEIAM próprioPor tenant ou global
IntegraçãoSistemas governamentais e corporativos externosCredencial específicaPor tenant
Inteligência ArtificialAI Gateway, serviços de IAIAM + tenant contextPor 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

VerboUso
GETLeitura de recurso ou coleção. Idempotente. Sem body.
POSTCriação de recurso ou execução de operação não idempotente.
PUTSubstituição idempotente de representação ou configuração completa.
PATCHAlteração parcial de recurso.
DELETERemoçã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ãoAplicação
IPAPIs públicas sem autenticação
Subject autenticadoAPIs de canal e administrativas
TenantTodas as APIs tenant-scoped
Tenant + endpoint sensívelAPIs 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ínioExemplos de Endpoints
IdentityPOST /auth/login · POST /auth/logout · GET /auth/govbr · GET /me · POST /users
TenantGET /tenants/{id} · POST /tenants/{id}/activate · GET /tenants/{id}/modules
CitizenGET /citizens/{id} · GET /citizens/{id}/360 · PUT /citizens/{id}/preferences
Service CatalogGET /services · GET /services/{id} · POST /services/{id}/publish
FormsGET /forms/{id}/versions/{v} · POST /forms/{id}/versions/{v}/publish
RequestPOST /requests · POST /requests/{id}/submit · GET /protocols/{number}
WorkflowPOST /process-instances · GET /process-instances/{id} · POST /process-instances/{id}/cancel
TaskGET /tasks · POST /tasks/{id}/claim · POST /tasks/{id}/complete
CRMGET /interactions · POST /conversations/{id}/messages · POST /interactions/{id}/close
CommunicationPOST /communications · GET /messages · POST /templates/{id}/versions
DocumentPOST /documents · GET /documents/{id}/download · POST /documents/{id}/classify
SchedulingGET /agendas/{id}/availability · POST /appointments · POST /appointments/{id}/cancel
OmbudsmanPOST /manifestations · POST /manifestations/{id}/respond
SatisfactionPOST /feedback · GET /feedback/summary
AnalyticsGET /dashboards · GET /metrics/{domain} · POST /reports/export
AIPOST /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çãoTimeoutRetryCircuit BreakerBulkheadAsync (RabbitMQ)
GOV.BROps idempotentes
MG APIOps idempotentesQuando adequado
SEI!MGOps idempotentesPreferencial
MG-OuvOps idempotentesQuando adequado
Data Lake MG
SEG.IDOps 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/json exigido 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çãoFinalidadeTipoStatus
GOV.BRIdentidade federada do cidadãoOIDC/OAuth2Confirmada
IAM PróprioIdentidade e perfis da plataformaProtocolo próprioConfirmado
MG APIBarramento de serviços estaduaisAPI RESTContratos a levantar
SEI!MGGestão documental governamentalAdapter dedicadoContratos a levantar
MG-OuvOuvidoria estadualAdapter dedicadoContratos a levantar
Data Lake MGCompartilhamento de dadosEventos + fluxosConfirmada
SEG.IDIdentidade e segurança estadualA validarContratos a levantar
PRO SMTPEnvio de e-mail transacionalSMTP AdapterInfraestrutura a confirmar
Provedores de IAModelos de linguagemAPI via AI GatewayDesacoplado de provedores
RabbitMQMensageria internaAMQPConfirmado
Sistemas dos órgãosSistemas corporativos específicosAdapter por órgãoSob demanda

14.26 Decisões Confirmadas

  1. APIs são a principal interface síncrona entre canais e serviços de domínio;
  2. o API Gateway é o único ponto de entrada HTTP dos canais externos;
  3. regras de negócio residem nos serviços de domínio, nunca no Gateway;
  4. autorização de recurso é sempre validada pelo serviço de domínio;
  5. Tenant Context é estabelecido por componente confiável, não por parâmetro do cliente;
  6. GOV.BR é o provedor de identidade federada para cidadãos (OpenID Connect);
  7. IAM próprio gerencia usuários internos e cidadãos com cadastro local;
  8. contratos HTTP são formalizados em OpenAPI;
  9. erros seguem Problem Details (RFC 9457);
  10. integrações externas são encapsuladas por adapters com Anti-Corruption Layer;
  11. a arquitetura de IA preserva desacoplamento de provedores via AI Gateway;
  12. serviços de domínio nunca dependem diretamente de provedores de LLM;
  13. tokens e credenciais nunca em query string ou logs;
  14. rate limiting é aplicado em múltiplas dimensões;
  15. 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

RiscoConsequênciaMitigação
Autorização apenas no GatewayServiço retorna recursos de outro tenantAutorização de negócio obrigatória no serviço de domínio
Tenant via header não validadoAcesso cruzado entre órgãosTenant Context derivado de identidade autenticada, não de header do cliente
Integração sem ACLDomínio contaminado por modelo externoAnti-Corruption Layer obrigatório para sistemas com modelo diferente
API sem versionamentoBreaking change quebra consumidoresVersionamento por URI, detectado no pipeline
Token em query stringExposição em logs e históricoTokens somente em headers; validação no pipeline e code review
Rate limit só no GatewayQuota de IA excedida sem controle granularQuotas de IA aplicadas na plataforma de IA por tenant, modelo e tokens
Circuit breaker ausente em integraçãoFalha em cascata quando sistema externo degradaCircuit breaker obrigatório em todos os adapters de integração externa
Streaming mal implementado em React NativeFalhas silenciosas em conexões móveisTeste específico de streaming em condições de rede degradada

14.29 Decisões Arquiteturais

ADRTema
ADR-083Classificação de APIs e controles por categoria
ADR-084Produto e configuração do API Gateway
ADR-085Adoção e escopo de BFF por canal
ADR-086REST Guideline corporativo
ADR-087Convenção JSON e padrão de datas
ADR-088Estratégia de versionamento de APIs
ADR-089Problem Details — formato estendido
ADR-090Estratégia de paginação por tipo de API
ADR-091Idempotency-Key — implementação e retenção
ADR-092ETag e controle de concorrência otimista
ADR-093OpenAPI como contrato — Design First vs. Code First
ADR-094Tenant Context em HTTP — headers internos e validação
ADR-095Autenticação service-to-service (mTLS vs. tokens)
ADR-096Rate limiting — dimensões e política por categoria de API
ADR-097Anti-Corruption Layer — padrão de implementação
ADR-098Integração GOV.BR — contrato e fluxo OpenID Connect
ADR-099IAM Próprio — protocolo e modelo de tokens
ADR-100Integração MG API — catálogo e contratos
ADR-101Integração SEI!MG — protocolo e modo assíncrono
ADR-102Integração MG-Ouv — protocolo e adapter
ADR-103Integração Data Lake MG — formato e frequência
ADR-104Integração SEG.ID — escopo e protocolo
ADR-105Integração PRO SMTP — configuração e adapter
ADR-106Webhooks — política, assinatura e reentrega
ADR-107Streaming de IA — SSE vs. alternativas por canal
ADR-108Contratos 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

CampoValor
DocumentoDocumento Mestre — Plataforma de Relacionamento Digital com o Cidadão
Capítulo14 — Arquitetura de APIs e Integrações
Versão1.0
SituaçãoConcluído
Última atualização15/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.

Nesta página

14.1 Objetivo do Capítulo14.2 Papel das APIs na Plataforma14.3 Classificação de APIs14.4 API Gateway14.5 Backend for Frontend (BFF)14.6 Padrões REST14.6.1 Verbos HTTP14.6.2 Códigos HTTP14.6.3 URLs14.6.4 Convenção JSON14.6.5 Datas e Timestamps14.6.6 Identificadores14.7 Tratamento de Erros14.7.1 Problem Details (RFC 9457)14.8 PaginaçãoPor OffsetPor Cursor14.9 Filtros e OrdenaçãoFiltros SimplesFiltros ComplexosOrdenação14.10 IdempotênciaIdempotency-KeyETag e Controle de Concorrência14.11 Contratos OpenAPICiclo de Vida de API14.12 Versionamento de APIs14.13 Autenticação14.13.1 IAM Próprio14.13.2 Integração com GOV.BR14.13.3 Service-to-Service14.14 Autorização e Tenant Context14.14.1 Modelo de Autorização14.14.2 Tenant Context14.14.3 BOLA — Broken Object Level Authorization14.15 Rate Limiting e Quotas14.16 Catálogo Inicial de APIs por Domínio14.17 Anti-Corruption Layer14.18 Integrações Governamentais14.18.1 GOV.BR14.18.2 MG API14.18.3 SEI!MG14.18.4 MG-Ouv14.18.5 Data Lake MG14.18.6 SEG.ID14.18.7 PRO SMTP14.19 Resiliência em Integrações ExternasTimeoutRetryCircuit BreakerBulkheadMatriz de Resiliência por Integração14.20 APIs de Inteligência ArtificialStreaming de RespostasEndpoints de IA14.21 Webhooks e CallbacksWebhooks para Sistemas ExternosCallbacks Assíncronos14.22 Segurança nas APIsPrincípiosLogs de API14.23 Observabilidade de APIsMétricas RED por APIRastreamento DistribuídoMétricas de Integração14.24 Governança de APIsAPI Review14.25 Catálogo de Integrações14.26 Decisões Confirmadas14.27 Benefícios da Arquitetura14.28 Riscos e Mitigações14.29 Decisões Arquiteturais14.30 Rastreabilidade com o Anexo III14.31 Considerações Finais14.32 Controle de Versão14.33 Rastreabilidade PRODEMGE