Configurações por seção
Lê todas as configurações da loja de uma vez e grava uma seção por vez, com mesclagem dos campos enviados.
GET /settings devolve as configurações da loja organizadas em seções (general, checkout, payment...). PUT /settings grava uma seção por vez. É a rota por trás das telas de Configurações do painel.
Exigem o privilégio manage_settings.
Ler as configurações
/api/v1/admin/settingsAdminLer todas as seções de configuração
Sem parâmetros. Devolve um objeto com uma chave por seção.
curl "$BASE_URL/api/v1/admin/settings" \
-H "Authorization: Bearer $TOKEN"{
"general": { "store_name": "Loja Exemplo", "store_email": "contato@loja.example.com", "currency": "BRL", "language": "pt-BR", "timezone": "America/Sao_Paulo" },
"checkout": { "min_order_amount": 5000, "allow_guest_checkout": true, "one_step_checkout": false },
"payment": { "default_gateway": "", "enable_pix": true, "pix_discount_percent": 500, "max_installments": 12, "min_installment_value": 500, "interest_rate": 0, "free_installments": 3 },
"shipping": { "default_method": "standard", "free_ship_min": 19900, "enable_tracking": true },
"notification": { "order_confirmation": true, "admin_email": "admin@loja.example.com", "smtp_host": "smtp.example.com", "smtp_port": 587 }
}A resposta real traz as 12 seções: general, features, checkout, payment, shipping, notification, storefront_filters, security, appearance, vendors, focusnfe e order_timeline.
Gravar uma seção
/api/v1/admin/settingsAdminGravar os campos de uma seção
Grava os campos de data dentro da seção section. A gravação mescla: as chaves que você manda são atualizadas, as outras ficam como estão. Valores null são ignorados (nunca apagam). Se a chave já existe, o novo valor é convertido para o mesmo tipo (um "12" vira 12 onde o campo é número).
Corpo da requisição
sectionstringobrigatóriogeneralfeaturescheckoutpaymentshippingnotificationstorefront_filterssearchfocusnfesecurityappearancevendorssocial_proofprice_transparencyproduct_qapdp_mediafbtreview_rewardsorder_timelinedataobjectobrigatóriocurl -X PUT "$BASE_URL/api/v1/admin/settings" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"section":"payment","data":{"max_installments":10,"pix_discount_percent":500}}'{ "message": "settings updated" }Campos de cada seção
Dinheiro em centavos inteiros. Porcentagens de juros e do PIX em pontos-base (500 = 5%).
general
| Campo | Tipo | Significado |
|---|---|---|
store_name | texto | Nome da loja. |
store_email, support_email, support_phone | texto | Contatos exibidos. |
dpo_name, dpo_email, dpo_phone | texto | Encarregado de dados (LGPD), citado na política de privacidade padrão. |
currency, language, timezone | texto | Moeda (BRL), idioma (pt-BR) e fuso. |
logo_url, favicon_url | texto | Logo e favicon. |
category_include_children | booleano | Ao filtrar por categoria, inclui os produtos das subcategorias. |
hide_empty_categories | booleano | Esconde categorias sem produtos. |
simple_registration | booleano | Cadastro só com contato (nome, e-mail, telefone, CPF/CNPJ); o endereço fica para depois. |
company_year_started | inteiro | Ano de fundação, usado em rodapés de e-mail. |
admin_primary_color, vendor_primary_color, seller_primary_color | texto | Cor de destaque (hexadecimal) do painel do administrador, do painel do seller e do app de campo. Vazio herda a anterior. |
seller_monthly_goal_cents | inteiro | Meta mensal de vendas exibida no app de campo, em centavos. |
payment
| Campo | Tipo | Significado |
|---|---|---|
default_gateway | texto | Meio de pagamento padrão. |
enable_pix, enable_boleto, enable_card | booleano | Liga cada forma de pagamento. |
pix_discount_percent | inteiro | Desconto do PIX em pontos-base (500 = 5%, 0 = sem desconto). Aplicado pelo servidor ao pagar com PIX. |
max_installments | inteiro | Máximo de parcelas (padrão 12). |
min_installment_value | inteiro | Valor mínimo da parcela, em centavos (padrão 500). |
interest_rate | inteiro | Juros mensais em pontos-base (150 = 1,5%; 0 = sem juros). |
free_installments | inteiro | Quantas parcelas sem juros (padrão 3). |
shipping
| Campo | Tipo | Significado |
|---|---|---|
default_method | texto | Forma de envio padrão. |
free_ship_min | inteiro | Total do pedido, em centavos, a partir do qual o frete é grátis. |
enable_tracking | booleano | Liga o rastreamento. |
notification
| Campo | Tipo | Significado |
|---|---|---|
order_confirmation, shipping_update, promotion_emails | booleano | Quais avisos a loja envia ao cliente. |
admin_email | texto | E-mail geral da equipe. Departamentos sem e-mail próprio usam este. |
orders_department_email, users_department_email, help_department_email, newsletter_reply_to_email | texto | E-mails por departamento e de resposta da newsletter. |
smtp_host, smtp_port, smtp_username, smtp_password, smtp_encryption | texto e inteiro | Servidor de envio. smtp_encryption: tls, starttls ou none. Usuário e senha andam juntos: informar só um dos dois é recusado com 400. |
from_name, from_address | texto | Remetente dos e-mails. |
checkout
| Campo | Tipo | Significado |
|---|---|---|
min_order_amount | inteiro | Pedido mínimo, em centavos. |
min_order_includes_destination | booleano | Quando true, o pedido mínimo da área de entrega do cliente também entra no mínimo efetivo, por grupo de seller. Padrão false: o mínimo da área só libera o frete. |
allow_guest_checkout, allow_guest_cart, allow_guest_view_price | booleano | Compra, carrinho e visualização de preço sem login. |
allow_shopping_unlogged | booleano | false exige login desde o início (site, mini-loja e atendente de WhatsApp). |
one_step_checkout | booleano | Checkout em uma única página. |
allow_multiple_addresses | booleano | Endereços de cobrança e entrega separados. |
min_qty_per_product, max_qty_per_product | inteiro | Limites por produto no carrinho (0 = sem limite). |
checkout_from_cart_only, estimate_shipping_on_cart, group_cart_by_vendor | booleano | Exige passar pelo carrinho; estima frete no carrinho; agrupa itens por seller. |
use_single_coupon, unified_discount_code_field | booleano | Um único cupom por carrinho; um só campo para cupom, voucher e vale-presente. |
prices_include_tax, disable_tax_engine | booleano | Preços já com imposto; desliga o cálculo de impostos. |
terms_required, terms_text, terms_page_slug | booleano e texto | Aceite de termos no pedido: se é obrigatório, o texto ao lado da caixa (aceita HTML) e a página de CMS com o texto completo. |
customer_cancellation_enabled | booleano | Mostra ao cliente a ação de pedir cancelamento. |
customer_cancellation_auto_until_status, customer_cancellation_auto_days, customer_cancellation_auto_refund | texto, inteiro, booleano | Até qual status e quantos dias o cancelamento é automático, e se reembolsa. |
customer_cancellation_requested_status, customer_cancellation_approved_status, customer_cancellation_allow_review_after_limit | texto, booleano | Status do pedido durante e depois do pedido de cancelamento; permite pedir revisão após o limite. |
require_address_number, require_address_district | booleano | Exige número e bairro no endereço. |
cep_consistency | texto | off (padrão) ou block: com block, recusa endereço cujo CEP não bate com UF, cidade e bairro. |
qty_tier_rule | texto | Como a quantidade é precificada nas faixas de preço: lowest (padrão, o menor preço entre as faixas atingidas) ou highest_quantity (a faixa da maior quantidade atingida). |
offer_account_after_order, offer_passkey_after_order | booleano | Oferece criar conta ou passkey após o pedido. |
disable_rep_price_override, disable_catalog_delivery_filter | booleano | Desliga a edição de preço pelo representante; desliga o filtro por área de entrega. |
customer_invoice_email | booleano | Deixa o cliente enviar o PDF do pedido por e-mail. |
allow_seller_chat | booleano | Chat com o seller durante o checkout. |
features
Todos booleanos: wishlists, bestsellers, banners, seo, promotions, blog, newsletter, live_chat, order_audit_log, categories_by_vendor, product_premoderation, product_premoderation_updates, vendor_debt_payout, vendor_categories_fee, master_products, master_products_list_masters_only, realtime_order_notify. As chaves multi_vendor, soft_delete, field_masking e cdn_support são antigas e sem efeito.
vendors
| Campo | Tipo | Significado |
|---|---|---|
allow_vendor_registration | booleano | Permite que usuários peçam conta de seller. |
display_product_vendor | booleano | Mostra o seller na página do produto. |
review_vendors_before_access | booleano | Exige revisão do administrador antes de liberar o painel ao seller. |
vendors_per_page | inteiro | Sellers por página (padrão 12). |
marketplace_payments_enabled | booleano | Modo de pagamento de marketplace: divisão do pagamento com sellers, cobrança de comissão e repasses. Desligado, a loja é só um catálogo multi-seller. |
require_kyc_for_payouts | booleano | Exige verificação (KYC) aprovada para pedir repasse. |
default_settlement_term_days, default_settlement_term_anchor | inteiro, texto | Prazo padrão de repasse do boleto faturado e a âncora: payment (conta da confirmação do pagamento) ou per_installment (conta do vencimento de cada parcela do cliente). |
require_product_barcode, unique_product_barcode | booleano | Código de barras obrigatório; código de barras único (conflito dá 409). |
hidden_product_fields | lista de texto | Campos do formulário de produto que a operação não usa e o painel esconde. |
storefront_filters
enable_price_filter, enable_brand_filter, enable_feature_filters, enable_vendor_filter, enable_stock_filter, enable_free_shipping_filter (booleanos); price_filter, stock_filter, free_shipping_filter, vendor_filter (booleanos) com os respectivos *_name (rótulos); e feature_display_names (mapa de id de característica para o rótulo exibido).
security
reCAPTCHA (recaptcha_site_key, recaptcha_secret_key, recaptcha_min_score), entrada com Google (google_enabled, google_client_id, google_client_secret, google_redirect_uri, google_admin_login, google_vendor_login), entrada com Facebook para clientes (facebook_enabled, facebook_app_id, facebook_app_secret, facebook_redirect_uri), require_email_verification e login_identity (email, phone ou both).
order_timeline, appearance e focusnfe
order_timeline tem enabled e a lista steps (as etapas da barra do pedido). appearance está em Preferências de exibição. focusnfe guarda a integração fiscal: api_token, cnpj, environment, dados cadastrais e endereço da empresa, regime_tributario, auto_issue_on_complete e webhook_secret.
Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 400 | Corpo que não é JSON. | {"error":"invalid request body","detail":"..."} |
| 400 | Sem section, sem data, ou seção desconhecida. O detail ensina a forma do corpo e lista as seções. | {"error":"section is required","detail":"o corpo de PUT /settings é {\"section\":\"<seção>\",\"data\":{...}}, ..."} |
| 400 | Dados que a seção recusa por incoerência (por exemplo SMTP com senha e sem usuário, ou o contrário; ou status de cancelamento que não existe nos status da loja). | {"error":"O usuário do SMTP (smtp_username) ficaria em branco com a senha (smtp_password) preenchida, e nenhum e-mail sairia. ..."} |
| 401 | Sem token ou token expirado. | {"error":"invalid or expired token"} |
| 403 | Sem manage_settings. | {"error":"insufficient privileges","required":"manage_settings"} |
| 500 | Falha ao gravar. | {"error":"failed to update settings","detail":"..."} |
Mensagens que o servidor devolve em português chegam exatamente assim.