Lotes de Producto Tikin

Esta guía describe el flujo de compatibilidad de Producto Tikin, bajo /payment-batch/{integration}. Tiene rutas y estados propios; el contrato de Plataforma /v1/bonus_batches se documenta aparte.

Subir y revisar

POST /payment-batch/{integration}/process-batch recibe un formulario con process, currency, concept y file; conserva los headers account, user-id e Idempotency-Key.

Se validan estructura del Excel, teléfonos o tags, montos mínimos/máximos por fila, cuentas de destino y autoenvíos. También se calcula la comisión. Los bonos pueden crear el registro de cuenta de un beneficiario nuevo.

Cuando el archivo es válido, status_file_validator queda COMPLETED y status_transactions, PENDING. Esto no reserva saldo ni garantiza el pago de todas las filas. Los errores de formato siguen devolviendo su detalle por fila.

Confirmar la dispersión

POST /payment-batch/{integration}/trigger-event/{batch_id}, con header account, inicia la ejecución. El libro procesa cada beneficiario, comprueba saldo y reglas aplicables, y conserva una llave estable por lote y wallet para evitar pagos duplicados.

Consultar y descargar

GET /payment-batch/{integration}/batch-status/{batch_id} permite seguir el lote. Los estados finales de transacciones son:

• COMPLETE: todas las filas procesadas terminaron correctamente.
• INCOMPLETE: hay filas rechazadas; revisar el resultado antes de actuar.
• FAILED: falló la preparación o ejecución global del lote.

GET /payment-batch/{integration}/download-transactions-file/{batch_id} entrega el Excel con estado, identificador de transacción y motivo de rechazo por fila. Un rechazo no impide intentar las otras filas; el total refleja únicamente las transferencias confirmadas. Un error global puede no producir archivo de resultados.

Repetir una petición con la misma llave recupera el job existente; no reabre un lote terminal ni garantiza reintentar sus filas fallidas. Ante una interrupción o un resultado incierto, conciliar el estado antes de generar otro lote.