Protocolo de sincronización

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

---

Endpoint de propiedades

Endpoint principal que devuelve sus propiedades activas.

GET https://su-crm.com/api/v1/spot2/properties

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
updated_since	ISO 8601	Sí (excepto primer ciclo)	Devuelve solo propiedades modificadas desde esta fecha. En el primer ciclo Spot2 lo omite, y su API debe devolver el catálogo completo. Su API puede usar otro nombre: date_from (Tokko), updatedAtMin (Shopify), etc. — Spot2 se adapta. Su API puede usar otro nombre: date_from (Tokko), updatedAtMin (Shopify), etc. — Spot2 se adapta.
limit	integer	No	Page size. Default: 200.
Páginación	—	Sí	offset, page, o cursor (misma mecánica que antes).

Comportamiento

• Spot2 envía updated_since con la fecha del último ciclo exitoso. Su API filtra y devuelve solo items con updated_at > updated_since.
• Si su API no puede filtrar por fecha, no puede integrarse con este contrato.
• En el primer ciclo (no hay timestamp previo), Spot2 no envía updated_since. Su API debe devolver el catálogo completo de propiedades activas.

Autenticación

Elija uno de estos métodos. Nosotros configuramos las credenciales de nuestro lado.

Método	Implementación
API Key (header)	Header x-api-key: <su-key>. Simple, recomendado.
API Key (query param)	Query parameter ?api_key=<su-key>. Ejemplo: Tokko.
Bearer Token	Header Authorization: Bearer <su-token>.
Header personalizado	Cualquier otro header que defina.

Requisitos de la credencial:

• No debe expirar automáticamente. Si necesita rotarla, avísenos con anticipación.
• Debe tener alcance de solo lectura sobre las propiedades.
• Recomendamos que sea una clave dedicada exclusivamente a la integración con Spot2.

Paginación

Su API debe soportar paginación con una de estas tres estrategias. Nos adaptamos a la que implemente.

Offset-based (recomendado)

GET /properties?offset=0&limit=200

La respuesta incluye meta.next (URL para la siguiente página, o null si es la última). Paramos cuando next es null.

Page-based

GET /properties?page=1&limit=50

La respuesta incluye pagination.current_page, pagination.total_pages, pagination.total_count. Paramos cuando current_page >= total_pages.

Cursor-based

GET /properties?limit=100

La respuesta incluye next_cursor (token opaco, o null si es la última). Siguiente request: GET /properties?cursor=<next_cursor>.

Formato de respuesta

La respuesta es un objeto JSON con dos secciones:

1. Lista de propiedades en un array (campo data, objects, o items — lo detectamos automáticamente).
2. Metadata de paginación en un objeto separado.

Cada propiedad sigue el schema definido en Esquema de propiedad.

Códigos HTTP

Status	Significado
200	Éxito. Feed recibido correctamente.
204	Feed vacío (sin propiedades modificadas desde updated_since). No es un error.
400	Falta updated_since (excepto primer ciclo).
400	updated_since mal formateado (debe ser ISO 8601).
503	Mantenimiento. Incluir Retry-After.

Rate limits

Nuestro límite por defecto es 60 requests por minuto. Respetamos Retry-After.

Timeout

Timeout por defecto: 30 segundos por request.

Frecuencia de sincronización

• Ciclos programados: típicamente cada 1 hora (configurable entre 5 minutos y 24 horas).
• Ciclos bajo demanda: podemos ejecutar un ciclo manual si necesita forzar una sincronización.

---

Endpoint de eliminados

Endpoint para reportar bajas. Obligatorio.

GET https://su-crm.com/api/v1/spot2/properties/deleted

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
since	ISO 8601	Sí (excepto primer ciclo)	Devuelve IDs eliminados desde esta fecha. En el primer ciclo Spot2 lo omite, y su API debe devolver todos los IDs eliminados que conozca.

Formato de respuesta

{
  "deleted_ids": ["prop-001", "prop-002", "prop-005"],
  "since": "2026-06-29T14:30:00Z",
  "generated_at": "2026-06-30T10:00:00Z"
}

Campo	Tipo	Descripción
deleted_ids	string[]	external_id de propiedades eliminadas desde since.
since	ISO 8601	Eco del parámetro recibido.
generated_at	ISO 8601	Timestamp de cuándo se generó esta respuesta.

Comportamiento

• Spot2 envía since con la fecha del último ciclo exitoso.
• Su API devuelve todos los external_id eliminados después de esa fecha.
• Si since es más antiguo que su retención, devuelva todos los IDs disponibles.
• Retención mínima del historial de eliminaciones: 30 días.
• Si devuelve array vacío ("deleted_ids": []), no hay bajas en este ciclo.

Autenticación y rate limits

Igual que el endpoint principal. Timeout: 30 segundos.

---

Qué NO hacer

• No cambiar el orden de los items entre requests paginados.
• No usar paginación infinita sin indicador de fin.
• No comprimir la respuesta con algoritmos no estándar.

---

Próxima lectura

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