Versionado

La API está bajo /v1, y los cambios dentro de /v1 solo agregan. Podemos agregar:

• nuevas operaciones y nuevos parámetros opcionales;
• nuevos campos en las respuestas y en los payloads de webhooks;
• nuevos valores en enumeraciones (un nuevo estado de Lead, un nuevo tipo de evento);
• nuevos campos opcionales en las solicitudes.

No eliminaremos ni renombraremos una operación, un campo o un valor, ni restringiremos un tipo, ni haremos obligatorio un dato opcional. Un check de CI compara cada cambio con el contrato publicado y falla ante cualquiera de esos casos.

Escribe clientes que toleren adiciones: ignora los campos que no conoces, maneja con cuidado los valores de enumeración y tipos de evento desconocidos, y no dependas del orden de las claves JSON.

Deprecación

Si algo debe desaparecer, primero se marca como deprecado y sigue funcionando. Desde entonces, cada respuesta incluye:

Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://www.letsrealty.io/en/developers/versioning>; rel="deprecation"

• Deprecation (RFC 9745) — desde cuándo, como timestamp Unix.
• Sunset (RFC 8594) — cuándo deja de funcionar.
• Link — dónde leer sobre el reemplazo.

La operación también aparece marcada como deprecated en la referencia de la API. Registra estos headers en tu cliente para enterarte de un sunset con tiempo.

Payloads de webhooks

Los sobres de los eventos llevan "version": 1. Los payloads crecen igual que la API: solo con campos nuevos. Un cambio incompatible en un payload saldría como una versión nueva.

El contrato

El documento OpenAPI 3.1 publicado, con todas las operaciones públicas y payloads de webhooks, está en /openapi.json. Genera un cliente a partir de él, o compáralo con la copia con la que construiste el tuyo.