Paginación, idempotencia y límites

Recorre listados por página o por cursor, reintenta sin duplicar y maneja el 429.

GuíaREST

Recorre listados por página o por cursor

Todos los listados aceptan page (desde 1) y pageSize, y traen meta.total y meta.totalPages. Contactos, negocios y tareas aceptan además cursor: pasa el meta.nextCursor de la respuesta anterior hasta que meta.hasMore sea false. Con includeTotal=false no se cuenta el total (llega en null) y va más rápido. El pageSize máximo es 500 en contactos, negocios, tareas y citas, y 48 en propiedades.

// Contactos, negocios y tareas: por cursor, sin contar el total (lo más rápido).
async function* all(path, params = {}) {
  let cursor;
  do {
    const qs = new URLSearchParams({ ...params, pageSize: "500", includeTotal: "false",
                                     ...(cursor ? { cursor } : {}) });
    const res = await api(`${path}?${qs}`);
    const { data, meta } = await res.json();
    yield* data;
    cursor = meta.hasMore ? meta.nextCursor : undefined;
  } while (cursor);
}

for await (const contact of all("/contacts", { status: "NEW" })) { /* … */ }

En propiedades el cursor es el id de la última recibida (no hay nextCursor) y no mandes includeTotal=false: ahí «false» cuenta como verdadero.

Reintenta sin duplicar

Manda Idempotency-Key en POST, PATCH, PUT y DELETE: de 8 a 128 caracteres (letras, números y . _ : -), única por operación dentro de tu inmobiliaria. Durante 24 horas, la misma clave con el mismo método, ruta y cuerpo devuelve la respuesta guardada sin repetir el cambio. Las respuestas 5xx no se guardan: puedes reintentar con la misma clave.

cURL

curl -X POST https://api.bydomu.com/v1/contacts \
  -H "X-API-Key: $BYDOMU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync:contact:u_123" \
  -d '{"firstName":"Laura","phone":"+573000000001"}'

# 1.ª vez   → 201 · Idempotency-Status: created
# repetida  → 201 · Idempotency-Status: replayed (la misma respuesta, sin crear otro)
# otro body → 409 IDEMPOTENCY_CONFLICT
# en curso  → 409 IDEMPOTENCY_IN_PROGRESS

Deriva la clave de tu propio id (crm-sync:contact:u_123) y no de la hora: así un reintento, aunque sea desde otro proceso, cae sobre la misma operación.

Límites por minuto y el 429

Cada clave tiene dos baldes por minuto: todas las peticiones y, aparte, las escrituras. Soporte puede aprobar más. Además hay un tope de escrituras por organización (TENANT_RATE_LIMITED).

ClaveLímite

Clave publicable300/min · 60 escrituras

Clave secreta60/min · 30 escrituras

Clave de antes de los niveles1000/min

Qué diceEncabezado

Tope por minuto de la claveX-RateLimit-Limit

Lo que queda en este minutoX-RateLimit-Remaining

Segundos para que se reinicieX-RateLimit-Reset

Tope de escrituras (en un 429 de escritura)X-RateLimit-Write-Limit

Escrituras de toda la organizaciónX-Tenant-RateLimit-Remaining

Segundos a esperar (en el 429)Retry-After

Un cliente que reintenta bien

Ante 429 espera los segundos de Retry-After; ante 5xx, espera creciente con algo de azar. Nunca reintentes un 4xx distinto de 429: no va a cambiar.

import { randomUUID } from "node:crypto";

// Reintenta 429 y 5xx con la MISMA Idempotency-Key: nunca duplica.
export async function api(path, { method = "GET", body, idempotencyKey } = {}) {
  const key = idempotencyKey ?? (method === "GET" ? undefined : randomUUID());
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(`https://api.bydomu.com/v1${path}`, {
      method,
      headers: {
        "X-API-Key": process.env.BYDOMU_API_KEY,
        ...(body ? { "Content-Type": "application/json" } : {}),
        ...(key ? { "Idempotency-Key": key } : {}),
      },
      ...(body ? { body: JSON.stringify(body) } : {}),
    });
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt === 5) return res;
    const retryAfter = Number(res.headers.get("Retry-After"));
    const wait = retryAfter > 0 ? retryAfter * 1000 : Math.min(30_000, 500 * 2 ** attempt);
    await new Promise((r) => setTimeout(r, wait + Math.random() * 250));
  }
}