Blueprint Completo: Integrando um Novo Parceiro

Este guia mostra como habilitar um parceiro a enviar propostas diretamente para a ModoSeguro via POST /api/propostas, com autenticação por X-Partner-Key e (opcional) amarração ao produto da seguradora via X-Insurance-Model-Id / insurance_model_id.

0 Pré-requisitos

Planejamento
  • Documentação de Payload: Definir o JSON mínimo: nome, cpf, email, plano_nome, valor, e opcionalmente telefone, data_inicio, insurance_model_id (ou aliases model_id, id_model).
  • Credenciais: Gerar e distribuir uma X-Partner-Key exclusiva por parceiro.
  • De-Para (opcional): Se o parceiro não enviar insurance_model_id, planeje um mapeamento local de plano_nome → insurance_model_id.

1 Configuração do Backend (PostgreSQL + Flask)

Infraestrutura e Lógica

1.1 Banco de Dados

Cada parceiro precisa de uma partner_api_key na tabela model.tenants. O endpoint usa essa chave para resolver o tenant_id.

-- Exemplo: gerar/atribuir uma partner_api_key ao tenant do parceiro
UPDATE model.tenants
   SET partner_api_key = 'partner_sk_xxxxx'
 WHERE tenant_id = 3;

-- Status necessários
INSERT INTO model.status_contrato (nome) VALUES ('Em Aberto')
ON CONFLICT (nome) DO NOTHING;

1.2 Endpoint Externo

O endpoint externo é POST /api/propostas. Autenticação por header X-Partner-Key. Se o parceiro souber o produto exato da seguradora, pode enviar o insurance_model_id no header X-Insurance-Model-Id (ou no body).

Prioridade de modelo: Header X-Insurance-Model-Id → body insurance_model_id/model_id/id_model → (fallback) mapeamento por plano_nome.

SCD-2: Para o par (tenant_id, cliente_id, plano_nome), a versão atual é fechada e uma nova é criada com is_current = TRUE.

1.3 Contrato de API (OpenAPI/Swagger)

POST /api/propostas
Headers:
  X-Partner-Key: string (obrigatório)
  X-Insurance-Model-Id: integer (opcional)

Body (JSON):
{
  "nome": "Maria Souza",
  "cpf": "11122233300",
  "email": "maria@email.com",
  "telefone": "11999990000",
  "plano_nome": "Seguro de celular",
  "valor": 99.90,
  "data_inicio": "2025-09-01",
  "insurance_model_id": 20
}

201 Created:
{
  "mensagem": "Proposta criada com sucesso",
  "tenant_id": 3,
  "cliente_id": 42,
  "contrato_id": 77,
  "insurance_model_id": 20
}

2 Atualização do Frontend

Interface

2.1 Visualização

A UI já consome as visões/marts e exibe contratos por tenant. Ao habilitar a partner_api_key e criar propostas, os novos contratos aparecem automaticamente nos relatórios, filtros e BI.

3 Checklist de Validação e Testes

Qualidade
  • Autenticação: requisição sem X-Partner-Key deve retornar 401; chave inválida, 403.
  • Dados mínimos: faltar qualquer campo obrigatório → 400.
  • Modelo: quando enviado insurance_model_id, ele deve ser persistido no contrato; sem ele, verifique se o fallback funciona.
  • Banco: cliente upsert, SCD-2 cria nova versão (fecha versão atual do mesmo BK).
  • UI/BI: contrato aparece nos relatórios e dashboards do tenant correto.

4 Boas Práticas e Considerações Finais

Manutenção

Segurança: rotacione chaves, registre logs, valide entradas (valor > 0, CPF válido).

Versionamento: mantenha /api/propostas compatível; versões novas podem ser adicionadas como /v2/... quando houver breaking changes.

Monitoramento: logue cada proposta (tenant, cliente, contrato) e falhas de banco.

Mapeamentos: mantenha uma tabela de de-para de plano_nome → insurance_model_id para parceiros que não enviam o ID.

Apêndice: Exemplos de Requisição

curl

curl -X POST http://<host>:5000/api/propostas \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: partner_sk_xxxxx" \
  -H "X-Insurance-Model-Id: 20" \
  -d '{
    "nome": "Maria Souza",
    "cpf": "11122233300",
    "email": "maria@email.com",
    "telefone": "11999990000",
    "plano_nome": "Seguro de celular",
    "valor": 99.90,
    "data_inicio": "2025-09-01"
  }'

PowerShell

$api = "http://localhost:5000/api/propostas"
$headers = @{
  "Content-Type" = "application/json"
  "X-Partner-Key" = "partner_sk_xxxxx"
  "X-Insurance-Model-Id" = "20"
}
$body = @{
  nome="Maria Souza"; cpf="11122233300"; email="maria@email.com";
  telefone="11999990000"; plano_nome="Seguro de celular"; valor=99.90;
  data_inicio="2025-09-01"
} | ConvertTo-Json
Invoke-RestMethod -Uri $api -Headers $headers -Method Post -Body $body