Errores comunes¶

Problemas frecuentes y cómo resolverlos.

El code del login es siempre incorrecto

Síntoma: Recibes YP-0006 al llamar a /session/login.

Causas más frecuentes:

1. Estás usando la Clave secreta como Seed (o viceversa). El HMAC se calcula usando el Código de semilla como clave — no la Clave secreta. Son dos valores distintos del portal.
2. La fecha usada en el HMAC no coincide con la del servidor. El code incluye la fecha actual en formato YYYY-MM-DD. Si el reloj de tu servidor está desfasado, el hash no coincidirá. Verifica que tu sistema esté sincronizado con NTP.
3. Hay un espacio o carácter extra en las credenciales. Al copiar del portal, a veces se copia un espacio al final. Haz trim() antes de usar los valores.
4. Concatenación incorrecta. El mensaje debe ser exactamente {api-key}{YYYY-MM-DD} sin ningún separador. Ejemplo: 30170525-6ba7-4606-98e3-1391f38662d32025-07-07.

// Verifica que esto sea correcto:
const mensaje = apiKey.trim() + fecha; // SIN guión, espacio ni separador

El filtro COLLECTION_ALIAS no devuelve resultados

Síntoma: /movement/history con filtro devuelve YP-0001 (sin datos) aunque sé que hay transacciones.

Causas más frecuentes:

1. El nombre del alias no coincide exactamente. El filtro es sensible a mayúsculas y espacios. Usa GET /collection-method para obtener los nombres exactos y cópialos directamente.
2. Las transacciones son de un rango de fechas diferente. Prueba con un rango más amplio para confirmar que el alias existe.
3. El punto de cobro no generó transacciones en el período. El endpoint devuelve YP-0001 cuando no hay datos — no es un error.

Intento anular una transacción y recibo YP-0014

Síntoma: YP-0014 — la reversa no puede ser procesada porque ya se liquidó.

Causa: La transacción ya pasó por el proceso de liquidación — el dinero ya está en tu cuenta bancaria. En ese punto, la anulación programática no es posible.

Solución: Para revertir un cobro ya liquidado debes gestionar un reintegro manual directamente con el cliente o a través del portal de Yappy Comercial. El endpoint solo puede anular transacciones en estado EXECUTED.

El token JWT expira antes de lo esperado

Síntoma: Empiezas a recibir errores de autorización después de pocas horas, aunque el token debería durar 24 horas.

Causas posibles:

1. Regeneraste las credenciales — esto invalida el token activo inmediatamente.
2. Llamaste a /session/logout — el token se invalida en ese momento.
3. Desincronización de relojes — si el reloj de tu servidor está adelantado, el cálculo del vencimiento puede ser incorrecto.

Recomendación: implementa detección de error de sesión (YP-0006) y reautenticación automática en tu cliente:

async function llamarConReintentoDeLogin(endpoint, options) {
  let respuesta = await fetch(endpoint, options);
  let data = await respuesta.json();

  if (data.status?.code === 'YP-0006') {
    // Token expirado — renovar y reintentar
    const nuevoToken = await hacerLogin();
    options.headers.authorization = nuevoToken;
    respuesta = await fetch(endpoint, options);
    data = await respuesta.json();
  }

  return data;
}

YP-0008 — Faltan headers

Síntoma: Error en cualquier endpoint con mensaje “cabeceras obligatorias faltantes”.

Verificar:

• api-key presente en el header.
• secret-key presente en el header.
• authorization presente (en todos los endpoints excepto /session/login).
• Los nombres de los headers están en minúsculas (algunos frameworks HTTP son sensibles a esto).

# Correcto
api-key: tu-api-key
secret-key: tu-secret-key
authorization: eyJlbmMi...

# Incorrecto (framework podría normalizar mal)
API-Key: tu-api-key