Parceiros e organizações filhas

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.

Como funcionaCopiar link da seção

• 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çarCopiar link da seção

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.

Criar uma organização filhaCopiar link da seção

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": "growth"
  }'

{
  "id": "11112222-3333-4444-8555-666677778888",
  "name": "Minha Loja",
  "plan": "growth",
  "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"
}

O campo owner_invite diz o que aconteceu com o dono:

Com billing_mode: "partner", a filha já nasce ativa: não tem período de teste nem limite de lojas, e o relatório PCI DSS sob demanda fica liberado em qualquer plano. A filha também recebe as políticas de aprovação padrão.

Agir numa filhaCopiar link da seção

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.

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 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 consumoCopiar link da seção

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:

{
  "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 compartilhadoCopiar link da seção

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.

Webhooks nas filhasCopiar link da seção

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:

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.

LimitaçõesCopiar link da seção

• 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 passosCopiar link da seção