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:
| Valor | Significado |
|---|---|
sent | El correo no tenía cuenta; se envió una invitación para crear la contraseña |
existing_user | El correo ya tenía cuenta; se agregó como dueño de la hija, sin correo de aviso |
failed | No se pudo enviar la invitación; la hija se creó de todos modos |
skipped | La 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
POSTyPATCH:{"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ón | Respuesta |
|---|---|
Token sin orgs:manage | 403 insufficient_scope |
org_id no es hija directa de la organización del token | 404 not_found |
org_id sin formato UUID | 400 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.