Sincronización de datos a través de la API

1) Por qué se necesita sincronización y qué objetivos

Consistencia de dominios: perfil, cartera, directorios, límites, KYC.
Reducción de los retrasos: casi en tiempo real para procesos críticos (pagos, bonificaciones).
Sostenibilidad: Experimentamos interrupciones en la red/proveedor sin pérdida de eventos.
Economía: minimizar la egresa/CPU a través de delta y paquetes.

Métricas de Éxito: lag (s) entre fuente y consumidor, freshness, proporción de duplicados, porcentaje de conflictos, costo de GB/hora azul.

2) Modelos de sincronización

2. 1 Pull (polling)

El cliente solicita los cambios a intervalos.

Pros: simplicidad, control de carga.
Las contras son: el trago, las encuestas «en blanco», el riesgo de saltar a alta velocidad de cambio.
Mejoras: If-Modified-Since, Etag/If-None-Match, change_token.

2. 2 Push (webhooks/events)

La fuente dispara los eventos al destinatario.

Pros: casi en tiempo real, ahorro de encuestas.
Contras: necesita entrega con retrés, deduplicación, seguridad (firma, mTLS).
Requisitos: medidores idempotentes, backoff exponencial, replay.

2. 3 CDC/streaming (Change Data Capture)

Instantánea de cambios del registro de transacciones/eventos (Kafka, Debezium).

Pros: plenitud, orden, escala.
Contras: complejidad, necesita control de tipos de operaciones (insert/update/delete/tombstone).

2. 4 Híbrido

Webhooks como «disparador», polling - como fallback y para reconciliation.

3) Delta incremental

3. 1 Watermark (marca de tiempo)

El cliente almacena 'last _ seen _ ts' y solicita' updated _ at> watermark '.

Riesgos: deriva horaria: utilice UTC y NTP; tome la ventana superpuesta (overlap) 1-2 min y dedoup por ID + versión.

3. 2 Change Token / Cursor

Token de secuencia estable: '? cursor = eyJvZmZzZXQiOjEwMDB9'.

Ventajas: resistencia al cambio de orden, escala.
Requisitos: cursores sostenibles, TTL y replay seguro.

3. 3 Offsets numerados (auto-incremento)

`id > last_id`. Simple, pero se rompe al chardear y «agujeros» en la secuencia.

4) Paginación de grandes selecciones

Keyset/cursor (preferiblemente): '? after = cursor & limit = 1000' - estable en los cambios.
Offset/limit es simple, pero caro y sujeto a cambios.
Siempre especifique una clave sort estable (por ejemplo, '(updated_at, id)').

json
{
"items": [ { "id": "u_1", "updated_at": "2025-11-03T16:59:10Z" } ],
"next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0xMS0wM1QxNjo1OToxMFoifQ==",
"has_more": true
}

5) Semántica de cambios: upsert, merge, delete

5. 1 Upsert/merge

'PUT/resource/{ id}' es un reemplazo completo.
'PATCH/resource/{ id}' es una actualización parcial (parches merge con validación).
Idempotencia por 'Idempotency-Key' para todos los write.

5. 2 Desinstalaciones

Soft delete (campo 'deleted = true', 'deleted _ at') - guardar el historial; el azul da tombstone.
Hard delete - regala el evento 'deleted' antes de desaparecer.

json
{ "id":"u_1", "event":"deleted", "deleted_at":"2025-11-03T17:00:00Z" }

6) Control de versiones y competencia

6. 1 ETag/If-Match (bloqueos optimistas)

La lectura devuelve 'ETag:' v123 '.
Actualización con 'If-Match: «v123»' - protección contra «actualizaciones perdidas».
En caso de conflicto, 409 Conflict con 'error _ code: "CONFLICT_VERSION"'.

6. 2 Versificación de registros

El campo 'version '/' updated _ at' está en el cálculo de deduplicación y delta.

6. 3 Conflictos

Políticas: last-write-wins, server-wins, merge-strategy por campos (por ejemplo, sumas de → aditivamente, marcas → prioridad de origen).

7) Orden y deduplicación

7. 1 Orden de entrega

Garantías: at-least-once más idempotencia → estándar de facto.
Para flujos de efectivo críticos: efectos exactos a través de la tienda idempotency.

7. 2 Claves de idempotencia

Composición de campos de dominio: 'source _ id' event _ type 'sequence'.
TTL de almacenamiento 24-72 horas (o más en SLA).

7. 3 Deduplicación

Guarde la última versión/seq aplicada en el receptor; Descartar los más antiguos.

8) Repeticiones, tiempos de espera, backoff

Retriable: 5xx/429/408/temporizadores; Non-retriable: 400/401/403/404/409/422/410/412.
Backoff + jitter exponencial: 1s, 2s, 4s... hasta 30-60s.
Retry-After respetar para 429/503.
Tiempos de espera del cliente: conexión 3-5s, consulta general 10-30s; límite total de intentos 3-6.

9) Control de lagunas y SLA

9. 1 SLI/SLO

SLI Lag: la mediana/r95 de un lag entre 'occurred _ at' y 'aplicado en el consumidor'.
SLO: por ejemplo, 'p95 lag ≤ 60s (28d)', 'fracción de eventos perdidos = 0', 'fracción de duplicados ≤ 0. 01%».
Error Budget: gastamos en lanzamientos/experimentos.

9. 2 Métricas

`sync_lag_seconds`, `events_received_total`, `events_applied_total`, `duplicates_total`, `conflicts_total`, `retries_total`, `backlog_size`, `cursor_advance_rate`.

10) Reconciliation (conciliaciones) y backfill

Conciliaciones diurnas/horarias: cifras totales/hashes por ventana.
API de conciliación: 'GET/reconciliation? from =... & to =... 'devuelve sumas de comprobación y discrepancias.
Backfill: dosificación segura de datos históricos por paquetes con cursor, sin fuente DDOS; respeta los límites.

11) Esquemas y ejemplos

11. 1 Webhook eventos (señalizados)

json
{
"event": "user. updated",
"id": "evt_01HX",
"occurred_at": "2025-11-03T18:00:05Z",
"sequence": 123456,
"data": { "id": "u_1", "email": "a@b. com", "updated_at": "2025-11-03T18:00:02Z" }
}

• `X-Signature: sha256=`
• `X-Event-Id: evt_01HX`
• `X-Retry: 0..N`

11. 2 Muestra incremental (polling)

`GET /v1/users? updated_after=2025-11-03T17: 58:00Z&cursor=...&limit=1000`

11. 3 Idempotent upsert

POST /v1/users
Idempotency-Key: upsert-u_1-20251103T1800Z
{ "id":"u_1","email":"a@b. com","version":124 }
→ 201/200 (stable)

12) Seguridad y cumplimiento

Auth: OAuth2 scopes/JWT; para canales azul - mTLS bajo demanda.
Firmas: Encabezados HMAC para webhooks, rotación de secretos.
Minimización PII, enmascaramiento en logs; GDPR/DSAR: descarga/eliminación.
RBAC/ABAC: acceso por tenante/organización, cuotas estrictas.

13) Observabilidad y registros

Лейблы: `env`, `service`, `tenant`, `source`, `cursor`, `seq`, `event_type`.
Correlación: 'trace _ id' desde la entrada → aplíquelo a los registros y alineaciones.
Dashboards: lag, backlog, velocidad del cursor, errores por tipo, 429/5xx, costo (egress/min).

14) FinOps: costo de sincronización

Paquete (batch size 100-1000) + compresión (gzip/br).
Almacenamiento en caché y ETag para páginas no intercambiadas.
Fine payload's: sólo campos modificados, referencia a un recurso completo bajo demanda.
Límites de concurrencia y «ventanas nocturnas» para backfill.

15) Pruebas y calidad

15. 1 Contratos y casos negativos

Validar esquemas JSON, campos obligatorios, estabilidad 'error _ code'.
Pruebas: fuera de orden, duplicados, omisión de eventos, conflicto de versiones, 429/5xx.

15. 2 Chaos/juegos

Inyecciones: retardos de red, drop 10-30% eventos, reorder.
Criterios: ¿Han mantenido el orden/la integridad? ¿No hay pérdidas? ¿Hay un trago dentro de SLO?

16) Lista de verificación de implementación

• Se seleccionó el modelo (push/pull/hybrid) y la fuente de la verdad.
• Delta incremental: watermark o cursor/token.
• Paginación: cursor/keyset con variedad estable.
• Idempotency-store, llaves y TTL; dedoup por '(id, version/seq)'.
• ETag/If-Match y la política de conflicto (LWW/server-wins/merge).
• Retry/backoff/jitter, el respeto de 'Retry-After'.
• Métricas log/backlog/duplicates/conflicts, dashboards y alertas.
• Reconciliation API + conciliaciones diarias.
• Seguridad: OAuth2/JWT, firmas de webhooks, mTLS, políticas PII.
• FinOps: batch + compression, límites de concurrencia, cuotas egress.
• Conjunto de pruebas: reorder, duplicates, outages, backfill.

17) Plan de implementación (3 iteraciones)

1. MVP (1-2 semanas):

Cursor-paginación, watermark-deltas, idempotente upsert, métricas de base lag/backlog, retry + backoff.

2. Escala (2-3 semanas):

Webhooks como disparador + polling-fallback, firmas HMAC, reconciliation, ETag/If-Match, dashboards y burn-alerts por laguna.

3. Pro (3-4 semanas):

CDC/streaming (Kafka/Debezium) para dominios calientes, auto-backfill, scripts de DR, optimización de FinOps (batch/brotley), SLA por lag y reporting.

18) Mini preguntas frecuentes

¿Qué elegir: watermark o cursor?
Cursor/keyset es más resistente al reorder y a la escala; watermark es más fácil de iniciar, pero añadir overlap y dedoup.

¿Es necesario un exactly-once?
En general, es caro. Práctica - at-least-once + idempotencia; exactly-once - sólo para efectos monetarios.

¿Cómo minimizar los conflictos?
Use ETag/If-Match, diseñe el merge en los campos, evite los efectos secundarios «ocultos».

Resultado

La sincronización confiable es deltas incrementales + paginación correcta + idempotencia y control de versiones, reforzado por la observabilidad, la conciliación y el transporte económico. Elija el modelo adecuado (push/pull/CDC), asegure el SLO por laguna, implemente políticas de conflicto y pruebas de escenarios «sucios» - y su intercambio de datos será predecible, sostenible y económico.