Documentación de la API de Consulta de Pagos

Descripción

Esta API permite consultar pagos realizados por pago móvil, validando que el monto, teléfono y fecha coincidan con una transacción registrada.

URL DE LA API

https://api.pagomovil.guiapay.com/

Cabeceras requeridas

Content-Type: application/json
x-api-key: {API_KEY}

Endpoint de Prueba

POST /user/test

Body de prueba

{
  "telefono": "00584241325566",
  "monto": "15.96",
  "fecha": "2025-01-06",
  "agente": true
}

Endpoint de Produccion

POST /user/check

Parámetros de entrada (JSON)

{
  "telefono": "00584241325566",
  "monto": "15.96",
  "fecha": "20250106",
  "agente": false
}

Descripción de los parámetros

telefono (string, requerido): Número de teléfono asociado al pago, con el prefijo 0058.
monto (float, requerido): Monto exacto del pago a consultar.
fecha (string, requerido): Fecha de la transacción en formato YYYY-MM-DD.
agente (boolean, opcional): Indica si la consulta es realizada por un agente. Por defecto es false.

Respuestas de la API

✅ 200 - Pago encontrado y registrado exitosamente

{
  "mensaje": "Pago encontrado y registrado exitosamente.",
  "pago": {
    "telefonoCliente": "00584123456789",
    "monto": "100.50",
    "referencia": "123456789",
    "fecha": "2024-02-24"
  },
  "comision": 5.25,
  "montoConComision": 95.25,
  "agente": false
}

⚠️ 400 - Solicitud inválida

{
  "error": "Solicitud inválida",
  "mensaje": "Debe proporcionar teléfono, monto y fecha para realizar la consulta. El campo agente es opcional."
}

⚠️ 400 - Monto inválido

{
  "error": "Monto inválido",
  "mensaje": "El monto debe ser un número válido mayor que cero."
}

❌ 404 - Pago no encontrado

{
  "error": "Pago no encontrado",
  "mensaje": "No se encontró un pago que coincida con los datos proporcionados."
}

⚠️ 409 - Pago duplicado

{
  "error": "Pago duplicado",
  "mensaje": "El pago ya ha sido consultado previamente.",
  "detalles": {
    "referencia": "123456789",
    "telefonoCliente": "00584123456789",
    "monto": "100.50",
    "fecha": "2024-02-24"
  }
}

❌ 500 - Error en la consulta de pagos

{
  "error": "Error en la consulta de pagos",
  "mensaje": "Ocurrió un problema al intentar consultar los pagos. Verifique los datos y vuelva a intentarlo.",
  "detalles": "Descripción detallada del error."
}

Notas adicionales

La API requiere autenticación con api-key
Si se encuentra un pago, se registra en la base de datos del usuario.
El campo agente se guarda tanto en MongoDB como en Google Sheets para fines de seguimiento, pero no afecta la validación del pago.

📌 Contacto

Si tienes dudas o necesitas soporte, contáctanos en soporte@ejemplo.com