Partners y organizaciones hijas

Si eres una agencia, una plataforma de e-commerce o un gateway y proteges el checkout de varios clientes, usa el modelo de partner: cada cliente se convierte en una organización hija de tu organización, con tiendas, scripts, alertas y reportes separados, y tú las operas todas con el mismo token.

Cómo funcionaCopiar enlace de la sección

• Tu organización (partner) puede tener varias hijas. Hay un solo nivel: una hija no crea hijas.
• Cada hija tiene su propio dueño, que recibe una invitación por correo electrónico y usa el dashboard con normalidad.
• Tu token sigue perteneciendo a tu organización. Para actuar en una hija, indicas cuál con org_id.
• En el dashboard, los miembros de la organización partner pueden ver los datos de las hijas, pero los cambios en las hijas se hacen mediante la API o por los miembros de la propia hija.

Antes de empezarCopiar enlace de la sección

Crea un token en Ajustes → API con el alcance orgs:manage y los alcances de las operaciones que vas a hacer en las hijas (por ejemplo stores:write, scripts:review, webhooks:manage, usage:read). Consulta Tokens y alcances.

Crear una organización hijaCopiar enlace de la sección

curl -s -X POST "https://app.proteside.com/api/v1/organizations" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8d1f4b2a-0c3e-4a5b-9d6f-1e2a3b4c5d6e" \
  -d '{
    "name": "Mi Tienda",
    "owner_email": "tu@mitienda.com",
    "plan": "growth"
  }'

{
  "id": "11112222-3333-4444-8555-666677778888",
  "name": "Mi Tienda",
  "plan": "growth",
  "billing_mode": "partner",
  "parent_org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "owner_email": "tu@mitienda.com",
  "partner_settings": {},
  "created_at": "2026-10-06T12:05:00.000Z",
  "owner_invite": "sent"
}

El campo owner_invite indica qué pasó con el dueño:

Con billing_mode: "partner", la hija nace activa: no tiene período de prueba ni límite de tiendas, y el reporte PCI DSS bajo demanda queda habilitado en cualquier plan. La hija también recibe las políticas de aprobación predeterminadas.

Actuar en una hijaCopiar enlace de la sección

Envía el ID de la hija en org_id:

• en la query string, con cualquier método: GET /stores?org_id=11112222-…;
• o en el cuerpo JSON, en POST y PATCH: {"org_id": "11112222-…", "domain": "mitienda.com"}.

En GET y DELETE, usa siempre la query string. Sin org_id, la llamada actúa en tu propia organización.

CHILD=11112222-3333-4444-8555-666677778888

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

GET /organizations, POST /organizations y GET /organizations/{id}/usage ignoran org_id: los dos primeros siempre actúan en la organización del token, y el de consumo usa el {id} de la ruta.

Todo lo que cambias en una hija queda en su auditoría con el autor api:<prefijo del token>.

Listar hijas y seguir el consumoCopiar enlace de la sección

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

curl -s "https://app.proteside.com/api/v1/organizations/$CHILD/usage" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"

El consumo siempre trae los últimos 7 meses (el actual y los 6 anteriores), del más reciente al más antiguo, con ceros en los meses sin uso. Los contadores se actualizan en tiempo real:

{
  "org_id": "11112222-3333-4444-8555-666677778888",
  "months": [
    {
      "period_month": "2026-10-01",
      "payment_pageviews": 18420,
      "events": 91234,
      "alerts": 12,
      "synthetic_runs": 4,
      "stores": [
        {
          "store_id": "0c1d2e3f-1111-4222-8333-444455556666",
          "payment_pageviews": 18420,
          "events": 91234,
          "alerts": 12,
          "synthetic_runs": 4
        }
      ]
    }
  ]
}

El {id} puede ser tu propia organización o una hija. Este endpoint exige usage:read (no orgs:manage).

Límite de solicitudes compartidoCopiar enlace de la sección

El límite de 120 solicitudes por minuto aplica a tu organización (dueña del token) y suma las llamadas hechas en todas las hijas. Si sincronizas muchos clientes, distribuye las llamadas a lo largo del tiempo y respeta el Retry-After. Consulta Convenciones.

Webhooks en las hijasCopiar enlace de la sección

Los eventos de una hija solo van a los canales de la propia hija. Un webhook creado en tu organización no recibe alertas de las tiendas de las hijas. Crea un webhook en cada hija:

curl -s -X POST "https://app.proteside.com/api/v1/webhooks?org_id=$CHILD" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://ops.parceiro.example/hooks/proteside", "min_severity": "medium"}'

Puedes usar la misma URL en todas las hijas. Para saber de qué cliente vino cada evento, usa el org_id del sobre. Cada webhook tiene su propio secreto, así que guarda el secreto de cada hija o envía un secret propio al crearlo. Detalles en Webhooks.

LimitacionesCopiar enlace de la sección

• No hay endpoints para consultar, modificar o eliminar una hija específica: solo listar (GET /organizations) y crear (POST /organizations). El plan y el nombre elegidos al crearla no se pueden cambiar mediante la API.
• No es posible crear tokens para una hija mediante la API. El dueño de la hija puede crear sus propios tokens en el dashboard.
• Una tienda suspendida (DELETE /stores/{id}) no se puede reactivar mediante la API.

Próximos pasosCopiar enlace de la sección