Produtos por token de app

Acesso de aplicativos de terceiros para criar, alterar e excluir produtos com token vat_ e escopo write_products, sem usuário administrador.

Um app de terceiros (um conector de ERP, um hub de marketplace, uma ferramenta de catálogo) normalmente não deve usar o login de uma pessoa. A plataforma oferece outra forma de acesso: o app é cadastrado no portal de desenvolvedores da loja, recebe um token de app (começa com vat_live_ ou vat_test_) e só pode o que os escopos aprovados permitem. Para saber como o token é obtido e como o app é aprovado, veja Pedidos por token de app, que explica o mesmo mecanismo.

As rotas de escrita de produtos sob /api/admin/... aceitam esse token. Elas usam o corpo e a resposta do cadastro de administração do produto: dinheiro em centavos inteiros, ids em UUID e erros no formato {"error","detail"}, diferente do formato decimal das rotas /api/v1.0/products. Esta página descreve o cabeçalho, o escopo, as rotas disponíveis e os campos de cada uma.

Pontos-chave

Cabeçalho: Authorization: Bearer vat_live_... (o token do app, não um JWT de usuário).
Escopo: write_products para criar, alterar e excluir. Sem o escopo, a resposta é 403 missing_scope.
Aceita somente token de app. Um JWT de usuário nestas rotas responde 401 app_token_required.
Os privilégios finos do painel (como manage_catalog) não são verificados aqui; o que vale é o escopo aprovado para o app.
Não há rota de leitura de produtos por token de app, só a de estoque (read_inventory, em Preço e estoque). Para ler o catálogo, use Listar produtos com as credenciais de um usuário.
A criação por token de app se comporta como a criação por um administrador: o produto nasce direto no status pedido, sem passar pela moderação. O histórico de alterações registra a mudança sem usuário.

Rotas disponíveis com token de app

Rota	Escopo	Operação
`POST /api/admin/products`	`write_products`	Criar produto
`PUT /api/admin/products/{id}`	`write_products`	Alterar produto
`DELETE /api/admin/products/{id}`	`write_products`	Excluir produto
`GET /api/admin/products/{id}/inventory`	`read_inventory`	Estoque

POST/api/admin/productsAutenticada

Token de app: criar um produto

Responde 201 com o produto completo. Escopo write_products.

Corpo da requisição

namestringobrigatório

Nome do produto, até 255 caracteres.

vendor_iduuidobrigatório

Seller dono do produto.

category_iduuidobrigatório

Categoria principal.

priceintegerobrigatório

Preço de venda em centavos.

skustring

Código do produto, único na loja. Recomendado, para poder repetir a chamada com segurança.

quantitynumber

Estoque inicial.

statusstringpadrão: A

ADH

Status inicial.

Campos opcionais adicionais:

Outros campos do corpo

additional_category_idsarray

Ids de categorias adicionais.

list_priceinteger

Preço "de" (riscado) em centavos. Se maior que zero, não pode ser menor que price.

cost_priceinteger

Custo em centavos. Nunca aparece para o cliente.

barcodestring

EAN/GTIN.

ncm_codestring

Código NCM, 8 dígitos.

slugstring

Slug da URL. Sem ele, sai do nome.

descriptionstring

Descrição completa, em HTML.

short_descriptionstring

Descrição curta.

min_quantitynumber

Quantidade mínima por compra.

max_quantitynumber

Quantidade máxima por compra (0 = sem máximo).

quantity_stepnumber

Múltiplo de compra.

weightnumber

Peso em kg.

lengthnumber

Comprimento em cm.

widthnumber

Largura em cm.

heightnumber

Altura em cm.

PUT/api/admin/products/{id}Autenticada

Token de app: alterar um produto

Responde 200 com o produto atualizado. Escopo write_products. O ajuste é parcial: só os campos enviados mudam.

Parâmetros de caminho

iduuidobrigatório

UUID do produto. Um id zero ou negativo é recusado com 400 antes de chegar ao produto.

Corpo da requisição

priceinteger

Novo preço em centavos.

quantitynumber

Novo estoque absoluto.

statusstring

ADHRX

Novo status.

Qualquer campo de "Outros campos do corpo" da criação também vale na alteração, além de name, vendor_id e category_id.

DELETE/api/admin/products/{id}Autenticada

Token de app: excluir um produto

Exclusão suave: 200 {"message":"product deleted"}, e o produto vai para a lixeira por 30 dias. Escopo write_products.

Parâmetros de caminho

iduuidobrigatório

UUID do produto.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/admin/products/0497b6a8-c868-43be-ac21-2abddd24cd3c" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price": 5290, "quantity": 20}'

Resposta

200Produto alterado

json

{
  "id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
  "name": "Caneca Esmaltada 350 ml",
  "sku": "CAN-350-AZ",
  "price": 5290,
  "quantity": 20,
  "status": "A",
  "price_str": "52.90",
  "amount": 20
}

Resposta abreviada: o corpo real traz todos os campos do produto.

Campos da resposta

iduuid

Id do produto.

display_idinteger

Número curto mostrado no painel.

namestring

Nome do produto.

skustring

Código do produto.

slugstring

Slug da URL.

priceinteger

Preço de venda em centavos.

list_priceinteger

Preço "de" em centavos.

cost_priceinteger

Custo em centavos.

quantitynumber

Estoque disponível.

statusstring

ADHRX

Status do produto.

vendor_iduuid

Seller dono do produto.

category_iduuid

Categoria principal.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

*any

Na exclusão, a resposta é só {"message":"product deleted"}.

Erros

Status	Quando	Corpo
400	`{id}` zero ou negativo	`{"error":"invalid id parameter"}`
401	Sem token, ou o token não é de app (por exemplo um JWT de usuário)	`{"error":"app_token_required"}`
401	Token de app inválido, revogado ou expirado	A mensagem sai do serviço de tokens
403	O token não tem o escopo `write_products`	`{"error":"missing_scope","required":"write_products"}`
400, 404, 409, 500	Erros de negócio: corpo inválido, produto inexistente, SKU repetido, falha interna	`{"error":"...","detail":"..."}`

Veja também

Produtos por token de app

Acesso de aplicativos de terceiros para criar, alterar e excluir produtos com token vat_ e escopo write_products, sem usuário administrador.

Pontos-chave

Cabeçalho: Authorization: Bearer vat_live_... (o token do app, não um JWT de usuário).
Escopo: write_products para criar, alterar e excluir. Sem o escopo, a resposta é 403 missing_scope.
Aceita somente token de app. Um JWT de usuário nestas rotas responde 401 app_token_required.
Os privilégios finos do painel (como manage_catalog) não são verificados aqui; o que vale é o escopo aprovado para o app.
Não há rota de leitura de produtos por token de app, só a de estoque (read_inventory, em Preço e estoque). Para ler o catálogo, use Listar produtos com as credenciais de um usuário.
A criação por token de app se comporta como a criação por um administrador: o produto nasce direto no status pedido, sem passar pela moderação. O histórico de alterações registra a mudança sem usuário.

Rotas disponíveis com token de app

Rota	Escopo	Operação
`POST /api/admin/products`	`write_products`	Criar produto
`PUT /api/admin/products/{id}`	`write_products`	Alterar produto
`DELETE /api/admin/products/{id}`	`write_products`	Excluir produto
`GET /api/admin/products/{id}/inventory`	`read_inventory`	Estoque

POST/api/admin/productsAutenticada

Token de app: criar um produto

Responde 201 com o produto completo. Escopo write_products.

Corpo da requisição

namestringobrigatório

Nome do produto, até 255 caracteres.

vendor_iduuidobrigatório

Seller dono do produto.

category_iduuidobrigatório

Categoria principal.

priceintegerobrigatório

Preço de venda em centavos.

skustring

Código do produto, único na loja. Recomendado, para poder repetir a chamada com segurança.

quantitynumber

Estoque inicial.

statusstringpadrão: A

ADH

Status inicial.

Campos opcionais adicionais:

Outros campos do corpo

additional_category_idsarray

Ids de categorias adicionais.

list_priceinteger

Preço "de" (riscado) em centavos. Se maior que zero, não pode ser menor que price.

cost_priceinteger

Custo em centavos. Nunca aparece para o cliente.

barcodestring

EAN/GTIN.

ncm_codestring

Código NCM, 8 dígitos.

slugstring

Slug da URL. Sem ele, sai do nome.

descriptionstring

Descrição completa, em HTML.

short_descriptionstring

Descrição curta.

min_quantitynumber

Quantidade mínima por compra.

max_quantitynumber

Quantidade máxima por compra (0 = sem máximo).

quantity_stepnumber

Múltiplo de compra.

weightnumber

Peso em kg.

lengthnumber

Comprimento em cm.

widthnumber

Largura em cm.

heightnumber

Altura em cm.

PUT/api/admin/products/{id}Autenticada

Token de app: alterar um produto

Responde 200 com o produto atualizado. Escopo write_products. O ajuste é parcial: só os campos enviados mudam.

Parâmetros de caminho

iduuidobrigatório

UUID do produto. Um id zero ou negativo é recusado com 400 antes de chegar ao produto.

Corpo da requisição

priceinteger

Novo preço em centavos.

quantitynumber

Novo estoque absoluto.

statusstring

ADHRX

Novo status.

Qualquer campo de "Outros campos do corpo" da criação também vale na alteração, além de name, vendor_id e category_id.

DELETE/api/admin/products/{id}Autenticada

Token de app: excluir um produto

Exclusão suave: 200 {"message":"product deleted"}, e o produto vai para a lixeira por 30 dias. Escopo write_products.

Parâmetros de caminho

iduuidobrigatório

UUID do produto.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/admin/products/0497b6a8-c868-43be-ac21-2abddd24cd3c" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price": 5290, "quantity": 20}'

Resposta

200Produto alterado

json

{
  "id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
  "name": "Caneca Esmaltada 350 ml",
  "sku": "CAN-350-AZ",
  "price": 5290,
  "quantity": 20,
  "status": "A",
  "price_str": "52.90",
  "amount": 20
}

Resposta abreviada: o corpo real traz todos os campos do produto.

Campos da resposta

iduuid

Id do produto.

display_idinteger

Número curto mostrado no painel.

namestring

Nome do produto.

skustring

Código do produto.

slugstring

Slug da URL.

priceinteger

Preço de venda em centavos.

list_priceinteger

Preço "de" em centavos.

cost_priceinteger

Custo em centavos.

quantitynumber

Estoque disponível.

statusstring

ADHRX

Status do produto.

vendor_iduuid

Seller dono do produto.

category_iduuid

Categoria principal.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

*any

Na exclusão, a resposta é só {"message":"product deleted"}.

Erros

Status	Quando	Corpo
400	`{id}` zero ou negativo	`{"error":"invalid id parameter"}`
401	Sem token, ou o token não é de app (por exemplo um JWT de usuário)	`{"error":"app_token_required"}`
401	Token de app inválido, revogado ou expirado	A mensagem sai do serviço de tokens
403	O token não tem o escopo `write_products`	`{"error":"missing_scope","required":"write_products"}`
400, 404, 409, 500	Erros de negócio: corpo inválido, produto inexistente, SKU repetido, falha interna	`{"error":"...","detail":"..."}`