Onboarding de una empresa
De «queremos pagar bonos» a «el primer empleado cobró» — qué hace la empresa, qué hace Tikin y qué hace tu integración, en orden.
Dar de alta una empresa en Tikin Bonus son cuatro momentos, cada uno con un dueño claro. Lo que está en la app lo hace la empresa; lo que está en el API lo hace tu integración; lo que exige criterio lo hace Tikin. Nada de esto se automatiza en secuencia: cada paso deja un estado que se puede consultar, y el siguiente empieza cuando el anterior terminó de verdad.
1. La empresa se registra (app)
La empresa abre su cuenta business desde la app de Tikin, con su NIT y su representante legal. Al nacer, la cuenta:
- tiene su alias público (
$acme) y su bolsillo principal en COP, - recibe pero no envía: sin verificación no sale dinero (por qué →),
- abre su expediente: KYB de la empresa y KYC del representante legal, dentro del mismo expediente.
Si la empresa ya existe como cliente de tu plataforma y la creas por API, es
POST /v1/accounts con type: business, legal_name
y su documento — el bolsillo y el expediente nacen igual.
2. Tikin la verifica (Tikin)
La verificación es un hecho fechado con fuente, no un switch. La empresa queda
verified cuando el KYB de la empresa y el KYC de sus personas clave cierran;
uno solo no alcanza. Mientras tanto la cuenta puede cargar saldo, pero no pagar.
Consulta el estado cuando quieras:
curl https://api.tikin.is/v1/accounts/{account_id} \
-H "Authorization: Bearer tk_live_…"{ "id": "…", "type": "business", "alias": "$acme", "legal_name": "Acme S.A.S.", "verification": "verified" }Y si registraste webhooks, account.verified te avisa el momento
exacto. Qué documentos pide Tikin, qué motivos de rechazo admiten un segundo intento y
cuáles no: verificación y cumplimiento.
3. La llave y sus límites (Tikin + tu integración)
Antes de pagar, confirma con qué vas a pagar:
curl https://api.tikin.is/v1/tenant -H "Authorization: Bearer tk_live_…"scopes dice qué puede tu token — para pagar bonos necesitas bonuses; para
consultar, read. Pide la llave con el mínimo: la que corre en el servidor que
paga no debería ser la misma que pinta saldos en un dashboard. Los límites de la
cuenta (por operación y mensuales) los define la plataforma según la verificación; un
pago que los excede responde 422 con el código que dice cuál y cuánto —
errores →.
4. Los empleados cobran (app + tu integración)
Cada empleado se registra en la app de Tikin como persona (su celular es su
identidad; su alias $… es a donde le pagas). Tu integración solo necesita resolverlo:
curl "https://api.tikin.is/v1/accounts/lookup?alias=%24mariap" \
-H "Authorization: Bearer tk_live_…"Con el account_id, un bono individual es POST /v1/bonuses
(síncrono, con el fee desglosado) y una nómina de bonos es un
lote en tres actos: subir, revisar, disparar. Un
empleado que no está verificado recibe igual — la regla es «recibe pero no envía» —
así que el bono llega aunque su KYC esté en curso; lo que no podrá es sacarlo hasta
verificarse.
La lista de control
Una empresa está lista para operar cuando todo esto es verdad. Cada punto se puede comprobar por API, no por memoria:
| Cómo se comprueba | |
|---|---|
| Cuenta business creada, con alias | GET /v1/accounts/{id} → type: business |
| Verificación cerrada | verification: "verified" (o el evento account.verified) |
| Token con el scope justo | GET /v1/tenant → scopes incluye bonuses |
| Saldo suficiente para la primera nómina | GET /v1/accounts/{id}/balances → available ≥ total + fees |
| Primer empleado resuelto | GET /v1/accounts/lookup?alias=… → 200 |
| Un bono de prueba pagado y visto | POST /v1/bonuses → 201; GET …/movements lo muestra como bonus_out |
Soporte y escalamiento
- La cuenta no verifica: el estado y el motivo están en el expediente; los motivos que admiten reintento y los que no, en verificación.
- Un pago responde
422: elcodedice si es saldo, límite o capacidad, y elmessagetrae los números. No se reintenta a ciegas. - Algo no cuadra: cita el
Tikin-Request-Idde la respuesta al escribir a soporte; con él encontramos el request en segundos.
Lo que este flujo no hace, a propósito: no automatiza secuencias de correo ni promete features que no están en el contrato. Si tu caso necesita algo que no ves aquí, es una conversación con Tikin antes que una integración.