# README - Posnet `solicitud_pago_pinpad.php` ## Objetivo El endpoint `Posnet/solicitud_pago_pinpad.php` genera una operación de pago en ePagos y luego envía esa operación a una terminal PINPAD (Posnet), dejando trazabilidad en base de datos. Resumen funcional: 1. Recibe datos mínimos del comprobante y contexto del operador. 2. Consulta datos del comprobante/cuenta en Informix. 3. Crea la operación en ePagos (vía endpoint interno de QR). 4. Registra la transacción en tabla de Posnet. 5. Dispara `solicitud_pago_pinpad` con el SDK de ePagos. 6. Devuelve JSON con estado final de la gestión. --- ## Archivo - Endpoint: `Posnet/solicitud_pago_pinpad.php` - Ejecución operativa: `Posnet/posnet_pinpad.bash` - Dependencias directas: - `../permisos.php` - `../conect.php` - `../lib/epagos_api.class.php` - Configuración requerida (vía `env.php` cargado por `conect.php`): - `ID_ORGANISMO_POSNET` - `ID_USUARIO_POSNET` - `PASSWORD_POSNET` - `HASH_POSNET` - `EPAGOS_ENTORNO_POSNET` --- ## Ejecución La ejecución de este flujo se realiza mediante el bash: ```bash Posnet/posnet_pinpad.bash ``` Para su ejecución se requiere usar el **path absoluto** del archivo `posnet_pinpad.bash`. Ejemplo de ejecución: ```bash bash /ruta/absoluta/api-epagos/Posnet/posnet_pinpad.bash 123456 36768 emanuel.mangani@vicentelopez.gov.ar comin 10.10.10.10 ``` Este script es el mecanismo operativo para invocar la solicitud de pago al PINPAD. ### Recupero de respuesta post ejecución Luego de ejecutar el bash, la forma de recuperar la respuesta del proceso es mediante el stored procedure: `sp_get_mensaje_4gl(xn_comprob DECIMAL(16,0))` Se debe enviar el `n_comprobante` (recibo) como parámetro `xn_comprob`. La respuesta del SP devuelve: ```sql INTEGER as c_mensaje, CHAR(100) as d_mensaje; ``` - `c_mensaje`: código de estado/mensaje. - `d_mensaje`: descripción del resultado (hasta 100 caracteres). --- ## Método y formato - Método HTTP esperado: `POST` - `Content-Type`: `application/json` - Body: JSON ### Input esperado ```json { "recibo": 123456, "legajo": 999, "email": "contribuyente@dominio.com", "d_sistema": "TSG", "ip": "10.10.10.10" } ``` ### Campos de entrada | Campo | Tipo | Requerido | Descripción | | ----------- | ---------------------- | --------- | -------------------------------------------------------------------- | | `recibo` | number/string numérico | Sí | Número de comprobante. | | `legajo` | number/string | Sí | Identificador del operador/legajo. | | `email` | string | Sí | Email del pagador. Si viene vacío, se reemplaza por espacio (`" "`). | | `d_sistema` | string | Sí | Descripción de sistema para trazabilidad (`"POSNET " + d_sistema`). | | `ip` | string | Sí | IP del puesto, usada para resolver terminal Posnet. | --- ## Flujo funcional detallado 1. **Lectura de entrada** - Lee `php://input`. - Decodifica JSON a arreglo asociativo. 2. **Búsqueda de datos base por comprobante** - Ejecuta `sp_get_datos_cuenta(recibo)` para obtener: - `C_CUENTA` → cuenta - `C_SISTEMA` → sistema - `D_TASA` → tasa/descripción de ítem - Si no hay cuenta o sistema inválido (`0`): - Registra mensaje en 4GL con error. - Finaliza ejecución. 3. **Obtención de importe y vencimiento** - Ejecuta `sp_get_periodos_comprob(recibo)`: - `I_TOTAL` → `valor` - `F_VTO` → `fechaV` - Si `valor <= 0`: corta con error en 4GL. - Validación de vencimiento está comentada en código (no activa). 4. **Construcción de nombre del pagador según sistema** - Ejecuta `sp_datos_padron_cuentas(sistema, cuenta, recibo)`. - Luego consulta tabla temporal según `sistema`: - `1` → `tmp_pad_comercios` - `2` → `tmp_pad_abl` - `4` → `tmp_pad_rodados` - `31` → `tmp_pad_vehiculos` - Arma `nombre` (conversión `ISO-8859-1` → `UTF-8`). - Si sistema no reconocido: error en 4GL y fin. 5. **Resolución de terminal Posnet** - Requiere `ip`. - Ejecuta `sp_get_terminal(ip)` y toma `D_EPAGOS_TERMINAL`. 6. **Validaciones previas operativas** - Requiere: `legajo`, `terminal`, `d_sistema`, `email`. - Revalida: `cuenta` numérica, `recibo` numérico, `terminal` no vacío. 7. **Armado de payload ePagos** - `operacion`: - `id_moneda_operacion = 1` - `monto_operacion = valor` - `detalle_operacion` con `desc_item = tasa` y `monto_item = valor` - `pagador` con datos básicos y doc armado desde `cuenta` - `numero_operacion = recibo` - `identificador_externo_2 = "POSNET " + d_sistema` - `identificador_externo_3 = tasa` - `identificador_externo_4 = cuenta` - `opc_fecha_vencimiento = fechaV` - `opc_devolver_qr = 1` - `fp` (formas de pago): - `id_fp = 34` - `monto_fp = valor` - `cuotas_tarjeta_fp = 1` 8. **Autenticación SDK ePagos** - Instancia `epagos_api(ID_ORGANISMO_POSNET, ID_USUARIO_POSNET)`. - Define entorno con `EPAGOS_ENTORNO_POSNET`. - Obtiene token con `obtener_token(...)`. 9. **Generación de transacción base en ePagos** - Hace `POST` a: - `https://apiepagos.vicentelopez.gov.ar/api-epagos/QR/solicitud_pago.php` - Recupera `id_transaccion` del response. 10. **Persistencia local y envío a pinpad** - Ejecuta: - `sp_insert_ep_posnet(id_transaccion, recibo, legajo, terminal, email, d_sistema)` - Si SP devuelve `C_ESTADO = 0`: - Llama `epagos->solicitud_pago_pinpad(id_transaccion, valor, terminal)` - Responde éxito. - Si no, responde error de persistencia. 11. **Registro de mensaje 4GL** - En éxito: `sp_post_mensaje_4gl(recibo, 0, "Enviado correctamente.")` - En errores operativos: `sp_post_mensaje_4gl(recibo, 1, "...")` --- ## Stored Procedures utilizados | SP | Propósito | | --------------------------------------------------------------------------------- | ----------------------------------------------- | | `sp_get_datos_cuenta(recibo)` | Obtiene cuenta, sistema y tasa del comprobante. | | `sp_get_periodos_comprob(recibo)` | Obtiene importe total y fecha de vencimiento. | | `sp_datos_padron_cuentas(sistema, cuenta, recibo)` | Prepara/actualiza tablas temporales de padrón. | | `sp_get_terminal(ip)` | Obtiene terminal Posnet asociada a la IP. | | `sp_insert_ep_posnet(id_transaccion, recibo, legajo, terminal, email, d_sistema)` | Registra transacción para seguimiento Posnet. | | `sp_post_mensaje_4gl(recibo, estado, mensaje)` | Registra estado/mensaje de proceso para 4GL. | --- ## Respuestas JSON ### Caso exitoso ```json { "id_operacion": 123456789, "c_estado": 0, "respuesta_solicitud_pago_pinpad": { "...": "respuesta del SDK ePagos" } } ``` ### Error de inserción en `sp_insert_ep_posnet` ```json { "id_operacion": 123456789, "c_estado": 1, "respuesta_solicitud_pago_pinpad": null } ``` ### Falla de ejecución de query de inserción ```json { "id_operacion": 123456789, "c_estado": 2, "respuesta_solicitud_pago_pinpad": null } ``` ### Excepción del SDK ePagos (`EPagos_Exception`) ```json { "id_operacion": null, "c_estado": 3, "respuesta_solicitud_pago_pinpad": "mensaje de error" } ``` --- ## Errores de validación/control registrados Durante validaciones de negocio, el script corta ejecución y registra en 4GL mensajes como: - `No se encontraron datos para el comprobante proporcionado.` - `El valor del comprobante debe ser mayor a cero.` - `Sistema no reconocido.` - `IP es requerida` - `Legajo es requerido` - `Terminal es requerido` - `Descripción del sistema es requerida` - `Email es requerido` - `Cuenta no puede ser vacio` - `Recibo no puede ser vacio.` - `Terminal no puede ser vacio.` --- ## Ejemplo de consumo (cURL) ```bash curl --location 'https://apiepagos.vicentelopez.gov.ar/api-epagos/Posnet/solicitud_pago_pinpad.php' \ --header 'Content-Type: application/json' \ --data '{ "recibo": 123456, "legajo": 999, "email": "contribuyente@dominio.com", "d_sistema": "TSG", "ip": "10.10.10.10" }' ``` --- ## Observaciones técnicas importantes 1. El endpoint de creación de operación está **hardcodeado** a producción (`https://apiepagos.vicentelopez.gov.ar/.../QR/solicitud_pago.php`) y no usa la constante `API_URL_SOLICITUD_PAGO`. 2. Las respuestas HTTP no normalizan códigos de estado (`200/4xx/5xx`), sino JSON de control con `c_estado` y/o escritura de mensaje 4GL. 3. El helper `post_request()` usa `file_get_contents` sin timeout explícito ni manejo de errores HTTP detallado. 4. Hay validaciones que usan `isset` en vez de `empty`; si una clave viene presente pero vacía, algunos controles se aplican más adelante. 5. La validación de vencimiento está comentada y actualmente no bloquea comprobantes vencidos. --- ## Checklist operativo para soporte - Verificar que la IP del puesto exista en `sp_get_terminal`. - Confirmar que `sp_get_datos_cuenta` y `sp_get_periodos_comprob` devuelvan datos válidos. - Revisar resultado de `sp_insert_ep_posnet` (`C_ESTADO = 0`). - Si falla PINPAD, inspeccionar `respuesta_solicitud_pago_pinpad` y logs de ePagos/SDK. - Consultar mensaje trazado en `sp_post_mensaje_4gl` por `recibo`.