API atual/Referência completa/Venddor Intelligence

Briefing diário do seller

Lista e lê as edições do briefing diário (Dicas do Dia) do seu seller e marca o que o usuário já leu.

O briefing diário é uma mensagem por dia que resume o que importa no seu seller: vendas, estoque crítico, notícias do segmento e, às vezes, uma promoção sugerida e banners. Nas rotas ele se chama venddor-pulse; no painel, "Dicas do Dia". Cada seller recebe no máximo uma edição por data civil, e só enxerga as próprias edições. O estado de leitura é por usuário: ler não afeta os outros usuários do seller. O seller só lê: gerar edições novas é uma ação do administrador da loja.

Listar

Devolve as edições do seu seller, da data mais recente para a mais antiga, com is_read calculado para o usuário do token. A lista inclui edições em andamento e as que falharam.

GET/api/v1/vendor/intelligence/venddor-pulseSeller

Listar o briefing diário

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de consulta

limitintegerpadrão: 20

Quantidade. Padrão 20, teto 60.

offsetintegerpadrão: 0

Itens a pular.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/venddor-pulse?limit=7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Edições

json

{
  "display_title": "",
  "insights": [
    {
      "id": "5f68c2d5-ee3d-439c-a0f9-1b7737878ce4",
      "analysis_date": "2026-10-11",
      "audience": "vendor",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "day_type": "weekend",
      "day_type_label": "Mensagem de Fim de Semana",
      "topics_covered": [
        "revenue_week",
        "products_stock_critical"
      ],
      "greeting": "**Oi! Uma passadinha rápida no fim de semana**",
      "formatted_message": "Sua loja vendeu 2 unidades da Camisa Azul esta semana. Dois produtos estão com estoque crítico.",
      "supporting_facts": [
        "Receita dos últimos 7 dias: R$ 585,87."
      ],
      "generation_status": "completed",
      "is_backfill": false,
      "created_at": "2026-10-11T07:00:12Z",
      "is_read": false
    }
  ],
  "total": 1
}

Campos da resposta

insightsarray

Edições, com os campos abaixo.

insights[].iduuid

Id da edição.

insights[].analysis_datestring

Data civil AAAA-MM-DD (São Paulo) a que a edição se refere.

insights[].audiencestring

Para quem é a edição. Nestas rotas, sempre vendor.

insights[].vendor_iduuid

Seller dono da edição (o seu).

insights[].day_typestring

month_startmonth_endmon_plantue_market_intelmidweek_followupthu_hidden_opportunitiesfri_wrapweekend

Tipo editorial do dia.

insights[].day_type_labelstring

Nome do tipo do dia, para exibição.

insights[].topics_coveredarray

Assuntos tratados na edição.

insights[].mentioned_product_idsarray

Ids de produtos citados. Pode faltar.

insights[].mentioned_category_idsarray

Ids de categorias citadas. Pode faltar.

insights[].greetingstring

Saudação, em Markdown.

insights[].formatted_messagestring

Mensagem completa, em Markdown.

insights[].supporting_factsarray

Fatos e números usados na mensagem. Pode faltar.

insights[].assumptionsarray

Suposições feitas quando faltou dado. Pode faltar.

insights[].decision_rationalearray

Justificativa das sugestões. Pode faltar.

insights[].news_refsarray

Notícias citadas: title e url. Pode faltar.

insights[].suggested_promotionobject

Promoção sugerida, criada desativada: id, name, discount_label, valid_from, valid_until, status. Pode faltar.

insights[].bannersarray

Banners gerados para a edição: generated_image_id e image_url. Pode faltar.

insights[].generation_statusstring

pendingcollectinggeneratingcompletedfailed

Estado da geração. A lista não devolve edições pending.

insights[].error_messagestring

Motivo, quando failed.

insights[].is_backfillboolean

true para edições geradas retroativamente.

insights[].created_atstring

RFC 3339.

insights[].is_readboolean

Se o usuário do token já leu esta edição.

totalinteger

Quantidade devolvida nesta página (não é o total geral).

display_titlestring

Rótulo personalizado do cartão (até 80 caracteres). Vazio usa o padrão "Dicas do Dia".

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	A conta tem papel de seller mas nenhum seller vinculado.	`{"error":"no vendor scope on this account"}`

Ler uma edição

Devolve uma edição do seu seller. Não marca como lida: use a rota seguinte.

GET/api/v1/vendor/intelligence/venddor-pulse/{id}Seller

Ler uma edição

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/venddor-pulse/$ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Edição

json

{
  "id": "5f68c2d5-ee3d-439c-a0f9-1b7737878ce4",
  "analysis_date": "2026-10-11",
  "audience": "vendor",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "day_type": "weekend",
  "day_type_label": "Mensagem de Fim de Semana",
  "topics_covered": [
    "revenue_week",
    "products_stock_critical"
  ],
  "greeting": "**Oi! Uma passadinha rápida no fim de semana**",
  "formatted_message": "Sua loja vendeu 2 unidades da Camisa Azul esta semana. Dois produtos estão com estoque crítico.",
  "supporting_facts": [
    "Receita dos últimos 7 dias: R$ 585,87."
  ],
  "generation_status": "completed",
  "is_backfill": false,
  "created_at": "2026-10-11T07:00:12Z",
  "is_read": false
}

Os campos são os mesmos de cada item da lista.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	A conta tem papel de seller mas nenhum seller vinculado.	`{"error":"no vendor scope on this account"}`
404	A edição não existe ou não é do seu seller.	`{"error":"insight not found"}` (ou `{"error":"venddor pulse: insight <id> not found"}` para um id que não existe)

Marcar como lida

Marca a edição como lida para o usuário do token. É idempotente: marcar de novo devolve o mesmo 200. Não existe rota para marcar como não lida nem para contar as não lidas; conte pelo is_read da lista.

POST/api/v1/vendor/intelligence/venddor-pulse/{id}/readSeller

Marcar como lida

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/venddor-pulse/$ID/read" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Marcada

json

{
  "ok": true
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	A conta tem papel de seller mas nenhum seller vinculado.	`{"error":"no vendor scope on this account"}`
404	A edição não existe ou não é do seu seller.	`{"error":"insight not found"}` (ou `{"error":"venddor pulse: insight <id> not found"}` para um id que não existe)

Veja também

API atual/Referência completa/Venddor Intelligence

Briefing diário do seller

Lista e lê as edições do briefing diário (Dicas do Dia) do seu seller e marca o que o usuário já leu.

Listar

Devolve as edições do seu seller, da data mais recente para a mais antiga, com is_read calculado para o usuário do token. A lista inclui edições em andamento e as que falharam.

GET/api/v1/vendor/intelligence/venddor-pulseSeller

Listar o briefing diário

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de consulta

limitintegerpadrão: 20

Quantidade. Padrão 20, teto 60.

offsetintegerpadrão: 0

Itens a pular.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/venddor-pulse?limit=7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Edições

json

{
  "display_title": "",
  "insights": [
    {
      "id": "5f68c2d5-ee3d-439c-a0f9-1b7737878ce4",
      "analysis_date": "2026-10-11",
      "audience": "vendor",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "day_type": "weekend",
      "day_type_label": "Mensagem de Fim de Semana",
      "topics_covered": [
        "revenue_week",
        "products_stock_critical"
      ],
      "greeting": "**Oi! Uma passadinha rápida no fim de semana**",
      "formatted_message": "Sua loja vendeu 2 unidades da Camisa Azul esta semana. Dois produtos estão com estoque crítico.",
      "supporting_facts": [
        "Receita dos últimos 7 dias: R$ 585,87."
      ],
      "generation_status": "completed",
      "is_backfill": false,
      "created_at": "2026-10-11T07:00:12Z",
      "is_read": false
    }
  ],
  "total": 1
}

Campos da resposta

insightsarray

Edições, com os campos abaixo.

insights[].iduuid

Id da edição.

insights[].analysis_datestring

Data civil AAAA-MM-DD (São Paulo) a que a edição se refere.

insights[].audiencestring

Para quem é a edição. Nestas rotas, sempre vendor.

insights[].vendor_iduuid

Seller dono da edição (o seu).

insights[].day_typestring

month_startmonth_endmon_plantue_market_intelmidweek_followupthu_hidden_opportunitiesfri_wrapweekend

Tipo editorial do dia.

insights[].day_type_labelstring

Nome do tipo do dia, para exibição.

insights[].topics_coveredarray

Assuntos tratados na edição.

insights[].mentioned_product_idsarray

Ids de produtos citados. Pode faltar.

insights[].mentioned_category_idsarray

Ids de categorias citadas. Pode faltar.

insights[].greetingstring

Saudação, em Markdown.

insights[].formatted_messagestring

Mensagem completa, em Markdown.

insights[].supporting_factsarray

Fatos e números usados na mensagem. Pode faltar.

insights[].assumptionsarray

Suposições feitas quando faltou dado. Pode faltar.

insights[].decision_rationalearray

Justificativa das sugestões. Pode faltar.

insights[].news_refsarray

Notícias citadas: title e url. Pode faltar.

insights[].suggested_promotionobject

Promoção sugerida, criada desativada: id, name, discount_label, valid_from, valid_until, status. Pode faltar.

insights[].bannersarray

Banners gerados para a edição: generated_image_id e image_url. Pode faltar.

insights[].generation_statusstring

pendingcollectinggeneratingcompletedfailed

Estado da geração. A lista não devolve edições pending.

insights[].error_messagestring

Motivo, quando failed.

insights[].is_backfillboolean

true para edições geradas retroativamente.

insights[].created_atstring

RFC 3339.

insights[].is_readboolean

Se o usuário do token já leu esta edição.

totalinteger

Quantidade devolvida nesta página (não é o total geral).

display_titlestring

Rótulo personalizado do cartão (até 80 caracteres). Vazio usa o padrão "Dicas do Dia".

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	A conta tem papel de seller mas nenhum seller vinculado.	`{"error":"no vendor scope on this account"}`

Ler uma edição

Devolve uma edição do seu seller. Não marca como lida: use a rota seguinte.

GET/api/v1/vendor/intelligence/venddor-pulse/{id}Seller

Ler uma edição

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/venddor-pulse/$ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Edição

json

{
  "id": "5f68c2d5-ee3d-439c-a0f9-1b7737878ce4",
  "analysis_date": "2026-10-11",
  "audience": "vendor",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "day_type": "weekend",
  "day_type_label": "Mensagem de Fim de Semana",
  "topics_covered": [
    "revenue_week",
    "products_stock_critical"
  ],
  "greeting": "**Oi! Uma passadinha rápida no fim de semana**",
  "formatted_message": "Sua loja vendeu 2 unidades da Camisa Azul esta semana. Dois produtos estão com estoque crítico.",
  "supporting_facts": [
    "Receita dos últimos 7 dias: R$ 585,87."
  ],
  "generation_status": "completed",
  "is_backfill": false,
  "created_at": "2026-10-11T07:00:12Z",
  "is_read": false
}

Os campos são os mesmos de cada item da lista.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	A conta tem papel de seller mas nenhum seller vinculado.	`{"error":"no vendor scope on this account"}`
404	A edição não existe ou não é do seu seller.	`{"error":"insight not found"}` (ou `{"error":"venddor pulse: insight <id> not found"}` para um id que não existe)

Marcar como lida

POST/api/v1/vendor/intelligence/venddor-pulse/{id}/readSeller

Marcar como lida

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/venddor-pulse/$ID/read" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Marcada

json

{
  "ok": true
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	A conta tem papel de seller mas nenhum seller vinculado.	`{"error":"no vendor scope on this account"}`
404	A edição não existe ou não é do seu seller.	`{"error":"insight not found"}` (ou `{"error":"venddor pulse: insight <id> not found"}` para um id que não existe)