SDKs y herramientas

La API es pequeña y regular: un host, autenticación por cabecera Authorization, cuerpos JSON y un sobre de error estable. El cliente HTTP estándar de tu lenguaje es suficiente. Un envoltorio mínimo de una docena de líneas te da todo lo que haría un SDK hoy.

Las lecturas necesitan subscribers:read y las escrituras subscribers:write (o permisos que los incluyan). Las claves test devuelven 403 test_mode_unavailable: no hay sandbox operativo. Los ejemplos de creación que omiten consentimiento de email dejan el contacto como never_subscribed, no suscrito.

Un cliente mínimo

const BASE = 'https://fluyio.com/api/v1';

export async function fluyio<T = any>(
  method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
  path: string,
  body?: unknown,
  headers: Record<string, string> = {},
): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.FLUYIO_API_KEY}`,
      'Fluyio-Version': '2026-05-15',
      'Content-Type': 'application/json',
      ...headers,
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const raw = await res.text();
  const json = raw ? JSON.parse(raw) : null;
  if (!res.ok) {
    const e = json?.error ?? {};
    throw new Error(`${res.status} ${e.type}/${e.code}: ${e.message} (${e.request_id})`);
  }
  return json as T;
}

// Uso
const page = await fluyio('GET', '/subscribers?limit=10');
const ada = await fluyio('POST', '/subscribers', { email: '[email protected]' }, { 'Idempotency-Key': 'ada-0001' });

Lo que un SDK debería añadir por ti, y que conviene implementar en tu envoltorio:

• Reintentos en 429 respetando Retry-After. No reejecutes automáticamente escrituras con un 5xx o resultado incierto: si la operación ya fue reservada con Idempotency-Key, la reserva dura 24 horas. Reconcilia el estado antes de decidir el siguiente paso (idempotencia).
• Claves de idempotencia generadas una vez por operación y reutilizadas en cada reintento (idempotencia).
• Paginación siguiendo next_cursor hasta que has_more sea false (paginación).
• Registro del request_id de cada error para hablar con soporte (errores).

Un 503 idempotency_unavailable indica que no se inició la operación; no garantiza una reserva creada. Reintenta la misma operación con la misma clave, sin generar otra para eludir la protección.