API atual/Referência completa/WhatsApp: catálogo na Meta

Produtos sincronizados

Dispara a sincronização completa, lista o espelho dos produtos na Meta e tenta de novo os que falharam.

A plataforma guarda um espelho de cada produto enviado: o retailer_id (identificador do item na Meta), o resultado do último envio e o erro, se houve. Um produto só é reenviado quando seu conteúdo mudou (a plataforma compara uma assinatura do conteúdo). Estas rotas disparam o envio e permitem auditar o resultado.

Sincronização completa

Percorre os produtos ativos e visíveis no WhatsApp e envia os novos ou alterados; itens que deixaram de ser vendáveis são removidos da Meta. A chamada é síncrona e processa no máximo 200 produtos por vez, com pequena pausa entre eles. Catálogos maiores precisam de várias chamadas (ou esperar a sincronização automática). Se a Meta limitar a taxa, o ciclo para e o restante fica pending.

POST/api/v1/admin/whatsapp/catalog-sync/fullAdmin

Envia à Meta os produtos ativos do seller que mudaram

Corpo da requisição

vendor_idstringobrigatório

UUID do seller.

Exemplo de requisição (Sincronização completa)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/catalog-sync/full" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
  }'

Resposta (Sincronização completa)

200Resultado

json

{
  "pushed": 120,
  "skipped": 75,
  "failed": 5
}

Campos da resposta

pushedinteger

Produtos enviados, mais os removidos da Meta nesta chamada.

skippedinteger

Produtos sem mudança, não reenviados.

failedinteger

Produtos que a Meta recusou (veja o espelho para o motivo).

Erros (Sincronização completa)

Status	Quando	Corpo
400	Sem `vendor_id` (a rota exige o seller; usuários vinculados a um seller usam o próprio).	`{"error":"vendor_id required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
500	A sincronização não pôde começar (não está ligada, seller sem token...). O corpo traz também os contadores.	`{"error":"whatsapp catalog: sync not enabled for vendor","pushed":0,"skipped":0,"failed":0}`

Listar o espelho

Mostra, por produto, o estado do último envio à Meta.

GET/api/v1/admin/whatsapp/catalog-sync/productsAdmin

Lista os produtos enviados e o resultado de cada envio

Parâmetros de consulta

vendor_idstringobrigatório

UUID do seller. Obrigatório, a menos que o usuário esteja vinculado a um seller.

statusstring

pendingsuccessfailedremovedremove_failed

Resultado do último envio.

qstring

Trecho do retailer_id ou do id do produto.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, até 200. Fora disso vale 50.

Exemplo de requisição (Listar o espelho)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/catalog-sync/products?vendor_id=94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36&status=failed" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar o espelho)

200Espelho

json

{
  "rows": [
    {
      "id": "6e5d4c3b-2a19-4f08-9e7d-6c5b4a392817",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "retailer_id": "v2-22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "meta_product_id": "9988776655",
      "last_pushed_at": "2026-10-11T20:01:00Z",
      "last_push_status": "failed",
      "last_push_error": "meta 400: Invalid image URL",
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-11T20:01:00Z",
      "product_name": "Camisa do Flamengo Masculina I 26 Adidas"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Campos da resposta

rowsarray

Linhas do espelho.

idstring

UUID da linha.

vendor_idstring

Seller.

product_idstring

UUID do produto na loja.

retailer_idstring

Identificador do item na Meta.

meta_product_idstring

Id devolvido pela Meta.

last_pushed_atstring

Último envio.

last_push_statusstring

pending, success, failed, removed ou remove_failed.

last_push_errorstring

Motivo da falha, se failed.

product_namestring

Nome do produto (vazio se foi excluído).

created_atstring

Criação.

updated_atstring

Última alteração.

totalinteger

Total de linhas.

pageinteger

Página.

per_pageinteger

Itens por página.

Erros (Listar o espelho)

Status	Quando	Corpo
400	Sem `vendor_id` (a rota exige o seller; usuários vinculados a um seller usam o próprio).	`{"error":"vendor_id required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`

Tentar um produto de novo

Reenvia um único produto, normalmente um que ficou failed depois de você corrigir a causa (por exemplo, a imagem). O produto precisa estar entre os 500 primeiros produtos visíveis do seller.

POST/api/v1/admin/whatsapp/catalog-sync/products/{id}/retryAdmin

Reenvia um produto à Meta

Parâmetros de caminho

idstringobrigatório

UUID do produto (não da linha do espelho).

Corpo da requisição

vendor_idstringobrigatório

UUID do seller.

Exemplo de requisição (Tentar um produto de novo)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/catalog-sync/products/22fbd12a-1b6e-41ea-a84f-4d9cf06c8766/retry" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
  }'

Resposta (Tentar um produto de novo)

200Reenviado

json

{
  "ok": true
}

Campos da resposta

okboolean

true.

Erros (Tentar um produto de novo)

Status	Quando	Corpo
400	Sem `vendor_id` (a rota exige o seller; usuários vinculados a um seller usam o próprio).	`{"error":"vendor_id required"}`
400	Sincronização desligada, seller sem token, produto fora da lista ou recusa da Meta (a mensagem vem em `error`).	`{"error":"whatsapp catalog: sync not enabled for vendor"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`

Veja também

API atual/Referência completa/WhatsApp: catálogo na Meta

Produtos sincronizados

Dispara a sincronização completa, lista o espelho dos produtos na Meta e tenta de novo os que falharam.

Sincronização completa

POST/api/v1/admin/whatsapp/catalog-sync/fullAdmin

Envia à Meta os produtos ativos do seller que mudaram

Corpo da requisição

vendor_idstringobrigatório

UUID do seller.

Exemplo de requisição (Sincronização completa)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/catalog-sync/full" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
  }'

Resposta (Sincronização completa)

200Resultado

json

{
  "pushed": 120,
  "skipped": 75,
  "failed": 5
}

Campos da resposta

pushedinteger

Produtos enviados, mais os removidos da Meta nesta chamada.

skippedinteger

Produtos sem mudança, não reenviados.

failedinteger

Produtos que a Meta recusou (veja o espelho para o motivo).

Erros (Sincronização completa)

Status	Quando	Corpo
400	Sem `vendor_id` (a rota exige o seller; usuários vinculados a um seller usam o próprio).	`{"error":"vendor_id required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
500	A sincronização não pôde começar (não está ligada, seller sem token...). O corpo traz também os contadores.	`{"error":"whatsapp catalog: sync not enabled for vendor","pushed":0,"skipped":0,"failed":0}`

Listar o espelho

Mostra, por produto, o estado do último envio à Meta.

GET/api/v1/admin/whatsapp/catalog-sync/productsAdmin

Lista os produtos enviados e o resultado de cada envio

Parâmetros de consulta

vendor_idstringobrigatório

UUID do seller. Obrigatório, a menos que o usuário esteja vinculado a um seller.

statusstring

pendingsuccessfailedremovedremove_failed

Resultado do último envio.

qstring

Trecho do retailer_id ou do id do produto.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, até 200. Fora disso vale 50.

Exemplo de requisição (Listar o espelho)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/catalog-sync/products?vendor_id=94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36&status=failed" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar o espelho)

200Espelho

json

{
  "rows": [
    {
      "id": "6e5d4c3b-2a19-4f08-9e7d-6c5b4a392817",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "retailer_id": "v2-22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "meta_product_id": "9988776655",
      "last_pushed_at": "2026-10-11T20:01:00Z",
      "last_push_status": "failed",
      "last_push_error": "meta 400: Invalid image URL",
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-11T20:01:00Z",
      "product_name": "Camisa do Flamengo Masculina I 26 Adidas"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Campos da resposta

rowsarray

Linhas do espelho.

idstring

UUID da linha.

vendor_idstring

Seller.

product_idstring

UUID do produto na loja.

retailer_idstring

Identificador do item na Meta.

meta_product_idstring

Id devolvido pela Meta.

last_pushed_atstring

Último envio.

last_push_statusstring

pending, success, failed, removed ou remove_failed.

last_push_errorstring

Motivo da falha, se failed.

product_namestring

Nome do produto (vazio se foi excluído).

created_atstring

Criação.

updated_atstring

Última alteração.

totalinteger

Total de linhas.

pageinteger

Página.

per_pageinteger

Itens por página.

Erros (Listar o espelho)

Status	Quando	Corpo
400	Sem `vendor_id` (a rota exige o seller; usuários vinculados a um seller usam o próprio).	`{"error":"vendor_id required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`

Tentar um produto de novo

Reenvia um único produto, normalmente um que ficou failed depois de você corrigir a causa (por exemplo, a imagem). O produto precisa estar entre os 500 primeiros produtos visíveis do seller.

POST/api/v1/admin/whatsapp/catalog-sync/products/{id}/retryAdmin

Reenvia um produto à Meta

Parâmetros de caminho

idstringobrigatório

UUID do produto (não da linha do espelho).

Corpo da requisição

vendor_idstringobrigatório

UUID do seller.

Exemplo de requisição (Tentar um produto de novo)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/catalog-sync/products/22fbd12a-1b6e-41ea-a84f-4d9cf06c8766/retry" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
  }'

Resposta (Tentar um produto de novo)

200Reenviado

json

{
  "ok": true
}

Campos da resposta

okboolean

true.

Erros (Tentar um produto de novo)

Status	Quando	Corpo
400	Sem `vendor_id` (a rota exige o seller; usuários vinculados a um seller usam o próprio).	`{"error":"vendor_id required"}`
400	Sincronização desligada, seller sem token, produto fora da lista ou recusa da Meta (a mensagem vem em `error`).	`{"error":"whatsapp catalog: sync not enabled for vendor"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`