ElVendedorDocs

Contrato de sincronización v1

Referencia formal del protocolo de sync v1: endpoints, cabeceras, payloads, entidades por cliente, conflictos y códigos de error.

Para implementadores5 min de lecturaActualizado el 16 de noviembre de 2026

Esta página fija la forma del protocolo: rutas, cabeceras, cuerpos y códigos. Consúltala al implementar un cliente o al cambiar una forma de payload. Para la operación diaria usa Sincronización en producción.

Diagrama del flujo de sincronización: el cliente guarda los cambios en su base local y los sube (push) al backend cuando hay conexión; el backend valida la versión y aplica los cambios, y el cliente descarga (pull) los cambios de otros dispositivos.
La venta se guarda primero en el equipo; el push y el pull con el backend ocurren después.

Convenciones

  • Base: https://mi-servidor.example/api/v1. Formato: JSON UTF-8.
  • Autenticación: Sanctum, Authorization: Bearer <token>, con ability sync:owner (dueño) o sync:seller (vendedor). El token debe pertenecer al negocio actual.

Endpoints

Método Ruta Uso Token
GET /api/v1/sync/bootstrap Contrato, negocio, licencia y límites dueño o vendedor
GET /api/v1/sync/pull Cambios de servidor a cliente dueño o vendedor
POST /api/v1/sync/push Lote de cambios de cliente a servidor dueño o vendedor
POST /api/v1/sync/conflicts/{id}/resolve Resolver un conflicto abierto dueño o vendedor
GET /api/v1/sync/failed-events Resumen de eventos fallidos solo dueño
POST /api/v1/sync/reprocess-failed-events Reprocesar eventos fallidos solo dueño

El middleware sync.request valida protocolo y versión de app y añade meta.request_id, meta.server_sync_version y meta.server_app_version a cada respuesta.

Cabeceras

Cabecera Obligatoria Uso
Authorization sí Bearer <token>
X-Sync-Version sí Protocolo que habla el cliente (1)
X-Client-App-Version según política Versión de la app instalada
X-Client-Entities no (pull) CSV de entidades que el cliente aplica
X-Business-Data-Reset-Version no (push) Versión de limpieza de negocio aplicada

Bootstrap

GET /api/v1/sync/bootstrap entrega el contrato y el estado del negocio. Extracto real de la respuesta:

{
  "server_time": "2026-11-14T10:00:00+00:00",
  "sync_version": 1,
  "contract_version": 1,
  "compatibility": {
    "policy": "minimum_version",
    "enforced": true,
    "server_app_version": "2.1.6",
    "required_app_version": null,
    "minimum_app_version": "2.1.6",
    "compatible_app_versions": [],
    "server_sync_version": 1,
    "supported_sync_versions": [1]
  },
  "media_policy": "device_local",
  "current_business": {
    "id": 1,
    "name": "Demo Store",
    "default_currency": "CUP",
    "data_reset_version": 3,
    "license": { "status": "active", "expires_at": null, "is_usable": true }
  },
  "capabilities": { "push": true, "pull": true, "conflicts": true, "inventory_events": false },
  "push_contract": {
    "max_batch_size": 1000,
    "operations": ["create", "update", "delete", "upsert"],
    "business_data_reset_header": "X-Business-Data-Reset-Version"
  },
  "pull_contract": {
    "cursor_type": "iso8601",
    "default_limit": 500,
    "cursor_formats": ["v2-serial", "v3-server-version"],
    "client_entities_header": "X-Client-Entities"
  }
}

required_app_version solo se emite con política same_version; en el resto de políticas llega null y el cliente debe mirar policy y enforced, no la presencia del campo.

Pull

Parámetros: device_id (obligatorio, máximo 191 caracteres), cursor (opcional; ausente = desde el inicio) y limit (1–1000, por defecto 500).

{
  "cursor": "v3:128",
  "server_time": "2026-11-14T10:00:00+00:00",
  "changes": [
    {
      "event_id": "server:invoices:invoice:A:00000001:1760000000",
      "entity_type": "invoices",
      "entity_id": "invoice:A:00000001",
      "operation": "upsert",
      "occurred_at": "2026-11-14T09:59:00+00:00",
      "payload": { "documentType": "invoice", "displayNumber": "A-00000001" },
      "server_version": 128
    }
  ],
  "conflicts": [],
  "meta": { "has_more": false, "cursor_format": "v3-server-version", "applied_count": 1 }
}
  • operation es upsert o delete; el borrado lógico viaja como tombstone con payload.deleted_at.
  • has_more: true obliga a repetir la llamada con el cursor devuelto.
  • conflicts son conflictos abiertos, independientes del cursor de datos.

El filtro X-Client-Entities sirve la intersección entre lo que el cliente declara aplicar y lo que el servidor soporta; ausente o vacío equivale a “todo”.

Push

{
  "device": { "id": "device-uuid", "name": "Samsung A15", "platform": "android", "app_version": "2.1.6" },
  "cursor": "2026-11-14T09:00:00+00:00",
  "changes": [
    {
      "event_id": "evt_001",
      "entity_type": "invoices",
      "entity_id": "invoice:A:00000001",
      "operation": "upsert",
      "occurred_at": "2026-11-14T09:05:00+00:00",
      "payload": { "documentType": "invoice", "number": 1 }
    }
  ]
}
  • changes admite entre 1 y push_contract.max_batch_size (1000) elementos.
  • event_id es la clave de idempotencia por negocio: repetir un evento lo devuelve en duplicates sin volver a aplicarlo.
  • Los tokens sync:seller tienen un subconjunto de entidades y alcance por almacén; un cambio fuera de su almacén se rechaza.
  • Las fotos y adjuntos no viajan: media_policy es device_local.

La respuesta es 202 con accepted, duplicates, rejected y meta. Cada elemento rechazado trae la causa real:

{
  "event_id": "evt_002",
  "entity_type": "products",
  "entity_id": "product:123",
  "status": "failed",
  "reason": "Ya existe un producto con el mismo código.",
  "message": "Ya existe un producto con el mismo código.",
  "code": "sync_duplicate_product_code",
  "retryable": false,
  "conflict_type": null
}
  • retryable: true deja el cambio pendiente para el siguiente ciclo.
  • retryable: false es definitivo: el cliente debe mostrar reason y code y no reintentar en bucle.
  • message se conserva como alias de reason para clientes antiguos.

Conflictos

POST /api/v1/sync/conflicts/{id}/resolve recibe una estrategia y una nota opcional:

{ "resolution": "keep_remote", "notes": "Se reenvió la venta del móvil." }
Resolución Uso
keep_remote Se conserva la versión del servidor y se descarta la local
discard_local Se descarta el cambio local sin adoptar el remoto
reviewed Se revisó a mano; queda registrado quién y cuándo

La respuesta devuelve id, status, resolution_notes y resolved_at.

Eventos fallidos

  • GET /api/v1/sync/failed-events devuelve total_failed y per_entity.
  • POST /api/v1/sync/reprocess-failed-events reaplica eventos atascados en failed y devuelve attempted, applied, still_failed, remaining_failed, per_entity y reasons.

Entidades por cliente

El servidor soporta 26 entidades; cada cliente declara las que aplica.

Entidad Móvil Escritorio
business_profile, categories, employees, warehouses, points_of_sale sí sí
sales, purchases, expenses, stock_movements, stock_adjustments, product_losses, product_breakdowns, weight_journals, contacts sí sí
cash_register_sessions sí (lectura) sí (lectura)
license_catalog, license_quote sí no (solo bootstrap)
units, product_batches, catalog_storefront, catalog_products, marketplace_product_publications, metrics_snapshots sí no
invoices no sí
restaurant_layouts no sí

inventory_events no existe como entidad sincronizable: se anuncia con capabilities.inventory_events = false y el stock viaja en eventos discretos y en el snapshot del producto.

Versionado

Nivel Valor vigente Cómo se negocia
Protocolo 1 X-Sync-Version contra supported_sync_versions
Contrato de datos 1 contract_version; el cliente lo compara con el suyo
Versión de app 2.1.6 Política policy/enforced del bootstrap

Un desfase de protocolo o de contrato es no reintentable. Las combinaciones están en Compatibilidad de versiones.

Errores

code Causa ¿Reintentar?
sync_protocol_version_missing Falta X-Sync-Version no
sync_protocol_version_mismatch Protocolo no soportado no
sync_client_app_version_missing Falta la versión de app con política activa no
sync_app_version_mismatch same_version y no coincide no
sync_app_version_too_old minimum_version y está por debajo no
sync_contract_version_too_new El servidor habla un contrato más nuevo no
sync_contract_version_too_old El servidor está desactualizado no
business_data_reset_required El negocio se limpió en el servidor no: limpiar y re-bootstrapear
sync_duplicate_product_code Código de producto repetido no
sync_invoice_number_conflict Número repetido dentro de la serie no
sync_permission_denied El rol no puede gestionar ese dato no
sync_seller_scope_forbidden Movimiento fuera del almacén del vendedor no
sync_apply_error Fallo inesperado al aplicar sí

Reset de negocio

Si un push devuelve 409 con business_data_reset_required, el cliente debe borrar los datos locales del negocio, descartar el outbox pendiente, limpiar cursores, marcar bootstrap_completed = false, adoptar el data_reset_version del servidor y relanzar bootstrap. Reintentar tal cual resucita lo borrado.

↑↓ para navegar · Enter para abrir · Esc para cerrar