> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plataformas: organizações conectadas

> Crie, faça onboarding e opere organizações conectadas usando API key de plataforma e o header Organization.

Uma plataforma usa uma **API key de plataforma** para criar organizações
conectadas e, depois, operar recursos delas pelo header `Organization`.

O identificador público que você guarda é o ID da `organization` (`org_*`).
Não existe um objeto público separado para o vínculo plataforma↔organização.

## Fluxo recomendado

1. Crie a organização conectada para o CPF/CNPJ da conta.
2. Guarde o `id` retornado no seu sistema.
3. Quando precisar de cadastro financeiro, crie um onboarding session para o
   `organization_id` e envie o responsável pela conta para a `url` retornada.
4. Acompanhe `organization.created`, `onboarding.session.submitted`,
   `organization.review.required`, `organization.review.submitted` e
   `organization.updated` por webhook.
5. Para criar recursos para essa organização, use sua API key de plataforma com
   `Organization: <organization_id>`.

## Criar a organização conectada

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/organizations" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12.345.678/0001-90",
    "name": "Acme Ltda"
  }'
```

Resposta resumida:

```json theme={}
{
  "id": "org_123",
  "object": "organization",
  "activation_status": "activation_pending",
  "document": "12345678000190",
  "document_type": "cnpj",
  "metadata": {},
  "name": "Acme Ltda",
  "platform_id": "plat_123"
}
```

Chamadas repetidas com o mesmo CPF/CNPJ dentro da mesma plataforma retornam a
mesma organização. Guarde o `id` retornado; ele é o valor usado no header
`Organization`.

O `document` é a identidade fiscal **declarada** da organização: ele define se
o onboarding financeiro abre como pessoa física (CPF) ou jurídica (CNPJ).
Enquanto a organização não está ativa e não tem atividade de pagamento, o
documento pode ser corrigido com
[`POST /v1/organizations/{id}`](/api-reference/organizations/update) — útil
quando um cadastro é reprovado e a conta precisa tentar de novo com outro
documento, sem perder produtos e integrações já criados no mesmo `org_*`.
Depois da primeira ativação, o documento é permanente. O fluxo completo está
em [Reenviar KYC de uma organização](/guides/platform-organization-rekyc).

Veja o contrato completo em [Criar organização](/api-reference/organizations/create).

## Criar o onboarding session

Quando a organização precisar completar o cadastro financeiro, crie uma
onboarding session para o `id` da organização. A resposta emite uma URL fresca
para o fluxo hospedado.

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/onboarding-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "return_url": "https://meusite.com/onboarding/return"
  }'
```

A URL expira em 60 segundos. Para renovar, chame
`POST /v1/onboarding-sessions` de novo com o mesmo `organization_id`.

Veja o contrato completo em [Criar onboarding session](/api-reference/onboarding-sessions/create).

## Operar na organização conectada

Depois que você tem o ID da `organization`, envie esse valor no header
`Organization` em endpoints que aceitam atuação de plataforma.

Exemplo criando uma sessão de checkout:

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_123" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_123",
        "quantity": 1
      }
    ],
    "success_url": "https://meusite.com/sucesso",
    "cancel_url": "https://meusite.com/cancelado"
  }'
```

Exemplo criando um payment link:

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/payment-links" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_123" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_123",
        "quantity": 1
      }
    ],
    "success_url": "https://meusite.com/obrigado"
  }'
```

O header `Organization` é aceito apenas com API key de plataforma. API keys de
organização operam somente na própria organização e não podem usar esse header.

## Exibir a conta bancária

Para exibir a conta bancária cadastrada do host no admin da plataforma, consulte
a organização conectada:

```bash theme={}
curl -X GET "https://api.chargefy.io/v1/organizations/org_123" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}"
```

A conta ativa aparece em `bank_account`. Esse objeto inclui o `ba_*`, banco,
agência/roteamento, titular, tipo da conta, `is_active`, `is_verified` e os
quatro últimos dígitos. O número completo da conta nunca é retornado.

Quando a conta conectada muda, o webhook `organization.updated` também envia o
snapshot atual em `data.object.bank_account`. Para listar ou consultar contas
diretamente por `ba_*`, use os endpoints de
[`bank_accounts`](/api-reference/bank-accounts/object) com o header
`Organization`.

## Webhooks

Configure um endpoint para receber estes eventos:

* `organization.created`: a organização conectada foi criada e vinculada à plataforma.
* `onboarding.session.submitted`: a organização conectada concluiu o preenchimento do cadastro inicial.
* `organization.review.required`: há uma atualização cadastral pendente para a organização conectada.
* `organization.review.submitted`: a atualização cadastral hospedada foi enviada para análise.
* `organization.updated`: dados públicos ou status de ativação financeira mudaram.
* Eventos do recurso criado pela organização conectada, como `payment.intent.succeeded`
  e `checkout.session.completed`.

Em todos eles, o objeto público vem em `data.object`. Use o campo top-level
`organization` do evento para identificar a organização conectada que originou
o evento.

## Erros comuns

| Situação                                                                  | Resposta                                                                     |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| API key não é de plataforma                                               | `403`                                                                        |
| Header `Organization` ausente em chamada que exige atuação de plataforma  | `403`                                                                        |
| `Organization` aponta para organização sem vínculo ativo com a plataforma | `403`                                                                        |
| Organização ou onboarding session criado antes do setup da plataforma     | `409`                                                                        |
| URL do onboarding session expirada                                        | Chame `POST /v1/onboarding-sessions` novamente com o mesmo `organization_id` |