🚀 API Reference
La API de UnoPago es una interfaz RESTful que permite la integración programática de nuestros servicios financieros en sus propios sistemas. Esta guía contiene la referencia técnica completa, límites de rendimiento y protocolos de seguridad.
🔐 Autenticación y Seguridad
Todas las peticiones a la API deben realizarse sobre HTTPS y autenticarse mediante una API Key enviada en el encabezado de autorización.
Protocolo de Acceso
- Genere su clave en Configuración → API dentro de su panel administrativo.
- Utilice el esquema de autenticación Bearer Token.
Su API Key permite el control total de las operaciones financieras.
- Almacenamiento: Utilice variables de entorno (
.env), nunca archivos estáticos. - Exposición: No incluya claves en scripts de frontend (Client-side).
- Compromiso: Si detecta actividad inusual, revoque la clave inmediatamente desde el panel.
📡 Recursos Disponibles (Endpoints)
| Recurso | Método | Endpoint | Funcionalidad |
|---|---|---|---|
| Facturación | POST | /v1/invoices | Generación de nuevas órdenes de cobro. |
| Consultas | GET | /v1/payments | Recuperación del historial de transacciones. |
| Clientes | POST | /v1/customers | Registro y administración de perfiles. |
| Saldos | GET | /v1/balance | Consulta de fondos disponibles en cuenta. |
Visita https://api.unopago.com/ para ver todos los EndPoints disponibles.
📊 Límites de Uso y Rendimiento (Rate Limiting)
Para garantizar la estabilidad y alta disponibilidad de nuestros servicios, aplicamos las siguientes políticas de control de tráfico:
- Cuota Horaria: Hasta 1,000 peticiones por hora.
- Cuota de Ráfaga (Burst): Máximo 100 peticiones por minuto.
- Tamaño del Payload: El cuerpo de las peticiones
POST/PUTdebe ser inferior a 10MB.
Si su sistema requiere actualizaciones masivas o en tiempo real, le recomendamos implementar Webhooks. Esto permite que UnoPago envíe notificaciones automáticas (Push) a su servidor, evitando la saturación de la API por consultas constantes (Polling).
🛠️ Manejo de Errores y Estados HTTP
La API utiliza códigos de respuesta estándar para facilitar el diagnóstico de errores durante la integración.
| Código | Estado | Significado y Acción Sugerida |
|---|---|---|
| 401 | Unauthorized | API Key inválida o inexistente. Verifique el prefijo Bearer. |
| 400 | Bad Request | Error en la estructura JSON o campos obligatorios faltantes. |
| 404 | Not Found | El recurso solicitado (ID de factura, pago o cliente) no existe. |
| 429 | Too Many Requests | Cuota excedida. Implemente un algoritmo de back-off exponencial. |
| 500 | Server Error | Incidencia en los sistemas de UnoPago. Intente tras unos minutos. |
📈 Mejores Prácticas de Desarrollo
Para una integración robusta y escalable, siga estos lineamientos:
- Implementación de Caché: Almacene localmente datos estáticos o de baja rotación para minimizar llamadas innecesarias.
- Validación de Respuestas: Verifique siempre el código de estado HTTP antes de intentar procesar el objeto JSON de respuesta.
- Ambientes Separados: Utilice el Sandbox de UnoPago para fases de desarrollo y pruebas de estrés antes de migrar a Producción.
- Rotación de Credenciales: Recomendamos generar nuevas API Keys periódicamente (cada 90 días) como medida de seguridad preventiva.
❓ Preguntas Frecuentes (FAQ)
¿La API tiene un costo adicional? No, el acceso programático y el uso de las herramientas para desarrolladores están incluidos en todos los planes vigentes.
¿Puedo revocar una API Key sin afectar mis datos existentes? Es correcto. Revocar una llave solo invalida el acceso programático asociado a ese token; los registros de facturas, clientes y pagos permanecen intactos.
¿Es posible mantener múltiples llaves activas? Sí. Es la práctica recomendada para separar accesos entre diferentes departamentos, aplicaciones o entornos (Dev/Staging/Prod).
Si requiere soporte especializado, extensiones en sus límites de uso o asesoría en la arquitectura de su integración, contacte a nuestro equipo de soporte en: [email protected].