Produtos obrigatórios
Liga a um produto os itens que o acompanham, como pilhas ou garantia, e marca quais são obrigatórios.
Um produto obrigatório (required product) é um item que acompanha outro. Exemplo: o brinquedo que só funciona com pilhas, a impressora e o cartucho, o celular e a película. Você liga o brinquedo às pilhas e a vitrine mostra as pilhas na página do brinquedo. Cada ligação tem a marca is_mandatory: true quer dizer "sem isto o produto não funciona", false quer dizer "recomendado".
Diferença para a venda cruzada: a venda cruzada sugere alternativas ou complementos como vitrine de descoberta; o obrigatório descreve uma dependência do produto, e tem a marca de obrigatório.
Esta API só registra a ligação e a marca. A vitrine mostra a lista na página do produto, com aviso e selo nos obrigatórios; nenhuma rota de pedido recusa um pedido por falta do item.
Quatro operações. A relação é de um sentido: ligar A a B não liga B a A.
/api/v1/admin/products/{id}/required-productsAdminLista os produtos obrigatórios de um produto
Exige o privilégio view_catalog ou manage_catalog. Devolve as ligações com os dados atuais do produto exigido, em ordem de criação. Produto exigido que foi excluído some da lista.
Path parameters
iduuidobrigatório/api/v1/admin/products/{id}/required-productsAdminAdiciona um produto obrigatório
Exige o privilégio manage_catalog. Adiciona uma ligação, ou atualiza a marca is_mandatory se a ligação já existia. Devolve a lista completa.
Path parameters
iduuidobrigatórioCorpo da requisição
required_product_iduuidobrigatóriois_mandatorybooleanpadrão: falsetrue para obrigatório, false para recomendado./api/v1/admin/products/{id}/required-productsAdminSubstitui os produtos obrigatórios de um produto
Exige o privilégio manage_catalog. Apaga todas as ligações atuais e grava a lista enviada. Ligações do produto com ele mesmo são ignoradas. Lista vazia remove tudo. Se o produto {id} não existe, responde 500 sem apagar nada.
Path parameters
iduuidobrigatórioCorpo da requisição
required_productsarrayobrigatórioLista completa de ligações.
required_product_iduuidobrigatóriois_mandatorybooleanpadrão: false/api/v1/admin/products/{id}/required-products/{requiredId}AdminRemove um produto obrigatório
Exige o privilégio manage_catalog. Remove só a ligação; nenhum dos dois produtos é alterado.
Path parameters
iduuidobrigatóriorequiredIduuidobrigatórioExemplo de requisição
curl -X POST "$BASE_URL/api/v1/admin/products/74dd8f08-8b06-43a8-9a8b-3ef5e7478d52/required-products" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "required_product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d", "is_mandatory": true }'Resposta
{
"required_products": [
{
"product_id": "74dd8f08-8b06-43a8-9a8b-3ef5e7478d52",
"required_product_id": "48e87591-5fb1-40da-b32e-edec3a8c596d",
"is_mandatory": true,
"created_at": "2026-10-11T20:54:10.152579Z",
"required_product_name": "Mouse Gamer Titan",
"required_product_slug": "mouse-gamer-titan",
"required_product_price": 26239,
"required_product_image": "/uploads/exemplo/mouse-titan.png",
"required_product_quantity": 26,
"required_product_status": "A"
}
],
"total": 1
}{ "message": "required product removed" }Response fields
required_productsarrayrequired_products[].product_iduuidrequired_products[].required_product_iduuidrequired_products[].is_mandatorybooleantrue) ou recomendado (false).required_products[].created_atstringrequired_products[].required_product_namestringrequired_products[].required_product_slugstringrequired_products[].required_product_priceintegerrequired_products[].required_product_imagestringrequired_products[].required_product_quantityintegerrequired_products[].required_product_statusstringA ativo). Veja os status na home de Produtos.totalintegerErros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo não é JSON válido | {"error":"invalid request body","detail":"..."} |
| 400 | POST sem required_product_id | {"error":"required_product_id is required"} |
| 401 | Sem credenciais ou token expirado | {"error":"invalid or expired token"} |
| 403 | Sem permissão (manage_catalog para gravar) | {"error":"insufficient privileges","required":"manage_catalog"} |
| 404 | DELETE de uma ligação que não existe | {"error":"failed to remove required product","detail":"required product association not found"} |
| 500 | POST ligando o produto a ele mesmo | {"error":"failed to add required product","detail":"cannot require a product to itself"} |
| 500 | POST com um dos produtos inexistente ou excluído | {"error":"failed to add required product","detail":"one or both products not found"} |
| 500 | PUT em produto inexistente | {"error":"failed to set required products","detail":"product not found"} |
| 500 | PUT com required_product_id inexistente ou fora do formato UUID | {"error":"failed to set required products","detail":"..."} |