Módulo 11: Contratos & Assinatura — API

Status: Rascunho Inicial Regras de negócio: ver regras-negocio/11_contratos.md Domínio: ver dominio/contrato.md

---

1. Contratos de API (RESTful)

1.1 Geração e Envio do Contrato

POST /api/contratos
  Auth: Consultor | Gestor | Admin
  Body: { proposta_id, template_contrato_id }
  Return: { contrato_id, status: "GERADO", numero: "2026-00342" }
  Errors:
    422 — proposta não está em status ACEITA
    422 — vistoria obrigatória do plano não foi aprovada
    404 — template_contrato_id não encontrado ou inativo

GET /api/contratos/{id}
  Auth: Consultor (carteira própria) | Gestor | Admin
  Return: { ...atributos, signatarios[], proposta: { id, numero }, cliente: { id, nome } }

GET /api/contratos/{id}/pdf-preview
  Auth: Consultor | Gestor | Admin
  Return: { pdf_url, expiracao_url_s3 }
  Nota: Gera url temporária assinada do storage interno (S3/Cloud Storage) para renderizar no iframe.

POST /api/contratos/{id}/enviar-assinatura
  Auth: Consultor | Gestor
  Return: { provedor_envelope_id, status: "AGUARDANDO_ASSINATURA" }
  Nota: Dispara a requisição para o provedor externo cadastrado no Módulo 05.
  Errors:
    409 — contrato não está em status GERADO ou CANCELADO
    502 — erro de comunicação com o provedor de assinatura

POST /api/contratos/{id}/reenviar-link
  Auth: Consultor | Gestor
  Body: { signatario_id }
  Return: { link_reenvio }
  Nota: Solicita ao provedor o reenvio do e-mail/SMS para o signatário específico.

POST /api/contratos/{id}/cancelar
  Auth: Gestor | Admin
  Body: { motivo }
  Return: 200 OK
  Nota: Cancela o envelope no provedor de assinaturas e marca o contrato local como CANCELADO.

---

1.2 Webhook do Provedor de Assinaturas (Entrada)

Este endpoint unificado recebe as notificações de alteração de estado dos documentos diretamente do provedor de e-Signature.

POST /api/integracoes/assinatura/webhook
  Auth: Verificação de assinatura baseada em HMAC-SHA256 (Header: X-Webhook-Signature)
  Body:
  {
    "envelope_id": "string",
    "referencia_contrato_id": "uuid",
    "evento": "VISUALIZADO | ASSINADO | RECUSADO | EXPIRADO",
    "timestamp": "datetime",
    "signatario": {
      "email": "string",
      "status_assinatura": "VISUALIZADO | ASSINADO",
      "data_evento": "datetime",
      "ip": "string",
      "user_agent": "string"
    },
    "documento_assinado_url": "string (URL temporária do provedor para download) | null"
  }
  Return: 200 OK

Processamento Interno do Webhook:

1. Ao receber o evento ASSINADO para um signatário específico, atualiza o status de Signatario_Contrato e registra na timeline do contrato.
2. Se todos os signatários obrigatórios assinarem:
   • Faz o download do PDF assinado (documento_assinado_url) e do arquivo de logs/certificado gerado pelo provedor.
   • Salva os arquivos no storage interno do Tenant.
   • Atualiza o status do contrato para ATIVO.
   • Dispara gatilho de sucesso para o Módulo de Ativação (Módulo 12).
3. Si o evento for RECUSADO ou EXPIRADO:
   • Atualiza o status do contrato para CANCELADO.
   • Registra o motivo na timeline e envia alerta in-app para o consultor responsável.

---

2. Schemas de Dados

Contrato

{
  "id": "uuid",
  "tenant_id": "uuid",
  "proposta_id": "uuid",
  "template_contrato_id": "uuid",
  "numero": "string",
  "status": "GERADO | AGUARDANDO_ASSINATURA | ATIVO | CANCELADO",
  "provedor_envelope_id": "string | null",
  "documento_rascunho_url": "string | null",
  "documento_assinado_url": "string | null",
  "enviado_em": "datetime | null",
  "assinado_em": "datetime | null",
  "created_at": "datetime",
  "updated_at": "datetime"
}

Signatário (Signatario_Contrato)

{
  "id": "uuid",
  "contrato_id": "uuid",
  "nome": "string",
  "email": "string",
  "telefone": "string | null",
  "papel": "CONTRATANTE | TESTEMUNHA | REPRESENTANTE",
  "status_assinatura": "PENDENTE | VISUALIZADO | ASSINADO",
  "data_assinatura": "datetime | null",
  "ip_assinatura": "string | null"
}

---

3. Segurança e Boas Práticas

Regra	Implementação
Autenticação Webhook	Toda requisição para /api/integracoes/assinatura/webhook deve validar o payload contra o segredo compartilhado (secret) usando HMAC-SHA256.
Silo e Isolamento	tenant_id validado em todas as chamadas. Um consultor não tem acesso aos contratos de outros tenants ou de carteiras que ele não gerencie.
Download Definitivo	O download do PDF assinado deve ser feito de forma assíncrona (fila de background) assim que o webhook de conclusão for validado. Não confiar em links temporários expostos pela API do provedor.
Auditoria e Timeline	Toda transição de status (ex: envio, visualização de signatário, assinatura final) deve gerar um registro imutável na timeline do Contrato no CRM.