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

# Create an Onboarding Session

> Cria uma sessão de ativação financeira.

Cria ou renova uma sessão hospedada para ativar o perfil financeiro de uma
organização conectada existente. Envie o `organization`; a Chargefy usa os
dados fiscais cadastrados nessa organização para abrir o fluxo hospedado.

Chamadas repetidas para a mesma organização devolvem o mesmo `id` de
`onboarding_session`, com uma URL fresca por 60 segundos.

## Autenticação

API key de plataforma com escopo administrativo via header `Authorization:
Bearer {{API_KEY}}`.

## Attributes

<ParamField body="organization" type="string" required>
  ID da organização conectada (`org_*`) que será ativada financeiramente.
</ParamField>

<ParamField body="metadata" type="object">
  Mapa opcional `string → string` com até 50 chaves. Ecoado em
  `data.object.metadata` no webhook `onboarding.session.submitted`. Chaves:
  `[a-zA-Z0-9_\-.]{1,40}`. Valores: até 500 caracteres.
</ParamField>

<ParamField body="return_url" type="string" required>
  URL para onde o vendedor volta ao concluir ou sair do cadastro. Deve ser
  `http://` ou `https://` e ter no máximo 2048 caracteres.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/onboarding-sessions" \
    -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "organization": "org_789",
      "return_url": "https://example.com/onboarding/return"
    }'
  ```
</RequestExample>

## Resposta

A resposta é o recurso `onboarding_session`.

<ResponseField name="id" type="string">
  ID do onboarding session (`os_*`).
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"onboarding_session"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Quando o onboarding session foi criado.
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  ISO 8601 do momento em que a URL expira. `null` quando não há URL ativa.
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` quando o onboarding session foi criado com credencial de produção.
</ResponseField>

<ResponseField name="metadata" type="object">
  Eco do `metadata` enviado na criação.
</ResponseField>

<ResponseField name="opened_at" type="string | null">
  Quando o vendedor abriu o fluxo hospedado pela primeira vez.
</ResponseField>

<ResponseField name="organization" type="string">
  ID canônico da organização conectada (`org_*`).
</ResponseField>

<ResponseField name="platform" type="string">
  ID da sua plataforma (`plat_*`).
</ResponseField>

<ResponseField name="return_url" type="string">
  URL de retorno configurada na criação.
</ResponseField>

<ResponseField name="status" type="string">
  `created`, `in_progress`, `submitted`, `failed` ou `expired`.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Última modificação do onboarding session.
</ResponseField>

<ResponseField name="url" type="string | null">
  URL com `authorization_code` de uso único, válido por 60 segundos.
</ResponseField>

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "os_123",
    "object": "onboarding_session",
    "created_at": "2026-04-30T18:30:00Z",
    "expires_at": "2026-04-30T18:31:00Z",
    "livemode": true,
    "metadata": {},
    "opened_at": null,
    "organization": "org_789",
    "platform": "plat_456",
    "return_url": "https://meusite.com/onboarding/return",
    "status": "created",
    "updated_at": "2026-04-30T18:30:00Z",
    "url": "https://hosted.chargefy.io/onboarding/os_123?authorization_code=..."
  }
  ```
</ResponseExample>

## Regras

* `organization.activation_status = active`: não cria nova sessão; a organização já está apta a operar.
* `organization.activation_status = pending`: não cria nova sessão; aguarde o próximo `organization.updated`.
* `organization.activation_status = activation_pending`: cria ou renova o link normalmente.
* `organization.activation_status = disabled`: cria ou renova uma nova tentativa para a mesma organização.

`disabled` não é terminal para a organização. Ele significa que o perfil
financeiro atual não está apto; uma nova tentativa de onboarding pode criar um
novo perfil financeiro interno mantendo o mesmo `org_*`.

## Erros

| Status | Quando                                                         |
| ------ | -------------------------------------------------------------- |
| `400`  | Payload inválido (`organization`, `return_url`, `metadata`).   |
| `401`  | API key ausente, inválida, revogada ou expirada.               |
| `403`  | API key sem escopo `platform_admin`.                           |
| `404`  | Organização conectada não encontrada para a plataforma.        |
| `409`  | Platform inativa, setup incompleto, org ativa ou org pendente. |
| `422`  | A organização ainda não tem documento fiscal válido.           |

Para consultar o estado financeiro atual, use
[`GET /v1/organizations/{id}`](/api-reference/organizations/get). Para receber
mudanças em tempo real, escute
[`organization.updated`](/api-reference/webhooks/organization.updated).