Protocolo de sincronización

Contrato para los endpoints REST que su CRM debe exponer para integrarse con Spot2 Ingestion.

---

Endpoint de propiedades

Endpoint principal que devuelve las publicaciones activas que el usuario marcó explícitamente para aparecer en Spot2.

GET /api/v1/spot2/properties?updated_since=2026-07-01T00:00:00Z&offset=0&limit=200 HTTP/1.1
Host: su-crm.com
x-api-key: <su-api-key>
Accept: application/json

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
updated_since	ISO 8601	No en primer ciclo; sí en ciclos incrementales	Devuelve publicaciones seleccionadas para Spot2 modificadas desde esta fecha.
offset	integer	Sí	Desplazamiento offset-based. El primer request usa 0.
limit	integer	Sí	Tamaño de página solicitado. El valor estándar es 200.

Comportamiento

• En el primer ciclo no enviamos updated_since; su API debe devolver el catálogo completo de publicaciones activas seleccionadas para Spot2.
• Después de un ciclo exitoso, enviamos updated_since con el timestamp del último ciclo exitoso.
• Su API debe devolver solo publicaciones seleccionadas para Spot2 con cambios posteriores a updated_since.
• Si una propiedad sigue activa en su CRM pero el usuario la retiró de la selección para Spot2, repórtela en el endpoint de eliminados.
• Si no hay resultados, puede responder 200 con data: [] y meta.next: null, o 204 No Content.

Formato de respuesta

Recomendamos devolver las propiedades bajo data y la paginación bajo meta:

{
  "data": [
    {
      "external_id": "PROP-001",
      "property_type": "office",
      "modality": "rent",
      "updated_at": "2026-07-24T15:40:43Z",
      "price": {
        "currency": "MXN",
        "rent_price": 120000,
        "sale_price": null
      },
      "location": {
        "latitude": 19.4326,
        "longitude": -99.1937,
        "street": "Avenida Presidente Masaryk",
        "city": "Ciudad de México",
        "state": "Ciudad de México",
        "postal_code": "11560"
      },
      "contact": {
        "name": "Broker CRM",
        "email": "broker@example.com",
        "phone": "525512345678"
      }
    }
  ],
  "meta": {
    "next": "/api/v1/spot2/properties?updated_since=2026-07-01T00:00:00Z&offset=200&limit=200",
    "total_count": 580
  }
}

Campo	Tipo	Descripción
data	object[]	Lista de propiedades. Cada objeto sigue el Esquema de propiedad.
meta.next	string o null	URL o indicador de siguiente página. null o ausente cuando no hay más páginas.
meta.total_count	integer	Opcional. Total esperado para auditoría.

El contrato estándar recomienda data, pero Spot2 también tolera objects o items como nombre del array de propiedades. Para integraciones nuevas use data.

Paginación

La paginación es offset-based:

GET /api/v1/spot2/properties?updated_since=2026-07-01T00:00:00Z&offset=200&limit=200 HTTP/1.1
Host: su-crm.com
x-api-key: <su-api-key>

Spot2 continúa mientras meta.next tenga un valor. El ciclo termina cuando meta.next viene null, vacío o ausente.

Códigos HTTP

Status	Significado
200	Éxito. Feed recibido correctamente.
204	Feed vacío. No hay propiedades para procesar en esa página o ciclo.
400	Parámetro inválido, por ejemplo updated_since mal formateado.
401 / 403	Credencial inválida o sin permiso.
429	Rate limit temporal.
503	Mantenimiento temporal.

---

Endpoint de eliminados

Endpoint obligatorio para reportar propiedades eliminadas del CRM o retiradas de la selección para Spot2.

GET /api/v1/spot2/properties/deleted?since=2026-07-01T00:00:00Z HTTP/1.1
Host: su-crm.com
x-api-key: <su-api-key>
Accept: application/json

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
since	ISO 8601	No en primer ciclo; sí en ciclos incrementales	Devuelve external_id eliminados o retirados de Spot2 desde esta fecha.

En el primer ciclo no enviamos since. Su API puede devolver todos los IDs eliminados que conserve o un conjunto vacío.

Formato de respuesta

{
  "deleted_ids": ["PROP-001", "PROP-002"],
  "since": "2026-07-01T00:00:00Z",
  "generated_at": "2026-07-24T15:40:43.143Z"
}

Si no hay bajas, responda:

{
  "deleted_ids": [],
  "since": null,
  "generated_at": "2026-07-24T15:40:43.143Z"
}

Campo	Tipo	Descripción
deleted_ids	string[]	external_id de propiedades eliminadas o retiradas de la selección para Spot2. Obligatorio, incluso si está vacío.
since	ISO 8601 o null	Eco del cursor recibido, o null cuando no aplica.
generated_at	ISO 8601 o null	Timestamp de generación de la respuesta.

También puede responder 204 No Content; Spot2 lo interpreta como deleted_ids: [].

Retención

Su CRM debe retener el historial de eliminaciones al menos 30 días. Si since es más antiguo que su ventana de retención, devuelva todos los IDs eliminados que tenga disponibles.

---

Autenticación

El contrato estándar recomienda API key por header:

x-api-key: <su-api-key>

También podemos configurar Bearer Token si su plataforma lo requiere:

Authorization: Bearer <su-token>

Requisitos:

• Credencial dedicada para Spot2.
• Alcance de solo lectura sobre propiedades y eliminados.
• Sin expiración automática. Si necesita rotarla, coordine una ventana de transición.

---

Rate limits y timeout

• Límite recomendado: al menos 60 requests por minuto para la credencial de Spot2.
• Si necesita aplicar rate limit o mantenimiento temporal, responda con un código HTTP claro (429 o 503) y un mensaje JSON legible.
• Timeout operativo estándar: hasta 300 segundos por request. Recomendamos que su API responda mucho antes de ese límite.

---

Qué no hacer

• No devuelva todo el inventario del CRM; devuelva solo publicaciones seleccionadas para Spot2.
• No cambie el orden de los items entre requests paginados del mismo ciclo.
• No use paginación infinita sin indicador de fin.
• No reporte eliminaciones por ausencia en el feed principal. Use siempre /properties/deleted.
• No incluya credenciales en query params.

---

Próxima lectura

• Esquema de propiedad: referencia completa de campos.
• Protocolo de eliminación: detalles de retención y flujo.
• Seguridad: autenticación, Bearer Token y TLS.