Conceptos Generales

Información del API

Propiedad	Valor
Base URL	https://api.alohapay.co/api/external/v1
Versión	v1
Content-Type	application/json

Todas las solicitudes y respuestas del API utilizan formato JSON. Las marcas de tiempo están en UTC (formato ISO 8601).

Autenticación

El External API utiliza autenticación mediante API Key. Las API Keys son específicas por cuenta e incluyen permisos (abilities).

Enviar la API Key

Incluye tu API Key en el header X-API-KEY:

X-API-KEY: tu_api_key_aqui

Permisos Requeridos (Abilities)

Cada endpoint requiere abilities específicos:

Endpoint	Ability Requerido
POST /v1/payment-links	payment_links:create
GET /v1/payment-links/{id}	payment_links:read
DELETE /v1/payment-links/{id}	payment_links:cancel

Propiedad de la API Key

Importante

La API Key hereda los permisos y contexto del usuario que la creó:

• Todos los payment links creados vía API Key se asocian al usuario creador
• La API Key solo puede acceder a payment links de su creador
• Si el usuario creador es desactivado, la API Key dejará de funcionar

Formato de Respuesta

Respuesta Exitosa

{
  "success": true,
  "message": "Operación completada exitosamente",
  "data": {
    // Los datos varían según el endpoint
  }
}

Respuesta de Error

{
  "success": false,
  "code": "CODIGO_ERROR",
  "message": "Mensaje de error legible",
  "errors": {
    // Opcional: Errores específicos por campo
  }
}

Formato alternativo (para errores de autenticación):

{
  "error": "Descripción del error",
  "code": "codigo_error"
}

Códigos de Error

Errores de Autenticación (401)

Código	Descripción
missing_api_key	No se proporcionó API key
invalid_key_format	Formato de API key inválido
invalid_tenant	Cuenta asociada no encontrada
invalid_api_key	API key inválida, expirada o revocada
USER_NOT_FOUND	Usuario asociado a la API key no encontrado

Errores de Autorización (403)

Código	Descripción
insufficient_scope	La API key no tiene el permiso requerido

Errores de Validación (422)

Código	Descripción
VALIDATION_FAILED	Validación fallida. Ver objeto errors
WALLET_NOT_FOUND	No hay wallet virtual configurado
PAYMENT_LINK_NOT_ACTIVE	Payment link no está activo
PAYMENT_LINK_CANNOT_CANCEL	Payment link ya fue usado

Errores de Recurso (404)

Código	Descripción
PAYMENT_LINK_NOT_FOUND	Payment link no encontrado
USER_NOT_FOUND	Usuario no encontrado

Errores de Sistema (500)

Código	Descripción
SYSTEM_DATABASE_ERROR	Error interno de base de datos

Estados de Payment Link

Estado	Descripción
active	Disponible para recibir pagos
completed	Pago procesado exitosamente
cancelled	Cancelado manualmente
expired	Expiró sin recibir pago

Mejores Prácticas

Seguridad

1. Nunca expongas tu API key en código del cliente o repositorios públicos
2. Usa HTTPS para todas las solicitudes
3. Rota las API keys periódicamente
4. Usa los permisos mínimos necesarios al crear API keys

Manejo de Errores

1. Siempre verifica el campo success en las respuestas
2. Implementa reintentos con backoff exponencial para errores 5xx
3. Registra los códigos de error para debugging

Integración

1. Almacena el id del payment link en tu sistema
2. Usa checkout_url para redirigir clientes al pago
3. Valida montos y monedas antes de crear payment links