Skip to main content

Módulo 12: Ativações & Vigência — API

Status: Rascunho Inicial Regras de negócio: ver regras-negocio/12_ativacoes.md Domínio: ver dominio/plano-contratado.md

1. Contratos de API (RESTful)​

1.1 Consulta e Gestão de Planos Contratados​

GET /api/planos-contratados
  Auth: Consultor | Gestor | Admin
  Query: ?status=ATIVO&cliente_id=uuid&placa=string
  Return: [{ id, cliente_id, veiculo_id, status, vigencia_inicio, vigencia_fim, placa }]

GET /api/planos-contratados/{id}
  Auth: Consultor (carteira própria) | Gestor | Admin
  Return: { ...atributos Plano_Contratado, cliente: { nome, cpf_cnpj }, veiculo: { marca, modelo, placa, chassi } }

POST /api/planos-contratados/{id}/alterar-status
  Auth: Gestor | Admin
  Body: { novo_status: "SUSPENSO | CANCELADO", motivo: string }
  Return: 200 OK
  Nota: Permite suspensão ou cancelamento administrativo direto pelo CRM.

PATCH /api/planos-contratados/{id}/emplacar
  Auth: Consultor | Gestor
  Body: { placa: string, renavam: string, documento_url: string }
  Return: { id, status: "ATIVO", placa, renavam }
  Errors:
    400 — placa inválida ou renavam fora do padrão nacional
    409 — veículo já possui placa cadastrada

1.2 Ativação e Faturamento (Integração ERP/Financeiro)​

POST /api/planos-contratados/{id}/ativar-manual
  Auth: Financeiro | Admin
  Body: { recebido_em: datetime, valor_recebido: decimal, observacao: string }
  Return: { status: "ATIVO", vigencia_inicio, vigencia_fim }
  Nota: Usado quando o gatilho do Tenant é PAGAMENTO_ADESAO e a baixa é manual.

GET /api/planos-contratados/{id}/faturas
  Auth: Consultor | Gestor | Admin
  Return: [{ competencia: "YYYY-MM", vencimento: "date", valor: "decimal", status: "PAGO | ABERTO | ATRASADO", link_boleto: "string" }]
  Nota: Proxy assíncrono para a API do ERP (ex: Hinova). Se o ERP estiver indisponível, retorna dados cacheados localmente.

1.3 Webhooks de Faturamento e Cobrança (ERP → CRM)​

Webhook configurado no ERP do parceiro para notificar mudanças de status financeiro das mensalidades.

POST /api/integracoes/erp/webhook/faturamento
  Auth: Validação via HMAC-SHA256 (Header: X-ERP-Signature)
  Body:
  {
    "id_externo_erp": "string",
    "evento": "FATURA_QUITADA | FATURA_EM_ATRASO | CONTRATO_SUSPENSO | CONTRATO_CANCELADO",
    "fatura": {
      "competencia": "YYYY-MM",
      "vencimento": "date",
      "data_pagamento": "datetime | null",
      "valor_pago": "decimal | null"
    },
    "dias_atraso_acumulado": 45
  }
  Return: 200 OK

Processamento Interno do Webhook:​

  • FATURA_QUITADA: Se o status do plano era INADIMPLENTE ou SUSPENSO:
    • Se SUSPENSO há menos de Y dias, volta automaticamente para ATIVO e zera tarefas de vistoria.
    • Se SUSPENSO há mais de Y dias, envia evento para o Módulo 10 gerar link de revistoria. O plano permanece bloqueado até a aprovação da vistoria.
  • FATURA_EM_ATRASO: Se ultrapassar o prazo de carência do tenant, altera status do plano para INADIMPLENTE.
  • CONTRATO_SUSPENSO: Altera status do plano contratado para SUSPENSO no CRM, bloqueia direitos a sinistro e envia notificação de alerta ao cliente.
  • CONTRATO_CANCELADO: Altera status do plano contratado para CANCELADO de forma definitiva.

2. Schema de Dados​

Plano_Contratado​

{
  "id": "uuid",
  "tenant_id": "uuid",
  "cliente_id": "uuid",
  "veiculo_id": "uuid",
  "contrato_origem_id": "uuid",
  "status": "AGUARDANDO_ATIVACAO | ATIVO | INADIMPLENTE | SUSPENSO | CANCELADO",
  "data_ativacao": "datetime | null",
  "vigencia_inicio": "datetime | null",
  "vigencia_fim": "datetime | null",
  "sincronizado_erp_em": "datetime | null",
  "id_externo_erp": "string | null",
  "created_at": "datetime",
  "updated_at": "datetime"
}

3. Segurança e Boas Práticas​

RegraImplementação
Assinatura do WebhookValidar o HMAC-SHA256 no header X-ERP-Signature usando a chave pública do ERP configurada no Tenant.
Cache de FaturasA listagem de faturas do ERP no CRM deve expirar a cada 1 hora. Não bater no ERP a cada renderização de tela.
Sincronização AssíncronaO sincronismo do plano com o ERP (POST inicial para criação) deve rodar em background. Falhas de rede do ERP devem gerar tentativas automáticas de envio (retry policy com exponential backoff).
Lock de ReativaçãoGarantir exclusão mútua na reativação para evitar que múltiplos webhooks processados em paralelo criem mais de uma vistoria ativa para o mesmo veículo.