Dispersión masiva de bonos
El lote en tres actos — subir, revisar, disparar. Con el curl de cada paso.
Pagar bonos a cientos de personas no debe ser un solo click. Por eso el lote son tres actos separados a propósito: el archivo se valida, alguien revisa los números, y recién entonces sale dinero.
Acto 1 — Subir el archivo
La plantilla (XLSX/CSV) va por multipart, junto con la cuenta de tu empresa:
curl -X POST https://api.tikin.is/v1/bonus_batches \
-H "Authorization: Bearer tk_live_…" \
-H "Idempotency-Key: $(uuidgen | tr 'A-Z' 'a-z')" \
-F "[email protected]" \
-F "source_account=7b0d0f52-3f3e-4bf0-9d5a-111111111111" \
-F "description=bono septiembre"201 — el lote nació validating. Se valida fila por fila y pasa a ready,
o a rejected con un archivo de errores que dice qué fila y por qué.
Acto 2 — Revisar
curl https://api.tikin.is/v1/bonus_batches/{batch_id} \
-H "Authorization: Bearer tk_live_…"{
"id": "…",
"status": "ready",
"rows": 312,
"rows_rejected": 3,
"total": { "raw": "4680000000", "asset": "COPM" },
"files": { "errors_url": "https://…", "result_url": null }
}Aquí está el momento humano: ¿312 filas y $46.800.000 es lo que esperabas?
Si rows_rejected > 0, baja el errors_url, corrige y sube un lote nuevo (con
llave nueva — es otro pedido). El evento bonus_batch.ready te avisa cuando
terminó de validar, si registraste webhooks.
Acto 3 — Disparar
curl -X POST https://api.tikin.is/v1/bonus_batches/{batch_id}/execute \
-H "Authorization: Bearer tk_live_…" \
-H "Idempotency-Key: $(uuidgen | tr 'A-Z' 'a-z')"202 — recién AQUÍ sale dinero. El lote pasa a executing y termina en
completed o partially_failed, con el result_url fila por fila. Disparar un
lote que no está ready (ya disparado, o rechazado) es 409 — imposible pagar
dos veces por accidente.
El resumen del flujo
validating → ready → executing → completed | partially_failed, con rejected
como salida temprana. Sigue el final por GET o por el evento
bonus_batch.completed. Para pagar a UNA persona no armes un lote: existe
POST /v1/bonuses, síncrono y con el fee desglosado.