API legada/Referência completa/Configurações e notificações

Rotas de configurações

Lista, consulta e altera as configurações da loja, uma chave por vez.

As configurações reúnem os ajustes da loja em seções (general, checkout, payment...). Cada ajuste é um par chave e valor, identificado por seção.chave. Estas rotas servem para um sistema externo ler a configuração da loja ou mudar um ajuste sem abrir o painel. Todas exigem um usuário administrador.

GET/api/v1.0/settingsAdmin

Listar as configurações

Devolve as configurações em uma lista plana, sem paginação. Use section_id para ficar com uma seção só.

Parâmetros de consulta

section_idstring

generalfeaturescheckoutpaymentshippingnotificationstorefront_filterssecurityappearancevendors

Devolve só as configurações dessa seção. Um valor que não é seção devolve a lista vazia.

GET/api/v1.0/settings/{id}Admin

Consultar uma configuração

Devolve uma configuração pelo id.

Parâmetros de caminho

idstringobrigatório

Id no formato seção.chave, por exemplo checkout.flow_type.

PUT/api/v1.0/settings/{id}Admin

Alterar uma configuração

Troca o valor de uma chave. As demais chaves da seção ficam como estão. Responde 200 com o id.

Parâmetros de caminho

idstringobrigatório

Id no formato seção.chave.

Corpo da requisição

valueanyobrigatório

Novo valor. Use o mesmo tipo que a configuração já tem (texto, número, booleano, lista ou objeto).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/settings?section_id=checkout"

curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/v1.0/settings/checkout.min_qty_per_product" \
  -H "Content-Type: application/json" \
  -d '{"value": 2}'

Resposta

200Configurações de uma seção

json

{
  "settings": [
    { "object_id": "checkout.flow_type", "name": "flow_type", "value": "single_step", "section_id": "checkout", "section_tab_id": "" },
    { "object_id": "checkout.min_qty_per_product", "name": "min_qty_per_product", "value": 1, "section_id": "checkout", "section_tab_id": "" },
    { "object_id": "checkout.allow_guest_checkout", "name": "allow_guest_checkout", "value": true, "section_id": "checkout", "section_tab_id": "" }
  ],
  "params": { "total_items": 3 }
}

200Configuração alterada

json

{ "setting_id": "checkout.min_qty_per_product" }

Campos da resposta

settingsarray

Configurações.

settings[].object_idstring

Id no formato seção.chave. É o que as outras rotas pedem em {id}.

settings[].namestring

A chave, sem a seção.

settings[].valueany

Valor atual, no tipo em que está guardado. Valores de dinheiro e de percentual podem estar em unidades internas (centavos, por exemplo); confira o valor da sua loja antes de gravar.

settings[].section_idstring

Seção da configuração.

settings[].section_tab_idstring

Sempre vazio.

params.total_itemsinteger

Quantidade de configurações devolvidas.

setting_idstring

Na alteração, o id da configuração alterada.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"invalid JSON","status":400}`
400	Id sem ponto	`{"message":"invalid setting id format, expected section.key","status":400}`
400	Seção que não existe	`{"message":"unknown section: zzz","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Configuração inexistente (consulta)	`{"message":"setting not found: checkout.nope","status":404}`

Veja também

Rotas de configurações

Lista, consulta e altera as configurações da loja, uma chave por vez.

GET/api/v1.0/settingsAdmin

Listar as configurações

Devolve as configurações em uma lista plana, sem paginação. Use section_id para ficar com uma seção só.

Parâmetros de consulta

section_idstring

generalfeaturescheckoutpaymentshippingnotificationstorefront_filterssecurityappearancevendors

Devolve só as configurações dessa seção. Um valor que não é seção devolve a lista vazia.

GET/api/v1.0/settings/{id}Admin

Consultar uma configuração

Devolve uma configuração pelo id.

Parâmetros de caminho

idstringobrigatório

Id no formato seção.chave, por exemplo checkout.flow_type.

PUT/api/v1.0/settings/{id}Admin

Alterar uma configuração

Troca o valor de uma chave. As demais chaves da seção ficam como estão. Responde 200 com o id.

Parâmetros de caminho

idstringobrigatório

Id no formato seção.chave.

Corpo da requisição

valueanyobrigatório

Novo valor. Use o mesmo tipo que a configuração já tem (texto, número, booleano, lista ou objeto).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/settings?section_id=checkout"

curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/v1.0/settings/checkout.min_qty_per_product" \
  -H "Content-Type: application/json" \
  -d '{"value": 2}'

Resposta

200Configurações de uma seção

json

{
  "settings": [
    { "object_id": "checkout.flow_type", "name": "flow_type", "value": "single_step", "section_id": "checkout", "section_tab_id": "" },
    { "object_id": "checkout.min_qty_per_product", "name": "min_qty_per_product", "value": 1, "section_id": "checkout", "section_tab_id": "" },
    { "object_id": "checkout.allow_guest_checkout", "name": "allow_guest_checkout", "value": true, "section_id": "checkout", "section_tab_id": "" }
  ],
  "params": { "total_items": 3 }
}

200Configuração alterada

json

{ "setting_id": "checkout.min_qty_per_product" }

Campos da resposta

settingsarray

Configurações.

settings[].object_idstring

Id no formato seção.chave. É o que as outras rotas pedem em {id}.

settings[].namestring

A chave, sem a seção.

settings[].valueany

Valor atual, no tipo em que está guardado. Valores de dinheiro e de percentual podem estar em unidades internas (centavos, por exemplo); confira o valor da sua loja antes de gravar.

settings[].section_idstring

Seção da configuração.

settings[].section_tab_idstring

Sempre vazio.

params.total_itemsinteger

Quantidade de configurações devolvidas.

setting_idstring

Na alteração, o id da configuração alterada.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"invalid JSON","status":400}`
400	Id sem ponto	`{"message":"invalid setting id format, expected section.key","status":400}`
400	Seção que não existe	`{"message":"unknown section: zzz","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Configuração inexistente (consulta)	`{"message":"setting not found: checkout.nope","status":404}`