API Reference

Todas las solicitudes a la API requieren autenticación mediante una API Key privada. Debés incluirla en el header X-API-KEY en cada request. Podés generar o regenerar tu clave desde el Dashboard → API Key.

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API Key",
  "timestamp": "2026-04-15T18:00:00Z"
}

Envía un código OTP de 6 dígitos a un número de teléfono vía SMS. Cuesta 1 crédito por envío exitoso. El mensaje contendrá automáticamente el nombre de tu aplicación registrada. Podés configurar la longitud del código y el tiempo de expiración. Para reintentos seguros, enviá una clave única en Idempotency-Key; repetirla devuelve el mismo OTP sin generar otro envío.

curl -X POST "https://api.rufiar.com/api/v1/otp" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: checkout-otp-2026-0001" \
  -d '{
    "channel": "SMS",
    "destinationPhone": "+5491112345678",
    "expiresInMinutes": 5,
    "otpLength": 6
  }'

Envía un código OTP a una dirección de email. Cuesta 0.1 créditos por envío. El asunto y cuerpo del email se generan automáticamente. Podés reintentar de forma segura usando la misma clave Idempotency-Key; no la reutilices con otro payload.

curl -X POST "https://api.rufiar.com/api/v1/otp" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: email-otp-2026-0001" \
  -d '{
    "channel": "EMAIL",
    "destinationEmail": "user@example.com",
    "expiresInMinutes": 10,
    "otpLength": 4
  }'

Valida el código ingresado por el usuario contra el OTP enviado. Necesitás el id retornado por el endpoint de envío y el código de 6 dígitos. Un OTP solo puede verificarse una vez; si ya fue verificado, expirado o falló, retorna error.

curl -X POST "https://api.rufiar.com/api/v1/otp/e8a9b3d2-1f4c-4a2e-9c7d-0f3b8e6a1d5f/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "code": "482916"
  }'

Consultá el saldo de créditos disponibles para tu cuenta. Cada SMS exitoso descuenta 1 crédito. Podés recargar créditos desde el Dashboard → Billing.

curl -X GET "https://api.rufiar.com/api/v1/balance/me" \
  -H "X-API-KEY: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Obtiene el historial paginado de todos los OTPs enviados desde tu cuenta, ordenados por fecha de creación descendente. Útil para auditoría, debugging y monitoreo de tus flujos de verificación.

curl -X GET "https://api.rufiar.com/api/v1/otp/history?page=0&size=10&sortDir=desc" \
  -H "X-API-KEY: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Todos los errores siguen el mismo formato JSON con los campos code, message y timestamp.

// Formato estándar de error
{
  "code": "INSUFFICIENT_CREDITS",     // Código de error interno
  "message": "Descripción del error", // Mensaje legible
  "timestamp": "2026-04-15T21:00:00Z",// ISO 8601
  "fieldErrors": [ ... ]              // Solo en errores de validación (400)
}

Para correr tests automatizados (CI/CD) o verificar tu integración sin consumir créditos, disponemos de un número mágico de sandbox que siempre responde exitosamente pero no envía mensajes a la red telefónica real.