API atual/Referência completa/WhatsApp Commerce: canal e catálogo

Catálogo na Meta

Liga a sincronização dos produtos do seller com o catálogo do WhatsApp na Meta, envia os produtos e acompanha o resultado de cada um.

Estas rotas publicam os produtos do seller no Catálogo da Meta, que o WhatsApp exibe dentro da conversa. A cópia vai só no sentido plataforma para Meta: edite o produto na plataforma e a mudança segue para lá. O catálogo da Meta precisa ter sido criado antes, no Gerenciador de Catálogo da Meta; o seller informa o id dele.

Só entram os produtos ativos que podem ser vendidos pelo WhatsApp. Um produto que fica oculto, desativado ou apagado é retirado do catálogo da Meta na próxima passada.

Ver a situação

GET/api/v1/vendor/whatsapp/catalog-syncSeller

Mostra se a sincronização está ligada e como foi a última

Quando o seller nunca configurou um catálogo, a resposta é {"state": null}.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Situação

json

{
  "state": {
    "id": "a0b1c2d3-0000-4000-8000-000000000001",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "meta_catalog_id": "1234567890123456",
    "enabled": true,
    "last_full_sync_at": "2026-10-11T12:00:00Z",
    "last_full_sync_count": 180,
    "last_incremental_sync_at": "2026-10-11T13:00:00Z",
    "sync_frequency_seconds": 3600,
    "created_at": "2026-10-01T12:00:00Z",
    "updated_at": "2026-10-11T13:00:00Z"
  }
}

Campos da resposta

stateobject

A situação, ou null se não há catálogo configurado.

state.iduuid

Id do registro.

state.vendor_iduuid

Seller.

state.meta_catalog_idstring

Id do catálogo na Meta.

state.enabledboolean

true quando a sincronização está ligada.

state.last_full_sync_atstring

RFC 3339. Último envio completo. Ausente se nunca houve.

state.last_full_sync_countinteger

Quantos produtos o último envio completo enviou.

state.last_full_sync_errorstring

Erro do último envio completo, se houve.

state.last_incremental_sync_atstring

RFC 3339. Última passada automática.

state.sync_frequency_secondsinteger

Intervalo configurado da passada automática, em segundos.

state.created_atstring

RFC 3339.

state.updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado; seller sem cadastro	`{"error":"insufficient permissions"}` e demais
500	Falha ao ler	`{"error":"failed to load sync state","detail":"..."}`

Ligar a sincronização

POST/api/v1/vendor/whatsapp/catalog-sync/enableSeller

Informa o catálogo da Meta e liga a sincronização

Confere na Meta se o id existe e se o token do seller o alcança, antes de ligar. Chamar de novo troca o catálogo e confere outra vez. Exige que o seller tenha a credencial do número com token.

Corpo da requisição

meta_catalog_idstringobrigatório

Id do catálogo no Gerenciador de Catálogo da Meta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/enable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "meta_catalog_id": "1234567890123456"
}'

Resposta

200Sincronização ligada

json

{
  "state": {
    "id": "a0b1c2d3-0000-4000-8000-000000000001",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "meta_catalog_id": "1234567890123456",
    "enabled": true,
    "sync_frequency_seconds": 3600,
    "created_at": "2026-10-11T14:00:00Z",
    "updated_at": "2026-10-11T14:00:00Z"
  }
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
400	Falta `meta_catalog_id`	`{"error":"meta_catalog_id is required"}`
400	Id recusado pela Meta, ou seller sem número/token	`{"error":"failed to enable catalog sync","detail":"whatsapp catalog: vendor has no WhatsApp credentials configured"}`
401 / 403	Autenticação, módulo ou perfil	veja acima

Desligar

POST/api/v1/vendor/whatsapp/catalog-sync/disableSeller

Desliga a sincronização mantendo o histórico

Sem corpo. Para de enviar. O catálogo da Meta e o histórico de envio ficam como estão, então religar depois é barato. Os produtos já publicados não são removidos da Meta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/disable" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desligada

json

{ "ok": true }

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou perfil	veja acima
500	Falha ao desligar	`{"error":"failed to disable catalog sync","detail":"..."}`

Enviar os produtos agora

POST/api/v1/vendor/whatsapp/catalog-sync/fullSeller

Envia os produtos do seller ao catálogo da Meta

Sem corpo. Roda na hora, dentro da chamada, e só devolve quando termina; com muitos produtos pode demorar. Pula produtos que não mudaram desde o último envio com sucesso. Cada chamada trata no máximo 200 produtos, para respeitar o limite da Meta (cerca de 1.000 operações por hora por catálogo). Se a Meta limitar, a passada para e o resto fica pending. Em catálogos maiores, repita a chamada.

Depois do envio, produtos que deixaram de poder ser vendidos (até 200 por chamada) são retirados da Meta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/full" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Envio concluído

json

{ "pushed": 120, "skipped": 60, "failed": 2 }

Campos da resposta

pushedinteger

Produtos enviados com sucesso nesta chamada, mais os retirados da Meta.

skippedinteger

Produtos pulados por não terem mudado.

failedinteger

Produtos que a Meta recusou. O motivo de cada um está em catalog-sync/products.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou perfil	veja acima
500	Sincronização desligada, seller sem credencial ou falha geral	`{"error":"whatsapp catalog: sync not enabled for vendor","pushed":0,"skipped":0,"failed":0}`

Acompanhar produto a produto

GET/api/v1/vendor/whatsapp/catalog-sync/productsSeller

Lista o resultado do envio de cada produto

Ordenado do mais recentemente atualizado para o mais antigo.

Parâmetros de consulta

statusstring

pendingsuccessfailedremoved

Filtra pelo resultado do último envio. pending aguarda nova tentativa, success foi publicado, failed a Meta recusou, removed foi retirado da Meta.

qstring

Busca por trecho do id do produto ou do retailer_id.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Acima de 200 volta para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/products?status=failed" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos

json

{
  "rows": [
    {
      "id": "f0e1d2c3-0000-4000-8000-000000000001",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "retailer_id": "SD-002373",
      "last_pushed_at": "2026-10-11T13:00:05Z",
      "last_push_status": "failed",
      "last_push_error": "Invalid parameter: image_url",
      "product_name": "Tênis Urbano Preto",
      "created_at": "2026-10-05T12:00:00Z",
      "updated_at": "2026-10-11T13:00:05Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Campos da resposta

rowsarray

Produtos da página.

rows[].iduuid

Id do registro de envio. Não é o id do produto.

rows[].product_iduuid

Id do produto na plataforma. Use no retry.

rows[].retailer_idstring

Identificador do produto no catálogo da Meta.

rows[].meta_product_idstring

Id do produto na Meta. Ausente se nunca foi publicado.

rows[].last_pushed_atstring

RFC 3339. Último envio.

rows[].last_push_statusstring

pendingsuccessfailedremoved

Resultado do último envio.

rows[].last_push_errorstring

Mensagem de erro do último envio. Ausente quando deu certo.

rows[].product_namestring

Nome atual do produto. Vazio se o produto foi apagado.

rows[].created_atstring

RFC 3339.

rows[].updated_atstring

RFC 3339.

totalinteger

Total que atende ao filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página usado.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou perfil	veja acima
500	Falha ao ler	`{"error":"failed to list catalog mirror rows","detail":"..."}`

Reenviar um produto

POST/api/v1/vendor/whatsapp/catalog-sync/products/{id}/retrySeller

Reenvia um produto ao catálogo da Meta

Sem corpo. Útil depois de corrigir o motivo de uma falha (por exemplo, a imagem). Só funciona para produtos do próprio seller e com a sincronização ligada.

Parâmetros de caminho

iduuidobrigatório

Id do produto (rows[].product_id), não o id do registro de envio.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/products/$PRODUCT_ID/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Reenviado

json

{ "ok": true }

Erros

Status	Quando	Corpo
400	Sincronização desligada, seller sem credencial, produto inexistente ou a Meta recusou de novo	`{"error":"failed to retry product sync","detail":"..."}`
401 / 403	Autenticação, módulo ou perfil	veja acima

Veja também

API atual/Referência completa/WhatsApp Commerce: canal e catálogo

Catálogo na Meta

Liga a sincronização dos produtos do seller com o catálogo do WhatsApp na Meta, envia os produtos e acompanha o resultado de cada um.

Só entram os produtos ativos que podem ser vendidos pelo WhatsApp. Um produto que fica oculto, desativado ou apagado é retirado do catálogo da Meta na próxima passada.

Ver a situação

GET/api/v1/vendor/whatsapp/catalog-syncSeller

Mostra se a sincronização está ligada e como foi a última

Quando o seller nunca configurou um catálogo, a resposta é {"state": null}.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Situação

json

{
  "state": {
    "id": "a0b1c2d3-0000-4000-8000-000000000001",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "meta_catalog_id": "1234567890123456",
    "enabled": true,
    "last_full_sync_at": "2026-10-11T12:00:00Z",
    "last_full_sync_count": 180,
    "last_incremental_sync_at": "2026-10-11T13:00:00Z",
    "sync_frequency_seconds": 3600,
    "created_at": "2026-10-01T12:00:00Z",
    "updated_at": "2026-10-11T13:00:00Z"
  }
}

Campos da resposta

stateobject

A situação, ou null se não há catálogo configurado.

state.iduuid

Id do registro.

state.vendor_iduuid

Seller.

state.meta_catalog_idstring

Id do catálogo na Meta.

state.enabledboolean

true quando a sincronização está ligada.

state.last_full_sync_atstring

RFC 3339. Último envio completo. Ausente se nunca houve.

state.last_full_sync_countinteger

Quantos produtos o último envio completo enviou.

state.last_full_sync_errorstring

Erro do último envio completo, se houve.

state.last_incremental_sync_atstring

RFC 3339. Última passada automática.

state.sync_frequency_secondsinteger

Intervalo configurado da passada automática, em segundos.

state.created_atstring

RFC 3339.

state.updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado; seller sem cadastro	`{"error":"insufficient permissions"}` e demais
500	Falha ao ler	`{"error":"failed to load sync state","detail":"..."}`

Ligar a sincronização

POST/api/v1/vendor/whatsapp/catalog-sync/enableSeller

Informa o catálogo da Meta e liga a sincronização

Confere na Meta se o id existe e se o token do seller o alcança, antes de ligar. Chamar de novo troca o catálogo e confere outra vez. Exige que o seller tenha a credencial do número com token.

Corpo da requisição

meta_catalog_idstringobrigatório

Id do catálogo no Gerenciador de Catálogo da Meta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/enable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "meta_catalog_id": "1234567890123456"
}'

Resposta

200Sincronização ligada

json

{
  "state": {
    "id": "a0b1c2d3-0000-4000-8000-000000000001",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "meta_catalog_id": "1234567890123456",
    "enabled": true,
    "sync_frequency_seconds": 3600,
    "created_at": "2026-10-11T14:00:00Z",
    "updated_at": "2026-10-11T14:00:00Z"
  }
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body","detail":"..."}`
400	Falta `meta_catalog_id`	`{"error":"meta_catalog_id is required"}`
400	Id recusado pela Meta, ou seller sem número/token	`{"error":"failed to enable catalog sync","detail":"whatsapp catalog: vendor has no WhatsApp credentials configured"}`
401 / 403	Autenticação, módulo ou perfil	veja acima

Desligar

POST/api/v1/vendor/whatsapp/catalog-sync/disableSeller

Desliga a sincronização mantendo o histórico

Sem corpo. Para de enviar. O catálogo da Meta e o histórico de envio ficam como estão, então religar depois é barato. Os produtos já publicados não são removidos da Meta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/disable" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desligada

json

{ "ok": true }

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou perfil	veja acima
500	Falha ao desligar	`{"error":"failed to disable catalog sync","detail":"..."}`

Enviar os produtos agora

POST/api/v1/vendor/whatsapp/catalog-sync/fullSeller

Envia os produtos do seller ao catálogo da Meta

Depois do envio, produtos que deixaram de poder ser vendidos (até 200 por chamada) são retirados da Meta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/full" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Envio concluído

json

{ "pushed": 120, "skipped": 60, "failed": 2 }

Campos da resposta

pushedinteger

Produtos enviados com sucesso nesta chamada, mais os retirados da Meta.

skippedinteger

Produtos pulados por não terem mudado.

failedinteger

Produtos que a Meta recusou. O motivo de cada um está em catalog-sync/products.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou perfil	veja acima
500	Sincronização desligada, seller sem credencial ou falha geral	`{"error":"whatsapp catalog: sync not enabled for vendor","pushed":0,"skipped":0,"failed":0}`

Acompanhar produto a produto

GET/api/v1/vendor/whatsapp/catalog-sync/productsSeller

Lista o resultado do envio de cada produto

Ordenado do mais recentemente atualizado para o mais antigo.

Parâmetros de consulta

statusstring

pendingsuccessfailedremoved

Filtra pelo resultado do último envio. pending aguarda nova tentativa, success foi publicado, failed a Meta recusou, removed foi retirado da Meta.

qstring

Busca por trecho do id do produto ou do retailer_id.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Acima de 200 volta para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/products?status=failed" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produtos

json

{
  "rows": [
    {
      "id": "f0e1d2c3-0000-4000-8000-000000000001",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "retailer_id": "SD-002373",
      "last_pushed_at": "2026-10-11T13:00:05Z",
      "last_push_status": "failed",
      "last_push_error": "Invalid parameter: image_url",
      "product_name": "Tênis Urbano Preto",
      "created_at": "2026-10-05T12:00:00Z",
      "updated_at": "2026-10-11T13:00:05Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

Campos da resposta

rowsarray

Produtos da página.

rows[].iduuid

Id do registro de envio. Não é o id do produto.

rows[].product_iduuid

Id do produto na plataforma. Use no retry.

rows[].retailer_idstring

Identificador do produto no catálogo da Meta.

rows[].meta_product_idstring

Id do produto na Meta. Ausente se nunca foi publicado.

rows[].last_pushed_atstring

RFC 3339. Último envio.

rows[].last_push_statusstring

pendingsuccessfailedremoved

Resultado do último envio.

rows[].last_push_errorstring

Mensagem de erro do último envio. Ausente quando deu certo.

rows[].product_namestring

Nome atual do produto. Vazio se o produto foi apagado.

rows[].created_atstring

RFC 3339.

rows[].updated_atstring

RFC 3339.

totalinteger

Total que atende ao filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página usado.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou perfil	veja acima
500	Falha ao ler	`{"error":"failed to list catalog mirror rows","detail":"..."}`

Reenviar um produto

POST/api/v1/vendor/whatsapp/catalog-sync/products/{id}/retrySeller

Reenvia um produto ao catálogo da Meta

Sem corpo. Útil depois de corrigir o motivo de uma falha (por exemplo, a imagem). Só funciona para produtos do próprio seller e com a sincronização ligada.

Parâmetros de caminho

iduuidobrigatório

Id do produto (rows[].product_id), não o id do registro de envio.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/catalog-sync/products/$PRODUCT_ID/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Reenviado

json

{ "ok": true }

Erros

Status	Quando	Corpo
400	Sincronização desligada, seller sem credencial, produto inexistente ou a Meta recusou de novo	`{"error":"failed to retry product sync","detail":"..."}`
401 / 403	Autenticação, módulo ou perfil	veja acima