# Partners y organizaciones hijas

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

URL: https://docs.proteside.com/es/docs/api/partners

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](https://proteside.com/es/soluciones/plataformas-de-ecommerce),
[PSP y pasarelas](https://proteside.com/es/soluciones/proveedores-de-pago) y el
[programa de socios](https://proteside.com/es/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](https://docs.proteside.com/es/docs/api/authentication).

> **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```bash
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"
  }'
```

```json
{
  "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"
}
```

- `name` (`string`): Nombre de la organización, de 2 a 120 caracteres.
- `owner_email` (`string`): Correo electrónico de quien será dueño de la hija.
- `plan` (`'essential' | 'business_50k' | 'business_100k' | 'business_150k' | 'business_200k' | 'business_250k' | 'business_300k' | 'business_400k' | 'business_500k' | 'enterprise'`), predeterminado: `'business_100k'`: Plan de la hija: essential es el Store; business_<n>k es el tramo del Business según el volumen mensual de páginas vistas de checkout.
- `billing_mode` (`'partner' | 'stripe'`), predeterminado: `'partner'`: partner: el cobro es contigo, el partner. stripe: la hija se suscribe directamente, con 14 días de prueba.

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 `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.

```bash
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```bash
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:

```json
{
  "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](https://docs.proteside.com/es/docs/api/conventions#l%C3%ADmite-de-solicitudes).

> **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:

```bash
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](https://docs.proteside.com/es/docs/api/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
- [Receta: tienda en una hija](https://docs.proteside.com/es/docs/api/recipes#partner-crear-una-tienda-en-una-organizaci%C3%B3n-hija): Del registro de la hija al snippet del SDK.
- [Referencia: organizaciones](https://docs.proteside.com/es/docs/api/reference/organizations/createOrganization): Campos y respuestas de los endpoints de organización.
