Produtos e variantes
Endereço base: https://api.denaryx.com/admin/2026-10. Exemplos e regras no guia Produtos, coleções e marcas. Os erros seguem o formato comum. A especificação inteira: baixar o OpenAPI.
GET /products
Os produtos da loja
Escopo read_products ou read_content
Na ordem da última mudança, da mais antiga à mais nova, com o id para desempatar: para sincronizar, guarde o updated_at do último que leu e peça updated_at_min na próxima vez. A mudança de estoque de uma variante (um pedido, um ajuste) muda só o updated_at dela, e não o do produto: para o estoque, ver GET /variants.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
limit | consulta | integer | Quantos itens por página, de 1 a 100 (50 sem ele). |
cursor | consulta | string | O next_cursor da página anterior, como veio. Os filtros continuam os mesmos. |
ids | consulta | string | Só estes ids, separados por vírgula (até 100). |
updated_at_min | consulta | string (data e hora) | Só o que mudou a partir desta data (ISO 8601): a sincronização incremental. |
created_at_min | consulta | string (data e hora) | Só o criado a partir desta data (ISO 8601). |
created_at_max | consulta | string (data e hora) | Só o criado até esta data (ISO 8601). |
active | consulta | string | true: só os à venda; false: só os ocultos.Um de: true, false. |
collection_id | consulta | string (uuid) | Só os produtos da coleção e das coleções de baixo dela. |
Resposta
200 Sucesso. (ProductList)
Os campos da resposta (73)
| Campo | Tipo | Descrição |
|---|---|---|
data | lista de Product | |
data[].id | string (uuid) | |
data[].title | string | |
data[].handle | string | |
data[].description | string | |
data[].active | boolean | |
data[].template_suffix | string | |
data[].seo | objeto | |
data[].seo.title | string | |
data[].seo.description | string | |
data[].options | lista de objeto | |
data[].options[].name | string | |
data[].options[].attribute_id | string (uuid) ou null | |
data[].brand_id | string (uuid) ou null | |
data[].mpn | string | |
data[].condition | string | Um de: new, used, refurbished. |
data[].tax | objeto | |
data[].tax.ncm | string | |
data[].tax.cest | string | |
data[].tax.origin | string ou null | Um de: 0, 1, 2, 3, 4, 5, 6, 7, 8. |
data[].tax.unit | string | |
data[].dimensions | objeto ou null | |
data[].dimensions.weight_grams | integer | Maior que 0, até 30000. |
data[].dimensions.height_cm | integer | Maior que 0, até 200. |
data[].dimensions.width_cm | integer | Maior que 0, até 200. |
data[].dimensions.length_cm | integer | Maior que 0, até 200. |
data[].inventory_tracked | boolean | |
data[].sold_separately | boolean | |
data[].requires_prescription | boolean | |
data[].prescription_type | string | Um de: glasses, contact_lens. |
data[].contact_lens_mode | string | Um de: by_prescription, by_power. |
data[].collection_ids | lista de string (uuid) | |
data[].specifications | lista de objeto | |
data[].specifications[].attribute_id | string (uuid) | |
data[].specifications[].value | string ou number ou boolean ou lista de string (uuid) | |
data[].variants | lista de Variant | |
data[].variants[].id | string (uuid) | |
data[].variants[].product_id | string (uuid) | |
data[].variants[].options | lista de string | |
data[].variants[].sku | string ou null | |
data[].variants[].barcode | string ou null | |
data[].variants[].price | integer | |
data[].variants[].compare_at_price | integer ou null | |
data[].variants[].cost | integer ou null | |
data[].variants[].inventory_quantity | integer | |
data[].variants[].inventory_tracked | boolean | |
data[].variants[].prescription_range | objeto ou null | |
data[].variants[].prescription_range.sphere_min | number | |
data[].variants[].prescription_range.sphere_max | number | |
data[].variants[].prescription_range.cylinder_max | number | |
data[].variants[].prescription_range.add_min | number ou null | Sem ele: null. |
data[].variants[].prescription_range.add_max | number ou null | Sem ele: null. |
data[].variants[].prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
data[].variants[].prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
data[].variants[].position | integer | |
data[].variants[].updated_at | string (data e hora) | |
data[].images | lista de ProductImage | |
data[].images[].id | string (uuid) | |
data[].images[].src | string | |
data[].images[].thumbnail_src | string | |
data[].images[].width | integer | |
data[].images[].height | integer | |
data[].images[].alt | string | |
data[].images[].position | integer | |
data[].images[].variant_option | objeto ou null | |
data[].images[].variant_option.option_index | integer | |
data[].images[].variant_option.value | string | |
data[].try_on | objeto | |
data[].try_on.available | boolean | |
data[].try_on.type | string ou null | Um de: 2d, 3d. |
data[].created_at | string (data e hora) | |
data[].updated_at | string (data e hora) | |
next_cursor | string ou null |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
POST /products
Cria um produto
Escopo write_products
Com as variantes (de 1 a 100). Sem handle, o endereço sai do título. Um produto à venda nas coleções que pedem atributos obrigatórios precisa deles em specifications. O SKU, o código de barras e o handle não se repetem na loja (409).
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Corpo application/json: ProductCreate
| Campo | Tipo | Descrição |
|---|---|---|
titleobrigatório | string | De 2 a 120 caracteres. |
handle | string | Até 100 caracteres. |
description | string | Até 5000 caracteres.Sem ele: "". |
active | boolean | Sem ele: true. |
template_suffix | string | Até 40 caracteres.Sem ele: "". |
seo | objeto | Sem ele: {}. |
seo.title | string | Até 70 caracteres. |
seo.description | string | Até 320 caracteres. |
options | lista de objeto | Até 3 itens.Sem ele: []. |
options[].nameobrigatório | string | Até 30 caracteres. |
options[].attribute_id | string (uuid) ou null | |
brand_id | string (uuid) ou null | |
mpn | string | Até 60 caracteres.Sem ele: "". |
condition | string | Um de: new, used, refurbished.Sem ele: "new". |
tax | objeto | Sem ele: {}. |
tax.ncm | string | |
tax.cest | string | |
tax.origin | string ou null | Um de: 0, 1, 2, 3, 4, 5, 6, 7, 8. |
tax.unit | string | |
dimensions | objeto ou null | |
dimensions.weight_gramsobrigatório | integer | Maior que 0, até 30000. |
dimensions.height_cmobrigatório | integer | Maior que 0, até 200. |
dimensions.width_cmobrigatório | integer | Maior que 0, até 200. |
dimensions.length_cmobrigatório | integer | Maior que 0, até 200. |
inventory_tracked | boolean | Sem ele: true. |
sold_separately | boolean | Sem ele: true. |
requires_prescription | boolean | Sem ele: false. |
prescription_type | string | A receita que a lente pede: glasses (óculos) ou contact_lens (lente de contato). Só vale com requires_prescription.Um de: glasses, contact_lens.Sem ele: "glasses". |
contact_lens_mode | string | Como a lente de contato é vendida: by_prescription (o grau vem da receita, a variante tem a faixa) ou by_power (uma opção só, o grau, como -2,00; cada variante é a caixa de um grau, com sku, barcode e estoque, e a prescription_range sai do grau). Só vale com prescription_type contact_lens.Um de: by_prescription, by_power.Sem ele: "by_prescription". |
collection_ids | lista de string (uuid) | Até 10 itens.Sem ele: []. |
specifications | lista de objeto | Até 100 itens.Sem ele: []. |
specifications[].attribute_idobrigatório | string (uuid) | |
specifications[].valueobrigatório | string ou number ou boolean ou lista de string (uuid) | |
variantsobrigatório | lista de VariantCreate | De 1 a 100 itens. |
variants[].options | lista de string | Até 3 itens.Sem ele: []. |
variants[].sku | string ou null | Até 64 caracteres. |
variants[].barcode | string ou null | |
variants[].priceobrigatório | integer | De 0 a 100000000. |
variants[].compare_at_price | integer ou null | De 0 a 100000000. |
variants[].cost | integer ou null | De 0 a 100000000. |
variants[].inventory_quantity | integer | De 0 a 1000000.Sem ele: 0. |
variants[].prescription_range | objeto ou null | |
variants[].prescription_range.sphere_minobrigatório | number | |
variants[].prescription_range.sphere_maxobrigatório | number | |
variants[].prescription_range.cylinder_maxobrigatório | number | |
variants[].prescription_range.add_min | number ou null | Sem ele: null. |
variants[].prescription_range.add_max | number ou null | Sem ele: null. |
variants[].prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
variants[].prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
Resposta
201 Sucesso. (Product)
Os campos da resposta (71)
| Campo | Tipo | Descrição |
|---|---|---|
id | string (uuid) | |
title | string | |
handle | string | |
description | string | |
active | boolean | |
template_suffix | string | |
seo | objeto | |
seo.title | string | |
seo.description | string | |
options | lista de objeto | |
options[].name | string | |
options[].attribute_id | string (uuid) ou null | |
brand_id | string (uuid) ou null | |
mpn | string | |
condition | string | Um de: new, used, refurbished. |
tax | objeto | |
tax.ncm | string | |
tax.cest | string | |
tax.origin | string ou null | Um de: 0, 1, 2, 3, 4, 5, 6, 7, 8. |
tax.unit | string | |
dimensions | objeto ou null | |
dimensions.weight_grams | integer | Maior que 0, até 30000. |
dimensions.height_cm | integer | Maior que 0, até 200. |
dimensions.width_cm | integer | Maior que 0, até 200. |
dimensions.length_cm | integer | Maior que 0, até 200. |
inventory_tracked | boolean | |
sold_separately | boolean | |
requires_prescription | boolean | |
prescription_type | string | Um de: glasses, contact_lens. |
contact_lens_mode | string | Um de: by_prescription, by_power. |
collection_ids | lista de string (uuid) | |
specifications | lista de objeto | |
specifications[].attribute_id | string (uuid) | |
specifications[].value | string ou number ou boolean ou lista de string (uuid) | |
variants | lista de Variant | |
variants[].id | string (uuid) | |
variants[].product_id | string (uuid) | |
variants[].options | lista de string | |
variants[].sku | string ou null | |
variants[].barcode | string ou null | |
variants[].price | integer | |
variants[].compare_at_price | integer ou null | |
variants[].cost | integer ou null | |
variants[].inventory_quantity | integer | |
variants[].inventory_tracked | boolean | |
variants[].prescription_range | objeto ou null | |
variants[].prescription_range.sphere_min | number | |
variants[].prescription_range.sphere_max | number | |
variants[].prescription_range.cylinder_max | number | |
variants[].prescription_range.add_min | number ou null | Sem ele: null. |
variants[].prescription_range.add_max | number ou null | Sem ele: null. |
variants[].prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
variants[].prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
variants[].position | integer | |
variants[].updated_at | string (data e hora) | |
images | lista de ProductImage | |
images[].id | string (uuid) | |
images[].src | string | |
images[].thumbnail_src | string | |
images[].width | integer | |
images[].height | integer | |
images[].alt | string | |
images[].position | integer | |
images[].variant_option | objeto ou null | |
images[].variant_option.option_index | integer | |
images[].variant_option.value | string | |
try_on | objeto | |
try_on.available | boolean | |
try_on.type | string ou null | Um de: 2d, 3d. |
created_at | string (data e hora) | |
updated_at | string (data e hora) |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).409O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
GET /products/count
Quantos produtos casam com os filtros
Escopo read_products ou read_content
Os mesmos filtros da lista.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
ids | consulta | string | Só estes ids, separados por vírgula (até 100). |
updated_at_min | consulta | string (data e hora) | Só o que mudou a partir desta data (ISO 8601): a sincronização incremental. |
created_at_min | consulta | string (data e hora) | Só o criado a partir desta data (ISO 8601). |
created_at_max | consulta | string (data e hora) | Só o criado até esta data (ISO 8601). |
active | consulta | string | true: só os à venda; false: só os ocultos.Um de: true, false. |
collection_id | consulta | string (uuid) | Só os produtos da coleção e das coleções de baixo dela. |
Resposta
200 Sucesso. (Count)
Os campos da resposta (1)
| Campo | Tipo | Descrição |
|---|---|---|
count | integer |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
GET /products/{id}
Um produto
Escopo read_products ou read_content
O produto, com as variantes e as fotos.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
Resposta
200 Sucesso. (Product)
Os campos da resposta (71)
| Campo | Tipo | Descrição |
|---|---|---|
id | string (uuid) | |
title | string | |
handle | string | |
description | string | |
active | boolean | |
template_suffix | string | |
seo | objeto | |
seo.title | string | |
seo.description | string | |
options | lista de objeto | |
options[].name | string | |
options[].attribute_id | string (uuid) ou null | |
brand_id | string (uuid) ou null | |
mpn | string | |
condition | string | Um de: new, used, refurbished. |
tax | objeto | |
tax.ncm | string | |
tax.cest | string | |
tax.origin | string ou null | Um de: 0, 1, 2, 3, 4, 5, 6, 7, 8. |
tax.unit | string | |
dimensions | objeto ou null | |
dimensions.weight_grams | integer | Maior que 0, até 30000. |
dimensions.height_cm | integer | Maior que 0, até 200. |
dimensions.width_cm | integer | Maior que 0, até 200. |
dimensions.length_cm | integer | Maior que 0, até 200. |
inventory_tracked | boolean | |
sold_separately | boolean | |
requires_prescription | boolean | |
prescription_type | string | Um de: glasses, contact_lens. |
contact_lens_mode | string | Um de: by_prescription, by_power. |
collection_ids | lista de string (uuid) | |
specifications | lista de objeto | |
specifications[].attribute_id | string (uuid) | |
specifications[].value | string ou number ou boolean ou lista de string (uuid) | |
variants | lista de Variant | |
variants[].id | string (uuid) | |
variants[].product_id | string (uuid) | |
variants[].options | lista de string | |
variants[].sku | string ou null | |
variants[].barcode | string ou null | |
variants[].price | integer | |
variants[].compare_at_price | integer ou null | |
variants[].cost | integer ou null | |
variants[].inventory_quantity | integer | |
variants[].inventory_tracked | boolean | |
variants[].prescription_range | objeto ou null | |
variants[].prescription_range.sphere_min | number | |
variants[].prescription_range.sphere_max | number | |
variants[].prescription_range.cylinder_max | number | |
variants[].prescription_range.add_min | number ou null | Sem ele: null. |
variants[].prescription_range.add_max | number ou null | Sem ele: null. |
variants[].prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
variants[].prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
variants[].position | integer | |
variants[].updated_at | string (data e hora) | |
images | lista de ProductImage | |
images[].id | string (uuid) | |
images[].src | string | |
images[].thumbnail_src | string | |
images[].width | integer | |
images[].height | integer | |
images[].alt | string | |
images[].position | integer | |
images[].variant_option | objeto ou null | |
images[].variant_option.option_index | integer | |
images[].variant_option.value | string | |
try_on | objeto | |
try_on.available | boolean | |
try_on.type | string ou null | Um de: 2d, 3d. |
created_at | string (data e hora) | |
updated_at | string (data e hora) |
Erros
401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
PATCH /products/{id}
Muda campos de um produto
Escopo write_products ou write_content
Só o que vier muda. As variantes ficam como estão: elas mudam pelas rotas delas e pelos lotes de estoque e de preço. As listas (options, collection_ids, specifications) trocam a anterior inteira. Com write_content, só os textos: title, description, seo e handle (o endereço antigo leva ao novo); qualquer outro campo dá 403 missing_scope, com os campos que pedem write_products em fields.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Corpo application/json: ProductUpdate
| Campo | Tipo | Descrição |
|---|---|---|
title | string | De 2 a 120 caracteres. |
handle | string | Até 100 caracteres. |
description | string | Até 5000 caracteres. |
active | boolean | |
template_suffix | string | Até 40 caracteres. |
seo | objeto | |
seo.title | string | Até 70 caracteres. |
seo.description | string | Até 320 caracteres. |
options | lista de objeto | Até 3 itens. |
options[].nameobrigatório | string | Até 30 caracteres. |
options[].attribute_id | string (uuid) ou null | |
brand_id | string (uuid) ou null | |
mpn | string | Até 60 caracteres. |
condition | string | Um de: new, used, refurbished. |
tax | objeto | |
tax.ncm | string | |
tax.cest | string | |
tax.origin | string ou null | Um de: 0, 1, 2, 3, 4, 5, 6, 7, 8. |
tax.unit | string | |
dimensions | objeto ou null | |
dimensions.weight_gramsobrigatório | integer | Maior que 0, até 30000. |
dimensions.height_cmobrigatório | integer | Maior que 0, até 200. |
dimensions.width_cmobrigatório | integer | Maior que 0, até 200. |
dimensions.length_cmobrigatório | integer | Maior que 0, até 200. |
inventory_tracked | boolean | |
sold_separately | boolean | |
requires_prescription | boolean | |
prescription_type | string | A receita que a lente pede: glasses (óculos) ou contact_lens (lente de contato). Só vale com requires_prescription.Um de: glasses, contact_lens. |
contact_lens_mode | string | Como a lente de contato é vendida: by_prescription (o grau vem da receita, a variante tem a faixa) ou by_power (uma opção só, o grau, como -2,00; cada variante é a caixa de um grau, com sku, barcode e estoque, e a prescription_range sai do grau). Só vale com prescription_type contact_lens.Um de: by_prescription, by_power. |
collection_ids | lista de string (uuid) | Até 10 itens. |
specifications | lista de objeto | Até 100 itens. |
specifications[].attribute_idobrigatório | string (uuid) | |
specifications[].valueobrigatório | string ou number ou boolean ou lista de string (uuid) |
Resposta
200 Sucesso. (Product)
Os campos da resposta (71)
| Campo | Tipo | Descrição |
|---|---|---|
id | string (uuid) | |
title | string | |
handle | string | |
description | string | |
active | boolean | |
template_suffix | string | |
seo | objeto | |
seo.title | string | |
seo.description | string | |
options | lista de objeto | |
options[].name | string | |
options[].attribute_id | string (uuid) ou null | |
brand_id | string (uuid) ou null | |
mpn | string | |
condition | string | Um de: new, used, refurbished. |
tax | objeto | |
tax.ncm | string | |
tax.cest | string | |
tax.origin | string ou null | Um de: 0, 1, 2, 3, 4, 5, 6, 7, 8. |
tax.unit | string | |
dimensions | objeto ou null | |
dimensions.weight_grams | integer | Maior que 0, até 30000. |
dimensions.height_cm | integer | Maior que 0, até 200. |
dimensions.width_cm | integer | Maior que 0, até 200. |
dimensions.length_cm | integer | Maior que 0, até 200. |
inventory_tracked | boolean | |
sold_separately | boolean | |
requires_prescription | boolean | |
prescription_type | string | Um de: glasses, contact_lens. |
contact_lens_mode | string | Um de: by_prescription, by_power. |
collection_ids | lista de string (uuid) | |
specifications | lista de objeto | |
specifications[].attribute_id | string (uuid) | |
specifications[].value | string ou number ou boolean ou lista de string (uuid) | |
variants | lista de Variant | |
variants[].id | string (uuid) | |
variants[].product_id | string (uuid) | |
variants[].options | lista de string | |
variants[].sku | string ou null | |
variants[].barcode | string ou null | |
variants[].price | integer | |
variants[].compare_at_price | integer ou null | |
variants[].cost | integer ou null | |
variants[].inventory_quantity | integer | |
variants[].inventory_tracked | boolean | |
variants[].prescription_range | objeto ou null | |
variants[].prescription_range.sphere_min | number | |
variants[].prescription_range.sphere_max | number | |
variants[].prescription_range.cylinder_max | number | |
variants[].prescription_range.add_min | number ou null | Sem ele: null. |
variants[].prescription_range.add_max | number ou null | Sem ele: null. |
variants[].prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
variants[].prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
variants[].position | integer | |
variants[].updated_at | string (data e hora) | |
images | lista de ProductImage | |
images[].id | string (uuid) | |
images[].src | string | |
images[].thumbnail_src | string | |
images[].width | integer | |
images[].height | integer | |
images[].alt | string | |
images[].position | integer | |
images[].variant_option | objeto ou null | |
images[].variant_option.option_index | integer | |
images[].variant_option.value | string | |
try_on | objeto | |
try_on.available | boolean | |
try_on.type | string ou null | Um de: 2d, 3d. |
created_at | string (data e hora) | |
updated_at | string (data e hora) |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).409O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).422O pedido é válido, mas não pode ser atendido como está (invalid_request).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
DELETE /products/{id}
Exclui um produto
Escopo write_products
Com as variantes e as fotos. Os pedidos já feitos continuam com o nome e o preço da compra.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Resposta
204 Sucesso, sem corpo.
Erros
401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
POST /products/{id}/variants
Acrescenta uma variante
Escopo write_products
No fim da lista do produto, com um valor para cada opção dele. A combinação de valores não se repete no produto.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Corpo application/json: VariantCreate
| Campo | Tipo | Descrição |
|---|---|---|
options | lista de string | Até 3 itens.Sem ele: []. |
sku | string ou null | Até 64 caracteres. |
barcode | string ou null | |
priceobrigatório | integer | De 0 a 100000000. |
compare_at_price | integer ou null | De 0 a 100000000. |
cost | integer ou null | De 0 a 100000000. |
inventory_quantity | integer | De 0 a 1000000.Sem ele: 0. |
prescription_range | objeto ou null | |
prescription_range.sphere_minobrigatório | number | |
prescription_range.sphere_maxobrigatório | number | |
prescription_range.cylinder_maxobrigatório | number | |
prescription_range.add_min | number ou null | Sem ele: null. |
prescription_range.add_max | number ou null | Sem ele: null. |
prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
Resposta
201 Sucesso. (Variant)
Os campos da resposta (20)
| Campo | Tipo | Descrição |
|---|---|---|
id | string (uuid) | |
product_id | string (uuid) | |
options | lista de string | |
sku | string ou null | |
barcode | string ou null | |
price | integer | |
compare_at_price | integer ou null | |
cost | integer ou null | |
inventory_quantity | integer | |
inventory_tracked | boolean | |
prescription_range | objeto ou null | |
prescription_range.sphere_min | number | |
prescription_range.sphere_max | number | |
prescription_range.cylinder_max | number | |
prescription_range.add_min | number ou null | Sem ele: null. |
prescription_range.add_max | number ou null | Sem ele: null. |
prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
position | integer | |
updated_at | string (data e hora) |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).409O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
PATCH /products/{id}/variants/{variant_id}
Muda campos de uma variante
Escopo write_products
Só o que vier muda. inventory_quantity grava o número absoluto: com pedidos acontecendo, prefira POST /inventory/adjust.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
variant_idobrigatório | caminho | string (uuid) | O id da variante. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Corpo application/json: VariantUpdate
| Campo | Tipo | Descrição |
|---|---|---|
options | lista de string | Até 3 itens. |
sku | string ou null | Até 64 caracteres. |
barcode | string ou null | |
price | integer | De 0 a 100000000. |
compare_at_price | integer ou null | De 0 a 100000000. |
cost | integer ou null | De 0 a 100000000. |
inventory_quantity | integer | De 0 a 1000000. |
prescription_range | objeto ou null | |
prescription_range.sphere_minobrigatório | number | |
prescription_range.sphere_maxobrigatório | number | |
prescription_range.cylinder_maxobrigatório | number | |
prescription_range.add_min | number ou null | Sem ele: null. |
prescription_range.add_max | number ou null | Sem ele: null. |
prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
Resposta
200 Sucesso. (Variant)
Os campos da resposta (20)
| Campo | Tipo | Descrição |
|---|---|---|
id | string (uuid) | |
product_id | string (uuid) | |
options | lista de string | |
sku | string ou null | |
barcode | string ou null | |
price | integer | |
compare_at_price | integer ou null | |
cost | integer ou null | |
inventory_quantity | integer | |
inventory_tracked | boolean | |
prescription_range | objeto ou null | |
prescription_range.sphere_min | number | |
prescription_range.sphere_max | number | |
prescription_range.cylinder_max | number | |
prescription_range.add_min | number ou null | Sem ele: null. |
prescription_range.add_max | number ou null | Sem ele: null. |
prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
position | integer | |
updated_at | string (data e hora) |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).409O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
DELETE /products/{id}/variants/{variant_id}
Exclui uma variante
Escopo write_products
O produto fica com as outras. A única variante não sai: exclua o produto.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
variant_idobrigatório | caminho | string (uuid) | O id da variante. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Resposta
204 Sucesso, sem corpo.
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
GET /variants
As variantes da loja
Escopo read_products
Na ordem da última mudança, como a lista de produtos: é por aqui que se sincroniza o estoque e o preço (updated_at_min). Com sku, acha a variante pelo SKU.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
limit | consulta | integer | Quantos itens por página, de 1 a 100 (50 sem ele). |
cursor | consulta | string | O next_cursor da página anterior, como veio. Os filtros continuam os mesmos. |
ids | consulta | string | Só estes ids, separados por vírgula (até 100). |
sku | consulta | string | A variante com este SKU (exato). |
product_id | consulta | string (uuid) | Só as variantes deste produto. |
updated_at_min | consulta | string (data e hora) | Só o que mudou a partir desta data (ISO 8601): a sincronização incremental. |
Resposta
200 Sucesso. (VariantList)
Os campos da resposta (22)
| Campo | Tipo | Descrição |
|---|---|---|
data | lista de Variant | |
data[].id | string (uuid) | |
data[].product_id | string (uuid) | |
data[].options | lista de string | |
data[].sku | string ou null | |
data[].barcode | string ou null | |
data[].price | integer | |
data[].compare_at_price | integer ou null | |
data[].cost | integer ou null | |
data[].inventory_quantity | integer | |
data[].inventory_tracked | boolean | |
data[].prescription_range | objeto ou null | |
data[].prescription_range.sphere_min | number | |
data[].prescription_range.sphere_max | number | |
data[].prescription_range.cylinder_max | number | |
data[].prescription_range.add_min | number ou null | Sem ele: null. |
data[].prescription_range.add_max | number ou null | Sem ele: null. |
data[].prescription_range.base_curve | number ou null | A curva base (BC) da caixa, em mm: só na contact_lens. |
data[].prescription_range.diameter | number ou null | O diâmetro (DIA) da caixa, em mm: só na contact_lens. |
data[].position | integer | |
data[].updated_at | string (data e hora) | |
next_cursor | string ou null |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
POST /products/{id}/images
Acrescenta uma foto
Escopo write_products
O arquivo (JPEG, PNG ou WebP, até 10 MB) num multipart, ou, em JSON, o endereço https de onde a API baixa a foto. A foto entra no fim da lista, em WebP, em dois tamanhos. Um produto tem até 10 fotos. O endereço precisa ser público: a API não busca endereços internos nem segue mais de 3 redirecionamentos.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Corpo multipart/form-data
| Campo | Tipo | Descrição |
|---|---|---|
fileobrigatório | arquivo | A foto. |
alt | string | O texto da foto (até 125 caracteres). |
Corpo application/json: ProductImageFromUrl
Ou, no lugar do envio do arquivo, um JSON:
| Campo | Tipo | Descrição |
|---|---|---|
srcobrigatório | string | Até 2000 caracteres. |
alt | string | Até 125 caracteres.Sem ele: "". |
Resposta
201 Sucesso. (ProductImage)
Os campos da resposta (10)
| Campo | Tipo | Descrição |
|---|---|---|
id | string (uuid) | |
src | string | |
thumbnail_src | string | |
width | integer | |
height | integer | |
alt | string | |
position | integer | |
variant_option | objeto ou null | |
variant_option.option_index | integer | |
variant_option.value | string |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).413O corpo ou o arquivo passou do tamanho máximo (invalid_request).422O pedido é válido, mas não pode ser atendido como está (invalid_request).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
PATCH /products/{id}/images/{image_id}
Muda o texto de uma foto
Escopo write_products ou write_content
O texto alternativo (alt), que os buscadores e os leitores de tela leem. Vazio, a vitrine usa o nome do produto. O arquivo e a ordem não mudam por aqui.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
image_idobrigatório | caminho | string (uuid) | O id da foto. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Corpo application/json: ProductImageUpdate
| Campo | Tipo | Descrição |
|---|---|---|
altobrigatório | string | Até 125 caracteres. |
Resposta
200 Sucesso. (ProductImage)
Os campos da resposta (10)
| Campo | Tipo | Descrição |
|---|---|---|
id | string (uuid) | |
src | string | |
thumbnail_src | string | |
width | integer | |
height | integer | |
alt | string | |
position | integer | |
variant_option | objeto ou null | |
variant_option.option_index | integer | |
variant_option.value | string |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
DELETE /products/{id}/images/{image_id}
Exclui uma foto
Escopo write_products
As outras fotos sobem uma posição.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
image_idobrigatório | caminho | string (uuid) | O id da foto. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Resposta
204 Sucesso, sem corpo.
Erros
401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
GET /products/{id}/try_on
O provador virtual do produto
Escopo read_products
O arquivo do produto, que vale para as variantes sem um próprio (null, sem arquivo), e as variantes que têm o delas.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
Resposta
200 Sucesso. (ProductTryOn)
Os campos da resposta (41)
| Campo | Tipo | Descrição |
|---|---|---|
product_id | string (uuid) | |
try_on | TryOn ou null | |
try_on.type | string | Um de: 2d, 3d. |
try_on.width_mm | number | |
try_on.adjustments | objeto | |
try_on.adjustments.vertical_offset_mm | number | |
try_on.adjustments.tilt_degrees | number | |
try_on.adjustments.size_factor | number | |
try_on.front | objeto ou null | |
try_on.front.src | string | |
try_on.front.width | integer | |
try_on.front.height | integer | |
try_on.side | objeto ou null | |
try_on.side.src | string | |
try_on.side.width | integer | |
try_on.side.height | integer | |
try_on.model | objeto ou null | |
try_on.model.src | string | |
try_on.model.triangles | integer | |
try_on.updated_at | string (data e hora) | |
variants | lista de objeto | |
variants[].variant_id | string (uuid) | |
variants[].try_on | TryOn | |
variants[].try_on.type | string | Um de: 2d, 3d. |
variants[].try_on.width_mm | number | |
variants[].try_on.adjustments | objeto | |
variants[].try_on.adjustments.vertical_offset_mm | number | |
variants[].try_on.adjustments.tilt_degrees | number | |
variants[].try_on.adjustments.size_factor | number | |
variants[].try_on.front | objeto ou null | |
variants[].try_on.front.src | string | |
variants[].try_on.front.width | integer | |
variants[].try_on.front.height | integer | |
variants[].try_on.side | objeto ou null | |
variants[].try_on.side.src | string | |
variants[].try_on.side.width | integer | |
variants[].try_on.side.height | integer | |
variants[].try_on.model | objeto ou null | |
variants[].try_on.model.src | string | |
variants[].try_on.model.triangles | integer | |
variants[].try_on.updated_at | string (data e hora) |
Erros
401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
PUT /products/{id}/try_on
Grava o provador virtual do produto
Escopo write_products
Os arquivos vão por endereço https público, e a API baixa e processa cada um, como no painel: no 2d, a frente (front_url) e o lado (side_url, opcional), em PNG com o fundo transparente, até 10 MB; no 3d, o GLB (model_url), até 8 MB. type e width_mm sempre. Sem arquivo novo, fica o gravado do mesmo tipo: a largura e os ajustes mudam sem reenviar. Os ajustes que não vierem ficam como estavam (no arquivo novo, os padrões). side_url null tira o lado. A foto que não serve (sem transparência, pequena demais) e o GLB recusado dão 422 try_on_rejected, com o motivo.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Corpo application/json: TryOnUpdate
| Campo | Tipo | Descrição |
|---|---|---|
typeobrigatório | string | Um de: 2d, 3d. |
width_mmobrigatório | number | De 80 a 200. |
adjustments | objeto | |
adjustments.vertical_offset_mm | number | De -10 a 10. |
adjustments.tilt_degrees | number | De -5 a 20. |
adjustments.size_factor | number | De 0.8 a 1.2. |
front_url | string | Até 2000 caracteres. |
side_url | string ou null | Até 2000 caracteres. |
model_url | string | Até 2000 caracteres. |
Resposta
200 Sucesso. (ProductTryOn)
Os campos da resposta (41)
| Campo | Tipo | Descrição |
|---|---|---|
product_id | string (uuid) | |
try_on | TryOn ou null | |
try_on.type | string | Um de: 2d, 3d. |
try_on.width_mm | number | |
try_on.adjustments | objeto | |
try_on.adjustments.vertical_offset_mm | number | |
try_on.adjustments.tilt_degrees | number | |
try_on.adjustments.size_factor | number | |
try_on.front | objeto ou null | |
try_on.front.src | string | |
try_on.front.width | integer | |
try_on.front.height | integer | |
try_on.side | objeto ou null | |
try_on.side.src | string | |
try_on.side.width | integer | |
try_on.side.height | integer | |
try_on.model | objeto ou null | |
try_on.model.src | string | |
try_on.model.triangles | integer | |
try_on.updated_at | string (data e hora) | |
variants | lista de objeto | |
variants[].variant_id | string (uuid) | |
variants[].try_on | TryOn | |
variants[].try_on.type | string | Um de: 2d, 3d. |
variants[].try_on.width_mm | number | |
variants[].try_on.adjustments | objeto | |
variants[].try_on.adjustments.vertical_offset_mm | number | |
variants[].try_on.adjustments.tilt_degrees | number | |
variants[].try_on.adjustments.size_factor | number | |
variants[].try_on.front | objeto ou null | |
variants[].try_on.front.src | string | |
variants[].try_on.front.width | integer | |
variants[].try_on.front.height | integer | |
variants[].try_on.side | objeto ou null | |
variants[].try_on.side.src | string | |
variants[].try_on.side.width | integer | |
variants[].try_on.side.height | integer | |
variants[].try_on.model | objeto ou null | |
variants[].try_on.model.src | string | |
variants[].try_on.model.triangles | integer | |
variants[].try_on.updated_at | string (data e hora) |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).409O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).413O corpo ou o arquivo passou do tamanho máximo (invalid_request).422O pedido é válido, mas não pode ser atendido como está (invalid_request).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
DELETE /products/{id}/try_on
Tira o provador virtual do produto
Escopo write_products
Os arquivos saem. Na variante, ela volta a usar o arquivo do produto. Sem arquivo, 404.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Resposta
204 Sucesso, sem corpo.
Erros
401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
GET /products/{id}/variants/{variant_id}/try_on
O provador virtual da variante
Escopo read_products
O arquivo próprio da variante (a cor). null: a variante usa o do produto.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
variant_idobrigatório | caminho | string (uuid) | O id da variante. |
Resposta
200 Sucesso. (VariantTryOn)
Os campos da resposta (21)
| Campo | Tipo | Descrição |
|---|---|---|
product_id | string (uuid) | |
variant_id | string (uuid) | |
try_on | TryOn ou null | |
try_on.type | string | Um de: 2d, 3d. |
try_on.width_mm | number | |
try_on.adjustments | objeto | |
try_on.adjustments.vertical_offset_mm | number | |
try_on.adjustments.tilt_degrees | number | |
try_on.adjustments.size_factor | number | |
try_on.front | objeto ou null | |
try_on.front.src | string | |
try_on.front.width | integer | |
try_on.front.height | integer | |
try_on.side | objeto ou null | |
try_on.side.src | string | |
try_on.side.width | integer | |
try_on.side.height | integer | |
try_on.model | objeto ou null | |
try_on.model.src | string | |
try_on.model.triangles | integer | |
try_on.updated_at | string (data e hora) |
Erros
401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
PUT /products/{id}/variants/{variant_id}/try_on
Grava o provador virtual da variante
Escopo write_products
Os arquivos vão por endereço https público, e a API baixa e processa cada um, como no painel: no 2d, a frente (front_url) e o lado (side_url, opcional), em PNG com o fundo transparente, até 10 MB; no 3d, o GLB (model_url), até 8 MB. type e width_mm sempre. Sem arquivo novo, fica o gravado do mesmo tipo: a largura e os ajustes mudam sem reenviar. Os ajustes que não vierem ficam como estavam (no arquivo novo, os padrões). side_url null tira o lado. A foto que não serve (sem transparência, pequena demais) e o GLB recusado dão 422 try_on_rejected, com o motivo.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
variant_idobrigatório | caminho | string (uuid) | O id da variante. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Corpo application/json: TryOnUpdate
| Campo | Tipo | Descrição |
|---|---|---|
typeobrigatório | string | Um de: 2d, 3d. |
width_mmobrigatório | number | De 80 a 200. |
adjustments | objeto | |
adjustments.vertical_offset_mm | number | De -10 a 10. |
adjustments.tilt_degrees | number | De -5 a 20. |
adjustments.size_factor | number | De 0.8 a 1.2. |
front_url | string | Até 2000 caracteres. |
side_url | string ou null | Até 2000 caracteres. |
model_url | string | Até 2000 caracteres. |
Resposta
200 Sucesso. (VariantTryOn)
Os campos da resposta (21)
| Campo | Tipo | Descrição |
|---|---|---|
product_id | string (uuid) | |
variant_id | string (uuid) | |
try_on | TryOn ou null | |
try_on.type | string | Um de: 2d, 3d. |
try_on.width_mm | number | |
try_on.adjustments | objeto | |
try_on.adjustments.vertical_offset_mm | number | |
try_on.adjustments.tilt_degrees | number | |
try_on.adjustments.size_factor | number | |
try_on.front | objeto ou null | |
try_on.front.src | string | |
try_on.front.width | integer | |
try_on.front.height | integer | |
try_on.side | objeto ou null | |
try_on.side.src | string | |
try_on.side.width | integer | |
try_on.side.height | integer | |
try_on.model | objeto ou null | |
try_on.model.src | string | |
try_on.model.triangles | integer | |
try_on.updated_at | string (data e hora) |
Erros
400A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).409O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).413O corpo ou o arquivo passou do tamanho máximo (invalid_request).422O pedido é válido, mas não pode ser atendido como está (invalid_request).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).
DELETE /products/{id}/variants/{variant_id}/try_on
Tira o provador virtual da variante
Escopo write_products
Os arquivos saem. Na variante, ela volta a usar o arquivo do produto. Sem arquivo, 404.
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | caminho | string (uuid) | O id do produto. |
variant_idobrigatório | caminho | string (uuid) | O id da variante. |
Idempotency-Key | cabeçalho | string | Até 255 caracteres. A mesma escrita mandada de novo com a mesma chave, em até 24 horas, devolve a resposta guardada (com Idempotent-Replayed: true) em vez de acontecer duas vezes. |
Resposta
204 Sucesso, sem corpo.
Erros
401O token falta, não existe, foi revogado ou venceu (authentication_error).403O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).404O recurso não existe nesta loja (not_found).429Chamadas demais: espere o Retry-After (rate_limited).500Erro do nosso lado (api_error).503A API está ocupada com outras chamadas: espere o Retry-After (api_error).