APIs por público

1. Introdução¶

Nesta opção, existem APIs diferentes por público, cada uma com base URL e contrato próprios, mesmo que por trás elas apontem para o mesmo backend/monólito internamente (pelo menos no começo).

Exemplos de “produtos de API”: - api-cliente - api-corretor - api-superapp - api-parceiros - api-webhooks - api-ia

O objetivo é criar muros claros entre públicos, evitando que um consumidor “encoste” em endpoints de outro, e permitindo governança e ciclos de versionamento diferentes por público.

2. Visão estratégica¶

2.1. O que esta opção resolve¶

Isolamento de superfície e contrato: cada público tem uma API própria, com rotas e documentação separadas. Isso reduz o risco de exposição acidental.
Governança por produto: dá para aplicar políticas, autenticação, CORS, rate limit, quotas e versionamento de forma diferente para cada público.
Menos risco de “vazamento de endpoints internos”: o que é interno pode ficar em APIs internas sem aparecer para parceiros.
Evolução progressiva: mesmo que tudo ainda aponte para um backend legado, a borda já fica organizada e pronta para evoluir.

2.2. O que esta opção não resolve sozinha¶

Autorização real ainda é obrigatória: mesmo com APIs separadas, o backend precisa validar vínculo/ownership e permissões.
Complexidade de produto aumenta: vira “mais de um produto” para manter (docs, versionamento, compatibilidade, suporte).
Risco de duplicação: contratos separados podem levar a duplicação de modelos/DTOs e regras de validação se não houver padrão e reaproveitamento.

3. Visão de negócio¶

3.1. Benefícios¶

Parceiros e webhooks ficam muito mais seguros por desenho: a API de parceiros expõe apenas o que foi contratado, e a de webhooks é mínima e controlada.
Ciclos de mudança independentes: superapp pode evoluir com mais frequência sem impactar cliente/corretor, por exemplo.
Melhor comunicação e responsabilidade: internamente fica claro “qual público usa qual API”, facilitando alinhamento com Produto, Operações e Atendimento.
Reduz risco jurídico/comercial: diminui a chance de um parceiro consumir endpoints não previstos em contrato.

3.2. Pontos de atenção para o negócio¶

É necessário manter governança de “produtos de API”:
- catálogo de APIs (o que existe, para quem, com qual contrato),
- política de versionamento (quando muda, como comunica),
- suporte e monitoramento por público.
Se as APIs se afastarem demais, pode existir custo de manter várias variantes de contratos e documentação.

4. Fluxo de funcionamento¶

%%{init:{ "theme":"neutral", "fontSize":22, "flowchart":{"curve":"basis","htmlLabels":true,"nodeSpacing":50,"rankSpacing":70} }}%% flowchart TB A["Consumidor faz requisicao"]:::ui_input --> B{Selecionar API por publico}:::decision B -- Cliente --> C["API Cliente base url cliente"]:::ui_input B -- Corretor --> D["API Corretor base url corretor"]:::ui_input B -- Superapp --> E["API Superapp base url app"]:::ui_input B -- Parceiros --> F["API Parceiros base url externa"]:::ui_input B -- Webhooks --> G["API Webhooks base url publica minima"]:::ui_input B -- IA --> H["API IA base url agentes"]:::ui_input C --> I["Politicas cliente token cors limites"]:::ui_input D --> J["Politicas corretor token cors limites"]:::ui_input E --> K["Politicas superapp token device limites"]:::ui_input H --> L["Politicas ia token limites auditoria"]:::ui_input F --> M["Politicas parceiros chave quota contrato"]:::ui_input G --> N["Politicas webhooks assinatura idempotencia"]:::ui_input I --> O{Autenticacao ok}:::decision J --> O K --> O L --> O O -- Nao --> P["Negar acesso 401 ou 403"]:::ui_button O -- Sim --> Q["Autorizacao por vinculo dados do solicitante"]:::ui_input Q --> R{Vinculo permitido}:::decision R -- Nao --> P R -- Sim --> S["Executar operacao no dominio contratos cobranca docs"]:::endpoint_post S --> T["Auditoria e metricas por publico"]:::ui_input T --> U["Resposta para consumidor"]:::endpoint_get M --> V{Acesso parceiro ok}:::decision V -- Nao --> P V -- Sim --> W["Operacoes do contrato subset de recursos"]:::endpoint_post W --> T N --> X{Webhook valido}:::decision X -- Nao --> P X -- Sim --> Y["Encaminhar comando interno service account"]:::endpoint_post Y --> S classDef endpoint_get fill:#e0f2fe,stroke:#0284c7,color:#0f172a,stroke-width:1px; classDef endpoint_post fill:#dcfce7,stroke:#16a34a,color:#052e16,stroke-width:1px; classDef endpoint_put fill:#fef9c3,stroke:#a16207,color:#3b2f0b,stroke-width:1px; classDef endpoint_delete fill:#fee2e2,stroke:#ef4444,color:#7f1d1d,stroke-width:1px; classDef ui_input fill:#eef2ff,stroke:#6366f1,color:#111827,stroke-width:1px; classDef ui_button fill:#ede9fe,stroke:#7c3aed,color:#1f2937,stroke-width:1px; classDef decision fill:#fff7ed,stroke:#f59e0b,color:#78350f,stroke-width:1px;

5. Manutenção e longo prazo¶

5.1. Manutenção do código¶

Mais “produtos” para manter: cada API precisa de documentação, versionamento, monitoramento e suporte.
Separação saudável de contratos: mesmo que o backend seja o mesmo, os controllers/rotas expostas ficam organizados por público.
Risco de duplicação de modelos/DTOs: como contratos são distintos, pode acontecer:
- DTOs diferentes para o mesmo conceito,
- validações repetidas,
- pequenos “drifts” entre contratos.

Boas práticas para manter sustentável:

Shared libs de modelos e validações (quando fizer sentido).
Camada de domínio única (serviços internos) com controllers finos por API.
Testes de contrato por API (garantindo que mudanças não quebrem consumidores).
Política clara de versionamento e depreciação (principalmente para parceiros).

5.2. Escalabilidade¶

Escala por público: dá para escalar api-superapp independentemente de api-cliente, por exemplo, mesmo se o core ainda for o mesmo.
Políticas por público ficam naturais:
- superapp: limites por device, picos e cache de leitura;
- parceiros: quotas e rate limit por chave/contrato;
- webhooks: limites fortes e proteção contra abuso.
Atenção ao gargalo do core: se todas as APIs apontarem para o mesmo backend interno, o core pode virar o gargalo. A separação de borda ajuda, mas não elimina necessidade de otimização interna.

6. Adaptação ao legado do PASI¶

Esta opção funciona bem quando vocês já têm múltiplos consumidores fortes (parceiros, WhatsApp, IA, superapp) e querem “muros” claros agora, mesmo antes de reescrever o core.

6.1. Caminho de adaptação recomendado¶

Criar novas bases URLs por público
- Colocar api-webhooks e api-parceiros como primeiros “muros”, por serem os mais sensíveis.
Reduzir superfície pública
- Tudo que for público por natureza vai para api-webhooks, com assinatura, idempotência e validação.
Criar contrato mínimo e seguro para parceiros
- Expor apenas subset de recursos, com autenticação por chave/token, quotas e auditoria.
Levar o superapp para uma API própria
- Evitar que o superapp “herde” endpoints do corretor/cliente (como acontece hoje).
Endurecer autorização no core em paralelo
- Mesmo com separação por API, manter validação de vínculo/ownership e permissões reais.

6.2. Por que esta opção é boa para transição¶

Entrega rapidamente uma separação clara para diretoria e para operação: “cada público tem sua API”.
Ajuda a controlar o legado: mesmo antes da refatoração, dá para parar de expor “tudo para todo mundo”.
Dá base para evoluir futuramente para:
- gateway mais forte,
- BFF por canal,
- ou um core mais limpo por trás.

7. Principais prós e contras¶

7.1. Prós¶

Isolamento de contrato e superfície (muito bom para parceiros e webhooks).
Dá para aplicar políticas e ciclos de versionamento diferentes por público.
Comunicação interna fica mais livre sem expor tudo.

7.2. Contras¶

Mais “produtos” para manter (docs, versionamento, compatibilidade).
Pode duplicar modelos/DTOs se não houver shared libs.
Ainda precisa de autorização real por vínculo.

8. Quando esta opção faz sentido¶

Quando parceiros, WhatsApp e IA são fortes e você quer “muros” claros entre públicos.
Quando o risco de exposição indevida é alto e você precisa de separação por contrato rapidamente.
Quando você quer manter a operação relativamente simples (sem BFF), mas com governança forte por público.