# Parceiros e organizações filhas

> Crie e gerencie as organizações dos seus clientes com um único token usando org_id e o escopo orgs:manage.

URL: https://docs.proteside.com/pt-BR/docs/api/partners

Se você é agência, plataforma de e-commerce ou gateway e protege o checkout de vários clientes, use o modelo de
parceiro: cada cliente vira uma **organização filha** da sua organização, com lojas, scripts, alertas e relatórios
separados, e você opera todas com o mesmo token.

O site apresenta a proposta para cada caso:
[plataformas de e-commerce](https://proteside.com/solucao/plataformas-de-ecommerce),
[PSPs, gateways e subadquirentes](https://proteside.com/solucao/provedores-de-pagamento) e o
[programa de parceiros](https://proteside.com/parceiros).

## Como funciona
* A sua organização (parceira) pode ter várias **filhas**. Há só um nível: uma filha não cria filhas.
* Cada filha tem o próprio dono, que recebe convite por e-mail e usa o dashboard normalmente.
* O seu token continua pertencendo à sua organização. Para agir numa filha, você indica qual com `org_id`.
* No dashboard, os membros da organização parceira conseguem **ver** os dados das filhas, mas alterações nas filhas
  são feitas pela API ou pelos membros da própria filha.

## Antes de começar
Crie um token em **Configurações → API** com o escopo `orgs:manage` e os escopos das operações que vai fazer nas
filhas (por exemplo `stores:write`, `scripts:review`, `webhooks:manage`, `usage:read`). Veja
[Tokens e escopos](https://docs.proteside.com/pt-BR/docs/api/authentication).

> **A organização parceira precisa de uma loja própria**
>
> O dashboard só abre para quem tem pelo menos uma loja. Uma organização parceira sem lojas não chega a
> **Configurações → API** e não consegue emitir o token. Cadastre uma loja da própria organização (por exemplo, o seu
> site) antes de começar.

## Criar uma organização filha```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": "Minha Loja",
    "owner_email": "voce@minhaloja.com.br",
    "plan": "business_100k"
  }'
```

```json
{
  "id": "11112222-3333-4444-8555-666677778888",
  "name": "Minha Loja",
  "plan": "business_100k",
  "billing_mode": "partner",
  "parent_org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "owner_email": "voce@minhaloja.com.br",
  "partner_settings": {},
  "created_at": "2026-10-06T12:05:00.000Z",
  "owner_invite": "sent"
}
```

- `name` (`string`): Nome da organização, 2 a 120 caracteres.
- `owner_email` (`string`): E-mail de quem será dono da filha.
- `plan` (`'essential' | 'business_50k' | 'business_100k' | 'business_150k' | 'business_200k' | 'business_250k' | 'business_300k' | 'business_400k' | 'business_500k' | 'enterprise'`), padrão: `'business_100k'`: Plano da filha: essential é o Store; business_<n>k é a faixa do Business pelo volume mensal de pageviews de checkout.
- `billing_mode` (`'partner' | 'stripe'`), padrão: `'partner'`: partner: a cobrança é com você, parceiro. stripe: a filha assina direto, com 14 dias de teste.

O campo `owner_invite` diz o que aconteceu com o dono:

| Valor           | Significado                                                                             |
| --------------- | --------------------------------------------------------------------------------------- |
| `sent`          | O e-mail não tinha conta; um convite foi enviado para criar a senha                     |
| `existing_user` | O e-mail já tinha conta; ele foi adicionado como dono da filha, **sem** e-mail de aviso |
| `failed`        | O convite não pôde ser enviado; a filha foi criada mesmo assim                          |
| `skipped`       | O convite não foi enviado; a filha foi criada mesmo assim                               |

O `billing_mode: "partner"` está disponível para parceiros aprovados; as condições comerciais são definidas em
contrato. A filha também recebe as políticas de aprovação padrão.

> **Relatório agendado depende do plano**
>
> O relatório PCI DSS **agendado** (semanal ou mensal) depende do plano da filha. Escolha o plano de acordo com os
> relatórios de que o cliente precisa.

## Agir numa filha
Envie o ID da filha em `org_id`:

* na **query string**, em qualquer método: `GET /stores?org_id=11112222-…`;
* ou no **corpo JSON**, em `POST` e `PATCH`: `{"org_id": "11112222-…", "domain": "minhaloja.com.br"}`.

Em `GET` e `DELETE`, use sempre a query string. Sem `org_id`, a chamada age na sua própria organização.

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

| Situação                                                | Resposta                 |
| ------------------------------------------------------- | ------------------------ |
| Token sem `orgs:manage`                                 | `403 insufficient_scope` |
| `org_id` não é filha **direta** da organização do token | `404 not_found`          |
| `org_id` fora do formato UUID                           | `400 invalid_request`    |

`GET /organizations`, `POST /organizations` e `GET /organizations/{id}/usage` ignoram `org_id`: as duas primeiras
sempre agem na organização do token, e a de consumo usa o `{id}` do caminho.

Tudo o que você altera numa filha fica na auditoria dela com o autor `api:<prefixo do token>`.

## Listar filhas e acompanhar o 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"
```

O consumo traz sempre os últimos 7 meses (o atual e os 6 anteriores), do mais recente para o mais antigo, com zeros nos
meses sem uso. Os contadores são atualizados em tempo 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
        }
      ]
    }
  ]
}
```

O `{id}` pode ser a sua própria organização ou uma filha. Esse endpoint exige `usage:read` (não `orgs:manage`).

## Limite de requisições compartilhado
O limite de 120 requisições por minuto vale para a **sua** organização (dona do token) e soma as chamadas feitas em
todas as filhas. Se você sincroniza muitos clientes, distribua as chamadas ao longo do tempo e respeite o
`Retry-After`. Veja [Convenções](https://docs.proteside.com/pt-BR/docs/api/conventions#limite-de-requisi%C3%A7%C3%B5es).

> **Uma Idempotency-Key por operação**
>
> Gere uma `Idempotency-Key` nova (por exemplo, um UUID) para cada operação, inclusive em cada filha. Reutilize a
> mesma chave só para repetir exatamente a mesma requisição.

## Webhooks nas filhas
Os eventos de uma filha só vão para os canais **da própria filha**. Um webhook criado na sua organização não recebe
alertas das lojas das filhas. Crie um webhook em cada filha:

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

Você pode usar a mesma URL em todas as filhas. Para saber de qual cliente veio cada evento, use o `org_id` do
envelope. Cada webhook tem o próprio segredo, então guarde o segredo de cada filha ou envie um `secret` seu na
criação. Detalhes em [Webhooks](https://docs.proteside.com/pt-BR/docs/api/webhooks).

## Limitações
* Não há endpoints para consultar, alterar ou excluir uma filha específica: só listar (`GET /organizations`) e criar
  (`POST /organizations`). O plano e o nome escolhidos na criação não podem ser alterados pela API.
* Não é possível criar tokens para uma filha pela API. O dono da filha pode criar os próprios tokens no dashboard.
* Uma loja suspensa (`DELETE /stores/{id}`) não pode ser reativada pela API.

## Próximos passos
- [Receita: loja numa filha](https://docs.proteside.com/pt-BR/docs/api/recipes#parceiro-criar-uma-loja-numa-organiza%C3%A7%C3%A3o-filha): Do cadastro da filha ao snippet do SDK.
- [Referência: organizações](https://docs.proteside.com/pt-BR/docs/api/reference/organizations/createOrganization): Campos e respostas dos endpoints de organização.
