Cotação

A cotação é o ponto de partida do ciclo de vida comercial no Simplafy Seguros. Ela representa o lead de seguro que entra na plataforma — seja por webhook automatizado, criação manual pelo operador ou via integração de parceiros — e segue por um pipeline de qualificação até virar uma proposta encaminhada ao backoffice.

Esta página descreve o fluxo end-to-end, os campos validados pela API e as transições de status suportadas pelo backend.

O que é uma cotação

Uma cotação no Simplafy Seguros é um registro que reúne três blocos de informação:

• Cliente (customer) — dados pessoais, endereço e contato do segurado.
• Veículo (vehicle) — identificação do bem segurado (placa, chassi, modelo, ano).
• Venda (sale) — vendedor responsável, data de aprovação do financiamento e valor.

O registro é persistido na tabela sell e está vinculado a entidades Person, Vehicle e Vendor. O ciclo da cotação cobre desde a captura do lead até o encaminhamento ao backoffice. Quando uma apólice é efetivamente emitida, ela passa a viver na entidade Policy, separada da cotação original.

Fluxo end-to-end

O fluxo padrão da cotação envolve três atores: o canal de origem (webhook ou operador), o agente SDR (Lia) que faz o primeiro contato, e o backoffice que recebe o lead qualificado para gerar a proposta.

Reprocessamento manual

Cotações já processadas podem ser reenviadas via POST /api/sales/:id/trigger-webhook. A operação ignora o filtro padrão de 15 dias e dispara o webhook novamente, registrando auditoria.

curl -X POST https://api-seguros.simplafy.com.br/api/sales/{id}/trigger-webhook \
  -H "x-api-key: $SIMPLAFY_SEGUROS_API_KEY"

Campos obrigatórios

A criação manual de cotação (POST /api/sales/manual) exige um payload com três objetos aninhados. As validações abaixo são aplicadas via class-validator no backend.

Exemplo de payload

{
  "customer": {
    "fullName": "Ana Pereira",
    "cpf": "12345678901",
    "phone": "11987654321",
    "birthDate": "1990-05-12",
    "gender": "F",
    "address": "Rua das Flores, 100",
    "zipCode": "01001000",
    "city": "São Paulo",
    "state": "SP"
  },
  "vehicle": {
    "manufacturer": "Volkswagen",
    "brand": "VW",
    "model": "Polo",
    "plate": "ABC1D23",
    "chassi": "9BWZZZ377VT004251",
    "yearManufacture": 2024,
    "yearModel": 2025
  },
  "sale": {
    "vendorId": "f3a2b1c4-1234-4abc-9def-0123456789ab",
    "financingApprovalDate": "2026-05-20",
    "saleValue": 65000.00
  }
}

Status e regras

A cotação possui dois eixos de estado: o pipeline de qualificação (enum PipelineStatus) e os eventos de transição aceitos pelo endpoint de status.

Status do pipeline

A progressão típica é: PENDING → IN_PROGRESS → CONTACTED → INTERESTED/NOT_INTERESTED/NO_CONTACT → CONVERTED.

Eventos de transição

O endpoint PATCH /api/sales/:id/status aceita os seguintes eventos:

curl -X PATCH https://api-seguros.simplafy.com.br/api/sales/{id}/status \
  -H "x-api-key: $SIMPLAFY_SEGUROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "lead_forwarded",
    "sent": true,
    "sent_to": "Backoffice Operador",
    "sent_to_number": "11999998888",
    "dealership": "Concessionária Central"
  }'

Motivos de não contato

Quando o evento é contact_failed, o campo no_contact_reason deve ser preenchido. Os valores permitidos vivem no enum NoContactReason (por exemplo, telefone ausente ou incorreto). Consulte o módulo src/entity/no-contact-reason.enum.ts para a lista atualizada.

Cancelamento

Cancelar uma cotação significa removê-la do pipeline antes da conversão em apólice. A operação é destrutiva e gera registro de auditoria automático.

Excluir uma cotação

curl -X DELETE https://api-seguros.simplafy.com.br/api/sales/{id} \
  -H "x-api-key: $SIMPLAFY_SEGUROS_API_KEY"

Resposta esperada: HTTP 204 No Content.

A exclusão dispara um log na tabela de auditoria com:

• operationType: DELETE
• entity: sale
• entityId: <uuid da cotação>
• userId e ipAddress do solicitante

Reverter cancelamentos

Operações de exclusão ficam registradas em audit_logs e podem ser revertidas pela equipe via o módulo de reversão (revert-operation.service). Esse fluxo é restrito a usuários com permissão administrativa e está documentado em Auditoria.

Cotações não convertidas

Cotações com status NOT_INTERESTED ou NO_CONTACT permanecem no pipeline para fins históricos e de KPI. Para liberar capacidade da equipe sem perder o histórico, prefira manter o lead e ajustar o status em vez de excluí-lo.