PayZu CellOperações
Ler o saldo e o consumo de uma linha
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"json
{
"id": "cm3x2b7k90004q8f2m1n6p8rs",
"environment": "LIVE",
"customerId": "cm3x1z4d20002q8f2t6y9w3qe",
"customer": { "name": "Ana Lima", "document": "52998224725" },
"partnerId": "cm3w7k1t40000q8f2r5b9x3ad",
"nickname": null,
"plan": { "id": "cm3v9q5h10001q8f2g4j7l2xc", "name": "Start 6GB", "price": 29.9 },
"nextPlanId": null,
"msisdn": "5511987654321",
"iccid": "8955170100000000017",
"simType": "PHYSICAL",
"status": "ACTIVE",
"biometryStatus": "SUCCESS",
"cycleEndsOn": "2026-11-25",
"renewedUntil": null,
"dueDay": null,
"billingExempt": false,
"recurringCard": null,
"activatedAt": "2026-10-25T14:32:05.000Z",
"cancelledAt": null,
"createdAt": "2026-10-25T14:20:11.000Z"
}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"json
{
"msisdn": "5511987654321",
"dataRemainingMb": 4096,
"minutesRemaining": 169,
"smsRemaining": 19,
"planExpiresAt": "2026-11-25T23:59:59-03:00"
}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"json
{
"msisdn": "5511987654321",
"month": "2026-11",
"dataBytes": 1175269228,
"zeroRatingBytes": 89269228,
"zeroRatingByApp": { "WhatsApp": 55744782, "Waze": 33524446 },
"voiceSeconds": 1469,
"smsCount": 4,
"days": [
{
"date": "2026-11-01",
"dataBytes": 207744866,
"zeroRatingBytes": 10744866,
"voiceSeconds": 121,
"smsCount": 0
},
{
"date": "2026-11-02",
"dataBytes": 39474270,
"zeroRatingBytes": 11474270,
"voiceSeconds": 0,
"smsCount": 3
}
]
}- 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ódigo | HTTP | Mensagem |
|---|---|---|
PZC001 | 400 | Corpo ou parâmetro fora do formato. |
PZC020 | 404 | Recurso não encontrado. |
PZC200 | 409 | O estado atual da linha não permite esta operação. |
PZC201 | 409 | Outra operação na mesma linha está em andamento. |
PZC900 | 422 | A operadora recusou a operação. |
PZC005 | 429 | Limite de chamadas por minuto excedido. |
PZC901 | 502 | A operadora não respondeu; consulte o estado antes de repetir. |
- Parâmetro fora do formato: a busca sem
msisdne semiccid, com os dois ou com valor fora do formato, e omonthfora deYYYY-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
msisdnemnull, ou foi encerrada, emCANCELLED,CLOSED_BY_NETWORKouACTIVATION_FAILED. A linha encerrada é recusada sem consulta à operadora, com a mensagemLinha 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.