API atual/Referência completa/Produtos mestre

Fila de aprovação de ligações

Lista as ligações de produtos de sellers a mestres que aguardam decisão, aprova ou rejeita uma a uma e processa as pendências em lote.

Quando a loja pede revisão humana, a ligação automática de um produto de seller a um produto mestre não acontece sozinha: ela entra em uma fila de aprovação. Cada linha da fila é uma pergunta para o administrador, de um de dois tipos:

Ligar ao mestre encontrado. A plataforma achou um mestre com o mesmo SKU, mas o conteúdo do produto difere do dele. A linha traz master_product_id e um resumo das diferenças (conflict_summary).
Criar um mestre novo. Nenhum mestre combina. A linha tem master_product_id vazio: aprovar cria um mestre a partir do produto e liga.

Rejeitar deixa o produto do seller sem ligação. Leitura exige view_catalog ou manage_catalog; decidir e processar exigem manage_master_products ou manage_catalog.

Status de uma linha da fila

P (pendente)→A (aprovada) ou R (rejeitada)

Status	Significado
`P`	Pendente: espera decisão.
`A`	Aprovada: o produto foi ligado (ou o mestre foi criado e ligado).
`R`	Rejeitada pelo administrador, ou cancelada por não ter mais como ser resolvida.
`E`	Expirada: ficou 7 dias sem decisão. O produto continua no catálogo; salvar o produto de novo reabre a avaliação.

Linhas pendentes mais antigas que o prazo de 7 dias são expiradas quando você lista a fila. Linhas criadas antes do prazo existir não expiram.

GET/api/v1/admin/master-products/queueAdmin

Lista a fila de aprovação

Do mais novo para o mais antigo. Por padrão mostra só as pendentes.

Parâmetros de consulta

statusstringpadrão: P

PAREall

Status das linhas. all mostra todas. Aceita também palavras como pending.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

POST/api/v1/admin/master-products/queue/{queueId}/approveAdmin

Aprova uma linha da fila

Com master_product_id na linha, liga o produto a esse mestre. Sem ele, cria um mestre novo a partir do produto e liga. Antes de criar, a plataforma reconfere se um mestre com o mesmo SKU ou código de barras surgiu nesse meio-tempo e, se surgiu, liga a ele. O corpo é opcional.

Parâmetros de caminho

queueIduuidobrigatório

Id da linha da fila (id da lista).

Corpo da requisição (JSON, opcional)

notestring

Observação da decisão, guardada em resolution_note.

POST/api/v1/admin/master-products/queue/{queueId}/rejectAdmin

Rejeita uma linha da fila

Marca a linha como R. O produto do seller fica sem ligação. O corpo é opcional.

Parâmetros de caminho

queueIduuidobrigatório

Id da linha da fila.

Corpo da requisição (JSON, opcional)

notestring

Motivo da rejeição.

POST/api/v1/admin/master-products/queue/processAdmin

Processa as pendências em lote

Reavalia todas as linhas pendentes de uma vez, com as regras atuais da loja: liga o que não tem conflito, cria mestres onde a configuração permite e deixa para revisão humana os casos de conflito real. Sem corpo. É uma ação explícita do administrador; a fila não se processa sozinha.

Exemplo de requisição

bash

# listar as pendentes
curl "$BASE_URL/api/v1/admin/master-products/queue?status=P&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

# aprovar uma
curl -X POST "$BASE_URL/api/v1/admin/master-products/queue/$QUEUE_ID/approve" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"note":"Mesmo produto, mesma caixa"}'

Resposta

200Fila

json

{
  "entries": [
    {
      "id": "882da1fa-a2eb-4d1e-a1a7-070b3dd304b7",
      "vendor_product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "status": "P",
      "normalized_sku": "",
      "created_at": "2026-10-11T20:56:24.574026Z",
      "vendor_product_name": "Caneca Esmaltada 350 ml",
      "vendor_product_sku": "",
      "vendor_product_barcode": "7891234567895",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste"
    }
  ],
  "total": 2487,
  "page": 1,
  "per_page": 20,
  "total_pages": 125
}

200Aprovada

json

{ "message": "promotion approved" }

200Processamento em lote

json

{
  "processed": 40,
  "resolved": 31,
  "cancelled": 2,
  "conflicts": 5,
  "awaiting_moderation": 1,
  "skipped": 0,
  "errors": 0,
  "blocked": 1
}

Campos de cada linha da fila

iduuid

Id da linha. Use em aprovar e rejeitar.

vendor_product_iduuid

Produto do seller em questão.

master_product_iduuid

Mestre sugerido. Ausente nas linhas do tipo "criar mestre novo".

statusstring

PARE

Estado da linha.

normalized_skustring

SKU normalizado usado na busca por mestre.

conflict_summaryobject

Diferenças entre o produto e o mestre sugerido. Ausente quando não há.

created_atstring

Entrada na fila, RFC 3339.

resolved_atstring

Quando foi decidida. Ausente nas pendentes.

resolved_byuuid

Quem decidiu. Ausente nas decididas pelo sistema.

resolution_notestring

Observação da decisão ou motivo da expiração.

vendor_product_namestring

Nome do produto do seller.

vendor_product_skustring

SKU do produto do seller.

vendor_product_barcodestring

Código de barras do produto do seller.

vendor_iduuid

Seller.

vendor_namestring

Nome do seller.

master_namestring

Nome do mestre sugerido. Ausente quando não há.

Campos do processamento em lote

processedinteger

Linhas pendentes examinadas.

resolvedinteger

Ligadas a um mestre (existente ou criado agora).

cancelledinteger

Rejeitadas por não terem mais como ser resolvidas (o seller não quer, o produto ou o SKU sumiu).

conflictsinteger

Conflitos reais de campos: continuam pendentes para decisão humana.

awaiting_moderationinteger

Produtos que ainda não podem ser vendidos (aguardando moderação, rejeitados, desativados): continuam pendentes.

skippedinteger

Linhas intocadas porque a ligação automática está desligada na loja.

errorsinteger

Falhas de avaliação, sem alterar a linha. Veja os logs da loja.

blockedinteger

Linhas em que a criação automática do mestre falhou. Diferente de skipped: aqui a plataforma tentou e não conseguiu.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado, ou falta o privilégio	`{"error":"module_disabled","module":"master-products"}`
404	Recurso desligado na loja	`{"error":"feature not enabled","detail":"enable master_products via admin settings"}`
404	Aprovar: linha ou produto não existe mais	`{"error":"queue entry not found"}` ou `{"error":"vendor product no longer exists"}`
404	Rejeitar: linha não existe ou já foi decidida	`{"error":"queue entry not found or already resolved"}`
409	Aprovar uma linha já decidida	`{"error":"queue entry already resolved"}`
500	Aprovar com a ligação desligada na loja	`{"error":"master linking is disabled for this store (link_master_products = off)"}`
500	Aprovar produto ainda não vendável (moderação, rejeitado, desativado)	`{"error":"vendor product is not in a sellable status (R) ..."}`
500	Id que não é UUID	`{"error":"..."}`

Veja também

Fila de aprovação de ligações

Lista as ligações de produtos de sellers a mestres que aguardam decisão, aprova ou rejeita uma a uma e processa as pendências em lote.

Ligar ao mestre encontrado. A plataforma achou um mestre com o mesmo SKU, mas o conteúdo do produto difere do dele. A linha traz master_product_id e um resumo das diferenças (conflict_summary).
Criar um mestre novo. Nenhum mestre combina. A linha tem master_product_id vazio: aprovar cria um mestre a partir do produto e liga.

Rejeitar deixa o produto do seller sem ligação. Leitura exige view_catalog ou manage_catalog; decidir e processar exigem manage_master_products ou manage_catalog.

Status de uma linha da fila

P (pendente)→A (aprovada) ou R (rejeitada)

Status	Significado
`P`	Pendente: espera decisão.
`A`	Aprovada: o produto foi ligado (ou o mestre foi criado e ligado).
`R`	Rejeitada pelo administrador, ou cancelada por não ter mais como ser resolvida.
`E`	Expirada: ficou 7 dias sem decisão. O produto continua no catálogo; salvar o produto de novo reabre a avaliação.

Linhas pendentes mais antigas que o prazo de 7 dias são expiradas quando você lista a fila. Linhas criadas antes do prazo existir não expiram.

GET/api/v1/admin/master-products/queueAdmin

Lista a fila de aprovação

Do mais novo para o mais antigo. Por padrão mostra só as pendentes.

Parâmetros de consulta

statusstringpadrão: P

PAREall

Status das linhas. all mostra todas. Aceita também palavras como pending.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

POST/api/v1/admin/master-products/queue/{queueId}/approveAdmin

Aprova uma linha da fila

Parâmetros de caminho

queueIduuidobrigatório

Id da linha da fila (id da lista).

Corpo da requisição (JSON, opcional)

notestring

Observação da decisão, guardada em resolution_note.

POST/api/v1/admin/master-products/queue/{queueId}/rejectAdmin

Rejeita uma linha da fila

Marca a linha como R. O produto do seller fica sem ligação. O corpo é opcional.

Parâmetros de caminho

queueIduuidobrigatório

Id da linha da fila.

Corpo da requisição (JSON, opcional)

notestring

Motivo da rejeição.

POST/api/v1/admin/master-products/queue/processAdmin

Processa as pendências em lote

Exemplo de requisição

bash

# listar as pendentes
curl "$BASE_URL/api/v1/admin/master-products/queue?status=P&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

# aprovar uma
curl -X POST "$BASE_URL/api/v1/admin/master-products/queue/$QUEUE_ID/approve" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"note":"Mesmo produto, mesma caixa"}'

Resposta

200Fila

json

{
  "entries": [
    {
      "id": "882da1fa-a2eb-4d1e-a1a7-070b3dd304b7",
      "vendor_product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "status": "P",
      "normalized_sku": "",
      "created_at": "2026-10-11T20:56:24.574026Z",
      "vendor_product_name": "Caneca Esmaltada 350 ml",
      "vendor_product_sku": "",
      "vendor_product_barcode": "7891234567895",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste"
    }
  ],
  "total": 2487,
  "page": 1,
  "per_page": 20,
  "total_pages": 125
}

200Aprovada

json

{ "message": "promotion approved" }

200Processamento em lote

json

{
  "processed": 40,
  "resolved": 31,
  "cancelled": 2,
  "conflicts": 5,
  "awaiting_moderation": 1,
  "skipped": 0,
  "errors": 0,
  "blocked": 1
}

Campos de cada linha da fila

iduuid

Id da linha. Use em aprovar e rejeitar.

vendor_product_iduuid

Produto do seller em questão.

master_product_iduuid

Mestre sugerido. Ausente nas linhas do tipo "criar mestre novo".

statusstring

PARE

Estado da linha.

normalized_skustring

SKU normalizado usado na busca por mestre.

conflict_summaryobject

Diferenças entre o produto e o mestre sugerido. Ausente quando não há.

created_atstring

Entrada na fila, RFC 3339.

resolved_atstring

Quando foi decidida. Ausente nas pendentes.

resolved_byuuid

Quem decidiu. Ausente nas decididas pelo sistema.

resolution_notestring

Observação da decisão ou motivo da expiração.

vendor_product_namestring

Nome do produto do seller.

vendor_product_skustring

SKU do produto do seller.

vendor_product_barcodestring

Código de barras do produto do seller.

vendor_iduuid

Seller.

vendor_namestring

Nome do seller.

master_namestring

Nome do mestre sugerido. Ausente quando não há.

Campos do processamento em lote

processedinteger

Linhas pendentes examinadas.

resolvedinteger

Ligadas a um mestre (existente ou criado agora).

cancelledinteger

Rejeitadas por não terem mais como ser resolvidas (o seller não quer, o produto ou o SKU sumiu).

conflictsinteger

Conflitos reais de campos: continuam pendentes para decisão humana.

awaiting_moderationinteger

Produtos que ainda não podem ser vendidos (aguardando moderação, rejeitados, desativados): continuam pendentes.

skippedinteger

Linhas intocadas porque a ligação automática está desligada na loja.

errorsinteger

Falhas de avaliação, sem alterar a linha. Veja os logs da loja.

blockedinteger

Linhas em que a criação automática do mestre falhou. Diferente de skipped: aqui a plataforma tentou e não conseguiu.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Módulo desligado, ou falta o privilégio	`{"error":"module_disabled","module":"master-products"}`
404	Recurso desligado na loja	`{"error":"feature not enabled","detail":"enable master_products via admin settings"}`
404	Aprovar: linha ou produto não existe mais	`{"error":"queue entry not found"}` ou `{"error":"vendor product no longer exists"}`
404	Rejeitar: linha não existe ou já foi decidida	`{"error":"queue entry not found or already resolved"}`
409	Aprovar uma linha já decidida	`{"error":"queue entry already resolved"}`
500	Aprovar com a ligação desligada na loja	`{"error":"master linking is disabled for this store (link_master_products = off)"}`
500	Aprovar produto ainda não vendável (moderação, rejeitado, desativado)	`{"error":"vendor product is not in a sellable status (R) ..."}`
500	Id que não é UUID	`{"error":"..."}`