Tokens de API
Crea tokens con permisos limitados para tus integraciones, en vez de guardar credenciales de sesión.
Si tu integración necesita llamar a la API de forma continua —un bot que sigue el mercado P2P, un panel que lee saldos, un proceso que compra energía—, no guardes el token que devuelve POST /auth/login. Ese token puede hacer todo lo que puedes hacer tú: retirar fondos, transferir saldo y cambiar los ajustes de tu cuenta.
En su lugar, crea un token de API con permisos acotados desde qvapay.com/dev/tokens. Eliges exactamente qué puede hacer, y lo que no marques queda fuera.
Los tokens se crean desde el navegador, no por API. Un token no puede crear otros tokens, tenga los permisos que tenga.
Permisos disponibles
| Permiso | Qué abre |
|---|---|
read | Consultas: perfil, saldo, historial. Cualquier GET. No mueve nada. |
p2p:read | Ver ofertas, rankings y precios del P2P. |
p2p:trade | Crear ofertas, aplicar, marcar pagado, liberar y calificar. Mueve saldo. Incluye p2p:read. |
store | Comprar recargas, gift cards, eSIM y energía TRON. Gasta saldo. |
transfer | Enviar saldo a otro usuario de QvaPay. Mueve saldo. |
withdraw | Retirar fondos fuera de QvaPay. Irreversible. |
Crear un token con cualquier permiso que mueva dinero exige tu PIN o el código de tu app de autenticación.
Cómo se usa
Igual que cualquier token: en la cabecera Authorization.
curl -X GET "https://api.qvapay.com/p2p" \
-H "Authorization: Bearer 12345|tu-token"Cuando falta un permiso
La respuesta es 403 y te dice cuál falta:
{
"error": "Este token no tiene el permiso \"Operar en P2P\". Créalo de nuevo en qvapay.com/dev/tokens con ese permiso marcado.",
"code": "INSUFFICIENT_SCOPE",
"required": "p2p:trade"
}Los permisos no se pueden editar después de crear el token: revoca el que tengas y crea otro con lo que necesites. Así el token que está en tus servidores nunca gana capacidades sin que tú lo sustituyas.
Lo que conviene saber
- El secreto se enseña una sola vez, al crearlo. Si lo pierdes, revócalo y crea otro.
- Cambiar tu contraseña revoca todos tus tokens de API. Es a propósito: si alguien entrara en tu cuenta, cambiar la contraseña tiene que cortarlo todo de golpe.
- Los permisos se aplican encima de los límites de tu cuenta, no en lugar de ellos. Un token con
withdrawsigue sujeto a tu KYC, a tus permisos de cuenta y a las retenciones de seguridad. - Ningún token acotado alcanza el chat del P2P. Al otro lado hay una persona que cree estar hablando con otra persona.
- Rutas no contempladas. Un token acotado solo llega a lo que estos permisos cubren. Para cualquier otra cosa hace falta una sesión real.
- Puedes tener hasta 10 tokens a la vez. No cuentan como sesiones ni cierran las de tus dispositivos.
¿Y si mi integración es una app registrada?
Entonces puede que no necesites ningún token. Una app con app-id/app-secret ya opera por su cuenta en cobros, facturas y —si lo activas— en el P2P. Ver Operar en P2P con credenciales de app.