> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salvy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Consumo de dados: maiores e menores
> Descubra quais linhas mais e menos consomem dados em relação à franquia do plano, para ajustar planos e pacotes.
Sem acompanhamento, é difícil saber se os planos contratados combinam com o uso real. Algumas linhas estouram a franquia todo mês e outras mal usam os dados pelos quais a empresa paga.
Nesta receita, sua integração lista as linhas ativas, consulta o saldo de dados atualizado de cada uma e monta duas listas: as linhas que mais consumiram da franquia e as que menos consumiram. Tudo é somente leitura: nenhuma linha é alterada.
**Para quem é:** times de TI, compras ou gestão de telecom que revisam planos periodicamente e querem uma lista pronta toda semana em vez de conferir linha a linha no painel.
## O que você precisa
* Uma **chave de API de empresa** ou de **organização**. Como a receita só faz leituras, a chave de organização também serve e traz as linhas de todas as empresas da organização de uma vez. Veja [Chaves de API](/api-reference/v3/api-keys).
| Etapa | Endpoint |
| - | - |
| 1. Listar as linhas ativas | [`GET /api/v3/phone-accounts`](/api-reference/v3/phone-accounts/list) |
| 2. Consultar o saldo de cada linha | [`GET /api/v3/phone-accounts/{id}/balance`](/api-reference/v3/phone-accounts/balance) |
| 3. Calcular o consumo e montar o ranking | Na sua integração |
## Passo a passo
Filtre as linhas pelo status `active`. Cada linha já vem com o plano, incluindo a franquia de dados em `plan.availableDataAmountGB`, o colaborador e o centro de custo.
```bash theme={null}
curl -G "https://api.salvy.com.br/api/v3/phone-accounts" \
-H "Authorization: Bearer $SALVY_API_KEY" \
--data-urlencode "status=active" \
--data-urlencode "pageSize=200"
```
```json theme={null}
{
"data": [
{
"id": "0198c2f1-3815-45b7-9e60-8e137cad845c",
"phoneNumber": "+5541999887766",
"name": "Maria - Vendas",
"employee": { "id": "0197aa3e-3815-45b7-9e60-8e137cad845c", "fullName": "Maria de Souza" },
"costCenter": { "id": "0198c2f1-3815-45b7-9e60-8e137cad845d", "name": "Comercial" },
"plan": { "id": "0198c2f1-3815-45b7-9e60-8e137cad845e", "name": "Plano 20GB", "availableDataAmountGB": 20 }
}
],
"pagination": { "page": 1, "pageSize": 200, "totalCount": 1, "totalPages": 1 }
}
```
Se `pagination.totalPages` for maior que 1, busque as páginas seguintes com o parâmetro `page`. Descarte as linhas cujo plano não tem franquia de dados (`availableDataAmountGB` igual a 0, como planos só de WhatsApp): não dá para medir consumo contra uma franquia que não existe.
Para cada linha com franquia, consulte o saldo de dados.
```bash theme={null}
curl "https://api.salvy.com.br/api/v3/phone-accounts/0198c2f1-3815-45b7-9e60-8e137cad845c/balance" \
-H "Authorization: Bearer $SALVY_API_KEY"
```
```json theme={null}
{ "dataBalanceGB": 4.5, "dataBalanceUpdatedAt": "2026-09-30T11:00:00Z" }
```
Quando a última medição já está antiga, a Salvy mede o saldo de novo antes de responder. Por isso esta chamada pode demorar mais que ler o campo `dataBalanceGB` da listagem, que traz a última medição disponível. Faça as consultas em lotes pequenos, e não todas de uma vez.
Se a consulta falhar para uma linha, por exemplo com `422` porque ela deixou de estar ativa, deixe essa linha fora do ranking. O mesmo vale para `dataBalanceGB` nulo, que indica que a linha não tem dado mensurável. Não estime um saldo.
O consumo de cada linha é a franquia do plano menos o saldo atual, nunca abaixo de zero:
```
usadoGB = max(0, franquiaGB - saldoGB)
usoPct = usadoGB / franquiaGB × 100
```
Ordene pelo percentual de uso, do maior para o menor, e separe as primeiras e as últimas linhas. Se houver menos linhas que o dobro do tamanho das listas, não repita na lista de menor consumo uma linha que já está na de maior consumo.
## Sem código: workflow do n8n
Se você usa o [n8n](https://n8n.io), baixe o workflow pronto. Ele tem dois gatilhos: um manual, para testar, e uma agenda semanal, que roda toda segunda-feira às 8h.
`data-usage-ranking.json`: importe no n8n e siga as notas dentro do workflow.
1. No n8n, crie um workflow e importe o arquivo (menu **⋯ > Import from File**, ou cole o conteúdo do arquivo no editor).
2. Crie uma credencial **Bearer Auth** com a sua chave de API e selecione-a nos dois nós HTTP.
3. Execute o workflow. Ele gera um resumo para o gestor e um CSV com as linhas de maior e de menor consumo. Para mudar o tamanho das listas, ajuste `topN` (padrão 5) no nó **Configuração**.
4. Para receber o ranking toda semana, ative o workflow e conecte depois do nó **Resumo para o gestor** um nó de Slack, Teams ou e-mail.
## Como implementar
* **Gatilho:** uma rotina semanal, por exemplo toda segunda de manhã, com o resultado enviado ao gestor por Slack, Teams ou e-mail.
* **Consultas de saldo em lotes:** a consulta de saldo pode demorar; faça poucas chamadas em paralelo e ignore as linhas cujo saldo não puder ser lido.
* **Somente leitura:** a receita não altera nada na Salvy, então pode ser executada direto com uma chave de produção.
## Cuidados
O consumo é calculado a partir do saldo. Quando uma linha recebe um pacote de dados adicional, o saldo aumenta, e o consumo calculado fica menor do que o real. Uma linha que já precisou de pacote pode aparecer no meio ou até na lista de menor consumo.
Quando a medição está antiga, a Salvy mede o saldo de novo antes de responder. Com centenas de linhas, a execução leva alguns minutos. Mantenha os lotes pequenos e agende o ranking para um horário em que ninguém esteja esperando o resultado.
Ficam fora do ranking as linhas sem franquia de dados no plano, as que deixaram de estar ativas entre a listagem e a consulta de saldo (a consulta retorna `422`) e qualquer linha cujo saldo não pôde ser lido. Nenhum saldo é estimado.
O ranking não altera nada, mas as ações que ele sugere, sim. Um pacote adicional ([Adicionar dados](/api-reference/v3/phone-accounts/top-up-data)) ou uma troca de plano geram cobrança. Confira com o gestor antes de automatizar qualquer uma delas.
## Variações
* **Por centro de custo.** Agrupe as linhas pelo `costCenter` da listagem e monte um ranking por área, para cada gestor ver só a sua equipe.
* **Alerta de estouro.** Em vez de um ranking semanal, rode todo dia e avise quando uma linha passar de 90% da franquia antes do fim do ciclo.
* **Linhas sem uso.** Separe as linhas com consumo próximo de zero por várias semanas seguidas: são candidatas a [cancelamento](/api-reference/v3/phone-accounts/cancel) ou a um plano menor.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.