Introducción
Esta documentación describe los endpoints de la API de QR para generar y gestionar códigos QR de pago en TotalCoin.
Autenticación
El control de acceso a la API se realiza mediante OAuth 2.0 con Tokens Bearer.
Endpoint
POST
api/auth/login
Solicitud
{
"company": "",
"username": "",
"password": ""
}
| Campo | Tipo | Descripción | Requerido |
|---|---|---|---|
| company | String | Nombre de la Empresa | Sí |
| username | String | Nombre de Usuario | Sí |
| password | String | Contraseña | Sí |
Respuesta (HTTP 200)
{
"token": "",
"expires_in": 3600
}
| Campo | Tipo | Descripción |
|---|---|---|
| token | String | Token de autenticación |
| expires_in | Number | Tiempo de expiración del token en segundos |
Errores Comunes
| Código | Descripción |
|---|---|
| 401 | Credenciales inválidas o incorrectas |
| 403 | Permisos insuficientes para acceder a la API |
Endpoints de QR
Generar Código QR
POST
api/qr/generate
Solicitud
{
"amount": 100.00,
"currency": "USD",
"description": "Descripción del pago",
"expires_in": 3600,
"customer_email": "cliente@ejemplo.com",
"customer_name": "Nombre del Cliente"
}
| Campo | Tipo | Descripción | Requerido |
|---|---|---|---|
| amount | Number | Monto del pago | Sí |
| currency | String | Moneda del pago (USD, EUR, etc.) | Sí |
| description | String | Descripción del pago | Sí |
| expires_in | Number | Tiempo de expiración en segundos | No |
| customer_email | String | Correo electrónico del cliente | No |
| customer_name | String | Nombre del cliente | No |
Respuesta (HTTP 200)
{
"qr_id": "qr_123456789",
"qr_code": "data:image/png;base64,...",
"qr_url": "https://totalcoin.com/qr/qr_123456789",
"expires_at": "2024-03-13T11:00:00Z"
}
| Campo | Tipo | Descripción |
|---|---|---|
| qr_id | String | ID único del código QR |
| qr_code | String | Imagen del código QR en formato base64 |
| qr_url | String | URL para acceder al código QR |
| expires_at | String | Fecha y hora de expiración del código QR |
Consultar Estado del QR
GET
api/qr/{qr_id}/status
Respuesta (HTTP 200)
{
"status": "pending",
"amount": 100.00,
"currency": "USD",
"created_at": "2024-03-13T10:00:00Z",
"expires_at": "2024-03-13T11:00:00Z",
"paid_at": null
}
| Campo | Tipo | Descripción |
|---|---|---|
| status | String | Estado del QR (pending, paid, expired) |
| amount | Number | Monto del pago |
| currency | String | Moneda del pago |
| created_at | String | Fecha y hora de creación |
| expires_at | String | Fecha y hora de expiración |
| paid_at | String | Fecha y hora del pago (si aplica) |
Notas Importantes
• Todas las solicitudes deben incluir el token de autenticación en el encabezado Authorization: Bearer {token}
• Los montos deben ser números decimales con dos decimales
• El tiempo de expiración por defecto es de 1 hora (3600 segundos)
• Los códigos QR expirados no pueden ser utilizados para realizar pagos
• Se recomienda implementar un sistema de notificaciones para recibir actualizaciones sobre el estado del pago