Vincular responsável e fechar o contrato

POST /leads/{idApplication}/contract

Única forma de fechar o contrato de um lead — não existe endpoint isolado para setar só os
termos. Vincula, numa única chamada ao home-solutions-backend, um responsável já cadastrado
(6.10/6.11, pelo id) a este lead e define os termos comerciais. É o que conclui a originação e
dispara o envio do contrato para assinatura.

Request

{
  "contractResponsibleId": "8f14e0a1-2b3c-4d5e-9f01-abcdef123456",
  "contractTerms": {
    "tac": 150.00,
    "contractStartDate": "2026-10-01"
  }
}

Campo	Tipo	Obrigatório	Regras
`contractResponsibleId`	string	Sim	`id` de um responsável já registrado pra esta imobiliária via `POST /contract-responsible` (6.10)
`contractTerms`	objeto	Sim	—
`contractTerms.tac`	number	Sim	Entre 0 e 200
`contractTerms.contractStartDate`	string (date)	Sim	ISO 8601; estritamente futura (amanhã ou depois)

Sucesso — 200 OK

{
  "contractResponsible": {
    "id": "8f14e0a1-2b3c-4d5e-9f01-abcdef123456",
    "documentNumber": "12345678909",
    "name": "Maria Silva",
    "email": "[email protected]",
    "phoneNumber": "11999999999",
    "birthDate": "1990-05-10"
  },
  "contractTerms": {
    "tac": 150.00,
    "contractStartDate": "2026-10-01"
  }
}

Responde 200, não 201 com Location: não existe GET /leads/{idApplication}/contract.
A única forma de conferir o responsável vinculado é o corpo desta própria resposta — guarde-o
no seu lado. Os termos, sim, têm consulta: GET /leads/{idApplication}/contract-terms (6.14).

Um endpoint para buscar os dados completos do contrato será criado em versões futuras.

Erros mapeados

HTTP	`code`	Quando ocorre
400	(validação)	Bloco obrigatório ausente ou campo inválido — nada é gravado
404	`CONTRACT_RESPONSIBLE_NOT_FOUND`	`contractResponsibleId` não existe, não pertence ao `cnpj` deste lead, ou não está `ACTIVE`
409	`CONTRACT_TERMS_ALREADY_SET`	O lead já tem termos com valores diferentes
422	`CONTRACT_TERMS_INVALID`	`tac` fora de 0–200, ou `contractStartDate` não futura
500	`CONTRACT_INTEGRATION_FAILURE`	Falha de comunicação interna — o `message` diz qual das duas metades falhou

Idempotência

Repetir a mesma chamada com o mesmo contractResponsibleId é segura: o lead só é
vinculado uma vez, chamadas seguintes são um no-op que devolve o vínculo já existente. Um
timeout nesta chamada também é seguro de repetir.

Updated about 2 hours ago