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.
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, PSPs, gateways e subadquirentes e o programa de 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.
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
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"
}'{
"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"
}Propriedade
Tipo
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
POSTePATCH:{"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"| 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
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 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.
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:
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çõ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.