Conceptos Básicos

Esta sección cubre los conceptos básicos y herramientas para la integración con la API de OnSpot.

Enlaces Rápidos

• Colección Básica de Postman - Colección de Postman lista para usar
• Flujo de Trabajo de la API de Pagos de Dispersión OnSpot - Descripción general del flujo de trabajo de la API

Conceptos Fundamentales

Autenticación

La API de OnSpot utiliza un sistema de autenticación basado en claves API:

• Public Key: Identificador público de tu cuenta
• Secret Key: Clave privada para firmar las solicitudes
• Entornos: Separación entre testing y producción

Endpoints Principales

Autenticación

• POST /auth/login - Obtener token de acceso

Pagos

• POST /payouts - Crear un nuevo pago
• GET /payouts/:id - Consultar estado de un pago
• GET /payouts - Listar pagos

Beneficiarios

• POST /recipients - Crear beneficiario
• GET /recipients - Listar beneficiarios

Flujo de Trabajo Típico

1. Autenticación: Obtener token usando las credenciales
2. Crear Beneficiario: Registrar información del destinatario
3. Crear Pago: Enviar solicitud de pago
4. Monitorear: Consultar estado del pago
5. Confirmar: Verificar completación del pago

Códigos de Respuesta

• 200: Operación exitosa
• 201: Recurso creado exitosamente
• 400: Error en la solicitud
• 401: No autorizado
• 404: Recurso no encontrado
• 500: Error interno del servidor

Formatos de Datos

Solicitud de Pago

{
  "amount": 100.00,
  "currency": "USD",
  "recipient": {
    "name": "Juan Pérez",
    "email": "juan@example.com",
    "bankAccount": "1234567890"
  },
  "description": "Pago de servicios"
}

Respuesta de Pago

{
  "id": "payout_123456",
  "status": "pending",
  "amount": 100.00,
  "currency": "USD",
  "createdAt": "2024-01-15T10:30:00Z",
  "estimatedDelivery": "2024-01-16T10:30:00Z"
}

Mejores Prácticas

Seguridad

• Nunca expongas tu Secret Key en el frontend
• Usa HTTPS para todas las comunicaciones
• Implementa rate limiting en tu aplicación
• Valida todas las respuestas de la API

Manejo de Errores

• Implementa reintentos con backoff exponencial
• Registra todos los errores para debugging
• Proporciona mensajes de error claros a los usuarios
• Maneja timeouts apropiadamente

Monitoreo

• Implementa logging detallado
• Monitorea las tasas de éxito/fallo
• Configura alertas para errores críticos
• Mantén métricas de rendimiento

Herramientas de Desarrollo

Postman

• Colección completa de endpoints
• Variables de entorno preconfiguradas
• Ejemplos de solicitudes y respuestas
• Scripts de prueba automatizados

Webhooks

• Notificaciones en tiempo real
• Confirmación de pagos completados
• Actualizaciones de estado
• Manejo de eventos

---

Versión: 1.0 | Actualizado: hace 2 meses