VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Dashboards do seller

Alertas e agendamentos

Cria alertas que avisam quando um número cruza um limite e envios periódicos de um dashboard ou card por e-mail.

Uma assinatura liga um card (ou uma aba) a um e-mail. Há dois modos. No alerta (mode: A) a plataforma mede o card de tempos em tempos e avisa quando o valor viola uma regra, por exemplo "receita do mês abaixo de R$ 10.000". No agendamento (mode: S) ela envia o card ou a aba por e-mail na frequência escolhida. A verificação roda de hora em hora. As mensagens de erro desta rota vêm em português, como o servidor as devolve.

Listar assinaturas

GET/api/v1/vendor/dashboards/subscriptionsSeller

Listar assinaturas

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

dashboard_iduuid
Só as assinaturas desta aba.
card_iduuid
Só as assinaturas deste card.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/dashboards/subscriptions" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Assinaturas
json
{
  "subscriptions": [
    {
      "id": "a7c1e4d2-52f7-4bd0-9e0a-6c3f1b2a8d90",
      "dashboard_id": null,
      "card_id": "94c6b3ff-de9c-4552-8a12-e199e8427f57",
      "mode": "A",
      "schedule": "hourly",
      "name": "Receita do mês abaixo da meta",
      "alert_rule": {
        "op": "lt",
        "value": 1000000,
        "window": "thisMonth",
        "cooldown_minutes": 1440,
        "channels": [
          "email"
        ]
      },
      "recipients": [
        "financeiro@example.com"
      ],
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "is_active": true,
      "alert_state": "N",
      "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
      "created_at": "2026-10-11T22:00:00Z"
    }
  ]
}

Campos da resposta

subscriptionsobject[]

As assinaturas do seller.

iduuid
Id da assinatura (UUID).
dashboard_iduuid
Aba, quando a assinatura é da aba inteira.
card_iduuid
Card, quando é de um card.
modestring
AS
A alerta ou S agendamento.
schedulestring
hourlydailyweeklymonthly
Frequência de verificação ou envio.
namestring
Nome.
alert_ruleobject
A regra do alerta (modo A).
recipientsstring[]
E-mails de destino.
vendor_iduuid
Seller dono, sempre o do token.
is_activeboolean
Se está ligada.
last_sent_atstring
Último envio. Ausente se nunca enviou.
last_valuenumber
Último valor medido pelo alerta.
alert_statestring
NF
N normal (limiar não violado) ou F disparado (violado).
created_byuuid
Quem criou.
created_atstring
Criação, RFC 3339 em UTC.

Erros

StatusQuandoCorpo de exemplo
404Filtro por aba ou card que o seller não vê.{"error":"dashboard não encontrado"}
503O recurso não está configurado neste ambiente.{"error":"assinaturas de dashboard não estão configuradas neste ambiente"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}

Criar alerta ou agendamento

POST/api/v1/vendor/dashboards/subscriptionsSeller

Criar alerta ou agendamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

modestringobrigatório
AS
A alerta ou S agendamento.
card_iduuid
Card alvo. Obrigatório em alertas.
dashboard_iduuid
Aba alvo (agendamentos). Informe card_id ou dashboard_id.
schedulestring
hourlydailyweeklymonthly
Frequência. Omitida, vale hourly no alerta e daily no agendamento.
namestring
Nome. Passa de 160 caracteres, é cortado.
alert_ruleobject

Regra do alerta (só modo A).

alert_rule.opstringobrigatório
ltltegtgteeqne
Comparação do valor medido com value.
alert_rule.valuenumberobrigatório
Limiar, na unidade da coluna: dinheiro em centavos, percentuais em pontos-base.
alert_rule.metricstring
id da métrica a medir. Omitido: a primeira métrica do card.
alert_rule.windowstring
Período da medição (por exemplo today, last7, thisMonth). Omitido: o período do card ou last30.
alert_rule.cooldown_minutesinteger
Minutos sem repetir o aviso enquanto o limiar continua violado. Omitido: 60.
alert_rule.channelsstring[]
inapp e/ou email. Omitido: os dois.
recipientsstring[]
E-mails de destino, até 20. Obrigatório com pelo menos um no agendamento. Um endereço precisa ter @ e não ter espaços, vírgulas ou ponto e vírgula.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/dashboards/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "A", "card_id": "94c6b3ff-de9c-4552-8a12-e199e8427f57", "name": "Receita do mês abaixo da meta", "schedule": "hourly", "alert_rule": {"op": "lt", "value": 1000000, "window": "thisMonth", "cooldown_minutes": 1440, "channels": ["email"]}, "recipients": ["financeiro@example.com"]}'

Resposta

201Assinatura criada
json
{
  "id": "a7c1e4d2-52f7-4bd0-9e0a-6c3f1b2a8d90",
  "dashboard_id": null,
  "card_id": "94c6b3ff-de9c-4552-8a12-e199e8427f57",
  "mode": "A",
  "schedule": "hourly",
  "name": "Receita do mês abaixo da meta",
  "alert_rule": {
    "op": "lt",
    "value": 1000000,
    "window": "thisMonth",
    "cooldown_minutes": 1440,
    "channels": [
      "email"
    ]
  },
  "recipients": [
    "financeiro@example.com"
  ],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "is_active": true,
  "alert_state": "N",
  "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "created_at": "2026-10-11T22:00:00Z"
}

Campos da resposta

(campos / fields)object
Os mesmos da listagem.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"corpo da requisição inválido"}
400Nem card_id nem dashboard_id.{"error":"informe um dashboard ou um card"}
404Card ou aba que o seller não vê.{"error":"card não encontrado"}
422Falha de validação. O texto do erro vem em error: mode inválido: use 'A' (alerta) ou 'S' (agendamento), um alerta é sempre de um card, frequência inválida: ..., operador inválido: ..., cooldown não pode ser negativo, máximo de 20 destinatários por assinatura, e-mail inválido: ..., informe ao menos um destinatário.{"error":"operador inválido: foo"}
503O recurso não está configurado neste ambiente.{"error":"assinaturas de dashboard não estão configuradas neste ambiente"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}
Um aviso por violação

Enquanto o valor continua ruim, o alerta avisa uma vez (alert_state vira F) e só volta a avisar depois de normalizar ou do cooldown_minutes. Com o valor normal, alert_state volta a N.

Ligar ou desligar assinatura

Apesar do PUT, a única coisa que esta rota altera é o estado ligado/desligado. Para mudar a regra, apague e crie outra.

PUT/api/v1/vendor/dashboards/subscriptions/{id}Seller

Ligar ou desligar assinatura

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id da assinatura (UUID).

Corpo da requisição

is_activebooleanobrigatório
true liga, false desliga. Obrigatório.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/dashboards/subscriptions/a7c1e4d2-52f7-4bd0-9e0a-6c3f1b2a8d90" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Resposta

200Atualizada
json
{
  "id": "a7c1e4d2-52f7-4bd0-9e0a-6c3f1b2a8d90",
  "dashboard_id": null,
  "card_id": "94c6b3ff-de9c-4552-8a12-e199e8427f57",
  "mode": "A",
  "schedule": "hourly",
  "name": "Receita do mês abaixo da meta",
  "alert_rule": {
    "op": "lt",
    "value": 1000000,
    "window": "thisMonth",
    "cooldown_minutes": 1440,
    "channels": [
      "email"
    ]
  },
  "recipients": [
    "financeiro@example.com"
  ],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "is_active": false,
  "alert_state": "N",
  "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "created_at": "2026-10-11T22:00:00Z"
}

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON, ou is_active ausente.{"error":"informe is_active"}
404Assinatura inexistente ou de outro seller, ou o card/aba alvo não está visível.{"error":"assinatura não encontrada"}
503O recurso não está configurado neste ambiente.{"error":"assinaturas de dashboard não estão configuradas neste ambiente"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}

Apagar assinatura

DELETE/api/v1/vendor/dashboards/subscriptions/{id}Seller

Apagar assinatura

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id da assinatura (UUID).

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/dashboards/subscriptions/a7c1e4d2-52f7-4bd0-9e0a-6c3f1b2a8d90" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida
json
{
  "message": "assinatura removida"
}

Erros

StatusQuandoCorpo de exemplo
404Assinatura inexistente ou de outro seller, ou o card/aba alvo não está visível.{"error":"assinatura não encontrada"}
503O recurso não está configurado neste ambiente.{"error":"assinaturas de dashboard não estão configuradas neste ambiente"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}

Veja também

  • Execuções de alerta
  • Cards
Anterior
Card por pedido em texto
Próxima
Execuções de alerta
Nesta página
  • Listar assinaturas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar alerta ou agendamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ligar ou desligar assinatura
  • Exemplo de requisição
  • Resposta
  • Erros
  • Apagar assinatura
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também