Ligar a um mestre
Liga a oferta de um seller a um produto do catálogo mestre, copiando os dados do mestre, ou desliga a oferta, devolvendo o controle dos campos ao seller.
Em uma loja com vários sellers (marketplace), o mesmo item físico costuma ser vendido por mais de um seller. Para não cadastrar nome, descrição, imagens e características várias vezes, a loja mantém um catálogo mestre: um registro único do item (por exemplo, "Cafeteira Elétrica Branca"). Cada seller tem a sua oferta (um produto comum) apontando para esse mestre, e só cuida do que é dele: preço, estoque, SKU e status.
Estas duas rotas ligam e desligam uma oferta já existente de um mestre. Use ligar quando você cadastrou a oferta por conta própria e descobriu que o item já existe no catálogo mestre, e desligar quando a oferta passou a vender outro item, ou quando você quer voltar a editar nome e descrição à mão.
/api/v1/admin/products/{id}/link-masterAdminVincula uma oferta a um produto master
Autenticação: Authorization: Bearer <token> de um usuário administrador com o privilégio manage_master_products ou manage_catalog.
Path parameters
iduuidobrigatórioCorpo da requisição
master_product_iduuidobrigatórioExemplo de requisição (ligar)
curl -X POST "$BASE_URL/api/v1/admin/products/0497b6a8-c868-43be-ac21-2abddd24cd3c/link-master" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"master_product_id": "6b5806fe-4370-4f12-bc95-a7dbba04918b"}'Resposta (ligar)
{ "message": "product linked to master" }Campos da resposta
messagestringproduct linked to master (texto em inglês, como o servidor devolve). Para ver o resultado, consulte o produto: master_product_id passa a apontar para o mestre e os campos do mestre foram copiados./api/v1/admin/products/{id}/unlink-masterAdminDesvincula uma oferta do seu produto master
Desliga a oferta do mestre: master_product_id volta a ficar vazio e o seller passa a poder editar todos os campos. Os dados que foram copiados do mestre permanecem na oferta; a plataforma só recalcula a contagem de ofertas, o preço e a quantidade de referência do mestre antigo. Chamar numa oferta que não está ligada não faz nada e responde 200. Autenticação e privilégios como em ligar.
Path parameters
iduuidobrigatórioExemplo de requisição (desligar)
curl -X DELETE "$BASE_URL/api/v1/admin/products/0497b6a8-c868-43be-ac21-2abddd24cd3c/unlink-master" \
-H "Authorization: Bearer $TOKEN"Resposta (desligar)
{ "message": "product unlinked from master" }Campos da resposta
messagestringproduct unlinked from master.Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | (ligar) Sem master_product_id, ou JSON inválido | {"error":"master_product_id is required"} |
| 401 | Sem credenciais ou token expirado | {"error":"invalid or expired token"} |
| 403 | Usuário sem manage_master_products nem manage_catalog | {"error":"insufficient privileges","privilege_required_any":["manage_master_products","manage_catalog"]} |
| 404 | O catálogo mestre está desligado na loja | {"error":"feature not enabled","detail":"..."} |
| 404 | (ligar) O mestre ou o produto não existe | {"error":"master product not found"} ou {"error":"product not found"} |
| 429 | Limite de requisições | {"error":"rate limit exceeded","detail":"too many requests, please try again later"} |
| 500 | (ligar) O seller já tem outra oferta ligada a este mestre | {"error":"you already have a product linked to this master product"} |
| 500 | (ligar) O produto não está em status A ou H | {"error":"product is not in a sellable status (R)..."} |
| 500 | (ligar ou desligar) {id} ou master_product_id que não é UUID; (desligar) produto inexistente | {"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."} |
Por limitação conhecida, as recusas de regra de negócio da ligação (oferta duplicada e status não vendável) saem como 500 e não como 4xx; o texto do erro diz o motivo. Trate-as como erro do seu pedido, e não como falha do servidor.