Referência de organizações
Criar uma organização
Cria uma organização conectada.
Cria uma organização conectada para a sua plataforma e devolve o objeto
Não envie
As cores voltam no formato em que foram salvas: quem enviou
Os juros pertencem ao plano de taxas escolhido em
organization completo. O identificador retornado em id é o valor que você
usa depois no header Organization para criar produtos, preços, checkout
sessions, payment links, invoices e subscriptions em nome dessa organização.
Só name e document são obrigatórios. Todo o resto tem default ou é
resolvido pela Chargefy.
Chamadas repetidas com o mesmo CPF/CNPJ dentro da mesma plataforma e ambiente retornam a
organização já existente. O create não substitui campos de perfil de uma
organização existente; use POST /v1/organizations/{id}
para atualizar nome, email, marca ou metadata depois da criação.
Uma organização excluída não é
reaproveitada: cadastrar o mesmo documento depois de uma exclusão cria uma
organização nova, com outro id. Vendas, clientes e catálogo da
organização excluída permanecem no identificador antigo e não são
transferidos.
O mesmo CNPJ criado com uma chave de teste e uma chave live recebe dois IDs
org_* diferentes. Por exemplo, o cadastro feito com ch_test_... só pode ser
usado em operações de teste; crie o cadastro live para operar em produção.
Criar a organização não submete nem aprova o KYC. Uma organização excluída não
é reutilizada por chamadas posteriores com o mesmo documento.
Autenticação
Requer API key de plataforma com escopoplatform_admin.
A organização criada já fica conectada à plataforma. Isso não significa que o
cadastro financeiro está aprovado: consulte
activation_status e
requirements para saber se ela pode receber pagamentos.Attributes
CPF (11 dígitos) ou CNPJ (14 dígitos) da organização conectada. Máscaras são
aceitas e normalizadas para somente dígitos. O documento é conferido pelo
dígito verificador: quantidade de dígitos diferente, sequência repetida ou
dígito verificador incorreto retorna
400. Este campo é a chave de
idempotência dentro da plataforma e do ambiente.Tipo do documento. Quando omitido, inferimos pela quantidade de dígitos de
document: 11 → cpf, 14 → cnpj. Se enviado, deve bater com o document
— senão 400.URL de file da Chargefy (
https://storage.chargefy.io/file_...) com purpose
organization_avatar, criada via POST /v1/files. URLs externas são rejeitadas com
400. O file precisa pertencer à própria organização conectada, então o fluxo
típico é criar a organização primeiro, subir o file com o header
Organization e definir o avatar via
update. Use null ou omita para vazio.Marca inicial 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. Aceita só a chave
appearance. Omitido, a organização nasce sem aparência própria (appearance: null) e usa a da sua plataforma. A logo das páginas é o avatar_url da organização; marca do rodapé, domínio próprio e a escolha de quem apresenta a venda ficam no Dashboard. A ativação e a revisão cadastral de uma organização filha usam sempre a marca da plataforma. Os quatro formatos aceitos estão em Marca.Plano de taxas que a organização paga:
- omitido,
nullou"default": a organização recebe o plano padrão atual e permanece nele até outra atribuição; - ID de um plano da sua plataforma (
plan_*): a organização usa esse plano até você trocar.
ch_live_...), porque o plano define o preço das
vendas reais da organização. Com chave de teste, omita o campo: enviar
fee_plan, mesmo null ou "default", retorna 400 com
code: "livemode_mismatch".A resposta traz o ID do plano atribuído. Veja os exemplos em
Plano de taxas.Mapa opcional
string → string com até 50 chaves. A Chargefy só armazena e
ecoa este objeto; use as chaves que fizerem sentido para o seu sistema.
Chaves: [a-zA-Z0-9_\-.]{1,40}. Valores: até 500 caracteres.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.
Marca
A aparência vai embranding_settings.appearance: o bloco completo, com as seis chaves, ou null. Cada cor aceita três formas — nome, hex ou null —, e as duas podem ser diferentes no mesmo bloco. O guia Marca e aparência mostra o que cada campo pinta nas páginas.
A marca não tem modo: a mesma organização usa a mesma aparência em teste e em produção, com chave ch_test_... ou ch_live_.... Quando o mesmo documento já tem uma organização na sua plataforma e a API devolve a existente, a marca enviada não é aplicada; use POST /v1/organizations/{id}.
(a) Cores pelo nome
Use uma das 18 cores quando quiser um tom pronto. O nome garante contraste entre o botão e o texto dele; as 17 paletas usam o mesmo tom nos dois temas, e só acarbon muda entre o claro e o escuro. Neste exemplo, o comprador vê o painel do produto e o botão Pagar em índigo, cantos bem arredondados (ellipse) e textos em Inter.
(b) Cores em hex
Use hex#RRGGBB para a cor exata da sua marca. O hex vale igual no tema claro e no escuro, e o texto do botão fica preto ou branco, o que tiver mais contraste. Neste exemplo, o painel do produto fica em #F6F9FC, o botão Pagar em verde #278629 com texto branco, e o Pix copia e cola aparece em Geist Mono.
"indigo" lê "indigo", quem enviou "#278629" lê "#278629". Nome e hex podem ser misturados no mesmo bloco.
(c) Sem cor de marca
Envienull nas duas cores para uma página só em tons de cinza. Botão e painel do produto usam o tom forte do cinza escolhido: quase preto em páginas claras, quase branco em escuras. Neste exemplo, com theme: "dark", o botão Pagar fica quase branco com texto escuro, em cantos retos (hexagon).
(d) Seguir a plataforma
Omitabranding_settings, ou envie appearance: null. A organização nasce sem aparência própria e as páginas dela usam a aparência da sua plataforma — e, se a plataforma não tiver uma, a padrão da Chargefy. Quando você muda a aparência da plataforma, as páginas dessa organização mudam junto.
Erros da marca
Mensagens que a API devolve, literalmente:
Plano de taxas
Toda organização criada recebe o plano padrão atual da sua plataforma, a menos que você fixe outro plano emfee_plan. A tabela de juros vem do plano. Trocar
o padrão depois não muda o plano de quem já existe; para trocar o de uma
organização, use POST /v1/organizations/{id}. O guia
Planos de taxas das organizações filhas explica o padrão
e quando a taxa vale.
Sandbox e live têm cadastros separados. fee_plan configura o preço das vendas
reais e só é aceito com chave de produção. Com chave de teste, omita o campo:
o cadastro de teste recebe o plano padrão. Para definir taxas live, crie ou
atualize o cadastro live com a chave de produção. Repetir este create com o
mesmo documento no mesmo ambiente não troca o plano.
(a) Usar o plano padrão atual
Omitafee_plan, ou envie null ou "default". A organização recebe o padrão atual. Trocar o padrão depois não altera essa organização.
(b) Fixar um plano
Envie o ID de um plano da sua plataforma. A organização paga esse plano mesmo que o padrão mude. Enviar o ID do plano que hoje é o padrão também fixa esse plano.(c) Documento que já existe na plataforma
Quando o CPF/CNPJ já tem uma organização na sua plataforma, a API devolve essa organização com o plano que ela já tinha. Ofee_plan enviado é validado
(400 ou 404 se for inválido), mas não é aplicado. Para trocar o plano de uma
organização existente, use
POST /v1/organizations/{id}.
O que a Chargefy resolve sozinha
documenté normalizado para somente dígitos edocument_typeé inferido pela quantidade de dígitos (11 →cpf, 14 →cnpj).- Mesmo documento na mesma plataforma e ambiente → retorna a organização conectada já existente, sem criar duplicata e sem sobrescrever o perfil dela.
- O
activation_statusé resolvido automaticamente pela Chargefy. Uma organização nova nascenot_submitted, comrequirements.missinglistando tudo que o cadastro financeiro ainda precisa. - Os campos de perfil opcionais (
email,branding_settings,socials, etc.) e ofee_plansó são aplicados quando a organização é criada de fato. - Sem
branding_settings, a organização nasce comappearance: nulle as páginas dela usam a aparência da sua plataforma. countryedefault_currencynascem com a organização: hoje,BRebrlpara todas. São só de leitura; enviar qualquer um dos dois retorna400comcode: "parameter_read_only"e o campo emparam, sem criar nada.- O webhook
organization.createdé emitido para a plataforma somente quando a organização é criada de fato — reuso idempotente não dispara webhook.
Resposta
200 OK com o objeto organization completo. Campos declarados nunca são
omitidos; vazio vem como null, {} ou [].
Erros
Próximos passos
Depois de criar a organização, use oid retornado como header
Organization nos endpoints que criam recursos em nome dela.
Se a organização precisar completar cadastro financeiro, crie uma
activation_session usando o id
retornado. Ela devolve a URL hospedada para o vendedor concluir o fluxo.
Tabela de juros do parcelamento
Disponível somente no Chargefy for Platforms, para operar suas organizações filhas.
fee_plan. Cada plano fixa uma tabela de juros na criação; várias combinações podem reutilizar a mesma tabela.
O campo installment_plan é somente leitura. Enviá-lo retorna 400 parameter_read_only em produção; com chave de teste, retorna 400 livemode_mismatch. Para trocar os juros de uma organização, escolha outro plano de taxas. A resposta mostra o plano e a tabela efetivos.
Escolher fee_plan: "default" ou null fixa o plano que é padrão naquele momento. Trocar o padrão depois não altera essa organização.
