Alterar produto
Atualiza um produto existente enviando só os campos que mudam, como preço, estoque, status, categorias, descrições e dados de envio.
Use esta operação para manter o cadastro em dia: o ERP que atualiza preço e estoque, o PIM que corrige descrições, a regra que desativa um item descontinuado, ou o passo que publica um produto que estava aguardando aprovação. A alteração é parcial: você envia apenas as chaves que quer mudar e todo o resto fica como está. Enviar o produto inteiro também funciona, e é o que o painel faz.
Cada alteração relevante (preço, estoque, nome, status, SKU...) é registrada no histórico de alterações do produto, com o usuário e o horário. Mudar o estoque pelo campo de quantidade grava um movimento no extrato de estoque.
/api/v1.0/products/{id}AdminAlterar um produto
Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>. A rota também responde em /api/products/{id}, com ids decimais em string. Só as chaves enviadas são alteradas; chaves desconhecidas são ignoradas. Se nenhuma chave conhecida vier no corpo, ou se todas forem ignoradas, a resposta é 400 no fields to update.
Parâmetros de caminho
idstringobrigatórioproduct_id, em UUID (na rota /api/products/{id}, também o id decimal).Corpo da requisição
productstringcompany_idstring/api/products). vendor_id é aceito como sinônimo. "0" e vazio são ignorados.main_categorystringcategory_idsarraymain_category, a primeira vira a principal; as outras entram como adicionais.statusstringADHA ativo, D desativado, H oculto. Qualquer outro valor (inclusive R, X ou nomes como pending) vira A, e não gera erro. Enviar A em um produto aguardando aprovação o publica.pricestring"49.90", "49,90"). Um número JSON é lido em reais. Texto que não é número grava R$ 0,00 sem erro.list_pricestringproduct_codestring"" apaga o código.full_descriptionstringshort_descriptionstringseo_namestringamountstring"20" ou número 20). Uma string não inteira ("7.5") é ignorada.weightstringfree_shippingstringYNY frete grátis, N desliga.min_qtyintegernull grava 0; a ausência da chave não mexe.max_qtyintegermin_qty.qty_stepintegermin_qty.page_titlestringmeta_descriptionstringmeta_keywordsstringsearch_wordsstringpromo_textstringzero_price_actionstringPRAP vender por zero, R bloquear a compra online, A pedir orçamento.Exemplo de requisição
curl -u "$EMAIL:$API_KEY" -X PUT \
"$BASE_URL/api/v1.0/products/0497b6a8-c868-43be-ac21-2abddd24cd3c" \
-H "Content-Type: application/json" \
-d '{"price": "52.90", "amount": 20, "status": "A"}'Resposta
{ "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c" }Campos da resposta
product_idstring/api/v1.0; decimal em string em /api/products. Para ver o resultado, consulte o produto (Consultar produto).Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | JSON inválido, ou número em formato inválido | {"message":"Invalid JSON: ...","status":400} |
| 400 | Nenhum campo conhecido no corpo | {"message":"no fields to update","status":400} |
| 400 | Regra de negócio violada: preço ou custo negativos, list_price menor que o preço, nome longo demais, quantidades inválidas, código do produto ou de barras repetido, categoria inexistente | {"message":"<código>: <texto>","status":400}. O texto vem do serviço de catálogo e pode estar em português ou inglês |
| 400 | {id} que não é UUID | {"message":"update product abc: pq: invalid input syntax for type uuid: \"abc\" (22P02)","status":400} |
| 401 | Sem credenciais, chave inválida ou token expirado | {"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401} |
| 403 | Usuário sem permissão de escrita | {"message":"Forbidden: admin scope required","status":403} |
| 404 | O produto não existe ou está na lixeira | {"message":"Product not found","status":404} |
| 429 | Limite de requisições | {"error":"rate limit exceeded","detail":"too many requests, please try again later"} |