API atual/Referência completa/WhatsApp: caixa de entrada

Carrinho montado pelo atendente

Busca produtos, monta o carrinho do cliente dentro da conversa e envia o link para ele finalizar.

Em vez de ditar produtos por mensagem, o atendente pode montar o carrinho do cliente: busca os produtos, adiciona ao carrinho do cliente e envia pelo WhatsApp um resumo com o link "Finalizar" (a página de carrinho da loja). O cliente só confere e paga. Para isso a conversa precisa estar ligada a um cliente cadastrado; sem ele as rotas respondem 422 thread_no_customer_user.

Buscar produtos para adicionar

Busca produtos visíveis no WhatsApp, limitados ao seller da conversa (ou a toda a loja se a conversa não tem seller).

GET/api/v1/admin/whatsapp/threads/{id}/quick-addAdmin

Busca produtos do seller da conversa para o atendente adicionar

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Parâmetros de consulta

qstring

Texto da busca no nome do produto.

limitintegerpadrão: 10

Máximo de produtos, até 50.

Exemplo de requisição (Buscar produtos para adicionar)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/quick-add?q=camisa&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Buscar produtos para adicionar)

200Produtos

json

{
  "products": [
    {
      "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "sku": "FLA-I-26",
      "slug": "camisa-flamengo-masculina-i-26-adidas",
      "price": 30000,
      "list_price": 44990,
      "quantity": 38,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "category_name": "Camisetas",
      "image_url": "/uploads/dfe2555e/product/22fbd12a/camisa.png"
    }
  ],
  "query": "camisa",
  "limit": 5
}

Campos da resposta

productsarray

Produtos encontrados.

idstring

UUID do produto.

namestring

Nome.

skustring

Código do produto.

slugstring

Identificador de URL.

priceinteger

Preço em centavos (30000 = R$ 300,00).

list_priceinteger

Preço de tabela ("de") em centavos. Ausente quando não há.

quantityinteger

Estoque disponível.

vendor_idstring

UUID do seller.

category_idstring

UUID da categoria.

category_namestring

Nome da categoria.

image_urlstring

Caminho da imagem principal.

querystring

Busca aplicada.

limitinteger

Limite aplicado.

Erros (Buscar produtos para adicionar)

Status	Quando	Corpo
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_orders"}` ou `{"error":"admin access required"}`
404	A conversa não existe.	`{"error":"thread not found"}`

Listar variações do produto

Para produtos com variações, cada variação é um produto-filho. Esta rota lista as filhas ativas e visíveis no WhatsApp; o id de cada uma vai em variant_id ao montar o carrinho.

GET/api/v1/admin/whatsapp/products/{productId}/variantsAdmin

Lista as variações (tamanho, cor...) de um produto

Parâmetros de caminho

productIdstringobrigatório

UUID do produto pai.

Exemplo de requisição (Listar variações do produto)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/products/22fbd12a-1b6e-41ea-a84f-4d9cf06c8766/variants" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar variações do produto)

200Variações

json

{
  "variants": [
    {
      "id": "5b8f0a9e-0a43-4d0c-8f5b-0b6c3f1d7a10",
      "name": "Camisa do Flamengo Masculina I 26 Adidas - M",
      "sku": "FLA-I-26-M",
      "slug": "camisa-flamengo-masculina-i-26-adidas",
      "price": 30000,
      "list_price": 44990,
      "quantity": 12,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "category_name": "Camisetas",
      "image_url": "/uploads/dfe2555e/product/22fbd12a/camisa.png"
    }
  ]
}

Campos da resposta

variantsarray

Variações, com os mesmos campos de produto da busca. Vazio quando não há.

Erros (Listar variações do produto)

Status	Quando	Corpo
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_orders"}` ou `{"error":"admin access required"}`

Montar e enviar o carrinho

Adiciona cada item ao carrinho do cliente (somando à quantidade que já existir) e envia uma mensagem em português com o resumo e o link de finalização. Se qualquer linha falhar, nada é enviado. Esta rota não desliga o assistente.

POST/api/v1/admin/whatsapp/threads/{id}/send-cartAdmin

Adiciona itens ao carrinho do cliente e envia o resumo no WhatsApp

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Corpo da requisição

itemsarrayobrigatório

Itens a adicionar, ao menos um.

product_idstringobrigatório

UUID do produto.

variant_idstring

UUID da variação (produto-filho), para produtos com variações.

quantityintegerobrigatório

Quantidade.

Exemplo de requisição (Montar e enviar o carrinho)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/send-cart" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
        "variant_id": "5b8f0a9e-0a43-4d0c-8f5b-0b6c3f1d7a10",
        "quantity": 2
      }
    ]
  }'

Resposta (Montar e enviar o carrinho)

200Carrinho enviado

json

{
  "success": true,
  "result": {
    "cart_id": "9d6f4f6e-6a60-4a5b-9d7e-3a0a1c2b3d4e",
    "items_added": 1,
    "line_subtotals_cents": [
      60000
    ],
    "message": "Seu carrinho: 2x Camisa do Flamengo ... Finalizar: https://minhaloja.io.venddor.com.br/cart",
    "wa_message_id": "wamid.HBgNNTUx...",
    "checkout_url": "https://minhaloja.io.venddor.com.br/cart"
  }
}

Campos da resposta

resultobject

Resultado.

cart_idstring

UUID do carrinho do cliente.

items_addedinteger

Linhas adicionadas.

line_subtotals_centsarray

Subtotal de cada linha, em centavos, na ordem enviada.

messagestring

Texto enviado ao cliente.

wa_message_idstring

Id da mensagem na Meta.

checkout_urlstring

Link de finalização.

Erros (Montar e enviar o carrinho)

Status	Quando	Corpo
400	`items` vazio ou corpo inválido.	`{"error":"items 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_orders"}` ou `{"error":"admin access required"}`
422	A conversa não tem cliente cadastrado.	`{"error":"thread_no_customer_user","hint":"Customer is not linked to a registered user. Ask them to sign up on the storefront first."}`
500	Falha ao montar o carrinho (produto inexistente, sem estoque...).	`{"error":"Failed to send cart: ..."}`
502	Os itens entraram no carrinho, mas a Meta recusou a mensagem. A resposta traz `result` com o que foi feito.	`{"error":"cloud_api_send_failed","detail":"...","result":{}}`

Esvaziar o carrinho

Esvazia o carrinho do cliente ligado à conversa. Não envia mensagem. Sem corpo.

POST/api/v1/admin/whatsapp/threads/{id}/clear-cartAdmin

Remove todos os itens do carrinho do cliente da conversa

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Exemplo de requisição (Esvaziar o carrinho)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/clear-cart" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Esvaziar o carrinho)

200Esvaziado

json

{
  "success": "ok"
}

Campos da resposta

successstring

Sempre ok.

Erros (Esvaziar o carrinho)

Status	Quando	Corpo
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_orders"}` ou `{"error":"admin access required"}`
422	A conversa não tem cliente cadastrado.	`{"error":"thread_no_customer_user"}`

Veja também

API atual/Referência completa/WhatsApp: caixa de entrada

Carrinho montado pelo atendente

Busca produtos, monta o carrinho do cliente dentro da conversa e envia o link para ele finalizar.

Buscar produtos para adicionar

Busca produtos visíveis no WhatsApp, limitados ao seller da conversa (ou a toda a loja se a conversa não tem seller).

GET/api/v1/admin/whatsapp/threads/{id}/quick-addAdmin

Busca produtos do seller da conversa para o atendente adicionar

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Parâmetros de consulta

qstring

Texto da busca no nome do produto.

limitintegerpadrão: 10

Máximo de produtos, até 50.

Exemplo de requisição (Buscar produtos para adicionar)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/quick-add?q=camisa&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Buscar produtos para adicionar)

200Produtos

json

{
  "products": [
    {
      "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "sku": "FLA-I-26",
      "slug": "camisa-flamengo-masculina-i-26-adidas",
      "price": 30000,
      "list_price": 44990,
      "quantity": 38,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "category_name": "Camisetas",
      "image_url": "/uploads/dfe2555e/product/22fbd12a/camisa.png"
    }
  ],
  "query": "camisa",
  "limit": 5
}

Campos da resposta

productsarray

Produtos encontrados.

idstring

UUID do produto.

namestring

Nome.

skustring

Código do produto.

slugstring

Identificador de URL.

priceinteger

Preço em centavos (30000 = R$ 300,00).

list_priceinteger

Preço de tabela ("de") em centavos. Ausente quando não há.

quantityinteger

Estoque disponível.

vendor_idstring

UUID do seller.

category_idstring

UUID da categoria.

category_namestring

Nome da categoria.

image_urlstring

Caminho da imagem principal.

querystring

Busca aplicada.

limitinteger

Limite aplicado.

Erros (Buscar produtos para adicionar)

Status	Quando	Corpo
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_orders"}` ou `{"error":"admin access required"}`
404	A conversa não existe.	`{"error":"thread not found"}`

Listar variações do produto

Para produtos com variações, cada variação é um produto-filho. Esta rota lista as filhas ativas e visíveis no WhatsApp; o id de cada uma vai em variant_id ao montar o carrinho.

GET/api/v1/admin/whatsapp/products/{productId}/variantsAdmin

Lista as variações (tamanho, cor...) de um produto

Parâmetros de caminho

productIdstringobrigatório

UUID do produto pai.

Exemplo de requisição (Listar variações do produto)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/products/22fbd12a-1b6e-41ea-a84f-4d9cf06c8766/variants" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar variações do produto)

200Variações

json

{
  "variants": [
    {
      "id": "5b8f0a9e-0a43-4d0c-8f5b-0b6c3f1d7a10",
      "name": "Camisa do Flamengo Masculina I 26 Adidas - M",
      "sku": "FLA-I-26-M",
      "slug": "camisa-flamengo-masculina-i-26-adidas",
      "price": 30000,
      "list_price": 44990,
      "quantity": 12,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "category_id": "8fcaf422-1631-4282-b503-85cc57380649",
      "category_name": "Camisetas",
      "image_url": "/uploads/dfe2555e/product/22fbd12a/camisa.png"
    }
  ]
}

Campos da resposta

variantsarray

Variações, com os mesmos campos de produto da busca. Vazio quando não há.

Erros (Listar variações do produto)

Status	Quando	Corpo
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_orders"}` ou `{"error":"admin access required"}`

Montar e enviar o carrinho

POST/api/v1/admin/whatsapp/threads/{id}/send-cartAdmin

Adiciona itens ao carrinho do cliente e envia o resumo no WhatsApp

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Corpo da requisição

itemsarrayobrigatório

Itens a adicionar, ao menos um.

product_idstringobrigatório

UUID do produto.

variant_idstring

UUID da variação (produto-filho), para produtos com variações.

quantityintegerobrigatório

Quantidade.

Exemplo de requisição (Montar e enviar o carrinho)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/send-cart" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
        "variant_id": "5b8f0a9e-0a43-4d0c-8f5b-0b6c3f1d7a10",
        "quantity": 2
      }
    ]
  }'

Resposta (Montar e enviar o carrinho)

200Carrinho enviado

json

{
  "success": true,
  "result": {
    "cart_id": "9d6f4f6e-6a60-4a5b-9d7e-3a0a1c2b3d4e",
    "items_added": 1,
    "line_subtotals_cents": [
      60000
    ],
    "message": "Seu carrinho: 2x Camisa do Flamengo ... Finalizar: https://minhaloja.io.venddor.com.br/cart",
    "wa_message_id": "wamid.HBgNNTUx...",
    "checkout_url": "https://minhaloja.io.venddor.com.br/cart"
  }
}

Campos da resposta

resultobject

Resultado.

cart_idstring

UUID do carrinho do cliente.

items_addedinteger

Linhas adicionadas.

line_subtotals_centsarray

Subtotal de cada linha, em centavos, na ordem enviada.

messagestring

Texto enviado ao cliente.

wa_message_idstring

Id da mensagem na Meta.

checkout_urlstring

Link de finalização.

Erros (Montar e enviar o carrinho)

Status	Quando	Corpo
400	`items` vazio ou corpo inválido.	`{"error":"items 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_orders"}` ou `{"error":"admin access required"}`
422	A conversa não tem cliente cadastrado.	`{"error":"thread_no_customer_user","hint":"Customer is not linked to a registered user. Ask them to sign up on the storefront first."}`
500	Falha ao montar o carrinho (produto inexistente, sem estoque...).	`{"error":"Failed to send cart: ..."}`
502	Os itens entraram no carrinho, mas a Meta recusou a mensagem. A resposta traz `result` com o que foi feito.	`{"error":"cloud_api_send_failed","detail":"...","result":{}}`

Esvaziar o carrinho

Esvazia o carrinho do cliente ligado à conversa. Não envia mensagem. Sem corpo.

POST/api/v1/admin/whatsapp/threads/{id}/clear-cartAdmin

Remove todos os itens do carrinho do cliente da conversa

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Exemplo de requisição (Esvaziar o carrinho)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/clear-cart" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Esvaziar o carrinho)

200Esvaziado

json

{
  "success": "ok"
}

Campos da resposta

successstring

Sempre ok.

Erros (Esvaziar o carrinho)

Status	Quando	Corpo
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_orders"}` ou `{"error":"admin access required"}`
422	A conversa não tem cliente cadastrado.	`{"error":"thread_no_customer_user"}`