Referência de sessões de ativação
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 (
createdouin_progress), oPOSTdevolve o mesmoas_*com uma URL nova; - depois de
submitted, essa tentativa não é reaberta; - se a organização puder tentar novamente, o próximo
POSTcria outroactivation_session, com outroas_*.
org_* em todas as tentativas.
Autenticação
API key de plataforma com escopo administrativo via headerAuthorization: Bearer {{PLATFORM_API_KEY}}.
Attributes
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: {}.URL para onde o vendedor volta ao concluir ou sair do cadastro. Deve ser
http:// ou https:// e ter no máximo 2048 caracteres.O que a Chargefy resolve sozinha
- Uma sessão aberta por organização — enquanto a tentativa estiver aberta, repetir o
POSTdevolve o mesmoas_*. Uma nova tentativa recebe outroas_*; use oorg_*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.
urleexpires_at— a cadaPOST, uma URL nova é emitida comauthorization_codede uso único, válido por 1 hora.- Dados fiscais — o documento vem do cadastro da organização; sem documento válido, a criação retorna
422.
Resposta
A resposta é o recursoactivation_session.
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óximoorganization.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 querequirements.disabled_reasonestejanulle 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.
Erros
Para consultar o estado financeiro atual, use
GET /v1/organizations/{id}. Para receber mudanças em tempo real, escute organization.updated.
