organization representa uma organização conectada da sua plataforma. Nela ficam a identidade pública, os dados fiscais, o endereço de cobrança, a marca das páginas hospedadas (branding_settings), o status financeiro (activation_status) e a lista de tarefas da ativação (requirements), que mostra o que falta preencher, o que está em análise e o que foi reprovado.
O recurso organizations é exclusivo do Chargefy for Platforms. Somente uma API key de plataforma com escopo platform_admin pode criar, listar, consultar, atualizar ou enviar organizações conectadas para análise. Uma API key de organização padrão não acessa esse recurso; ela atua diretamente nos recursos da própria conta, como produtos, customers e pagamentos.
No recurso
organizations, autentique com a API key de plataforma, use a
coleção ou o {id} da URL e não envie o header Organization. Em produtos,
customers, checkouts, pagamentos e outros recursos pertencentes à conta
conectada, envie o org_* no header Organization.organization. Para eventos enviados à plataforma, esse campo aponta para a organização conectada que originou a mudança, não para a organização da plataforma.
A organização dona da plataforma também é uma organização conectada a ela:
aparece na lista, pode ser consultada e tem perfil, marca e metadata
atualizáveis como qualquer outra. O cadastro financeiro, o plano de taxas, o
envio para análise e a exclusão dela não são alterados pela API.
Plataformas criam organizações conectadas com POST /v1/organizations. Para o cadastro financeiro existem dois caminhos, que escrevem na mesma ficha:
- Hospedado — crie uma
activation_sessionusando oorganization; ela devolve a URL hospedada para o vendedor concluir o fluxo. - Por API — preencha os blocos de cadastro com
POST /v1/organizations/{id}e envie para análise comPOST /v1/organizations/{id}/submit. O passo a passo está em Ativar organização por API.
Plano de taxas
fee_plan diz qual plano de taxas a
organização paga em cada venda:
Toda plataforma tem um plano padrão a partir da liberação das condições dela:
nesse momento a Chargefy cria o plano Padrão, e depois você pode escolher
outro plano como padrão no painel. Para trocar o plano de uma organização, envie
fee_plan em
POST /v1/organizations/{id}. O guia
Planos de taxas das organizações filhas explica o
processo completo.
Os blocos de cadastro
Além do perfil público, a organização guarda o cadastro financeiro declarado:
Duas regras de visibilidade valem para a leitura:
- Dados de empresa são públicos.
companyvem do registro público do CNPJ e aparece em qualquer organização daquele documento, tenha ela preenchido o cadastro ou não. - Dados de pessoa física são privados.
individual,representativeebusiness_profilesó aparecem para quem os cadastrou: eles vivem na organização que os coletou, e uma organização criada por outra plataforma para o mesmo documento lê esses blocos comonull.
requirements.
payout_account e statement_descriptor são propriedades do documento fiscal: são compartilhados por organizações com o mesmo CPF/CNPJ no mesmo ambiente, e alterá-los redefine o padrão de recebimento e o nome na fatura para as cobranças daquele documento. A conta é sempre mascarada — o número completo nunca é retornado. Enquanto o cadastro da organização não tem decisão (activation_status: "in_review"), payout_account pode vir null mesmo que o documento fiscal já tenha conta: ela aparece quando a organização é aprovada.
Data Object
Este é o formato completo retornado emcreate, get, update, itens de list e em data.object dos webhooks organization.*.
Status financeiro da organização. Sempre presente, em qualquer contexto de autenticação. Em
disabled, requirements explica o motivo e o que fazer — a organização pode iniciar uma nova tentativa de ativação sem trocar de org_*.Uma organização recém-criada começa em
not_submitted, mesmo que o CPF/CNPJ
já tenha outro cadastro aprovado. O KYC é avaliado para esta organização e
este ambiente; acompanhe requirements e envie o cadastro. Uma repetição do
create pode devolver uma organização existente com o estado que ela já tinha.Quando o cadastro financeiro foi enviado para análise pela última vez. Vem
null antes do primeiro envio.URL pública do logo ou avatar, servida como file da Chargefy
(
https://storage.chargefy.io/file_...).Conta para saques principal conectada à organização. É o campo recomendado para plataformas exibirem a conta cadastrada no admin do parceiro. Nunca inclui o número completo da conta; use
account_number_last4 para identificação. Ser a conta principal não garante o crédito dos repasses: a organização deve conferir os recebimentos no extrato bancário.Marca da organização nas páginas do comprador — checkout, confirmação da compra, fatura hospedada e portal do cliente — e no botão dos e-mails enviados ao comprador. Sempre presente. Traz só o que a própria organização salvou: a aparência herdada da plataforma ou da Chargefy não aparece aqui. A logo das páginas é o
avatar_url, a menos que outra logo (ou nenhuma) tenha sido escolhida no Dashboard; marca do rodapé, domínio próprio e a escolha de quem apresenta a venda são configurados só no Dashboard. O guia Marca e aparência mostra o que cada campo pinta.Perfil de negócio declarado da organização. Vem
null até algum dado existir, e também quando a leitura vem de uma organização que não declarou esses dados.Dados cadastrais da empresa. Só existe em organizações CNPJ; vem
null até algum dado ser coletado. É informação pública do registro do CNPJ: aparece em qualquer organização daquele documento.País da conta, em código ISO 3166-1 de duas letras. Hoje toda organização é
BR, porque o documento é CPF ou CNPJ. Só de leitura.Moeda padrão da organização, em código ISO 4217 minúsculo: hoje,
brl para
todas. Vale quando uma request não informa currency, como ao criar um
pagamento ou uma fatura. Só de leitura. Veja
Moedas.ID do plano de taxas atribuído à organização (
plan_*). Ele define taxas e juros. Trocar o padrão da plataforma não altera essa atribuição. Antes de um plano ser configurado, retorna "default".A pessoa física titular de uma organização CPF. Vem
null em organizações CNPJ, antes da coleta, ou quando a leitura vem de uma organização que não cadastrou essa pessoa. document é o próprio CPF da organização. Fotos de verificação nunca aparecem aqui — o progresso é reportado em requirements.Metadata da relação entre a plataforma autenticada e a organização conectada.
Retorna
{} quando vazia.ID da plataforma vinculada à organização conectada. Nas operações públicas de
organizations, identifica a plataforma autenticada.O representante legal de uma organização CNPJ. Vem
null em organizações CPF,
antes da coleta, ou quando a leitura vem de uma organização que não cadastrou
essa pessoa. Mesmo formato de individual; aqui document é o CPF do
representante. Fotos de verificação nunca aparecem aqui — o progresso é
reportado em requirements.Lista de tarefas da ativação financeira e motivos de bloqueio. Cada
activation_status preenche um lado do objeto. Um bloqueio pode acrescentar disabled_reason em qualquer estado.not_submitted→missinglista o que falta preencher antes do envio.in_review→pending_verificationlista o que está sendo verificado.active→ tarefas de ativação vazias.disabled→errorstraz as reprovações,missingtraz o que é corrigível edisabled_reasonmarca os casos terminais.
Nome exibido na fatura do comprador. É propriedade do documento fiscal e é
compartilhado entre organizações com o mesmo CPF/CNPJ. Vem
null enquanto não
houver valor declarado nem cadastro enviado.Operações
- Listar organizations
- Criar organization
- Consultar organization
- Atualizar organization
- Enviar o cadastro para análise
Eventos
Mudanças nesse objeto disparam os seguintes eventos, exclusivos de endpoints comevents_from: "platform":
organization.createdorganization.updatedorganization.review.requiredorganization.review.submitted
organization.* são entregues somente às plataformas conectadas; endpoints com events_from: "organization" não podem assiná-los. organization.created e organization.updated carregam o objeto organization completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados. Os eventos organization.review.* carregam o objeto da solicitação de revisão e usam o campo top-level organization para identificar a conta conectada.
Suporte e termos do vendedor
Essas informações pertencem à organização. Aparecem na fatura, no portal do cliente e no checkout quandocheckout_experience.footer_expanded estiver habilitado. Os termos são exibidos sem exigir aceite do comprador e são independentes de terms_acceptance, que registra o aceite da organização ao ativar sua conta.
Texto do link de atendimento, até 80 caracteres. Sem rótulo, a página usa “Fale com o suporte”.
Link HTTP/HTTPS dos termos, até 2.048 caracteres. Preencher este campo limpa
terms_text.terms_text e terms_url preenchidos na mesma requisição. Campos omitidos preservam o valor; envie null para limpar.
Tabela de juros do parcelamento
Disponível somente no Chargefy for Platforms, para operar suas organizações filhas.
Tabela de juros do plano de taxas da organização filha, como
"00299". Somente leitura: para mudar a tabela, atribua outro fee_plan. Sem plano configurado, "default" indica que ainda não há uma combinação atribuída. Cobranças já criadas mantêm seus valores.
