Skip to main content

Módulo 10: Vistoria — API

Status: Rascunho Inicial Regras de negócio: ver regras-negocio/10_vistoria.md Domínio: ver dominio/vistoria.md

1. Visão da Integração​

O CRM atua como cliente da API do Microserviço de Vistoria. A comunicação é bidirecional:

DireçãoMecanismoQuando
CRM → MicroserviçoREST síncronoAo solicitar, reenviar ou cancelar uma vistoria
Microserviço → CRMWebhook assíncronoAo concluir e dar parecer sobre a vistoria

2. API do CRM (Endpoints Internos)​

2.1 Solicitar Vistoria​

POST /api/propostas/{proposta_id}/vistoria
  Auth: Consultor | Gestor
  Body: { modalidade: "SELF_SERVICE_LINK | INTERNA | TERCEIRIZADA" }
  Return: { vistoria_id, status: "PENDENTE", link_acesso }
  Nota: Internamente, o CRM chama o Microserviço e persiste a resposta em Proposta_Vistoria.
  Errors:
    409 — proposta não está em status ACEITA
    409 — já existe vistoria ativa para esta proposta
    422 — modalidade não habilitada no tenant
POST /api/vistorias/{id}/reenviar-link
  Auth: Consultor | Gestor
  Body: { canal: "WHATSAPP | SMS" }
  Return: { novo_link_acesso }
  Nota: Gera novo link no Microserviço. Link anterior é invalidado.
  Errors:
    409 — vistoria não está em status PENDENTE ou EM_ANDAMENTO

2.3 Cancelar Vistoria​

POST /api/vistorias/{id}/cancelar
  Auth: Consultor | Gestor | Admin
  Body: { motivo? }
  Return: 200 OK
  Nota: Notifica o Microserviço do cancelamento. Proposta retorna para status anterior (ACEITA).

2.4 Consultar Vistoria​

GET /api/vistorias/{id}
  Auth: Consultor | Gestor | Admin
  Return: { ...atributos Proposta_Vistoria, ressalvas[] }

2.5 Webhook de Entrada (Microserviço → CRM)​

POST /api/webhooks/vistoria
  Auth: Validação via X-Vistoria-Signature (HMAC-SHA256)
  Body:
  {
    "vistoria_id": "uuid_externo",
    "referencia_id": "proposta_uuid_do_crm",
    "status_final": "APROVADA | APROVADA_COM_RESSALVAS | REPROVADA",
    "data_conclusao": "datetime",
    "analista_id": "uuid | null",
    "laudo_pdf_url": "string",
    "ressalvas": [
      {
        "peca": "string",
        "tipo_dano": "string",
        "foto_url": "string"
      }
    ]
  }
  Return: 200 OK
  Errors:
    401 — assinatura inválida (webhook rejeitado)
    404 — referencia_id não encontrado

3. API do Microserviço (Chamadas do CRM para o Microserviço)​

Documentadas aqui como contrato de integração — a implementação pertence ao Microserviço.

3.1 Solicitar Vistoria​

POST https://api.vistoria.crm.com/v1/solicitacoes
  Headers: Authorization: Bearer {tenant_api_key}
  Body:
  {
    "tenant_id": "uuid",
    "referencia_id": "proposta_uuid",
    "modalidade": "SELF_SERVICE_LINK | INTERNA | TERCEIRIZADA",
    "veiculo": {
      "placa": "string | null",
      "chassi": "string",
      "tipo": "CARRO | MOTO | CAMINHAO | OUTROS"
    },
    "cliente": {
      "nome": "string",
      "telefone": "string (E.164)"
    },
    "callback_url": "https://{tenant}.crm.com/api/webhooks/vistoria"
  }
  Return: 201 { vistoria_id, status: "PENDENTE", link_acesso }

3.2 Cancelar Vistoria no Microserviço​

DELETE https://api.vistoria.crm.com/v1/solicitacoes/{vistoria_externa_id}
  Headers: Authorization: Bearer {tenant_api_key}
  Return: 200 OK

4. Schemas de Dados (armazenados no CRM)​

Proposta_Vistoria​

{
  "id": "uuid",
  "tenant_id": "uuid",
  "proposta_id": "uuid",
  "vistoria_externa_id": "string",
  "modalidade": "SELF_SERVICE_LINK | INTERNA | TERCEIRIZADA",
  "status": "PENDENTE | EM_ANDAMENTO | EM_ANALISE | APROVADA | APROVADA_COM_RESSALVAS | REPROVADA",
  "link_acesso": "string",
  "laudo_pdf_url": "string | null",
  "data_solicitacao": "datetime",
  "data_conclusao": "datetime | null",
  "motivo_reprovacao": "string | null"
}

Vistoria_Ressalva​

{
  "id": "uuid",
  "proposta_vistoria_id": "uuid",
  "peca_afetada": "string",
  "descricao_dano": "string",
  "url_foto_evidencia": "string"
}

5. Segurança e Boas Práticas​

RegraImplementação
Autenticação do webhookValidar X-Vistoria-Signature (HMAC-SHA256 com shared secret do tenant). Rejeitar com 401 se inválida.
Credencial do Microserviçotenant_api_key armazenada criptografada (AES-256). Nunca exposta nas respostas da API do CRM.
Sem armazenamento de imagensO CRM nunca salva imagens em blob, base64 ou storage próprio. Apenas url_foto_evidencia (string) é gravada no banco.
Idempotência do webhookO endpoint de webhook deve ser idempotente — reprocessar o mesmo vistoria_id com o mesmo status_final não deve duplicar registros nem disparar ações repetidas.
Timeout de chamada ao MicroserviçoChamadas do CRM ao Microserviço devem ter timeout de 10s. Em caso de falha, registrar erro e alertar o operador — não bloquear o fluxo da proposta.