Skip to main content
Todo checkout tem um campo config — um JSON que descreve o layout construído no Checkout Builder (o editor visual do painel Cakto). Esta página documenta o formato desse JSON para quem for lê-lo ou escrevê-lo via Atualizar Checkout.
config é validado pela API pública, mas com um schema próprio da API pública — não é o mesmo contrato interno que o Checkout Builder do painel usa para salvar. As diferenças estão marcadas ao longo desta página, principalmente na seção Imagens.

​
Visão geral

desktop e mobile são independentes e opcionais — você pode enviar só um dos dois num PUT/PATCH (o outro permanece como estava). Cada um tem três chaves:

​
rows → columns → components

Não existe campo order/position em nenhum nível — a ordem é sempre a posição no array. A primeira linha de rows[] é a primeira a aparecer na página; dentro dela, a primeira coluna de columns[] fica à esquerda; dentro da coluna, o primeiro item de components[] fica no topo.
A API não confere se o número de colunas bate com layout.length, nem se existe algum bloco type: "checkout" em algum lugar da árvore. Um checkout sem esse bloco é aceito pela API, mas fica sem formulário de pagamento na página pública — inclua sempre um bloco checkout em algum rows[].columns[].components[].

​
Catálogo de blocos (components[].type)

type só aceita um destes valores — qualquer outro é rejeitado com 400. attributes é validado de acordo com o type: campos fora dessa lista são ignorados, e o tipo de cada campo é conferido (string, número, booleano).

​
Blocos globais (extra)

Ficam fora da árvore de linhas — são renderizados de forma fixa (popup, notificação flutuante, widget de chat), não em uma posição específica da página.

​
Imagens

A API pública não tem endpoint de upload de imagem. Só é possível referenciar uma imagem já hospedada em algum lugar — não existe uma rota tipo /gallery/upload na API pública para enviar um arquivo e receber uma URL de volta.
Para os blocos image, header (backgroundImage/productImage) e extra.exitPopup, o atributo de imagem é validado como string simples (a URL da imagem). Enviar um objeto nesses campos falha a validação com 400.
A única exceção é testimonial.avatar, que aceita um valor JSON livre (string ou objeto) — não é validado como URL.
Essa regra é diferente do editor visual do painel Cakto: lá, ao fazer upload de uma imagem, o Checkout Builder grava um objeto { id, preview } (o retorno do upload interno para a galeria do produto). Se você ler o config de um checkout montado pelo painel via API pública e regravá-lo sem alterar as imagens, pode encontrar esse formato de objeto — mas ao escrever um valor novo por aqui, use sempre a string da URL.
Na prática, para colocar uma imagem num checkout via API: hospede o arquivo você mesmo (seu storage, um CDN, etc.) e use a URL pública dele nos atributos acima. Para reaproveitar uma imagem já enviada pelo painel, copie a URL do campo preview do objeto existente.

​
Erros de validação

Um config inválido — type de bloco desconhecido, campo do tipo errado, row/column/component sem id — retorna 400 com os erros por campo, no formato padrão de erro descrito em Erros.

​
Ver também

Personalizar Checkout

Referência do endpoint, com um exemplo completo de config

Obter Checkout

Como ler o config de um checkout existente

Criar um checkout

Onde o checkout entra no fluxo de criar um produto

Erros

Formato padrão de erro de validação