Estados y polling

Cómo enterarte de que algo cambió, hoy. La respuesta corta: los webhooks están declarados en el contrato y todavía no se emiten, así que el único mecanismo disponible es consultar. Esta guía dice qué se puede consultar, con qué techo de tasa, qué transiciones esperar — y, sobre todo, qué hoy no se puede saber por ninguna vía, para que no diseñes la conciliación alrededor de un dato que no vas a recibir.

1.Los webhooks no se emiten todavía

La referencia declara diez eventos (customer.kyc.completed, customer.kyc.rejected, account.opened, payment.completed, payment.failed, payment.returned, payout.completed, payout.failed, order.filled, quote.lock.expired), firmados con HMAC-SHA256 en Hamirach-Signature: t=<unix>,v1=<hex>, entrega at-least-once con deduplicación por event_id y backoff de 8 intentos.

Todo eso es contrato: lo que la API se va a comprometer a entregar. Hoy no hay emisor.

No se puede reusar lo que ya existe

Hamirach tiene otros emisores de webhooks para integraciones internas, y no sirven como anticipo de éste. Usan otro formato: X-Hamirach-Signature (con prefijo X-) llevando sólo el hex, el timestamp en un header aparte (X-Hamirach-Timestamp) en vez de dentro del mismo valor, y 3 intentos de entrega en lugar de 8. Su catálogo de eventos es otro y no tiene un solo nombre en común con los diez de arriba.

Lo decimos explícitamente porque el parecido invita al error: un verificador escrito contra ese formato no valida una firma del contrato público — el mensaje que se firma es distinto, el header es distinto y el parseo es distinto.

Qué hacer con esto

• No construyas todavía el receptor, la verificación de firma, la deduplicación por event_id, la cola de reintentos ni el runbook de reentrega. Hoy no hay contra qué probar ninguna de esas piezas: no existe un evento de prueba que podamos mandarte.
• Sí dejá decidida la forma, que no va a cambiar: entrega at-least-once (⇒ el receptor tiene que ser idempotente), deduplicación por event_id, ventana anti-replay de |now - t| ≤ 300s, y comparación de firma en tiempo constante. Eso es diseño, no código, y no se desperdicia.
• No hay fecha publicada para el emisor. No la inventamos: cuando exista, lo vas a ver funcionando en sandbox antes de que te lo anunciemos.

2.Qué se puede consultar hoy

Cuatro lecturas, todas sobre https://partners.hamirach.com/v1:

El resto de las rutas declaradas responde 404. No es un error de tu integración ni de tus credenciales: la ruta todavía no existe del lado del servidor.

Distinguí los dos 404 — no son lo mismo

Medido en producción — 2026-08-11

$ curl -sS https://partners.hamirach.com/v1/events
{"type":"about:blank","title":"Not Found","status":404,
 "code":"not_found","detail":"Cannot GET /v1/events",
 "request_id":"cfc7fd86-3bc9-4ca5-84d7-6d9bd59f3b2a"}

$ curl -sS https://partners.hamirach.com/v1/customers/cus_9f2k
{"type":"about:blank","title":"Not Found","status":404,
 "code":"not_found","detail":"Cannot GET /v1/customers/cus_9f2k",
 "request_id":"571e2f78-070b-4eee-a5ef-c7d2687cb597"}

Todo error sale como application/problem+json (RFC 9457) con code estable y request_id. Guardá el request_id en tu log: es lo que te vamos a pedir para diagnosticar cualquier respuesta que no entiendas.

Y los dos 503, que necesitan una rama propia

No son ni 429 ni 404, y tratarlos como cualquiera de los dos te deja mal parado.

3.Cómo consultar: intervalo, techo y backoff

Intervalo sugerido: 30 segundos

A 30 s, cada lectura son 2 peticiones por minuto. Pero el total no es una constante: depende de cuántas cuentas tengas, y ése es el número que hay que dimensionar.

El techo: 100 peticiones por minuto y por organización

Es un token bucket con capacidad 100 (PARTNER_API_RATE_LIMIT_PER_MINUTE, valor por defecto 100) aplicado por organización, no por credencial ni por IP.

La fórmula es peticiones/min = ciclos_por_minuto × (3 + N), con 2 ciclos/min a 30 s y 6 a 10 s. A 30 s el techo se toca en 48 cuentas: con 47 dan 100 exactos y con 48, 102.

Ese 3 es el caso naíf, barriendo las tres lecturas fijas en cada ciclo. Si seguís lo de Qué no poner en el loop —partners/me una vez al arrancar y rails una vez por día— el ciclo pasa a 1 + N y el quiebre se corre a 50 cuentas. La tabla usa el caso naíf a propósito: si dimensionás con ella y después optimizás, te sobra techo; al revés, no.

Pasado ese punto hay que escalonar las consultas de saldo en vez de barrerlas todas en cada ciclo — o consultar sólo las cuentas con actividad esperada. Si necesitás más techo, decínoslo con el volumen estimado: es un número configurable, no un límite del diseño.

La recarga es continua, no por ventana fija: se reponen 100/60 ≈ 1,67 tokens por segundo. En la práctica, una ráfaga de 100 pasa entera, la 101.ª del mismo segundo no, y ~600 ms después ya hay un token otra vez. Denegar no consume: un 429 no te empuja más atrás en la cola, así que un reintento razonable no se auto-castiga.

Cabeceras de respuesta

La especificación todavía no declara cabeceras de respuesta. Éstas sí viajan hoy, y podés programar contra ellas:

Las tres X-RateLimit-* viajan en toda respuesta autenticada, no sólo en el 429 — o sea que podés vigilar el margen sin esperar a chocarte con el techo.

Backoff ante 429

• Respetá Retry-After tal cual viene (segundos enteros).
• Si no viene, backoff exponencial con jitter. Sin jitter, varios pollers que arrancaron juntos vuelven a chocar juntos.
• Nunca reintentes en bucle cerrado. El balde recarga con el tiempo: la espera es el arreglo.
• Un 429 no es pérdida de datos — es una lectura, no una escritura. Volver a leer devuelve lo mismo.

Qué no poner en el loop

• GET /v1/partners/me — una vez al arrancar. Es barato y confirma credencial y scopes; no cambia cada 30 s.
• GET /v1/rails — a lo sumo una vez por día. El catálogo es cerrado y chico (hoy dos rieles) y los id son estables por diseño.

4.Transiciones de estado que podés esperar

Los valores de abajo salen de los enum del contrato, y son los que tu modelo de datos tiene que poder representar.

Cliente final — Customer.kyc.status

pending ──▶ in_review ──▶ approved
                      └──▶ rejected

Cuenta — Account.status

pending ──▶ active

Dejá frozen representable en tu modelo — el contrato lo declara y algún día va a llegar — pero no construyas la operación alrededor de él: hoy no hay forma de que aparezca, así que tampoco hay forma de probar tu manejo.

5.🔴 GET /v1/balances no es una fuente de conciliación

Responde 200 con la forma correcta, y el número que devuelve no se mueve. Sale de una columna que hoy escribe una sola cosa: la migración que siembra los datos. No hay ninguna ruta de escritura en el servicio, ni ningún proceso que actualice ese saldo.

Medido sobre el repositorio el 2026-08-11: cero escrituras de esa columna fuera de las migraciones.

Qué hacer: no conectes GET /v1/balances a la conciliación de acreditaciones todavía. Sirve, y mucho, para lo otro: ejercitar el transporte de punta a punta con una respuesta cuya forma es la definitiva.

6.Lo que hoy no se puede saber por polling

Explícito, para que no quede implícito en un endpoint que devuelve 404:

Ninguna de estas se arregla reintentando ni cambiando el intervalo. Si alguna es bloqueante para tu diseño, es una conversación de alcance con tu contacto en Hamirach, no un parámetro del cliente HTTP.

7.Qué construir ahora