Sistema de Promociones - Bingo Oasis Pilar

📡 Endpoints de la API

GET /api/v1/premios/:codigo_campana

Consulta los premios disponibles de una campaña y realiza el sorteo automático devolviendo el id_premio y código QR asignado. Este valor se usa como entrada para los endpoints POST.

📤 Petición

GET https://promosbienvenida.bingopilar.com.ar/api/v1/premios/7d5eb58d07

200 Respuesta exitosa

{
  "id_premio": "324",
  "premio": "TICKET 15.000",
  "qr_accion_web": "MGTLRJNNVY",
  "status_code": 200
}

400 Código de campaña inválido

{ "error": "El codigo campana no existe en params" }

404 Sin premios disponibles

{ "error": "No hay premios disponibles para esta campaña", "status_code": 404 }

500 Error del servidor

{ "error": "Error al realizar el sorteo", "status_code": 500 }

POST /api/v1/acciones/insertar-wordpress Versión 1

Registra la participación de un usuario identificado por nombre y apellido. Valida que el email no haya sido utilizado previamente en ninguna campaña, inserta la acción y envía un email con el código QR del premio.

📤 Petición

POST https://promosbienvenida.bingopilar.com.ar/api/v1/acciones/insertar-wordpress
Content-Type: application/json

{
  "nombre_apellido": "Juan Pérez",
  "email": "juan@example.com",
  "celular": "1123456789",
  "id_premio": "324"
}

200 Registro exitoso

{
  "message": "Acción registrada correctamente",
  "status_code": 200,
  "data": {
    "nombre": "Juan Pérez",
    "imagen_qr": "MGTLY3G3S4",
    "codigo_qr": "MGTLY3G3S4",
    "premio": "TICKET 15.000",
    "fecha_vigencia": "16/10/2025",
    "dias_vigencia_reclamo": 7,
    "email": "juan@example.com",
    "IMG_LOGO": "https://bingopilar.com.ar/...",
    "URL_QR": "https://atc.bingopilar.com.ar/...",
    "URL_MAPS": "https://maps.app.goo.gl/...",
    "DIRECCION": "PANAMERICANA KM 50.4"
  }
}

403 Email ya registrado

{ "error": "Email ya cargado anteriormente" }

400 Campo faltante o email inválido

{ "error": "Falta el campo requerido: email" }
{ "error": "Formato de correo electrónico inválido" }

500 Error del servidor

{ "error": "Error interno del servidor" }

📋 Campos requeridos

Campo	Tipo	Descripción
`nombre_apellido`	string	Nombre completo del participante. Si no está disponible, puede usarse el prefijo del email (antes del `@`).
`email`	string	Email único del participante. Se valida formato y que no haya sido usado antes.
`celular`	string	Teléfono del participante. Puede enviarse vacío `""` si no se dispone del dato.
`id_premio`	string / number	ID del premio sorteado. Se obtiene del endpoint GET de premios.

POST /api/v2/acciones/insertar-wordpress Versión 2 · Nuevo

Variante de registro para formularios que capturan el número de documento (DNI) en lugar del nombre. Aplica doble validación anti-fraude: verifica que el email y el número de documento no hayan sido utilizados previamente dentro de la misma campaña. El email con el premio se envía vía el servicio Python de email usando el template mail_v2.html, que muestra el DNI del participante en lugar del nombre.

📤 Petición

POST https://promosbienvenida.bingopilar.com.ar/api/v2/acciones/insertar-wordpress
Content-Type: application/json

{
  "n_documento": "44301493",
  "email": "juan@example.com",
  "celular": "1123456789",
  "id_premio": "324"
}

200 Registro exitoso

{
  "message": "Acción registrada correctamente",
  "status_code": 200,
  "data": {
    "n_documento": "44301493",
    "imagen_qr": "MNDKOKHC1C",
    "codigo_qr": "MNDKOKHC1C",
    "premio": "TICKET 15.000",
    "fecha_vigencia": "31/03/2026",
    "dias_vigencia_reclamo": 7,
    "email": "juan@example.com",
    "IMG_LOGO": "https://bingopilar.com.ar/...",
    "URL_QR": "https://atc.bingopilar.com.ar/...",
    "URL_MAPS": "https://maps.app.goo.gl/...",
    "DIRECCION": "PANAMERICANA KM 50.4"
  }
}

403 Email ya registrado

{ "error": "Email ya cargado anteriormente" }

403 Documento ya registrado en esta campaña

{ "error": "El documento ya fue utilizado en esta campaña" }

400 Campo faltante o email inválido

{ "error": "Falta el campo requerido: n_documento" }
{ "error": "Formato de correo electrónico inválido" }

500 Error del servidor

{ "error": "Error interno del servidor" }

📋 Campos requeridos

Campo	Tipo	Descripción
`n_documento`	string	Número de documento (DNI) del participante. Se valida que no haya sido usado en la misma campaña.
`email`	string	Email del participante. Se valida formato y unicidad. El prefijo (antes del `@`) se usa internamente como `nombre_apellido`.
`celular`	string	Teléfono del participante. Puede enviarse vacío `""` si no se dispone del dato.
`id_premio`	string / number	ID del premio sorteado. Se obtiene del endpoint GET de premios.

🔀 Diferencias entre v1 y v2

🟣 Versión 1 — /api/v1/

Identifica al usuario con nombre_apellido
Valida unicidad solo por email
No almacena número de documento
Email enviado con mail.html (muestra el nombre)
Envío de mail via servicio Python (puerto 3033)

🟡 Versión 2 — /api/v2/ · Nuevo

Identifica al usuario con n_documento (DNI)
Valida unicidad por email + DNI por campaña
Almacena DNI en columna n_documento
Email enviado con mail_v2.html (muestra el DNI)
Envío de mail via servicio Python (puerto 3033)

📊 Comparativa de campos

Característica	v1	v2
Campo de identificación	`nombre_apellido`	`n_documento`
Validación anti-fraude por email	✅ Sí (global)	✅ Sí (global)
Validación anti-fraude por documento	❌ No	✅ Sí (por campaña)
Servicio de email	Servicio Python · puerto 3033	Flask Python · puerto 3033
Template de email	`mail.html`	`mail_v2.html`
Ruta	`/api/v1/acciones/insertar-wordpress`	`/api/v2/acciones/insertar-wordpress`

🔁 Flujo completo (ambas versiones)

1. Frontend llama GET /api/v1/premios/:codigo_campana
   → Obtiene { id_premio, premio, qr_accion_web }

2. Usuario completa formulario con sus datos

3. Frontend llama POST /api/v[1|2]/acciones/insertar-wordpress
   → Validación de campos
   → Verificación anti-fraude (email / dni)
   → INSERT en acciones_web
   → Envío de email con QR
   → Respuesta con datos del premio

🎰 Sistema de Promociones y Sorteos

🟣 Versión 1 — /api/v1/

🟡 Versión 2 — /api/v2/ · Nuevo

Documentación Privada