Convenciones

Estas reglas aplican a todos los endpoints de la API v1. Síguelas una vez en tu cliente HTTP y todas las integraciones serán más simples.

Solicitudes y respuestasCopiar enlace de la sección

• JSON en snake_case. Las solicitudes con cuerpo (POST y PATCH) necesitan el header Content-Type: application/json, y el cuerpo debe ser un objeto JSON. Sin esto, la respuesta es 400 invalid_request.
• Los campos desconocidos se rechazan. Un campo que el endpoint no acepta genera 400 invalid_request con el mensaje Unexpected field "nome_do_campo". Así se evita que un error de tipeo pase desapercibido.
• Las fechas son strings ISO-8601 en UTC, como 2026-10-06T12:00:00.000Z. En los filtros (since, period_start, period_end), envíalas también en UTC.
• Los IDs son UUIDs, como 0c1d2e3f-1111-4222-8333-444455556666. Un id con formato incorrecto genera 400.
• Las respuestas exitosas incluyen Cache-Control: no-store. Las creaciones responden 201 y las demás operaciones, 200.

PaginaciónCopiar enlace de la sección

Las listas usan paginación por cursor. Envía limit (de 1 a 100, predeterminado 50) y, para las páginas siguientes, el cursor recibido:

curl -s "https://app.proteside.com/api/v1/alerts?status=open&limit=100" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"

{
  "data": [{ "id": "e1f2a3b4-8888-4999-8000-111122223333", "type": "PIX_TAMPERED", "...": "..." }],
  "next_cursor": "WyIyMDI2LTEwLTA2VDA5OjQwOjAwLjAwMFoiLCJlMWYyYTNiNC04ODg4LTQ5OTktODAwMC0xMTExMjIyMjMzMzMiXQ"
}

Cuando next_cursor viene en null, no hay más páginas. Trata el cursor como un valor opaco: no armes ni modifiques su contenido. Un cursor inválido genera 400 Invalid cursor.

Los elementos vienen del más nuevo al más antiguo (por fecha de creación; en GET /scripts, por la fecha en que se vio el script por primera vez). Dos listas no están paginadas y devuelven todo de una vez, sin next_cursor: GET /stores/{id}/pages y GET /reports/pci/schedule.

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

async function listAll(path, params = {}) {
  const items = [];
  let cursor = null;
  do {
    const qs = new URLSearchParams({ ...params, limit: '100' });
    if (cursor) qs.set('cursor', cursor);
    const res = await fetch(`${BASE}${path}?${qs}`, {
      headers: { Authorization: `Bearer ${process.env.PROTESIDE_TOKEN}` },
    });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const page = await res.json();
    items.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);
  return items;
}

const pendientes = await listAll('/scripts', { status: 'needs_review' });
console.log(`${pendientes.length} scripts esperando revisión`);

ErroresCopiar enlace de la sección

Todos los errores vienen con el mismo formato, con un código estable en error y un mensaje en inglés en message:

{ "error": "invalid_request", "message": "justification must have at least 10 characters" }

Usa error en tu lógica; message sirve para los logs y puede cambiar. Algunos errores traen campos extra, como limit y plan en plan_limit.

Un recurso de otra organización responde 404, no 403: la API no revela si el id existe en otro lugar.

Límite de solicitudesCopiar enlace de la sección

El límite es de 120 solicitudes por minuto por organización dueña del token, en una ventana deslizante de 60 segundos. Lo comparten todos los tokens de la organización y, para los partners, también las llamadas hechas en las organizaciones hijas.

Toda respuesta autenticada incluye:

Al superar el límite, la respuesta es 429 rate_limited con Retry-After: 60. Las llamadas con un token inválido (401) no cuentan; las llamadas con un token válido pero sin alcance (403) sí cuentan.

Repite con espera creciente los errores 429 y 500 y las fallas de red. Los demás 4xx no mejoran con un nuevo intento.

async function protesideFetch(url, init = {}, attempt = 0) {
  const res = await fetch(url, init);
  const retryable = res.status === 429 || res.status >= 500;
  if (!retryable || attempt >= 4) return res;

  const retryAfter = Number(res.headers.get('Retry-After'));
  const waitMs = retryAfter > 0
    ? retryAfter * 1000
    : Math.min(30_000, 1000 * 2 ** attempt) + Math.random() * 500;
  await new Promise((r) => setTimeout(r, waitMs));
  return protesideFetch(url, init, attempt + 1);
}

IdempotenciaCopiar enlace de la sección

Envía el header Idempotency-Key (1 a 255 caracteres) en cualquier POST para poder repetirlo de forma segura, por ejemplo después de un timeout. Si la misma clave vuelve a llegar dentro de las 24 horas, la API no ejecuta la operación otra vez: devuelve el mismo estado y el mismo cuerpo de la primera respuesta, con el header Idempotency-Replayed: true.

curl -s -X POST "https://app.proteside.com/api/v1/stores" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b8f2c1e-6d4a-4f0b-9c2e-7a1d5e8f9b30" \
  -d '{"domain":"mitienda.com"}'

• El header se ignora en GET, PATCH y DELETE.
• La misma clave usada con otro método u otra ruta genera 409 conflict.
• Las respuestas de error también se guardan: si el primer intento recibió 400, repetir con la misma clave devuelve el mismo 400 durante 24 horas. ¿Corregiste la solicitud? Genera una clave nueva.
• Las descargas de PDF y CSV no se guardan.

AuditoríaCopiar enlace de la sección

Todo cambio hecho por la API queda registrado en la auditoría con el autor api:<prefijo del token>, por ejemplo api:ps_live_Ab3dEf6hIj9kLm2nOp5qRs8t. La misma etiqueta aparece en los datos: en authorized_by de un script autorizado y en resolved_by_label de una alerta resuelta. Por eso conviene crear un token por integración: la auditoría muestra qué sistema hizo cada cambio.

Próximos pasosCopiar enlace de la sección