VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Guia rápido/Variações e opções

Combinações de opções

Lê, cria, altera e zera o estoque por combinação de opções de um produto pela API legada.

Quando duas opções se combinam (Tamanho M com Cor Azul), cada combinação pode ter estoque e código próprios. Estas rotas, no contrato da Venddor 1.0, mantêm esse estoque. A combinação é identificada por um hash calculado a partir do mapa id da opção -> id do valor; a plataforma o devolve ao criar. Todas as rotas exigem um administrador e também respondem sem o prefixo de versão (/api/combinations).

Listar as combinações de um produto

Devolve o estoque de cada combinação de opções que o produto tem cadastrada.

GET/api/v1.0/combinationsAdmin

Listar combinações de um produto

A resposta é uma lista JSON pura, na ordem de criação. Um produto sem combinações devolve []. Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de consulta

product_idstringobrigatório
Id do produto (UUID).

Exemplo de requisição

bash
curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/combinations?product_id=48e87591-5fb1-40da-b32e-edec3a8c596d"

Resposta

200Combinações devolvidas
json
[
  {
    "combination_hash": "d41d8cd98f00b204e9800998ecf8427e",
    "product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d",
    "product_code": "CAM-M-AZ",
    "amount": 12
  }
]

Campos da resposta

combination_hashstring
Identificador da combinação. Ele é calculado a partir do mapa de opções e valores: o mesmo mapa gera sempre o mesmo hash, em qualquer ordem.
product_idstring
Id do produto (UUID).
product_codestring
Código (SKU) da combinação; vazio se não houver.
amountinteger
Quantidade em estoque.

Erros

StatusQuandoCorpo
400product_id ausente{"error":"product_id is required"}
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"query option inventory list: ..."}

Consultar uma combinação

Devolve a quantidade em estoque de uma combinação. Serve para conferir o saldo antes ou depois de uma carga.

GET/api/v1.0/combinations/{hash}Admin

Consultar uma combinação

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

hashstringobrigatório
Hash da combinação, o mesmo devolvido na criação e na listagem.

Parâmetros de consulta

product_idstringobrigatório
Id do produto (UUID).

Exemplo de requisição

bash
curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/combinations/d41d8cd98f00b204e9800998ecf8427e?product_id=48e87591-5fb1-40da-b32e-edec3a8c596d"

Resposta

200Combinação devolvida
json
{
  "combination_hash": "d41d8cd98f00b204e9800998ecf8427e",
  "product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d",
  "amount": 12
}

Campos da resposta

combination_hashstring
O hash pedido.
product_idstring
Id do produto.
amountinteger
Estoque da combinação. Um hash que não existe devolve 0, não 404; esta resposta não traz product_code.

Erros

StatusQuandoCorpo
400product_id ausente{"error":"product_id is required"}
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"..."}

Criar uma combinação

Registra uma combinação de opções com seu estoque e código. A combinação é identificada pelo mapa de opções e valores, e a resposta devolve o hash.

POST/api/v1.0/combinationsAdmin

Criar uma combinação

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Corpo da requisição

product_idstringobrigatório
Id do produto (UUID).
combinationobjectobrigatório
Mapa id da opção -> id do valor que define a combinação, por exemplo Tamanho = M e Cor = Azul. Obrigatório e não vazio.
product_codestring
Código (SKU) da combinação. Se omitido, o código gravado fica vazio.
amountinteger
Quantidade em estoque da combinação. Aceita número ou texto numérico. Omitido ou inválido vale 0.

Exemplo de requisição

bash
curl -X POST -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d", "combination": {"5f3c1d52-8a41-4a39-9d44-1c0a6c1b7e10": "a1b2c3d4-0001-4aaa-9bbb-000000000001", "9e8d7c6b-0002-4aaa-9bbb-0000000000aa": "9e8d7c6b-0003-4aaa-9bbb-0000000000bb"}, "product_code": "CAM-M-AZ", "amount": 12}' \
  "$BASE_URL/api/v1.0/combinations"

Resposta

201Combinação criada
json
{
  "combination_hash": "d41d8cd98f00b204e9800998ecf8427e"
}

Campos da resposta

combination_hashstring
Hash da combinação. Guarde-o para consultar, alterar e zerar depois.

Erros

StatusQuandoCorpo
400JSON inválido, product_id ausente ou combination ausente ou vazio{"error":"Invalid JSON"} / {"error":"product_id is required"} / {"error":"combination is required"}
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"upsert option inventory: ..."}
Criar de novo não duplica

Enviar a mesma combinação outra vez para o mesmo produto não cria um segundo registro: o estoque e o código são substituídos.

Alterar uma combinação

Define o estoque e o código de uma combinação já conhecida pelo hash. Os dois valores são substituídos, não somados.

PUT/api/v1.0/combinations/{hash}Admin

Alterar uma combinação

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

hashstringobrigatório
Hash da combinação, o mesmo devolvido na criação e na listagem.

Corpo da requisição

product_idstringobrigatório
Id do produto (UUID).
product_codestring
Código (SKU) da combinação. Se omitido, o código gravado fica vazio.
amountinteger
Quantidade em estoque da combinação. Aceita número ou texto numérico. Omitido ou inválido vale 0.

Exemplo de requisição

bash
curl -X PUT -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d", "product_code": "CAM-M-AZ", "amount": 30}' \
  "$BASE_URL/api/v1.0/combinations/d41d8cd98f00b204e9800998ecf8427e"

Resposta

200Combinação alterada
json
{
  "combination_hash": "d41d8cd98f00b204e9800998ecf8427e"
}

Erros

StatusQuandoCorpo
400JSON inválido ou product_id ausente{"error":"Invalid JSON"} / {"error":"product_id is required"}
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"upsert option inventory: ..."}
Omitir o código apaga o código

Como o código também é substituído, um PUT sem product_code grava o código vazio. Reenvie sempre os dois campos.

Zerar uma combinação

Zera o estoque da combinação e limpa o código. O registro continua existindo, com quantidade 0.

DELETE/api/v1.0/combinations/{hash}Admin

Zerar uma combinação

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

hashstringobrigatório
Hash da combinação, o mesmo devolvido na criação e na listagem.

Parâmetros de consulta

product_idstringobrigatório
Id do produto (UUID).

Exemplo de requisição

bash
curl -X DELETE -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/combinations/d41d8cd98f00b204e9800998ecf8427e?product_id=48e87591-5fb1-40da-b32e-edec3a8c596d"

Resposta

204Combinação zerada, sem corpo
http
HTTP/1.1 204 No Content

Erros

StatusQuandoCorpo
400product_id ausente{"error":"product_id is required"}
401Sem credenciais ou chave inválida{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
403O usuário não é administrador{"message":"Forbidden: admin scope required","status":403}
500Falha ao consultar ou gravar (por exemplo, id que não é um UUID){"error":"..."}
Não é uma exclusão

Depois do DELETE, a combinação ainda aparece na listagem, com amount igual a 0.

Veja também

  • Cadastro de opções
  • Exceções
  • Estoque
Anterior
Cadastro de opções
Próxima
Exceções de opções
Nesta página
  • Listar as combinações de um produto
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma combinação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar uma combinação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar uma combinação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Zerar uma combinação
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também