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

Alertas e assinaturas

Cria alertas por limiar num card e envios agendados por e-mail de uma aba ou card, e liga, desliga, lista e apaga cada um.

Há dois tipos de assinatura. O alerta (mode: A) vigia o valor de um card e avisa quando ele cruza um limiar, por exemplo "receita abaixo de R$ 1.000". O agendamento (mode: S) envia por e-mail, de tempos em tempos, os dados de uma aba ou de um card. Listar exige apenas view_reports; criar, alterar, apagar exigem manage_dashboards, porque a assinatura envia e-mail em nome da loja. Para disparar uma assinatura agora e ver o histórico, veja Execuções.

Listar

GET/api/v1/admin/dashboards/subscriptionsAdmin

Listar assinaturas

Parâmetros de consulta

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

Exemplo de requisição (listar)

bash
curl "$BASE_URL/api/v1/admin/dashboards/subscriptions?dashboard_id=8da0f9c1-b05b-4809-b07d-0b36573489e7" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Assinaturas
json
{
  "subscriptions": [{
    "id": "a7ad8ff8-a167-4922-a503-9e0a2d13aa68",
    "card_id": "dd3470e6-dc16-4b41-9393-23797b50d7ba",
    "mode": "A",
    "schedule": "hourly",
    "name": "Receita baixa",
    "alert_rule": { "metric": "receita", "op": "lt", "value": 100000, "cooldown_minutes": 120, "channels": ["email"] },
    "recipients": ["gestor@example.com"],
    "is_active": true,
    "alert_state": "N",
    "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
    "created_at": "2026-10-11T21:10:56.156954Z"
  }]
}

Campos da resposta

subscriptionsarray
Assinaturas do painel do administrador, da mais nova para a mais antiga. [] se não houver.
subscriptions[].iduuid
Id da assinatura.
subscriptions[].dashboard_iduuid
Aba alvo (modo agendamento). Ausente se o alvo é um card.
subscriptions[].card_iduuid
Card alvo. Obrigatório no alerta.
subscriptions[].modestring
AS
A alerta, S agendamento.
subscriptions[].schedulestring
hourlydailyweeklymonthly
Frequência de verificação ou envio.
subscriptions[].namestring
Nome (até 160 caracteres).
subscriptions[].alert_ruleobject
Regra do alerta. Em agendamento vem {"op":"","value":0} vazio.
subscriptions[].recipientsarray
E-mails destinatários.
subscriptions[].vendor_iduuid
Preenchido apenas em assinaturas do painel do seller.
subscriptions[].is_activeboolean
Se está ligada.
subscriptions[].last_sent_atstring
Último envio, RFC 3339.
subscriptions[].last_valuenumber
Último valor medido (alertas).
subscriptions[].alert_statestring
NF
N normal ou F disparado (o limiar continua violado).
subscriptions[].created_byuuid
Quem criou.
subscriptions[].created_atstring
Criação, RFC 3339.

Erros (listar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
404A aba ou o card alvo não existe ou não é visível para você. A mensagem vem em português (card não encontrado quando o card_id não existe).{"error":"dashboard não encontrado"} ou {"error":"card não encontrado"}
503O recurso de assinaturas não está configurado neste ambiente.{"error":"assinaturas de dashboard não estão configuradas neste ambiente"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Criar

POST/api/v1/admin/dashboards/subscriptionsAdmin

Criar um alerta ou agendamento

Corpo da requisição

modestringobrigatório
AS
A alerta ou S agendamento.
dashboard_iduuid
Aba alvo. Informe dashboard_id ou card_id.
card_iduuid
Card alvo. Obrigatório no alerta.
schedulestring
hourlydailyweeklymonthly
Frequência. Padrão: hourly no alerta, daily no agendamento.
namestring
Nome, até 160 caracteres (o excesso é cortado).
alert_ruleobject

Regra do alerta. Obrigatória no modo A.

opstringobrigatório
ltltegtgteeqne
Comparação do valor medido com value.
valuenumberobrigatório
Limiar, na mesma unidade da coluna: dinheiro em centavos, percentuais em pontos-base.
metricstring
id da métrica a comparar. Vazio usa a primeira métrica do card.
windowstring
Período usado ao medir (today, last7, last30, thisMonth...). Vazio usa o período do card, ou last30.
cooldown_minutesinteger
Minutos sem repetir o aviso enquanto o limiar segue violado. 0 ou omitido vale 60.
channelsarray
inapp e/ou email. Vazio usa os dois.
recipientsarray
E-mails, até 20, sem espaços nem vírgulas. Obrigatório no modo S.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "dd3470e6-dc16-4b41-9393-23797b50d7ba", "mode": "A", "name": "Receita baixa", "alert_rule": {"metric": "receita", "op": "lt", "value": 100000, "cooldown_minutes": 120, "channels": ["email"]}, "recipients": ["gestor@example.com"]}'

Resposta (criar)

201Assinatura criada
json
{
  "id": "a7ad8ff8-a167-4922-a503-9e0a2d13aa68",
  "card_id": "dd3470e6-dc16-4b41-9393-23797b50d7ba",
  "mode": "A",
  "schedule": "hourly",
  "name": "Receita baixa",
  "alert_rule": { "metric": "receita", "op": "lt", "value": 100000, "cooldown_minutes": 120, "channels": ["email"] },
  "recipients": ["gestor@example.com"],
  "is_active": true,
  "alert_state": "N",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:10:56.156954Z"
}

Campos da resposta

(objeto)object
A assinatura criada, com os campos de Listar.

Erros (criar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"corpo da requisição inválido","detail":"json: unknown field \"foo\""}
404A aba ou o card alvo não existe ou não é visível para você. A mensagem vem em português (card não encontrado quando o card_id não existe).{"error":"dashboard não encontrado"} ou {"error":"card não encontrado"}
400Nem dashboard_id nem card_id.{"error":"informe um dashboard ou um card"}
422Modo, frequência, operador ou e-mail inválido; alerta sem card_id; agendamento sem destinatário; mais de 20 destinatários. A mensagem vem em português.{"error":"informe ao menos um destinatário"}
503O recurso de assinaturas não está configurado neste ambiente.{"error":"assinaturas de dashboard não estão configuradas neste ambiente"}

Ligar ou desligar

PUT/api/v1/admin/dashboards/subscriptions/{id}Admin

Ligar ou desligar uma assinatura

Parâmetros de caminho

iduuidobrigatório
Id da assinatura.

Corpo da requisição

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

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/admin/dashboards/subscriptions/f9f99133-ba51-49df-8f85-30ae9fd90eac" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Resposta (alterar)

200Assinatura alterada
json
{
  "id": "a7ad8ff8-a167-4922-a503-9e0a2d13aa68",
  "card_id": "dd3470e6-dc16-4b41-9393-23797b50d7ba",
  "mode": "A",
  "schedule": "hourly",
  "name": "Receita baixa",
  "alert_rule": { "metric": "receita", "op": "lt", "value": 100000, "cooldown_minutes": 120, "channels": ["email"] },
  "recipients": ["gestor@example.com"],
  "is_active": false,
  "alert_state": "N",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:10:56.156954Z"
}

Campos da resposta

(objeto)object
A assinatura, com os campos de Listar.

Erros (alterar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"corpo da requisição inválido","detail":"json: unknown field \"foo\""}
400Falta is_active.{"error":"informe is_active"}
404A assinatura não existe ou o alvo dela não é visível para você.{"error":"assinatura não encontrada"}
503O recurso de assinaturas não está configurado neste ambiente.{"error":"assinaturas de dashboard não estão configuradas neste ambiente"}

Apagar

DELETE/api/v1/admin/dashboards/subscriptions/{id}Admin

Apagar uma assinatura

Parâmetros de caminho

iduuidobrigatório
Id da assinatura.

Exemplo de requisição (apagar)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/dashboards/subscriptions/f9f99133-ba51-49df-8f85-30ae9fd90eac" \
  -H "Authorization: Bearer $TOKEN"

Resposta (apagar)

200Assinatura apagada
json
{
  "message": "assinatura removida"
}

Campos da resposta

messagestring
Confirmação em português do servidor. O histórico de execuções também é apagado.

Erros (apagar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
404A assinatura não existe ou o alvo dela não é visível para você.{"error":"assinatura não encontrada"}
503O recurso de assinaturas não está configurado neste ambiente.{"error":"assinaturas de dashboard não estão configuradas neste ambiente"}
PUT só liga e desliga

Não existe edição de uma assinatura: o PUT aceita apenas is_active. Para mudar limiar, frequência ou destinatários, apague e crie de novo.

Alerta dispara uma vez

O alerta guarda um estado: ao cruzar o limiar passa de N para F e avisa uma vez; só volta a avisar quando o valor se normalizar e cruzar de novo, ou depois do cooldown_minutes se o valor oscilar em torno do limiar. O agendamento envia o CSV dos dados (até 500 linhas) por e-mail.

Veja também

  • Execuções
  • Cards
  • Abas
Anterior
Classificação de status
Próxima
Assinaturas: executar e histórico
Nesta página
  • Listar
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Criar
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Ligar ou desligar
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Apagar
  • Exemplo de requisição (apagar)
  • Resposta (apagar)
  • Erros (apagar)
  • Veja também