Listar e buscar threads

Lista as conversas do cliente com a contagem de não lidas, acha uma conversa por seller e objeto e conta as mensagens não lidas.

Estas três rotas montam a caixa de entrada do cliente: a lista paginada de conversas, a busca de uma conversa específica (para não abrir duplicadas) e o número do selo de "não lidas" no menu.

GET/api/v1/storefront/messages/threadsCliente

Listar as threads do cliente

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor menor que 1 vira 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa, vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/messages/threads?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Threads do cliente

json

{
  "threads": [
    {
      "id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
      "subject": "Dúvida sobre o pedido PEDIDO-20261010-0004",
      "status": "A",
      "object_type": "order",
      "object_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "object_name": "PEDIDO-20261010-0004",
      "customer_user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Casa do Café",
      "customer_name": "Maria Souza",
      "last_message_preview": "Seu pedido sai amanhã.",
      "last_message_at": "2026-10-11T18:30:00Z",
      "unread_count": 1,
      "created_at": "2026-10-11T17:00:00Z",
      "updated_at": "2026-10-11T18:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

threadsarray

Threads da página. [] quando não há nenhuma.

threads[].iduuid

Id da thread.

threads[].subjectstring

Assunto da conversa, em texto puro.

threads[].statusstring

ARC

A aberta, R resolvida, C arquivada.

threads[].object_typestring

Tipo do objeto ligado (order, product, ...). Ausente quando não há.

threads[].object_iduuid

Id do objeto ligado. Ausente quando não há.

threads[].object_namestring

Rótulo do objeto para exibir (por exemplo o número do pedido). Ausente quando não há.

threads[].customer_user_iduuid

Cliente dono da thread.

threads[].vendor_iduuid

Seller da conversa. Ausente em thread da loja.

threads[].vendor_namestring

Nome do seller. Ausente em thread da loja.

threads[].customer_namestring

Nome do cliente para exibição.

threads[].last_message_previewstring

Início da última mensagem (até 100 caracteres). Para mensagem só com anexo, [attachment].

threads[].last_message_atstring

Data da última mensagem (RFC 3339).

threads[].unread_countinteger

Mensagens não lidas escritas pela outra parte.

threads[].created_atstring

Criação (RFC 3339).

threads[].updated_atstring

Última alteração (RFC 3339).

totalinteger

Total de threads do cliente.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	Token de chave de API sem o escopo `customer:read`.	`{"error":"missing_scope","required":"customer:read"}`
500	Falha ao consultar.	`{"error":"failed to list threads","detail":"..."}`

GET/api/v1/storefront/messages/threads/findCliente

Achar a thread de um seller e objeto

Procura a thread mais recente do cliente que combine com os três filtros. Cada filtro vazio significa "sem seller" ou "sem objeto", e não "qualquer um".

Parâmetros de consulta

vendor_iduuid

Seller da conversa. Vazio procura a thread da loja (sem seller).

object_typestring

Tipo do objeto ligado. Vazio procura threads sem objeto.

object_iduuid

Id do objeto ligado. Vazio procura threads sem objeto.

bash

curl "$BASE_URL/api/v1/storefront/messages/threads/find?vendor_id=$VENDOR_ID&object_type=order&object_id=$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN"

200Thread encontrada

json

{
  "id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
  "subject": "Dúvida sobre o pedido PEDIDO-20261010-0004",
  "status": "A",
  "object_type": "order",
  "object_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "object_name": "PEDIDO-20261010-0004",
  "customer_user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Casa do Café",
  "customer_name": "Maria Souza",
  "last_message_preview": "Seu pedido sai amanhã.",
  "last_message_at": "2026-10-11T18:30:00Z",
  "unread_count": 0,
  "created_at": "2026-10-11T17:00:00Z",
  "updated_at": "2026-10-11T18:30:00Z",
  "messages": [
    {
      "id": "5d0a0f4e-2c3b-4b8a-8a6d-0d9d2b1c7e10",
      "thread_id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
      "sender_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "sender_type": "customer",
      "body": "Quando meu pedido sai?",
      "attachments": [],
      "is_read": true,
      "created_at": "2026-10-11T17:00:00Z"
    }
  ]
}

A resposta é a mesma de Ler a thread, com o campo unread_count sempre 0 (ele só é calculado na lista).

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`
404	Nenhuma thread combina com os filtros.	`{"error":"thread not found"}`
500	Falha ao consultar.	`{"error":"failed to find thread","detail":"..."}`

GET/api/v1/storefront/messages/unread-countCliente

Contar mensagens não lidas

bash

curl "$BASE_URL/api/v1/storefront/messages/unread-count" \
  -H "Authorization: Bearer $TOKEN"

200Contagem

json

{ "count": 3 }

Campos da resposta

countinteger

Mensagens não lidas de todas as threads do cliente, escritas por seller ou administrador.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`

Veja também

Listar e buscar threads

Lista as conversas do cliente com a contagem de não lidas, acha uma conversa por seller e objeto e conta as mensagens não lidas.

Estas três rotas montam a caixa de entrada do cliente: a lista paginada de conversas, a busca de uma conversa específica (para não abrir duplicadas) e o número do selo de "não lidas" no menu.

GET/api/v1/storefront/messages/threadsCliente

Listar as threads do cliente

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor menor que 1 vira 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa, vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/messages/threads?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Threads do cliente

json

{
  "threads": [
    {
      "id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
      "subject": "Dúvida sobre o pedido PEDIDO-20261010-0004",
      "status": "A",
      "object_type": "order",
      "object_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "object_name": "PEDIDO-20261010-0004",
      "customer_user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Casa do Café",
      "customer_name": "Maria Souza",
      "last_message_preview": "Seu pedido sai amanhã.",
      "last_message_at": "2026-10-11T18:30:00Z",
      "unread_count": 1,
      "created_at": "2026-10-11T17:00:00Z",
      "updated_at": "2026-10-11T18:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

threadsarray

Threads da página. [] quando não há nenhuma.

threads[].iduuid

Id da thread.

threads[].subjectstring

Assunto da conversa, em texto puro.

threads[].statusstring

ARC

A aberta, R resolvida, C arquivada.

threads[].object_typestring

Tipo do objeto ligado (order, product, ...). Ausente quando não há.

threads[].object_iduuid

Id do objeto ligado. Ausente quando não há.

threads[].object_namestring

Rótulo do objeto para exibir (por exemplo o número do pedido). Ausente quando não há.

threads[].customer_user_iduuid

Cliente dono da thread.

threads[].vendor_iduuid

Seller da conversa. Ausente em thread da loja.

threads[].vendor_namestring

Nome do seller. Ausente em thread da loja.

threads[].customer_namestring

Nome do cliente para exibição.

threads[].last_message_previewstring

Início da última mensagem (até 100 caracteres). Para mensagem só com anexo, [attachment].

threads[].last_message_atstring

Data da última mensagem (RFC 3339).

threads[].unread_countinteger

Mensagens não lidas escritas pela outra parte.

threads[].created_atstring

Criação (RFC 3339).

threads[].updated_atstring

Última alteração (RFC 3339).

totalinteger

Total de threads do cliente.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	Token de chave de API sem o escopo `customer:read`.	`{"error":"missing_scope","required":"customer:read"}`
500	Falha ao consultar.	`{"error":"failed to list threads","detail":"..."}`

GET/api/v1/storefront/messages/threads/findCliente

Achar a thread de um seller e objeto

Procura a thread mais recente do cliente que combine com os três filtros. Cada filtro vazio significa "sem seller" ou "sem objeto", e não "qualquer um".

Parâmetros de consulta

vendor_iduuid

Seller da conversa. Vazio procura a thread da loja (sem seller).

object_typestring

Tipo do objeto ligado. Vazio procura threads sem objeto.

object_iduuid

Id do objeto ligado. Vazio procura threads sem objeto.

bash

curl "$BASE_URL/api/v1/storefront/messages/threads/find?vendor_id=$VENDOR_ID&object_type=order&object_id=$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN"

200Thread encontrada

json

{
  "id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
  "subject": "Dúvida sobre o pedido PEDIDO-20261010-0004",
  "status": "A",
  "object_type": "order",
  "object_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "object_name": "PEDIDO-20261010-0004",
  "customer_user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Casa do Café",
  "customer_name": "Maria Souza",
  "last_message_preview": "Seu pedido sai amanhã.",
  "last_message_at": "2026-10-11T18:30:00Z",
  "unread_count": 0,
  "created_at": "2026-10-11T17:00:00Z",
  "updated_at": "2026-10-11T18:30:00Z",
  "messages": [
    {
      "id": "5d0a0f4e-2c3b-4b8a-8a6d-0d9d2b1c7e10",
      "thread_id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
      "sender_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "sender_type": "customer",
      "body": "Quando meu pedido sai?",
      "attachments": [],
      "is_read": true,
      "created_at": "2026-10-11T17:00:00Z"
    }
  ]
}

A resposta é a mesma de Ler a thread, com o campo unread_count sempre 0 (ele só é calculado na lista).

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`
404	Nenhuma thread combina com os filtros.	`{"error":"thread not found"}`
500	Falha ao consultar.	`{"error":"failed to find thread","detail":"..."}`

GET/api/v1/storefront/messages/unread-countCliente

Contar mensagens não lidas

bash

curl "$BASE_URL/api/v1/storefront/messages/unread-count" \
  -H "Authorization: Bearer $TOKEN"

200Contagem

json

{ "count": 3 }

Campos da resposta

countinteger

Mensagens não lidas de todas as threads do cliente, escritas por seller ou administrador.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`