Proteside Docs

Partners y organizaciones hijas

Crea y gestiona las organizaciones de tus clientes con un único token usando org_id y el alcance orgs:manage.

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.

El sitio presenta la propuesta para cada caso: plataformas de e-commerce, PSP y pasarelas y el programa de socios.

Cómo funciona

  • 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 empezar

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.

La organización partner necesita una tienda propia

El dashboard solo se abre para quien tiene al menos una tienda. Una organización partner sin tiendas no llega a Ajustes → API y no puede emitir el token. Registra una tienda de la propia organización (por ejemplo, tu sitio) antes de empezar.

Crear una organización hija

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": "business_100k"
  }'
{
  "id": "11112222-3333-4444-8555-666677778888",
  "name": "Mi Tienda",
  "plan": "business_100k",
  "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"
}

Propiedad

Tipo

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

ValorSignificado
sentEl correo no tenía cuenta; se envió una invitación para crear la contraseña
existing_userEl correo ya tenía cuenta; se agregó como dueño de la hija, sin correo de aviso
failedNo se pudo enviar la invitación; la hija se creó de todos modos
skippedLa invitación no se envió; la hija se creó de todos modos

El billing_mode: "partner" está disponible para partners aprobados; las condiciones comerciales se definen por contrato. La hija también recibe las políticas de aprobación predeterminadas.

El reporte programado depende del plan

El reporte PCI DSS programado (semanal o mensual) depende del plan de la hija. Elige el plan según los reportes que necesita tu cliente.

Actuar en una hija

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"
SituaciónRespuesta
Token sin orgs:manage403 insufficient_scope
org_id no es hija directa de la organización del token404 not_found
org_id sin formato UUID400 invalid_request

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 consumo

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 compartido

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.

Una Idempotency-Key por operación

Genera una Idempotency-Key nueva (por ejemplo, un UUID) para cada operación, incluso en cada hija. Reutiliza la misma clave solo para repetir exactamente la misma solicitud.

Webhooks en las hijas

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.

Limitaciones

  • 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 pasos

En esta página