PayZu CellOperações

Ler o saldo e o consumo de uma linha


Nesta páginaAche a linhaLeia o saldoLeia o consumo do mêsErros

Mostre ao seu cliente quanto resta da franquia e quanto ele já usou no mês, partindo só do número da linha ou do chip.

Ache a linha

Envie um destes parâmetros, nunca os dois juntos:

  • msisdn: o número, com 55 e DDD.
  • iccid: o ICCID do chip, só dígitos.
bash
curl "https://api.payzucell.com.br/v1/lines/lookup?msisdn=5511987654321" \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"

Guarde o id, que as próximas chamadas usam. Se o chip já passou por mais de uma linha, a busca pelo ICCID traz a mais nova.

Referência: Localizar uma linha pelo número ou pelo ICCID

Leia o saldo

bash
curl https://api.payzucell.com.br/v1/lines/cm3x2b7k90004q8f2m1n6p8rs/balance \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"

O saldo é lido na operadora. Quando ela não informa um dos valores, o campo vem null.

Referência: Consultar o saldo de uma linha

Leia o consumo do mês

Informe o mês em month, no formato YYYY-MM. Sem ele, vale o mês corrente no horário de Brasília.

bash
curl "https://api.payzucell.com.br/v1/lines/cm3x2b7k90004q8f2m1n6p8rs/consumption?month=2026-11" \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"
  • Totais do mês: no topo da resposta.
  • Cada dia: em days. O exemplo mostra só os dois primeiros dias.
  • Unidades: dados em bytes e voz em segundos.

Referência: Consultar o consumo de uma linha

Erros

CódigoHTTPMensagem
PZC001400Corpo ou parâmetro fora do formato.
PZC020404Recurso não encontrado.
PZC200409O estado atual da linha não permite esta operação.
PZC201409Outra operação na mesma linha está em andamento.
PZC900422A operadora recusou a operação.
PZC005429Limite de chamadas por minuto excedido.
PZC901502A operadora não respondeu; consulte o estado antes de repetir.
  • Parâmetro fora do formato: a busca sem msisdn e sem iccid, com os dois ou com valor fora do formato, e o month fora de YYYY-MM.
  • Recurso não encontrado: nenhuma linha sua no ambiente da chave tem esse número, chip ou ID. No saldo e no consumo, a resposta é a mesma quando a operadora não acha o número.
  • Estado da linha: a linha não tem número, com msisdn em null, ou foi encerrada, em CANCELLED, CLOSED_BY_NETWORK ou ACTIVATION_FAILED. A linha encerrada é recusada sem consulta à operadora, com a mensagem Linha encerrada: a operadora não é consultada por este número.
  • Operação em andamento: a operadora está com outra operação na linha. Repita a consulta em instantes.
  • Limite de chamadas: o seu sistema passou do limite de chamadas por minuto. Espere antes de repetir.
  • Operadora sem resposta: repita a consulta em instantes.

O limite de chamadas da API está em Limites de requisição e os erros da chave, em Autenticação.