Generar QR

Este servicio permite generar un código QR de cobro con un monto y descripción específicos.

Especificación del Endpoint

• Ruta: api/v2/simple-qrs
• Método: POST

Headers

X-API-KEY: <TU_API_KEY>
Content-Type: application/json
Accept: application/json
Idempotency-Key: <UUID_V4> (Requerido)

Idempotencia Obligatoria

La generación de un QR exige idempotencia de manera mandatoria para evitar de forma absoluta la duplicidad de cobros ante posibles fallas de red o reintentos accidentales por parte del sistema integrador.

• Header: Idempotency-Key (Mandatorio)
• Formato: Un identificador único de tipo UUID v4 (ej. e1a50a12-872f-4b08-8e6d-5a8b79c2356c).
• Comportamiento: Si tu sistema realiza un reintento enviando el mismo Idempotency-Key y los mismos datos en el cuerpo de la petición, Vendis interceptará la solicitud y devolverá la misma respuesta almacenada en caché del primer intento, garantizando que no se dupliquen QRs para una misma orden o venta.

Body (Cuerpo de la Petición)

{
  "business_code": 17,
  "amount": 150.0,
  "modify_amount": true,
  "is_multi_use": true,
  "qr_expiration": "2024-01-15 23:59:00",
  "description": "Pago QR <CUSTOM DESCRIPCION>"
}

Validaciones de los Campos (Request Body)

Campo	Tipo / Formato	Requerido	Reglas de Validación
amount	Decimal (#.##)	Sí	• Monto mínimo: Bs. 0.01. • Monto máximo: Bs. 20,000.00. • Decimales: Debe enviarse con formato de hasta 2 decimales (ej. 150.50).
description	Texto (String)	Sí	• Longitud permitida: Entre 1 y 45 caracteres. • Glosa o concepto del cobro que se visualizará en la aplicación bancaria del cliente.
qr_expiration	Fecha/Hora ("YYYY-MM-DD HH:mm:ss")	Sí	• Debe ser una fecha futura válida (ej. "2024-01-15 23:59:00"). • Determina el límite de vigencia exacto en el cual el código QR dejará de estar disponible para el cobro.
modify_amount	Booleano	Sí	• Valores permitidos: true / false. • Determina si el cliente puede modificar el monto del QR desde su aplicación bancaria.
is_multi_use	Booleano	Sí	• Valores permitidos: true / false. • true (Multiuso): Acepta múltiples pagos. • false (Único uso): El QR expira inmediatamente tras recibir el primer pago exitoso.

Ejemplos de Respuesta

Respuesta Exitosa (HTTP 201 Created)

{
  "qr_image": "iVBORw0KGgoAAAANS....",
  "qr_url": "https://emizor-felapp.s3.amazonaws.com/Qr-Image/2023-11-27/QR-Pago-Device99454326-e640-4095-9e3e-541a2dfc96f65643.jpg",
  "qr_id": "816269745"
}

Respuestas de Error

Error de Validación (HTTP 422 Unprocessable Entity):

{
  "type": "validation_error",
  "code": "invalid_request_data",
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount must be a number."],
    "business_code": ["The business_code field is required."]
  }
}

Nota: Para conocer la estructura de errores generales como 401 Unauthorized o 500 Internal Server Error, por favor revisa la sección de Códigos HTTP y Errores.