API atual/Referência completa/Venddor Intelligence: insights e dicas

Briefing diário (Dicas do Dia)

Lista e lê as edições do briefing diário e controla o que cada administrador já leu.

O briefing diário é uma mensagem por dia que resume o que importa na loja, com fatos, 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". A cada data civil existe no máximo uma edição para os administradores. O estado de leitura é por usuário: ler não afeta os outros.

Listar

Devolve as edições, 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 que falharam.

GET/api/v1/admin/intelligence/venddor-pulseAdmin

Listar o briefing diário

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (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/admin/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": "admin",
      "day_type": "weekend",
      "day_type_label": "Mensagem de Fim de Semana",
      "topics_covered": ["revenue_month_progress", "products_stock_critical"],
      "greeting": "**Oi! Só uma passadinha rápida no fim de semana**",
      "formatted_message": "Oi! A Camisa do Flamengo foi o carro-chefe da semana, com 2 unidades vendidas...",
      "supporting_facts": ["Receita dos últimos 7 dias: R$ 585,87."],
      "news_refs": [{ "title": "Flamengo garrafa com menor preço", "url": "https://exemplo.com.br/noticia" }],
      "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.

iduuid

Id da edição.

analysis_datestring

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

audiencestring

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

day_typestring

month_startmonth_endmon_plantue_market_intelmidweek_followupthu_hidden_opportunitiesfri_wrapweekend

Tipo editorial do dia.

day_type_labelstring

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

topics_coveredarray

Assuntos tratados na edição.

mentioned_product_idsarray

Ids de produtos citados. Pode faltar.

mentioned_category_idsarray

Ids de categorias citadas. Pode faltar.

greetingstring

Saudação, em Markdown.

formatted_messagestring

Mensagem completa, em Markdown.

supporting_factsarray

Fatos e números usados na mensagem.

assumptionsarray

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

decision_rationalearray

Justificativa das sugestões. Pode faltar.

news_refsarray

Notícias citadas: title e url.

suggested_promotionobject

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

bannersarray

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

generation_statusstring

pendingcollectinggeneratingcompletedfailed

Estado da geração.

error_messagestring

Motivo, quando failed.

is_backfillboolean

true para edições geradas retroativamente.

created_atstring

RFC 3339.

is_readboolean

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

totalinteger

Quantidade devolvida.

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 administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`

Contar não lidas

Conta quantas edições o usuário do token ainda não leu (para o selo do sino).

GET/api/v1/admin/intelligence/venddor-pulse/unread-countAdmin

Contar não lidas

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/venddor-pulse/unread-count" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Contagem

json

{ "count": 81 }

Campos da resposta

countinteger

Edições não lidas pelo usuário do token.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`

Ler uma edição

Devolve uma edição. Não marca como lida: use Marcar como lida.

GET/api/v1/admin/intelligence/venddor-pulse/{id}Admin

Ler uma edição

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

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

Resposta

200Edição

json

{
  "id": "5f68c2d5-ee3d-439c-a0f9-1b7737878ce4",
  "analysis_date": "2026-10-11",
  "audience": "admin",
  "day_type": "weekend",
  "day_type_label": "Mensagem de Fim de Semana",
  "topics_covered": ["revenue_month_progress", "products_stock_critical"],
  "greeting": "**Oi! Só uma passadinha rápida no fim de semana**",
  "formatted_message": "Oi! A Camisa do Flamengo foi o carro-chefe da semana, com 2 unidades vendidas...",
  "supporting_facts": ["Receita dos últimos 7 dias: R$ 585,87."],
  "news_refs": [{ "title": "Flamengo garrafa com menor preço", "url": "https://exemplo.com.br/noticia" }],
  "generation_status": "completed",
  "is_backfill": false,
  "created_at": "2026-10-11T07:00:12Z",
  "is_read": false
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`
404	Edição inexistente.	`{"error":"venddor pulse: insight 00000000-0000-0000-0000-000000000000 not found"}`

Marcar como lida

Marca a edição como lida para o usuário do token.

POST/api/v1/admin/intelligence/venddor-pulse/{id}/readAdmin

Marcar como lida

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/venddor-pulse/$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 administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`
403	A edição é de um vendedor, não de administradores.	`{"error":"not an admin briefing"}`
404	Edição inexistente.	`{"error":"insight not found"}`

Marcar como não lida

Desfaz a leitura para o usuário do token.

DELETE/api/v1/admin/intelligence/venddor-pulse/{id}/readAdmin

Marcar como não lida

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/intelligence/venddor-pulse/$PULSE_ID/read" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desmarcada

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 administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`
403	A edição é de um vendedor.	`{"error":"not an admin briefing"}`
404	Edição inexistente.	`{"error":"insight not found"}`

Veja também

API atual/Referência completa/Venddor Intelligence: insights e dicas

Briefing diário (Dicas do Dia)

Lista e lê as edições do briefing diário e controla o que cada administrador já leu.

Listar

Devolve as edições, 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 que falharam.

GET/api/v1/admin/intelligence/venddor-pulseAdmin

Listar o briefing diário

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (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/admin/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": "admin",
      "day_type": "weekend",
      "day_type_label": "Mensagem de Fim de Semana",
      "topics_covered": ["revenue_month_progress", "products_stock_critical"],
      "greeting": "**Oi! Só uma passadinha rápida no fim de semana**",
      "formatted_message": "Oi! A Camisa do Flamengo foi o carro-chefe da semana, com 2 unidades vendidas...",
      "supporting_facts": ["Receita dos últimos 7 dias: R$ 585,87."],
      "news_refs": [{ "title": "Flamengo garrafa com menor preço", "url": "https://exemplo.com.br/noticia" }],
      "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.

iduuid

Id da edição.

analysis_datestring

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

audiencestring

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

day_typestring

month_startmonth_endmon_plantue_market_intelmidweek_followupthu_hidden_opportunitiesfri_wrapweekend

Tipo editorial do dia.

day_type_labelstring

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

topics_coveredarray

Assuntos tratados na edição.

mentioned_product_idsarray

Ids de produtos citados. Pode faltar.

mentioned_category_idsarray

Ids de categorias citadas. Pode faltar.

greetingstring

Saudação, em Markdown.

formatted_messagestring

Mensagem completa, em Markdown.

supporting_factsarray

Fatos e números usados na mensagem.

assumptionsarray

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

decision_rationalearray

Justificativa das sugestões. Pode faltar.

news_refsarray

Notícias citadas: title e url.

suggested_promotionobject

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

bannersarray

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

generation_statusstring

pendingcollectinggeneratingcompletedfailed

Estado da geração.

error_messagestring

Motivo, quando failed.

is_backfillboolean

true para edições geradas retroativamente.

created_atstring

RFC 3339.

is_readboolean

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

totalinteger

Quantidade devolvida.

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 administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`

Contar não lidas

Conta quantas edições o usuário do token ainda não leu (para o selo do sino).

GET/api/v1/admin/intelligence/venddor-pulse/unread-countAdmin

Contar não lidas

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/venddor-pulse/unread-count" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Contagem

json

{ "count": 81 }

Campos da resposta

countinteger

Edições não lidas pelo usuário do token.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`

Ler uma edição

Devolve uma edição. Não marca como lida: use Marcar como lida.

GET/api/v1/admin/intelligence/venddor-pulse/{id}Admin

Ler uma edição

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

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

Resposta

200Edição

json

{
  "id": "5f68c2d5-ee3d-439c-a0f9-1b7737878ce4",
  "analysis_date": "2026-10-11",
  "audience": "admin",
  "day_type": "weekend",
  "day_type_label": "Mensagem de Fim de Semana",
  "topics_covered": ["revenue_month_progress", "products_stock_critical"],
  "greeting": "**Oi! Só uma passadinha rápida no fim de semana**",
  "formatted_message": "Oi! A Camisa do Flamengo foi o carro-chefe da semana, com 2 unidades vendidas...",
  "supporting_facts": ["Receita dos últimos 7 dias: R$ 585,87."],
  "news_refs": [{ "title": "Flamengo garrafa com menor preço", "url": "https://exemplo.com.br/noticia" }],
  "generation_status": "completed",
  "is_backfill": false,
  "created_at": "2026-10-11T07:00:12Z",
  "is_read": false
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`
404	Edição inexistente.	`{"error":"venddor pulse: insight 00000000-0000-0000-0000-000000000000 not found"}`

Marcar como lida

Marca a edição como lida para o usuário do token.

POST/api/v1/admin/intelligence/venddor-pulse/{id}/readAdmin

Marcar como lida

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/venddor-pulse/$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 administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`
403	A edição é de um vendedor, não de administradores.	`{"error":"not an admin briefing"}`
404	Edição inexistente.	`{"error":"insight not found"}`

Marcar como não lida

Desfaz a leitura para o usuário do token.

DELETE/api/v1/admin/intelligence/venddor-pulse/{id}/readAdmin

Marcar como não lida

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da edição.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/intelligence/venddor-pulse/$PULSE_ID/read" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desmarcada

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 administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["view_reports","manage_settings"]}`
403	A edição é de um vendedor.	`{"error":"not an admin briefing"}`
404	Edição inexistente.	`{"error":"insight not found"}`