Sincronización de Clientes y Proyectos
En esta sección se documentan los endpoints para sincronizar clientes y sus proyectos asociados. Puedes sincronizar un cliente junto con sus proyectos en una sola llamada, o hacerlo de forma independiente.
1. Clientes
Crea o actualiza clientes. Admite proyectos inline en la misma llamada.
Caso de uso
- Crear cliente antes de sincronizar proyectos y facturas.
- Crear cliente y proyectos relacionados en una sola llamada.
Campos del Payload
Requeridos
| Campo | Tipo | Descripción |
|---|---|---|
source_id | string | ID único en el sistema de origen |
source_system | string | Sistema externo (ej. external_erp) |
client_code | string | Código del cliente |
Opcionales
| Campo | Tipo | Descripción |
|---|---|---|
is_active | boolean | Estado activo |
client_id | int | ID interno del cliente |
name | string | Nombre del cliente |
phone | string | Teléfono |
email | string | Correo electrónico |
projects | object / array | Proyectos inline |
Campos de projects[]
Requeridos
| Campo | Tipo | Descripción |
|---|---|---|
source_id | string | ID del proyecto en el sistema origen |
project_code | string | Código del proyecto |
Opcionales
| Campo | Tipo | Descripción |
|---|---|---|
source_system | string | Sistema origen (hereda del padre si no se especifica) |
is_active | boolean | Estado activo |
project_name | string | Nombre del proyecto |
exact_address | string | Dirección exacta |
contact_name | string | Nombre del contacto en obra |
latitude | number | Latitud |
longitude | number | Longitud |
in_gam | boolean | Dentro del GAM |
zip_code | string | Código postal |
delivery_window_from | string | Hora de inicio de ventana de entrega |
delivery_window_to | string | Hora fin de ventana de entrega |
phone | string | Teléfono del proyecto |
google_address | string | Dirección formateada de Google Maps |
Ejemplos
Request
{
"source_id": "res.partner:2253",
"source_system": "external_erp",
"client_code": "C-100",
"name": "Acme Logistics",
"phone": "555-0300",
"email": "purchases@example.com",
"projects": [
{
"source_id": "project.project:9001",
"project_code": "9001",
"project_name": "Proyecto Escazu",
"exact_address": "Escazu, San José",
"latitude": 9.93,
"longitude": -84.14
}
]
}Response
{
"ok": true,
"code": "SYNC_OK",
"message": "Sync processed successfully.",
"data": {
"client_id": 35,
"client_code": "C-100",
"source_id": "res.partner:2253",
"source_system": "external_erp",
"projects": [
{
"project_id": 120,
"project_code": "9001",
"upsert_action": "created"
}
],
"synced_at": "2026-04-07T12:00:00.000Z",
"upsert_action": "updated",
"project_upsert_actions": ["created"]
},
"meta": {
"route": "/transportes/sync/clients",
"method": "PostClientSync",
"operation": "upsert",
"upsert_action": "mixed",
"upsert_actions": ["updated", "created"],
"timestamp": "2026-04-07T12:00:00.000Z"
}
}2. Proyectos (Independientes)
Crea o actualiza proyectos. El cliente debe existir o resolverse por client_code.
Caso de uso
- Crear proyectos para poder asignar facturas a obra/proyecto.
- Actualizar dirección, contacto y coordenadas del proyecto.
Dependencias
Si client_code no existe, el endpoint responde con un error SYNC_MISSING_DEPENDENCIES solicitando sincronizar primero el recurso clients.
Campos del Payload
Requeridos
| Campo | Tipo | Descripción |
|---|---|---|
source_id | string | ID único en el sistema de origen |
source_system | string | Sistema externo |
project_code | string | Código del proyecto |
Opcionales
| Campo | Tipo | Descripción |
|---|---|---|
is_active | boolean | Estado activo |
project_id | int | ID interno del proyecto |
client_code | string | Código del cliente al que pertenece |
client_model | string | Modelo del cliente |
project_name | string | Nombre del proyecto |
exact_address | string | Dirección exacta |
contact_name | string | Nombre del contacto |
latitude | number | Latitud |
longitude | number | Longitud |
in_gam | boolean | Dentro del GAM |
zip_code | string | Código postal |
delivery_window_from | string | Hora inicio de ventana de entrega |
delivery_window_to | string | Hora fin de ventana de entrega |
phone | string | Teléfono |
google_address | string | Dirección formateada de Google Maps |
Ejemplos
Request
{
"source_id": "project.project:9001",
"source_system": "external_erp",
"project_code": "9001",
"client_code": "C-100",
"project_name": "Proyecto Escazu",
"exact_address": "Frente a edificio GAMA, Guachipelin",
"contact_name": "Juan Pérez",
"phone": "555-0500",
"latitude": 9.93,
"longitude": -84.14,
"delivery_window_from": "7",
"delivery_window_to": "16"
}Response
{
"ok": true,
"code": "SYNC_OK",
"message": "Sync processed successfully.",
"data": 120,
"meta": {
"route": "/transportes/sync/projects",
"method": "PostProjectSync",
"operation": "upsert",
"upsert_action": "updated",
"timestamp": "2026-04-07T12:00:00.000Z"
}
}