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

# Criar uma sessão de ativação

> 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 a uma plataforma. Envie o `organization`; a Chargefy usa os dados fiscais cadastrados nessa organização para abrir o fluxo hospedado.

**Apenas `organization` e `return_url` são obrigatórios. `metadata` é opcional, e URL, expiração e status são resolvidos pela Chargefy.**

Cada sessão representa **uma tentativa** de cadastro:

* se já existe uma sessão aberta (`created` ou `in_progress`), o `POST` devolve o mesmo `as_*` com uma URL nova;
* depois de `submitted`, essa tentativa não é reaberta;
* se a organização puder tentar novamente, o próximo `POST` cria outro `activation_session`, com outro `as_*`.

A organização continua com o mesmo `org_*` em todas as tentativas.

## Autenticação

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

## Attributes

<ParamField body="metadata" type="object">
  Mapa opcional `string → string` com até 50 chaves. Ecoado em `metadata` quando você consulta a sessão. Chaves: `[a-zA-Z0-9_\-.]{1,40}`. Valores: até 500 caracteres. Padrão: `{}`.
</ParamField>

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

## O que a Chargefy resolve sozinha

* **Uma sessão aberta por organização** — enquanto a tentativa estiver aberta, repetir o `POST` devolve o mesmo `as_*`. Uma nova tentativa recebe outro `as_*`; use o `org_*` como identificador estável da conta.
* **Etapas de ativação** — a Chargefy determina automaticamente o que precisa ser revisado ou preenchido e apresenta apenas as etapas necessárias no fluxo hospedado.
* **`url` e `expires_at`** — a cada `POST`, uma URL nova é emitida com `authorization_code` de uso único, válido por 60 segundos.
* **Dados fiscais** — o documento vem do cadastro da organização; sem documento válido, a criação retorna `422`.

<RequestExample>
  ```bash Mínimo theme={"theme":"css-variables"}
  curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
    -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "organization": "org_wkPueRS5fh1GMMij",
      "return_url": "https://meusite.com/activation/return"
    }'
  ```

  ```bash Com metadata theme={"theme":"css-variables"}
  curl -X POST "https://api.chargefy.io/v1/activation-sessions" \
    -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {},
      "organization": "org_wkPueRS5fh1GMMij",
      "return_url": "https://meusite.com/activation/return"
    }'
  ```
</RequestExample>

## Resposta

A resposta é o recurso `activation_session`.

<ResponseField name="id" type="string">
  ID da sessão de ativação (`as_*`).
</ResponseField>

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

<ResponseField name="created_at" type="string">
  Quando a sessão de ativação foi criada.
</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 a sessão de ativação foi criada 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">
  Estado da sessão.

  | Valor         | Descrição                                                              |
  | ------------- | ---------------------------------------------------------------------- |
  | `created`     | Sessão criada; o fluxo hospedado ainda não foi aberto.                 |
  | `in_progress` | O vendedor abriu o fluxo hospedado e está preenchendo.                 |
  | `submitted`   | Formulário enviado. Aprovação e reprovação pertencem à `organization`. |
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Última modificação da sessão de ativação.
</ResponseField>

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

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  {
    "id": "as_t6HURw6ftTuv13Gm",
    "object": "activation_session",
    "created_at": "2026-04-30T18:30:00Z",
    "expires_at": "2026-04-30T18:31:00Z",
    "livemode": true,
    "metadata": {},
    "opened_at": null,
    "organization": "org_wkPueRS5fh1GMMij",
    "platform": "plat_kQdRy4YQq22MA7Gy",
    "return_url": "https://meusite.com/activation/return",
    "status": "created",
    "updated_at": "2026-04-30T18:30:00Z",
    "url": "https://hosted.chargefy.io/activation/as_t6HURw6ftTuv13Gm?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 = in_review`: não cria nova sessão; aguarde o próximo `organization.updated`.
* `organization.activation_status = not_submitted`: cria ou renova o link normalmente.
* `organization.activation_status = disabled`: cria uma nova sessão para a mesma organização, desde que [`requirements.disabled_reason`](/platforms/resolve-activation-rejections) esteja `null` e o limite de tentativas não tenha sido atingido. Os dados já salvos na organização podem ser usados no preenchimento.

`disabled` não é definitivo para a organização. Ele significa que o perfil financeiro atual não está apto; uma nova tentativa de ativação pode reiniciar o cadastro mantendo o mesmo `org_*`. Antes de reenviar, leia `organization.requirements` e oriente a correção pelos caminhos em `missing` — o fluxo completo está em [Requisitos de ativação](/platforms/resolve-activation-rejections).

## Erros

| Status | `code`                              | Quando                                                                                              |
| ------ | ----------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`                   | Payload inválido (`organization`, `return_url`, `metadata`).                                        |
| `401`  | `authentication_failed`             | API key ausente, inválida, revogada ou expirada.                                                    |
| `403`  | `permission_denied`                 | API key sem escopo administrativo da plataforma.                                                    |
| `404`  | `resource_missing`                  | Organização conectada não encontrada para a plataforma.                                             |
| `409`  | `resource_state_conflict`           | Plataforma inativa ou configuração incompleta.                                                      |
| `409`  | `organization_already_active`       | Organização já ativada.                                                                             |
| `409`  | `organization_activation_in_review` | Organização já está em análise.                                                                     |
| `409`  | `activation_not_retryable`          | `requirements.disabled_reason` preenchido: sem caminho de reenvio ou limite de tentativas atingido. |
| `409`  | `document_already_in_use`           | O documento não pode ser usado nesta ativação.                                                      |
| `422`  | `organization_document_required`    | 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).