> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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 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**.

```bash theme={null}
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.

```bash theme={null}
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)

```typescript theme={null}
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.

```bash theme={null}
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)

```bash theme={null}
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.

```bash theme={null}
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](https://scaleup-c34c4386.mintlify.site/api-reference/sdk/organizations/checkouts-list.md)
* [Criar checkout do filho](https://scaleup-c34c4386.mintlify.site/api-reference/sdk/organizations/checkouts-create.md)
* [Obter checkout do filho](https://scaleup-c34c4386.mintlify.site/api-reference/sdk/organizations/checkouts-get.md)
* [Atualizar checkout do filho](https://scaleup-c34c4386.mintlify.site/api-reference/sdk/organizations/checkouts-update.md)

Exemplo rápido (criar):

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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`):

```bash theme={null}
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`.

```bash theme={null}
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:

```bash theme={null}
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)**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.