Sincronización de Facturas y Tipos

En esta sección se documentan los endpoints para sincronizar los tipos de documento (facturas, boletas, etc.) y las facturas operativas que contienen las líneas de producto a entregar.

1. Tipos de Factura

POST/transportes/sync/receipts/types

Crea o actualiza un tipo de factura en el sistema.

Caso de uso

Definir si un tipo de factura requiere pickups.
Definir color y descripción del tipo.

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`)
`receipt_type_code`	string	Código del tipo (ej. `FAC`)
`receipt_type_description`	string	Descripción legible del tipo

Opcionales

Campo	Tipo	Descripción
`is_active`	boolean	Estado activo
`receipt_type_id`	int	ID interno del tipo
`color_code`	string	Color en hex (ej. `#1E88E5`)
`pickups_needed`	boolean	Indica si el tipo requiere recolecciones previas

Ejemplos

Request

{
  "source_id": "smartfleet.receipt_type:1",
  "source_system": "external_erp",
  "receipt_type_code": "FAC",
  "receipt_type_description": "Factura",
  "color_code": "#1E88E5",
  "pickups_needed": true
}

Response

{
  "ok": true,
  "code": "SYNC_OK",
  "message": "Sync processed successfully.",
  "data": 1,
  "meta": {
    "route": "/transportes/sync/receipts/types",
    "method": "PostReceiptTypeSync",
    "operation": "upsert",
    "upsert_action": "updated",
    "timestamp": "2026-04-07T12:00:00.000Z"
  }
}

2. Facturas

POST/transportes/sync/receipts

Crea o actualiza facturas y sus líneas de productos.

Caso de uso

Crear facturas desde el sistema externo.
Actualizar estado, dirección, proyecto, sede, categorías y líneas.
Registrar pickups inline desde extra_data.pickups cuando la factura ya viene con OCs/traslados asociados.

Dependencias frecuentes

Sincronizar previamente: hubs, projects, clients, receipt_types, products, statuses.

Regla Especial: `NO_PROJECT`

Si project_code = "NO_PROJECT" o project_source_id = "project.project:NO_PROJECT", el backend intenta resolver un proyecto activo del cliente por main_account_name. Si no hay un cliente único o no tiene otro proyecto activo, usa NO_PROJECT y marca la factura como is_active = false.

Campos del Payload

Requeridos

Campo	Tipo	Descripción
`source_id`	string	ID único en el sistema de origen
`source_system`	string	Sistema externo
`receipt_code`	string	Código de la factura

Opcionales principales

Campo	Tipo	Descripción
`is_active`	boolean	Estado activo
`receipt_id`	int	ID interno de la factura
`receipt_type_id` / `receipt_type_source_id`	int/string	Tipo de factura
`receipt_type_model`	string	Modelo del tipo
`status_id`	int	Estado
`hub_id` / `hub_source_id`	int/string	Sede
`hub_model`	string	Modelo del hub
`order_code`	string	Código de la orden de venta
`address`	string	Dirección de entrega
`main_account_name`	string	Nombre del cliente principal
`recipient_name`	string	Nombre del destinatario (en ExactusSync: `COALESCE(FACTURA.NOMBRE_CLIENTE, CLIENTE.NOMBRE)`)
`recipient_phone`	string	Teléfono del destinatario
`document_date`	string	Fecha de negocio del documento (`YYYY-MM-DD` o ISO datetime; se normaliza a fecha). Alimenta el filtro por fecha de `GET /receipts` y `status-summary`
`weight`	number	Peso total
`lines_total_weight`	number	Suma de (cantidad × peso del producto) de las líneas activas; usado por reglas de overflow de ruteo
`delivery_window_from` / `delivery_window_to`	datetime	Ventana de entrega
`latitude` / `longitude`	number	Coordenadas
`details`	string	Detalles adicionales
`notes`	string	Notas internas
`is_express`	boolean	Entrega urgente
`has_restricted_product`	boolean	Tiene producto restringido
`is_dispatched`	boolean	Fue despachada
`is_pending_wms_preparation`	boolean	Pendiente preparación WMS
`is_dispatched_wms`	boolean	Despachada desde WMS
`wms_priority`	int	Prioridad WMS
`is_uber_available`	boolean	Disponible para Uber
`in_gam`	boolean	Dentro del GAM
`categories`	string[]	Categorías
`project_code` / `project_source_id`	string	Proyecto asociado
`project_model` / `client_model` / `product_model`	string	Modelos de referencia
`lines`	array	Líneas de productos
`replace_lines`	boolean	Reemplaza líneas. Default: `true`
`extra_data.pickups`	array	Pickups inline

Campos de `lines[]`

Requeridos

Campo	Tipo	Descripción
`product_code`	string	Código del producto
`quantity`	number	Cantidad

Opcionales

Campo	Tipo	Descripción
`quantity_base`	number	Cantidad base
`quantity_pickup_required`	number	Cantidad que requiere pickup
`warehouse`	string	Bodega
`status_id`	int	Estado de la línea
`location`	string	Ubicación en bodega
`lot`	string	Número de lote

Ejemplos

Request

{
  "source_id": "account.move:10001",
  "source_system": "external_erp",
  "receipt_code": "FAC-10001",
  "order_code": "SO-10001",
  "receipt_type_source_id": "smartfleet.receipt_type:1",
  "receipt_type_model": "smartfleet.receipt_type",
  "status_id": 1,
  "hub_source_id": "stock.warehouse:1",
  "hub_model": "stock.warehouse",
  "project_source_id": "project.project:9001",
  "project_model": "project.project",
  "client_model": "res.partner",
  "main_account_name": "Acme Logistics",
  "recipient_name": "Juan Pérez",
  "recipient_phone": "555-0100",
  "address": "San José, CR",
  "latitude": 9.93,
  "longitude": -84.14,
  "details": "Entregar en bodega principal",
  "is_express": false,
  "categories": ["PVC"],
  "product_model": "product.product",
  "replace_lines": true,
  "lines": [
    {
      "product_code": "00838",
      "quantity": 12,
      "quantity_base": 2,
      "quantity_pickup_required": 10,
      "warehouse": "WH/Stock",
      "location": "A-01",
      "lot": "L-2026"
    }
  ],
  "extra_data": {
    "pickups": [
      {
        "source_id": "purchase.order:371",
          "source_system": "external_erp",
        "pickup_type": "OC",
        "document_id": 371,
        "document_code": "OC-371",
        "receipt_code": "FAC-10001",
        "supplier_source_id": "res.partner:7001",
        "supplier_model": "res.partner",
        "status_id": 1,
        "lines": [
          {
            "product_code": "00838",
            "quantity": 5,
            "warehouse": "WH/Stock"
          }
        ]
      }
    ]
  }
}

Response

{
  "ok": true,
  "code": "SYNC_OK",
  "message": "Sync processed successfully.",
  "data": 2108,
  "meta": {
    "route": "/transportes/sync/receipts",
    "method": "PostReceiptSync",
    "operation": "upsert",
    "upsert_action": "mixed",
    "upsert_actions": ["updated", "created"],
    "timestamp": "2026-04-07T12:00:00.000Z"
  }
}

Restricciones y Paradas Recolecciones y Traslados

Sincronización de Facturas y Tipos

1. Tipos de Factura

Caso de uso

Campos del Payload

Requeridos

Opcionales

Ejemplos

2. Facturas

Caso de uso

Dependencias frecuentes

Regla Especial: NO_PROJECT

Campos del Payload

Requeridos

Opcionales principales

Campos de lines[]

Requeridos

Opcionales

Ejemplos

Regla Especial: `NO_PROJECT`

Campos de `lines[]`