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

# Visão geral de plataformas e marketplaces

> Conecte organizações à sua plataforma, ative cada conta e opere pagamentos sem misturar os recursos de vendedores diferentes.

Use o modelo de plataforma quando seu produto permite que outras empresas ou pessoas operem pagamentos. Cada vendedor, loja ou unidade se torna uma **organização conectada** com cadastro, ativação e recursos próprios.

Sua plataforma mantém uma integração central. O `org_*` identifica cada conta conectada e define onde os dados e pagamentos pertencem.

<Info>
  Na API pública, uma conta conectada é um objeto `organization` (`org_*`). Não existe um objeto separado chamado subconta. Use sempre “organização conectada” na interface e na integração.
</Info>

## Quando este modelo é adequado

| Cenário                           | Organização conectada                                      |
| --------------------------------- | ---------------------------------------------------------- |
| Marketplace                       | Cada vendedor que recebe por suas próprias vendas.         |
| Software vertical                 | Cada empresa cliente que cobra seus consumidores.          |
| Franquia ou operação multiunidade | Cada unidade que precisa de cadastro e operação separados. |
| Plataforma de criadores           | Cada criador que vende produtos, assinaturas ou eventos.   |

Se toda a operação pertence à mesma empresa e usa o mesmo cadastro financeiro, uma única organização costuma ser suficiente.

## Como os recursos se organizam

| Camada                | Responsabilidade                                                           |
| --------------------- | -------------------------------------------------------------------------- |
| Plataforma            | Mantém a integração central e o vínculo com organizações conectadas.       |
| Organização conectada | É dona de customers, produtos, pagamentos, assinaturas, faturas e extrato. |
| Activation Session    | Coleta ou atualiza os dados necessários para ativar uma organização.       |
| API key de plataforma | Autentica o servidor da plataforma.                                        |
| Header `Organization` | Seleciona a organização conectada ao operar recursos pertencentes à conta. |

Recursos de organizações diferentes não são agrupados no mesmo contexto. O ID da organização (`org_*`) deve ser persistido junto ao identificador do vendedor ou da conta no seu sistema.

<Note>
  O recurso `/v1/organizations` é exclusivo de Platforms. Autentique com a API key de plataforma e use a coleção ou o ID da URL para criar, listar, consultar ou atualizar uma organização conectada. Para operar customers, produtos, checkouts e pagamentos dessa conta, envie o mesmo `org_*` no header `Organization`.
</Note>

## Fluxo da organização conectada

<Steps>
  <Step title="Crie a organização">
    Envie nome e CPF/CNPJ para `POST /v1/organizations`. Guarde o `org_*` retornado.
  </Step>

  <Step title="Conclua a ativação">
    Use uma Activation Session hospedada ou envie o cadastro diretamente pela API. Os dois caminhos atualizam a mesma organização.
  </Step>

  <Step title="Acompanhe o status">
    Leia `activation_status` e `requirements` e processe os eventos `organization.*`.
  </Step>

  <Step title="Opere no contexto correto">
    Envie a API key de plataforma e `Organization: org_AinWSrAyKnG9x73A` para criar customers, checkouts, pagamentos e outros recursos daquela organização.
  </Step>
</Steps>

<Warning>
  Não confunda conexão ativa com ativação financeira. A conexão permite que a plataforma acesse a conta; `activation_status: "active"` informa que o perfil financeiro pode processar pagamentos. Uma conta em cadastro ou reprovação continua sendo a mesma organização conectada. Nos endpoints de recursos da conta, header ausente ou conexão inativa retorna `403`.
</Warning>

## Escolha o modelo de ativação

| Caminho                      | Use quando                                        | Responsabilidade da plataforma                               |
| ---------------------------- | ------------------------------------------------- | ------------------------------------------------------------ |
| Activation Session hospedada | Você quer o menor esforço de implementação.       | Criar a sessão e redirecionar o responsável pela conta.      |
| Ativação por API             | Você quer coletar os dados dentro do seu produto. | Construir a interface, enviar os blocos e tratar validações. |

Os caminhos podem ser usados em momentos diferentes sobre a mesma organização. O resultado chega pelo objeto `organization` e pelo evento `organization.updated`.

<Tip>
  Guarde um único `org_*` por vendedor. Use-o na URL dos endpoints de organizações, no header dos recursos da conta e para correlacionar o campo top-level `organization` recebido nos webhooks.
</Tip>

## Eventos da plataforma

Crie um endpoint com `events_from: "platform"` para receber eventos originados pelas organizações conectadas. O campo top-level `organization` identifica a conta que gerou cada evento.

Esse endpoint não inclui eventos da própria organização da plataforma. Se você precisa dos dois fluxos, crie outro endpoint com `events_from:
"organization"`.

## Decisões antes de implementar

* qual entidade do seu produto corresponde a uma organização conectada;
* quem coleta e corrige os dados de ativação;
* quais telas e ações a plataforma expõe para cada conta;
* quais eventos atualizam seu estado local;
* como o suporte identifica a organização responsável por cada operação.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Operar organizações conectadas" icon="building" href="/platforms/connected-organizations">
    Implemente criação, ativação, header `Organization` e webhooks.
  </Card>

  <Card title="Ativação hospedada" icon="arrow-up-right-from-square" href="/platforms/activate-with-hosted-session">
    Redirecione o responsável para uma Activation Session.
  </Card>

  <Card title="Ativação por API" icon="code" href="/platforms/activate-by-api">
    Colete e envie o cadastro dentro do seu produto.
  </Card>

  <Card title="Requisitos de ativação" icon="list-check" href="/platforms/resolve-activation-rejections">
    Trate pendências, reprovações e novas tentativas.
  </Card>
</CardGroup>