Uso do projeto
Mensagens enviadas hoje e neste mês (dias em UTC) pelo projeto e pela organização dele. Os planos são da organização, e todos os projetos dela contam para os limites diário e mensal: os envios são recusados com 429 quando o uso da organização passa deles. Traz também o plano, a assinatura da organização e o histórico diário do projeto nos últimos days dias (padrão 30, no máximo 366). Escopo necessário: usage:read.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador do projeto (tenantId), um UUID. Precisa ser um projeto que a chave alcança.
Parâmetros de consulta
daysstringQuantos dias de histórico trazer em dailyUsage, no máximo 366: um valor maior vira 366, e um valor que não é um número inteiro positivo vira 30.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | O uso do projeto e o da organização: tenantId; plan, o plano da organização (name, displayName, maxMessagesDay e maxMessagesMonth, em que -1 é ilimitado; null: sem limites); usage, as mensagens enviadas pelo próprio projeto (today, thisMonth) e quanto elas representam dos limites da organização (percentOfDailyLimit, percentOfMonthlyLimit, em porcentagem); organization, com id e o mesmo usage somando todos os projetos da organização, que é sobre o que os limites valem; subscription, a assinatura da organização (status: trialing, active, past_due, unpaid, incomplete, paused, canceled, expired ou suspended; trialEndsAt e currentPeriodEnd em ISO 8601, ou null); e dailyUsage, o histórico do projeto (date no formato AAAA-MM-DD em UTC, messagesSent, messagesRecv). |
| 400 | FST_ERR_VALIDATIONO id do projeto não é um UUID; message diz o que está errado. |
| 401 | Sem chave de API, ou com uma chave inválida: desconhecida, revogada, expirada ou de um projeto desativado. O corpo é {"error": "Unauthorized"}. |
| 403 | A chave não tem o escopo usage:read; a mensagem cita o escopo (This credential lacks the usage:read scope). |
| 404 | O projeto não existe ou a chave não o alcança ({"error": "Tenant not found"}): o projeto de outra pessoa responde exatamente como um que não existe. |
| 429 | Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After |
Detalhes
As contas de usage e de organization.usage usam só as mensagens enviadas: uma mensagem conta quando a fila do número a entrega ao WhatsApp, não quando o POST /connections/{id}/send a aceita. As recebidas aparecem só no histórico (dailyUsage[].messagesRecv).
As cotas valem sobre organization.usage, não sobre o uso do projeto. Por padrão, o gateway avisa a partir de 80% da cota (cabeçalho X-Usage-Warning no envio) e recusa a partir de 110% (uma folga de 10% para envios simultâneos), e no envio as mensagens aceitas e ainda na fila também contam. Veja Limites de envio.
As porcentagens não são arredondadas e podem passar de 100. Com plan igual a null, ou com um limite -1 (ilimitado), a porcentagem correspondente vem 0.
dailyUsage traz só os dias em que o projeto enviou ou recebeu alguma mensagem, do mais antigo ao mais recente, desde days dias atrás até hoje. Para uma série com os dias zerados, use Uso diário.
Guia: Uso e registros