Marketplace: OAT da organização pai e sub-organizações

Se você é um marketplace e cadastrou sub-organizações (vendedores filhos), não é obrigatório usar o Organization Access Token (OAT) de cada filho. Com o OAT da organização pai, você pode operar sobre recursos das sub-organizações desde que exista um vínculo direto na tabela organization_relationships (parent_organization_id → child_organization_id). Isso vale para:

Payment links — criar, listar, obter, atualizar e excluir links cujo produto pertence à sub-organização.
Checkouts — criar sessões de checkout para produtos da sub-organização; listar e consultar checkouts desses produtos.
Clientes — listar, exportar, criar, atualizar, excluir e gerar payment link personalizado para clientes da sub-organização.

Pré-requisitos

OAT da organização pai com os escopos necessários (por exemplo payment_links:write, customers:write, checkouts:write, etc.).
Relação pai–filho já criada (por exemplo via POST /v1/sdk/organizations/:orgId/link-as-parent ou fluxo de criação de sub-organização).

Defina variáveis de ambiente para os exemplos abaixo:

export API_BASE="https://api.chargefy.io/api"
export PARENT_OAT="oat_seu_token_do_marketplace"
export PARENT_ORG_ID="uuid_da_org_pai"
export CHILD_ORG_ID="uuid_da_sub_org"
export CHILD_PRODUCT_ID="uuid_produto_da_sub_org"
export CHILD_PRICE_ID="uuid_preco_do_produto"
export CUSTOMER_EMAIL="comprador@exemplo.com"

1. Listar payment links (pai + todas as sub-organizações)

Sem organization_id na query, o OAT do pai retorna links cuja organization_id é a própria org pai ou qualquer filho direto.

curl -s -X GET "${API_BASE}/v1/payment-links?page=1&limit=50" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Accept: application/json" | jq .

Filtrar apenas uma sub-organização

O valor de organization_id deve ser o UUID da sub-organização (filho). Só funciona se o token for da org pai desse filho.

curl -s -G "${API_BASE}/v1/payment-links" \
  --data-urlencode "organization_id=${CHILD_ORG_ID}" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Accept: application/json" | jq .

SDK (TypeScript)

import { Chargefy } from '@chargefy/sdk'

const chargefy = new Chargefy({ accessToken: process.env.PARENT_OAT! })

// Todos os links: org pai + sub-orgs (OAT do marketplace)
const allLinks = await chargefy.checkoutLinks.list({ page: 1, limit: 50 })
if (!allLinks.ok) throw allLinks.error

// Só links da sub-organização (organization_id na query)
const childOnly = await chargefy.checkoutLinks.list({
  organizationId: process.env.CHILD_ORG_ID!,
  page: 1,
  limit: 20,
})

// Criar link: basta productId (e price) do filho — organization_id é inferido do produto
const created = await chargefy.checkoutLinks.create({
  productId: process.env.CHILD_PRODUCT_ID!,
  productPriceId: process.env.CHILD_PRICE_ID!,
  successUrl: 'https://meusite.com/obrigado',
})
if (!created.ok) throw created.error

2. Criar checkout link para produto da sub-organização

O corpo segue o fluxo normal: product_id e product_price_id do produto da sub-org. A API valida se o OAT (pai) pode agir sobre a organização dona do produto.

curl -s -X POST "${API_BASE}/v1/payment-links" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "'"${CHILD_PRODUCT_ID}"'",
    "product_price_id": "'"${CHILD_PRICE_ID}"'",
    "success_url": "https://meusite.com/obrigado",
    "allow_discount_codes": true,
    "custom_price_amount": null
  }' | jq .

Resposta típica inclui url (link compartilhável) e id do link.

Com preço fixo em centavos (override)

curl -s -X POST "${API_BASE}/v1/payment-links" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "'"${CHILD_PRODUCT_ID}"'",
    "product_price_id": "'"${CHILD_PRICE_ID}"'",
    "success_url": "https://meusite.com/obrigado",
    "custom_price_amount": 19990
  }' | jq .

3. Criar sessão de checkout (POST /v1/checkouts)

Útil para fluxos programáticos (sem link reutilizável). O product_id é o da sub-organização.

curl -s -X POST "${API_BASE}/v1/checkouts" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "'"${CHILD_PRODUCT_ID}"'",
    "customer_email": "'"${CUSTOMER_EMAIL}"'",
    "amount": 19990
  }' | jq .

A resposta inclui client_secret e url para abrir o checkout.

3.1 URLs explícitas por sub-organização (recomendado para marketplaces)

Os endpoints /v1/sdk/organizations/:orgId/checkouts espelham listar / criar / obter / atualizar checkouts, mas fixam o vendedor filho no path. Isso evita enviar organization_id no corpo e garante que um produto de outro filho não seja aceito por engano (erro 422 na criação ou 404 na leitura). Documentação detalhada com exemplos cURL e TypeScript:

Exemplo rápido (criar):

curl -s -X POST "${API_BASE}/v1/sdk/organizations/${CHILD_ORG_ID}/checkouts" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "'"${CHILD_PRODUCT_ID}"'",
    "customer_email": "'"${CUSTOMER_EMAIL}"'"
  }' | jq .

4. Clientes na sub-organização

4.1 Listar clientes (pai + todos os filhos)

Sem organization_id, o OAT do pai lista clientes cuja organization_id está no conjunto da organização pai mais os filhos diretos.

curl -s -G "${API_BASE}/v1/customers" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Accept: application/json" | jq .

4.2 Listar só clientes de uma sub-organização

curl -s -G "${API_BASE}/v1/customers" \
  --data-urlencode "organization_id=${CHILD_ORG_ID}" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=50" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Accept: application/json" | jq .

4.3 Criar cliente na sub-organização

Com OAT do pai, envie organization_id no corpo apontando para a sub-org. A API exige que o pai seja pai direto dessa org.

curl -s -X POST "${API_BASE}/v1/customers" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "'"${CHILD_ORG_ID}"'",
    "email": "novo.cliente@exemplo.com",
    "name": "Cliente Sub-org"
  }' | jq .

Se você omitir organization_id com OAT, o cliente é criado na organização do token (a pai).

4.4 Exportar CSV (sub-org ou agregado)

Apenas sub-org:

curl -s -G "${API_BASE}/v1/customers/export" \
  --data-urlencode "organization_id=${CHILD_ORG_ID}" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -o clientes-suborg.csv

Pai + todas as sub-orgs (sem organization_id):

curl -s "${API_BASE}/v1/customers/export" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -o clientes-marketplace.csv

4.5 Link de checkout para um cliente específico (valor / vencimento recorrente)

Depois de obter o customer.id na sub-org. Payload mínimo (sem due_date nem no_fees_installments): para produto recorrente, a API define a primeira cobrança como o dia UTC atual; no_fees_installments assume false.

export CUSTOMER_ID="uuid_do_cliente_na_sub_org"

curl -s -X POST "${API_BASE}/v1/customers/${CUSTOMER_ID}/checkout-link" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "'"${CHILD_PRODUCT_ID}"'"}' | jq .

Com valor customizado e data de primeira cobrança explícita:

curl -s -X POST "${API_BASE}/v1/customers/${CUSTOMER_ID}/checkout-link" \
  -H "Authorization: Bearer ${PARENT_OAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "'"${CHILD_PRODUCT_ID}"'",
    "custom_amount": 24990,
    "due_date": "2026-04-15"
  }' | jq .

custom_amount: opcional; total em centavos para este checkout.
due_date: opcional (YYYY-MM-DD); para recorrentes, se omitido usa hoje UTC; se informado, entre hoje e +2 meses.
no_fees_installments: opcional; padrão false.

5. Erros comuns

Situação	Resposta típica
Produto de org que não é filha do token	`403` — produto não pertence à sua org nem a uma sub-organização direta
`organization_id` de cliente/checkout link de org não relacionada	`403` — texto sobre org ou sub-organização
Token é da sub-org tentando criar recurso na pai	Negado (o modelo só amplia pai → filho, não o contrário)

6. Referência rápida de endpoints

Ação	Método e caminho
Listar links	`GET /api/v1/payment-links`
Criar link	`POST /api/v1/payment-links`
Criar checkout	`POST /api/v1/checkouts`
Criar checkout (path do filho)	`POST /api/v1/sdk/organizations/:orgId/checkouts`
Listar / obter / atualizar checkout (path do filho)	`GET/PATCH /api/v1/sdk/organizations/:orgId/checkouts/...`
Listar clientes	`GET /api/v1/customers`
Criar cliente na sub-org	`POST /api/v1/customers` + `organization_id`
Exportar clientes	`GET /api/v1/customers/export`
Checkout link 1:1 cliente	`POST /api/v1/customers/:id/checkout-link`

Para criar produtos e descontos em nome do filho, continue usando os endpoints /v1/sdk/organizations/:orgId/... documentados em SDK (Sub-organizações).

Guias

Documentation Index

​Pré-requisitos

​1. Listar payment links (pai + todas as sub-organizações)

​Filtrar apenas uma sub-organização

​SDK (TypeScript)

​2. Criar checkout link para produto da sub-organização

​Com preço fixo em centavos (override)

​3. Criar sessão de checkout (POST /v1/checkouts)

​3.1 URLs explícitas por sub-organização (recomendado para marketplaces)

​4. Clientes na sub-organização

​4.1 Listar clientes (pai + todos os filhos)

​4.2 Listar só clientes de uma sub-organização

​4.3 Criar cliente na sub-organização

​4.4 Exportar CSV (sub-org ou agregado)

​4.5 Link de checkout para um cliente específico (valor / vencimento recorrente)

​5. Erros comuns

​6. Referência rápida de endpoints