API atual/Referência completa/Variações e opções

Produtos obrigatórios

Lista, adiciona, substitui e remove os produtos que acompanham um produto do seller no carrinho.

Um produto obrigatório é outro produto que deve ser comprado junto (por exemplo, a bateria de um brinquedo). Com is_mandatory: true o carrinho exige o item; com false ele é só sugerido ao cliente. O produto exigido pode ser de qualquer seller ou da loja, desde que exista.

Listar

GET/api/v1/vendor/products/{id}/required-productsSeller

Listar os produtos obrigatórios

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Exemplo de requisição (listar)

bash

curl "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/required-products" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Obrigatórios

json

{
  "required_products": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
      "is_mandatory": true,
      "created_at": "2026-10-11T21:40:00Z",
      "required_product_name": "Cabide Premium",
      "required_product_slug": "cabide-premium",
      "required_product_price": 990,
      "required_product_image": "/uploads/dfe2555e/cabide.png",
      "required_product_quantity": 80,
      "required_product_status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

required_productsarray

Produtos obrigatórios.

product_idstring (uuid)

Produto que exige.

required_product_idstring (uuid)

Produto exigido.

is_mandatoryboolean

true = obrigatório; false = apenas sugerido.

created_atstring

Criação (RFC 3339).

required_product_namestring

Nome do produto exigido.

required_product_slugstring

Slug do produto exigido.

required_product_priceinteger

Preço em centavos.

required_product_imagestring

Imagem principal.

required_product_quantityinteger

Estoque (inteiro).

required_product_statusstring

Status do produto exigido.

totalinteger

Quantidade.

Erros (listar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
404	Produto não existe.	`{"error":"product not found"}`

Adicionar

POST/api/v1/vendor/products/{id}/required-productsSeller

Adicionar um produto obrigatório

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

required_product_idstring (uuid)obrigatório

Produto a exigir. Tem de existir; não pode ser o próprio produto.

is_mandatorybooleanpadrão: false

Obrigatório (true) ou apenas sugerido.

Exemplo de requisição (adicionar)

bash

curl -X POST "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/required-products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
  "is_mandatory": true
}'

Resposta (adicionar)

200Lista atualizada

json

{
  "required_products": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
      "is_mandatory": true,
      "created_at": "2026-10-11T21:40:00Z",
      "required_product_name": "Cabide Premium",
      "required_product_slug": "cabide-premium",
      "required_product_price": 990,
      "required_product_image": "/uploads/dfe2555e/cabide.png",
      "required_product_quantity": 80,
      "required_product_status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

required_productsarray

Produtos obrigatórios.

product_idstring (uuid)

Produto que exige.

required_product_idstring (uuid)

Produto exigido.

is_mandatoryboolean

true = obrigatório; false = apenas sugerido.

created_atstring

Criação (RFC 3339).

required_product_namestring

Nome do produto exigido.

required_product_slugstring

Slug do produto exigido.

required_product_priceinteger

Preço em centavos.

required_product_imagestring

Imagem principal.

required_product_quantityinteger

Estoque (inteiro).

required_product_statusstring

Status do produto exigido.

totalinteger

Quantidade.

Erros (adicionar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
400	`required_product_id` ausente.	`{"error":"required_product_id is required"}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
500	Produto exigido inexistente, ou igual ao próprio produto.	`{"error":"failed to add required product","detail":"cannot require a product to itself"}`

Substituir

PUT/api/v1/vendor/products/{id}/required-productsSeller

Substituir a lista de obrigatórios

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

required_productsarrayobrigatório

Lista completa. Itens com required_product_id e is_mandatory. Referência ao próprio produto é ignorada.

Exemplo de requisição (substituir)

bash

curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/required-products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "required_products": [
    {
      "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
      "is_mandatory": true
    }
  ]
}'

Resposta (substituir)

200Lista atualizada

json

{
  "required_products": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
      "is_mandatory": true,
      "created_at": "2026-10-11T21:40:00Z",
      "required_product_name": "Cabide Premium",
      "required_product_slug": "cabide-premium",
      "required_product_price": 990,
      "required_product_image": "/uploads/dfe2555e/cabide.png",
      "required_product_quantity": 80,
      "required_product_status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

required_productsarray

Produtos obrigatórios.

product_idstring (uuid)

Produto que exige.

required_product_idstring (uuid)

Produto exigido.

is_mandatoryboolean

true = obrigatório; false = apenas sugerido.

created_atstring

Criação (RFC 3339).

required_product_namestring

Nome do produto exigido.

required_product_slugstring

Slug do produto exigido.

required_product_priceinteger

Preço em centavos.

required_product_imagestring

Imagem principal.

required_product_quantityinteger

Estoque (inteiro).

required_product_statusstring

Status do produto exigido.

totalinteger

Quantidade.

Erros (substituir)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
404	Produto não existe.	`{"error":"product not found"}`

Remover

DELETE/api/v1/vendor/products/{id}/required-products/{requiredId}Seller

Remover um produto obrigatório

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

requiredIdstring (uuid)obrigatório

Id do produto exigido (não o de uma associação).

Exemplo de requisição (remover)

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/required-products/$REQUIRED_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (remover)

200Removido

json

{
  "message": "required product removed"
}

Campos da resposta

messagestring

Confirmação fixa.

Erros (remover)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
404	Esta associação não existe.	`{"error":"failed to remove required product","detail":"required product association not found"}`

Veja também

API atual/Referência completa/Variações e opções

Produtos obrigatórios

Lista, adiciona, substitui e remove os produtos que acompanham um produto do seller no carrinho.

Listar

GET/api/v1/vendor/products/{id}/required-productsSeller

Listar os produtos obrigatórios

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Exemplo de requisição (listar)

bash

curl "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/required-products" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Obrigatórios

json

{
  "required_products": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
      "is_mandatory": true,
      "created_at": "2026-10-11T21:40:00Z",
      "required_product_name": "Cabide Premium",
      "required_product_slug": "cabide-premium",
      "required_product_price": 990,
      "required_product_image": "/uploads/dfe2555e/cabide.png",
      "required_product_quantity": 80,
      "required_product_status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

required_productsarray

Produtos obrigatórios.

product_idstring (uuid)

Produto que exige.

required_product_idstring (uuid)

Produto exigido.

is_mandatoryboolean

true = obrigatório; false = apenas sugerido.

created_atstring

Criação (RFC 3339).

required_product_namestring

Nome do produto exigido.

required_product_slugstring

Slug do produto exigido.

required_product_priceinteger

Preço em centavos.

required_product_imagestring

Imagem principal.

required_product_quantityinteger

Estoque (inteiro).

required_product_statusstring

Status do produto exigido.

totalinteger

Quantidade.

Erros (listar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
404	Produto não existe.	`{"error":"product not found"}`

Adicionar

POST/api/v1/vendor/products/{id}/required-productsSeller

Adicionar um produto obrigatório

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

required_product_idstring (uuid)obrigatório

Produto a exigir. Tem de existir; não pode ser o próprio produto.

is_mandatorybooleanpadrão: false

Obrigatório (true) ou apenas sugerido.

Exemplo de requisição (adicionar)

bash

curl -X POST "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/required-products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
  "is_mandatory": true
}'

Resposta (adicionar)

200Lista atualizada

json

{
  "required_products": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
      "is_mandatory": true,
      "created_at": "2026-10-11T21:40:00Z",
      "required_product_name": "Cabide Premium",
      "required_product_slug": "cabide-premium",
      "required_product_price": 990,
      "required_product_image": "/uploads/dfe2555e/cabide.png",
      "required_product_quantity": 80,
      "required_product_status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

required_productsarray

Produtos obrigatórios.

product_idstring (uuid)

Produto que exige.

required_product_idstring (uuid)

Produto exigido.

is_mandatoryboolean

true = obrigatório; false = apenas sugerido.

created_atstring

Criação (RFC 3339).

required_product_namestring

Nome do produto exigido.

required_product_slugstring

Slug do produto exigido.

required_product_priceinteger

Preço em centavos.

required_product_imagestring

Imagem principal.

required_product_quantityinteger

Estoque (inteiro).

required_product_statusstring

Status do produto exigido.

totalinteger

Quantidade.

Erros (adicionar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
400	`required_product_id` ausente.	`{"error":"required_product_id is required"}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
500	Produto exigido inexistente, ou igual ao próprio produto.	`{"error":"failed to add required product","detail":"cannot require a product to itself"}`

Substituir

PUT/api/v1/vendor/products/{id}/required-productsSeller

Substituir a lista de obrigatórios

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

Corpo da requisição

required_productsarrayobrigatório

Lista completa. Itens com required_product_id e is_mandatory. Referência ao próprio produto é ignorada.

Exemplo de requisição (substituir)

bash

curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/required-products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "required_products": [
    {
      "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
      "is_mandatory": true
    }
  ]
}'

Resposta (substituir)

200Lista atualizada

json

{
  "required_products": [
    {
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "required_product_id": "5b4a3c2d-0001-4e1f-8a2b-9c8d7e6f5a4b",
      "is_mandatory": true,
      "created_at": "2026-10-11T21:40:00Z",
      "required_product_name": "Cabide Premium",
      "required_product_slug": "cabide-premium",
      "required_product_price": 990,
      "required_product_image": "/uploads/dfe2555e/cabide.png",
      "required_product_quantity": 80,
      "required_product_status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

required_productsarray

Produtos obrigatórios.

product_idstring (uuid)

Produto que exige.

required_product_idstring (uuid)

Produto exigido.

is_mandatoryboolean

true = obrigatório; false = apenas sugerido.

created_atstring

Criação (RFC 3339).

required_product_namestring

Nome do produto exigido.

required_product_slugstring

Slug do produto exigido.

required_product_priceinteger

Preço em centavos.

required_product_imagestring

Imagem principal.

required_product_quantityinteger

Estoque (inteiro).

required_product_statusstring

Status do produto exigido.

totalinteger

Quantidade.

Erros (substituir)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
404	Produto não existe.	`{"error":"product not found"}`

Remover

DELETE/api/v1/vendor/products/{id}/required-products/{requiredId}Seller

Remover um produto obrigatório

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do produto.

requiredIdstring (uuid)obrigatório

Id do produto exigido (não o de uma associação).

Exemplo de requisição (remover)

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/required-products/$REQUIRED_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (remover)

200Removido

json

{
  "message": "required product removed"
}

Campos da resposta

messagestring

Confirmação fixa.

Erros (remover)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}`
403	O produto existe mas é de outro seller (ou da loja).	`{"error":"you do not have access to this product"}`
404	Esta associação não existe.	`{"error":"failed to remove required product","detail":"required product association not found"}`