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

Use apenas o token da sua organização (pai) para gerenciar clientes, checkouts e links de checkout das sub-organizações vinculadas.

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:

• Checkout 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 link de checkout personalizado para clientes da sub-organização.

​

Pré-requisitos

1. OAT da organização pai com os escopos necessários (por exemplo checkout_links:write, customers:write, checkouts:write, etc.).
2. 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="[e-mail]"

---

​

1. Listar checkout 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/checkout-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/checkout-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/checkout-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/checkout-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:

• Listar checkouts do filho
• Criar checkout do filho
• Obter checkout do filho
• Atualizar checkout do filho

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": "[e-mail]",
    "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/checkout-links
Criar link	POST /api/v1/checkout-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).