Marca e aparência

A aparência é a parte da marca que define como as páginas do comprador se parecem. São sete escolhas que valem juntas: cor principal, cor secundária, tons de cinza, estilo, fonte, fonte de código e tema claro ou escuro. Elas vestem o checkout, a confirmação da compra, a fatura hospedada, o portal do cliente e o botão dos e-mails enviados ao comprador. A aparência fica em Configurações → Branding, no Dashboard, junto com a logo principal, a marca do rodapé e o domínio próprio, descritos em Configurar sua página de checkout. Uma organização nova começa sem aparência própria e usa a aparência padrão da Chargefy até você salvar a sua.

O que cada escolha pinta

Escolha	Campo na API	O que pinta	Valores
Cor principal	`button_color`	Botões, links, foco e itens selecionados nas páginas; o botão dos e-mails ao comprador.	Uma das 17 cores, hex `#RRGGBB` ou nenhuma (`null`).
Cor secundária	`background_color`	Painel do produto no checkout — a metade esquerda no computador, o bloco do topo no celular — e painel lateral do portal do cliente.	Uma das 17 cores, hex `#RRGGBB` ou nenhuma (`null`).
Escala de cinza	`gray_color`	Fundos, bordas e textos.	`neutral`, `stone`, `zinc`, `mauve`, `olive`, `mist` ou `taupe`.
Estilo	`style`	Forma, cantos e densidade de botões, campos e cards.	`vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera` ou `rhea`.
Fonte	`font`	Títulos, textos, preços, campos e botões.	`system` ou uma de 25 fontes.
Fonte de código	`font_mono`	Códigos que o comprador copia, como o Pix copia e cola.	`system` ou uma de 8 fontes.
Tema	`theme`	Claro ou escuro das páginas do comprador.	`light` ou `dark`.

O nome do campo só importa para quem define a aparência pela API, um recurso do Chargefy for Platforms descrito mais abaixo. No Dashboard, você escolhe pelos nomes da primeira coluna.

Cores: nome, hex ou nenhuma

Cor principal e cor secundária aceitam as mesmas três formas, e cada uma pode usar uma forma diferente:

Forma	Exemplo	O que o comprador vê
Uma das 17 cores	`green`	Um verde pronto, com o tom ajustado ao tema claro e ao escuro e contraste garantido entre o botão e o texto dele.
Hex `#RRGGBB`	`#278629`	Exatamente a cor da sua marca, igual nos dois temas. O texto do botão fica preto ou branco, o que tiver mais contraste.
Nenhuma (`null`)	`null`	Sem cor de marca: o tom forte da escala de cinza escolhida — quase preto em páginas claras, quase branco em páginas escuras.

As 17 cores são amber, blue, cyan, emerald, fuchsia, green, indigo, lime, orange, pink, purple, red, rose, sky, teal, violet e yellow. Se o hex do botão for quase igual à cor da página — um #FAFAFA em tema claro, por exemplo —, o botão ganha uma borda para continuar visível.

Estilo

Valor	Como fica
`vega`	Cantos levemente arredondados e espaçamento padrão.
`nova`	Cantos arredondados e espaçamento mais enxuto.
`maia`	Botões e campos em cápsula, cards bem arredondados e espaçamento generoso.
`lyra`	Cantos retos e texto compacto.
`mira`	Cantos levemente arredondados, texto menor e espaçamento denso.
`luma`	Cantos bem arredondados, botões em cápsula e cards com sombra suave.
`sera`	Cantos retos, botões em maiúsculas e espaçamento amplo.
`rhea`	Cantos arredondados, entre o padrão e a cápsula, e cards com sombra leve.

Escala de cinza

Valor	Como fica
`neutral`	Cinza puro, sem puxar para nenhuma cor.
`stone`	Cinza quente, levemente bege.
`zinc`	Cinza frio, levemente azulado.
`mauve`	Cinza com fundo lilás.
`olive`	Cinza com fundo verde-oliva.
`mist`	Cinza frio e claro, com fundo azul-acinzentado.
`taupe`	Cinza amarronzado.

Fontes

Fonte (font): system, a fonte do aparelho do comprador, ou inter, roboto, open_sans, geist, poppins, montserrat, outfit, plus_jakarta_sans, dm_sans, ibm_plex_sans, nunito, lato, noto_sans, nunito_sans, figtree, raleway, public_sans, delius_swash_caps, barlow, hind, instrument_sans, manrope, oxanium, gabriela ou source_code_pro.
Fonte de código (font_mono): system ou jetbrains_mono, fira_code, source_code_pro, geist_mono, ibm_plex_mono, roboto_mono, space_mono ou ubuntu_mono.

Exemplo

Uma loja cuja marca é verde #278629 quer o checkout claro, com o painel do produto num cinza-azulado bem suave e cantos discretos. A aparência dela fica assim:

{
  "background_color": "#F6F9FC",
  "button_color": "#278629",
  "font": "geist",
  "font_mono": "geist_mono",
  "gray_color": "neutral",
  "style": "vega",
  "theme": "light"
}

No checkout de um produto de R$ 199,90, o comprador vê o nome, a foto e o preço num painel #F6F9FC; ao lado, o formulário em fundo claro, com bordas e textos em cinza neutro; e o botão Pagar em verde #278629 com texto branco, de cantos levemente arredondados. Todos os textos estão em Geist. Se ele escolher Pix, o código copia e cola aparece em Geist Mono. No e-mail com o link da fatura, o botão também sai em verde #278629.

Quando a mudança aparece

Na hora, inclusive no que já foi enviado. Cada página guarda de quem é a marca, não as cores, e lê a aparência atual ao abrir. Um link de pagamento compartilhado ontem já abre hoje com o botão novo.
Igual em teste e em produção. A marca não tem modo: as páginas de teste e as de produção usam a mesma aparência.

Chargefy for Platforms

Esta seção só se aplica a contas com o produto Chargefy for Platforms habilitado. Nesse produto, uma plataforma opera pagamentos para suas organizações filhas.

Herança da aparência

Uma organização filha sem aparência própria veste a aparência da plataforma. Se a plataforma também não tiver uma, vale a aparência padrão da Chargefy.

Plataforma	Organização filha	O comprador da organização filha vê
Com aparência	Sem aparência própria (`appearance: null`)	A aparência da plataforma.
Com aparência	Com aparência própria	A aparência da organização filha.
Sem aparência	Sem aparência própria (`appearance: null`)	A aparência padrão da Chargefy.

Por exemplo: sua plataforma usa o botão verde #278629. A Acme Ltda, uma organização filha que nunca escolheu aparência, vende com o botão verde da plataforma e com a logo e o nome da Acme. No dia em que você troca o verde da plataforma por indigo, o checkout da Acme também passa a ser índigo. Se a Acme salvar uma aparência própria, as mudanças da plataforma deixam de chegar até ela. A herança vale só para a aparência: a logo das páginas continua sendo a da organização filha.

Definir a aparência de uma organização filha pela API

Envie branding_settings.appearance em POST /v1/organizations/{id}, com a API key da plataforma e sem o header Organization:

curl -X POST "https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "branding_settings": {
      "appearance": {
        "background_color": "#F6F9FC",
        "button_color": "#278629",
        "font": "geist",
        "font_mono": "geist_mono",
        "gray_color": "neutral",
        "style": "vega",
        "theme": "light"
      }
    }
  }'

A resposta traz a organização completa, com a aparência salva:

{
  "id": "org_bRLZQqUe7DrQxY4s",
  "object": "organization",
  "...": "demais campos da organization",
  "branding_settings": {
    "appearance": {
      "background_color": "#F6F9FC",
      "button_color": "#278629",
      "font": "geist",
      "font_mono": "geist_mono",
      "gray_color": "neutral",
      "style": "vega",
      "theme": "light"
    }
  }
}

Regras da escrita:

O bloco vai inteiro. appearance leva as sete chaves — as duas cores aceitam null — ou é null. Não há atualização parcial: para trocar só a cor principal, releia a organização e reenvie as sete chaves com a cor nova. Uma chave ausente retorna 400 parameter_missing.
null devolve a herança. appearance: null apaga a aparência própria, e a organização filha volta a vestir a da plataforma.
branding_settings só aceita appearance. Qualquer outra chave retorna 400 parameter_unknown, e um valor fora das listas acima, 400 parameter_invalid com os valores aceitos.
A leitura mostra só o que foi salvo. Uma organização que segue a plataforma lê appearance: null, nunca a aparência herdada. As cores voltam no formato em que foram salvas: quem enviou "indigo" lê "indigo".
Na criação, o mesmo bloco. Em POST /v1/organizations, branding_settings.appearance define a aparência inicial; sem ele, a organização filha nasce seguindo a plataforma.

Os quatro formatos — cores pelo nome, cores em hex, sem cor de marca e seguir a plataforma — têm exemplos completos em Atualizar uma organização. Cada mudança gera o webhook organization.updated, com o bloco anterior em previous_attributes.branding_settings. A logo das páginas é o avatar_url da organização filha, a menos que outra logo tenha sido escolhida no Dashboard. A marca do rodapé, o domínio próprio e a escolha de quem apresenta a venda são configurados só no Dashboard.

Quem apresenta a venda

Em Configurações da plataforma → Checkout, na seção Identidade no cabeçalho, a plataforma escolhe quem apresenta as vendas que ela cria para as organizações filhas. Quando a escolha é a plataforma, os checkouts que ela cria mostram a marca da plataforma — aparência, logo e domínio —, mesmo que a organização filha tenha aparência própria. A ativação e a revisão cadastral das organizações filhas usam sempre a marca da plataforma. O guia Marca e domínio próprio da plataforma explica a escolha e as exceções por organização.

Próximos passos

Configurar sua página de checkout

Logo principal, marca do rodapé e o Checkout Builder.

Usar seu próprio domínio

Sirva checkout, faturas e portal do cliente em um subdomínio seu.

Marca e domínio próprio da plataforma

Quem apresenta as vendas que a plataforma cria para as organizações filhas.

Atualizar uma organização

Os quatro formatos de branding_settings.appearance e os erros da marca.

Pagamentos online

Receber pagamentos

Clientes e faturamento

Assinaturas

Operação e pós-pagamento

Marketing e rastreamento

Marca e aparência

O que cada escolha pinta

Cores: nome, hex ou nenhuma

Estilo

Escala de cinza

Fontes

Exemplo

Quando a mudança aparece

Chargefy for Platforms

Herança da aparência

Definir a aparência de uma organização filha pela API

Quem apresenta a venda

Próximos passos

Configurar sua página de checkout

Usar seu próprio domínio

Marca e domínio próprio da plataforma

Atualizar uma organização

​O que cada escolha pinta

​Cores: nome, hex ou nenhuma

​Estilo

​Escala de cinza

​Fontes

​Exemplo

​Quando a mudança aparece

​Chargefy for Platforms

​Herança da aparência

​Definir a aparência de uma organização filha pela API

​Quem apresenta a venda

​Próximos passos

Configurar sua página de checkout

Usar seu próprio domínio

Marca e domínio próprio da plataforma

Atualizar uma organização

O que cada escolha pinta

Cores: nome, hex ou nenhuma

Estilo

Escala de cinza

Fontes

Exemplo

Quando a mudança aparece

Chargefy for Platforms

Herança da aparência

Definir a aparência de uma organização filha pela API

Quem apresenta a venda

Próximos passos