Contrato de sincronización v1
Referencia formal del protocolo de sync v1: endpoints, cabeceras, payloads, entidades por cliente, conflictos y códigos de error.
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.
Convenciones
- Base:
https://mi-servidor.example/api/v1. Formato: JSON UTF-8. - Autenticación: Sanctum,
Authorization: Bearer <token>, con abilitysync:owner(dueño) osync: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 }
}operationesupsertodelete; el borrado lógico viaja como tombstone conpayload.deleted_at.has_more: trueobliga a repetir la llamada con elcursordevuelto.conflictsson 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 }
}
]
}changesadmite entre 1 ypush_contract.max_batch_size(1000) elementos.event_ides la clave de idempotencia por negocio: repetir un evento lo devuelve enduplicatessin volver a aplicarlo.- Los tokens
sync:sellertienen 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_policyesdevice_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: truedeja el cambio pendiente para el siguiente ciclo.retryable: falsees definitivo: el cliente debe mostrarreasonycodey no reintentar en bucle.messagese conserva como alias dereasonpara 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-eventsdevuelvetotal_failedyper_entity.POST /api/v1/sync/reprocess-failed-eventsreaplica eventos atascados enfailedy devuelveattempted,applied,still_failed,remaining_failed,per_entityyreasons.
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.
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte