Integración de albaranes

Introducción

Una vez que un pedido ha sido preparado y valorado, la Tol genera un JSON con los datos del albarán valorado y lo pone a disposición de los sistemas del cliente (ERP).

Mientras el JSON de pedido refleja lo que el cliente solicitó en el momento de la compra, el albarán refleja lo que finalmente se ha servido y cobrado: cantidades reales, precios reales, promociones recalculadas sobre la entrega real y el detalle del cobro.

Por ese motivo el albarán expone, en los puntos en los que aplica, un par de valores gemelos con la misma estructura:

pedido: valor solicitado originalmente en el pedido.
real: valor resultante tras la preparación y la valoración.

El albarán se genera a partir del estado PREPARADO (es decir, una vez valorado) y el fichero se nombrará con el código del albarán y una marca de tiempo: albaran{codigo}_{timestamp}.json.

Formato independiente del JSON de pedido

El JSON de albarán es un formato nuevo e independiente, con su propio versionado (version: "1.0"). No es compatible a nivel de estructura con el JSON de pedido (versionJ: 2.6) descrito en Pedidos realizados, por lo que requiere su propio tratamiento en el sistema destino.

Convenciones del formato

Estas convenciones aplican a todo el documento:

Convención	Detalle
Nombres de campo	En español, agrupados por concepto de negocio.
Fechas y horas	RFC 3339 en UTC: `YYYY-MM-DDTHH:mm:ssZ`. Los valores que sólo tienen fecha se informan con `T00:00:00Z`.
Horas de franja	Literal `HH:mm`.
Importes y cantidades	Numérico decimal. Nunca se informan a nulo: si no hay importe, el valor es `0`.
Booleanos	Booleano nativo (`true` / `false`), no `0` / `1`.
Listas	Las listas obligatorias están siempre presentes: si no tienen elementos se informan vacías (`[]`), nunca a nulo. Las listas no obligatorias se omiten del JSON cuando no tienen elementos.
Campos sin valor	Los campos simples sin valor se omiten del JSON en lugar de informarse a nulo.
Datos derivados	El documento no incluye datos calculables a partir del resto, salvo el campo de control `numeroLineas`.

Tipos de integración

La integración de los albaranes con el cliente se realiza mediante los mismos mecanismos que la integración de pedidos:

Envío mediante servidor de archivos
Envío del albarán mediante WS
Envío del albarán mediante email

Adicionalmente el cliente puede reenviar los albaranes o descargarlos en formato json desde el back-office.

Formato albaranes

La información estará contenida en un objeto JSON con el siguiente formato:

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Versión JSON “version”	Versión correspondiente a la estructura del JSON. Valor actual: “1.0”	Literal (50 caracteres máx.)	Sí
Datos Documento “documento”	Identificación, estado y fechas del albarán	Tipo Documento	Sí
Datos Cliente “cliente”	Datos del cliente y sus direcciones	Tipo Cliente	Sí
Datos Entrega “entrega”	Datos de la entrega: tipo, zona, fecha y franja	Tipo Entrega	Sí
Datos Cobro “pagos”	Lista de los cobros realizados sobre el albarán	Lista de Tipo Pago	Sí
Líneas “lineas”	Lista de las líneas servidas del albarán	Lista de Tipo Línea	Sí
Promociones “promociones”	Lista de promociones aplicadas al total del albarán	Lista de Bloque Promoción	No
Bundles “bundles”	Lista de conjuntos (bundles) aplicados al albarán	Lista de Tipo Bundle	No
Regalos “regalos”	Lista de regalos asociados al albarán	Lista de Tipo Regalo	No
Importes “importes”	Totales del documento, en versión pedido y versión real	Tipo Importes	Sí

El formato se construye a partir de un conjunto reducido de bloques reutilizables, que se describen a continuación y que se instancian de forma idéntica en todos los nodos en los que aparecen.

Bloques reutilizables

Bloque Producto

Identifica un producto en cualquier nodo donde aparezca (línea, producto original sustituido, producto de un bundle).

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Código “codigo”	Código interno del producto en los sistemas del cliente	Literal (50 caracteres máx.)	Sí
Descripción “descripcion”	Descripción corta del producto	Literal (500 caracteres máx.)	Sí
Descripción larga “descripcionLarga”	Descripción larga del producto. Sólo se informa en los nodos que la almacenan	Literal (255 caracteres máx.)	No

Bloque Impuesto

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Tipo “tipo”	Tipo de IVA aplicado	Numérico entero	Sí
Porcentaje “porcentaje”	Porcentaje de IVA aplicado. Ejemplo: 10.0	Numérico decimal	Sí

Bloque Promoción

Estructura única para ofertas, cupones y códigos promocionales. Se utiliza en la cabecera del albarán, en cada línea, en cada bundle y en cada regalo.

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Tipo “tipo”	Naturaleza de la promoción: “OFERTA”, “CUPON” o “CODIGO_PROMOCIONAL”	Literal (30 caracteres máx.)	Sí
Código “codigo”	Código de la oferta, del cupón o del código promocional, según el valor de “tipo”	Literal (30 caracteres máx.)	Sí
Código promoción “codigoPromocion”	Código de la promoción relacionada	Literal (50 caracteres máx.)	Sí
Código promoción cliente “codigoPromocionExterno”	Código de la promoción en los sistemas del cliente	Literal (50 caracteres máx.)	No
Descripción “descripcion”	Descripción corta de la promoción	Literal (255 caracteres máx.)	No
Tipo de descuento “descuento.tipo”	Naturaleza del descuento configurado en la promoción: “IMPORTE” o “PORCENTAJE”	Literal (30 caracteres máx.)	Sí
Valor del descuento “descuento.valor”	Valor configurado en la promoción: importe a descontar o porcentaje de descuento, según “descuento.tipo”	Numérico decimal (formato 0.00)	Sí
Descuento inmediato “descuento.inmediato”	Importe de descuento efectivamente aplicado en este albarán	Numérico decimal (formato 0.00)	Sí
Descuento diferido “descuento.diferido”	Importe a descontar en diferido. Requerirá carga de un cupón y no minora el total de este albarán	Numérico decimal (formato 0.00)	Sí

Descuento inmediato y diferido

descuento.valor es el valor configurado en la promoción, mientras que descuento.inmediato y descuento.diferido son los importes realmente aplicados en este albarán. En una promoción de tipo PORCENTAJE, descuento.valor es el porcentaje (por ejemplo 10.0) y descuento.inmediato es el importe resultante de aplicarlo.

Bloque Dirección

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Tipo de vía “tipoVia”	Calle, Plaza, Avenida, etc.	Literal (50 caracteres)	Sí
Nombre vía “nombreVia”	Nombre de la vía	Literal (100 caracteres)	Sí
Anexo vía “anexoVia”	Anexo de la vía	Literal (50 caracteres)	No
Número “numero”	Numero 3, 4 BIS, etc.	Literal (20 caracteres)	Sí
Escalera “escalera”	Escalera: A, DERECHA, etc.	Literal (30 caracteres)	No
Piso “piso”	Piso 1, Principal, Entresuelo, etc.	Literal (30 caracteres)	No
Letra “letra”	Letra 1, A, etc.	Literal (30 caracteres)	No
Ascensor “ascensor”	El domicilio dispone de ascensor	Booleano	No
Código postal “codigoPostal”	Código postal	Literal (5 caracteres)	Sí
Localidad “localidad”	Nombre de la localidad	Literal (100 caracteres)	Sí
Provincia “provincia”	Nombre de la provincia	Literal (100 caracteres)	Sí
País “codigoPais”	Codigo que identifica el pais (ISO-3166-1)	Numérico	Sí

Tipo Documento

Identifica el albarán, su estado y sus fechas.

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Tipo “tipo”	Tipo de documento. Valor constante: “ALBARAN”	Literal (30 caracteres máx.)	Sí
Código “codigo”	Código que identifica distintivamente el albarán	Literal (50 caracteres máx.)	Sí
Estado “estado”	Estado del albarán. Ver tabla de estados	Literal (30 caracteres máx.)	Sí
Fecha creación “fechaCreacion”	Fecha y hora de creación del albarán	Fecha y hora (RFC 3339 UTC)	Sí
Fecha recálculo “fechaRecalculo”	Fecha y hora en la que se ha valorado el albarán y recalculado sus promociones	Fecha y hora (RFC 3339 UTC)	No
Número de líneas “numeroLineas”	Número de líneas incluidas en el albarán. Campo de control para el sistema destino	Numérico entero	Sí
Código pedido “pedido.codigo”	Código del pedido del que procede el albarán	Numérico entero	Sí

Estados posibles del albarán:

Estado	Descripción
`PENDIENTE`	Albarán creado, pendiente de preparación
`EN_PREPARACION`	Pedido en proceso de preparación
`PREPARADO`	Pedido preparado y albarán valorado
`LISTO_PARA_REPARTO`	Albarán preparado y listo para su reparto
`EN_REPARTO`	Albarán en proceso de reparto
`ENTREGADO`	Albarán entregado al cliente
`INCIDENCIA`	Albarán con una incidencia registrada

Note

La generación del JSON se produce a partir del estado PREPARADO, por lo que los estados PENDIENTE y EN_PREPARACION no se informan en los ficheros exportados.

Tipo Cliente

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Código usuario “codigoUsuario”	Código que identifica al usuario distintivamente	Literal (50 caracteres)	Sí
Nombre “nombre”	Nombre del usuario	Literal (50 caracteres)	Sí
Apellido1 “apellido1”	Primer apellido del usuario	Literal (50 caracteres)	Sí
Apellido2 “apellido2”	Segundo apellido del usuario	Literal (50 caracteres)	No
Email “email”	Correo electrónico del usuario	Literal (50 caracteres)	Sí
Teléfono 1 “telefono1”	Teléfono principal del usuario	Literal (20 caracteres)	Sí
Teléfono 2 “telefono2”	Teléfono alternativo del usuario	Literal (20 caracteres)	No
Tipo documento “documento.tipo”	Tipo de documento del usuario	Literal (20 caracteres) CIF, NIF, PASAPORTE…	Sí
Número documento “documento.numero”	Número del documento identificativo del usuario	Literal (20 caracteres)	Sí
Dirección usuario “direcciones.usuario”	Dirección del usuario	Bloque Dirección	Sí
Dirección entrega “direcciones.entrega”	Dirección donde se ha entregado el albarán	Bloque Dirección	Sí
Datos factura “direcciones.factura”	Datos de facturación. No se informa si el pedido no tiene datos de factura	Tipo Factura	No

Dirección de entrega

La dirección de entrega es la que quedó registrada en el albarán en el momento de su creación. Los campos ascensor y codigoPais no forman parte de esa información, por lo que no se informan en direcciones.entrega.

Tipo Factura

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
CIF “cif”	CIF de la empresa	Literal (30 caracteres)	Sí
Razón social “razonSocial”	Razón social de la empresa	Literal (100 caracteres)	Sí
Recargo equivalencia “recargoEquivalencia”	Indicador si el usuario quiere recargo de equivalencia en la factura	Booleano	Sí
Dirección “direccion”	Dirección de la empresa	Bloque Dirección	Sí

Tipo Entrega

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Tipo de entrega “tipo”	Modalidad de entrega del pedido	Literal (30 caracteres máx.)	Sí
Entrega en domicilio “domicilio”	Indicador si el pedido se entrega en domicilio	Booleano	Sí
Código zona “zona.codigo”	Código de la zona	Numérico entero	Sí
Nombre zona “zona.nombre”	Nombre de la zona	Literal (100 caracteres máx.)	Sí
Id zona envío “zona.envio.codigo”	Identificador de la zona de envío	Literal (50 caracteres máx.)	Sí
Nombre zona envío “zona.envio.nombre”	Nombre de la zona de envío	Literal (100 caracteres máx.)	Sí
Fecha entrega “fecha”	Fecha de entrega seleccionada	Fecha y hora (RFC 3339 UTC)	Sí
Hora inicio franja “franja.inicio”	Hora de inicio de la franja de entrega seleccionada	Hora (HH:mm)	Sí
Hora fin franja “franja.fin”	Hora fin de la franja de entrega seleccionada	Hora (HH:mm)	Sí

Tipo Pago

Cada elemento de pagos representa un cobro realizado sobre el albarán, con su forma de pago, su estado y su importe. A diferencia del JSON de pedido, los datos de pago se informan únicamente en este nodo.

Un albarán tiene actualmente un único cobro, por lo que la lista contendrá un solo elemento. Se informa como lista para admitir varios cobros sobre un mismo albarán sin modificar el formato.

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Forma de pago “formaPago.codigo”	Identificador de la forma de pago seleccionada	Numérico entero	Sí
Descripción forma de pago “formaPago.descripcion”	Descripción de la forma de pago seleccionada	Literal (100 caracteres máx.)	Sí
Estado del cobro “estado”	Estado del cobro del albarán: “PENDIENTE”, “COBRADO” o “KO”	Literal (30 caracteres máx.)	Sí
Código autorización “codigoAutorizacion”	Código de autorización asociado al cobro	Literal (50 caracteres máx.)	No
Importe cobrado “importeCobrado”	Importe efectivamente cobrado al cliente	Numérico decimal (formato 0.00)	Sí
Fecha de cobro “fechaCobro”	Fecha y hora en la que se ha realizado el cobro	Fecha y hora (RFC 3339 UTC)	No
Otros datos “datosAdicionales”	Otra información relativa al proveedor del pago o al cobro. Variable en función del proveedor	Lista de Tipo Clave-Valor	No

Relación con el total del albarán

La suma de los importeCobrado de todos los elementos de pagos se corresponde con importes.real.total, que es el importe que finalmente se cobra al cliente. Cuando el albarán tiene un único cobro, importeCobrado coincide directamente con ese total.

Lista de Tipo Clave-Valor

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Nombre parámetro “nombre”	Identificador del parámetro	Literal (30 caracteres)	Sí
Valor del parámetro “valor”	Valor del parámetro	Literal (256 caracteres)	Sí

Los parámetros informados en datosAdicionales dependen de la plataforma de pago utilizada. Se corresponden con los mismos parámetros descritos en otrosDatosPago en la integración de pedidos.

Tipo Línea

Cada elemento de lineas representa un producto servido, con su valor solicitado en el pedido, su valor real tras la preparación y la desviación que se haya producido.

Sólo se incluyen las líneas servidas, es decir, aquellas con cantidad real mayor que cero.

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Producto “producto”	Producto servido en la línea	Bloque Producto	Sí
Unidad medida “unidadMedida”	Unidad de medida en la cual se expresa la cantidad. Ejemplo: “UN”, “KG”	Literal (10 caracteres máx.)	Sí
Impuesto “impuesto”	Impuesto aplicado al producto	Bloque Impuesto	Sí
Cantidad pedida “pedido.cantidad”	Cantidad solicitada en el pedido	Numérico decimal (formato 0.00)	Sí
Precio medio pedido “pedido.precioMedio”	Precio medio unitario según el pedido	Numérico decimal (formato 0.00)	Sí
Importe pedido “pedido.importe”	Importe de la línea según el pedido, sin aplicar descuentos	Numérico decimal (formato 0.00)	Sí
Cantidad servida “real.cantidad”	Cantidad realmente servida	Numérico decimal (formato 0.00)	Sí
Precio medio real “real.precioMedio”	Precio medio unitario realmente aplicado	Numérico decimal (formato 0.00)	Sí
Importe real “real.importe”	Importe real de la línea, sin aplicar descuentos	Numérico decimal (formato 0.00)	Sí
Descuento inmediato “descuentos.inmediato”	Suma de los descuentos inmediatos aplicados a la línea	Numérico decimal (formato 0.00)	Sí
Descuento diferido “descuentos.diferido”	Suma de los descuentos diferidos generados por la línea	Numérico decimal (formato 0.00)	Sí
Tipo desviación “desviacion.tipo”	Desviación producida entre lo solicitado y lo servido. Ver tabla de desviaciones	Literal (20 caracteres máx.)	Sí
Descripción desviación “desviacion.descripcion”	Descripción de la desviación producida	Literal (1500 caracteres máx.)	No
Producto original “desviacion.productoOriginal”	Producto solicitado originalmente. Sólo se informa cuando la línea ha sido sustituida	Bloque Producto	No
Promociones “promociones”	Lista de ofertas y cupones aplicados a la línea	Lista de Bloque Promoción	No

Tipos de desviación:

Tipo	Descripción
`OK`	La línea se ha servido tal y como se solicitó
`SUSTITUIDO`	El producto solicitado se ha sustituido por otro. Se informa `productoOriginal`
`AGREGADO`	Línea añadida durante la preparación, no presente en el pedido original
`PARCIAL`	Se ha servido una cantidad inferior a la solicitada
`CAMBIO_PESO`	Producto al peso servido con un peso distinto al solicitado

Note

Los productos solicitados que no han podido servirse no generan línea de albarán, por lo que no se informan en lineas.

Promociones de cabecera

El nodo promociones contiene, en una única lista, todas las promociones aplicadas al total del albarán. Cada elemento es un Bloque Promoción y el campo tipo indica su naturaleza:

Valor de “tipo”	Descripción
`OFERTA`	Oferta aplicada al albarán
`CUPON`	Cupón aplicado al albarán
`CODIGO_PROMOCIONAL`	Código promocional aplicado al albarán

Note

En el JSON de pedido las ofertas y los cupones se informan en dos listas separadas (ofertas y cupones) y los códigos promocionales no se informan. En el albarán los tres casos se unifican en la lista promociones.

Tipo Bundle

Cada elemento de bundles representa un conjunto (bundle) aplicado al albarán, con el desglose del reparto del descuento entre sus grupos y productos.

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Promociones “promociones”	Promoción que ha originado el bundle	Lista de Bloque Promoción	Sí
Precio original “importes.precioOriginal”	Importe del conjunto antes de aplicar el descuento	Numérico decimal (formato 0.00)	Sí
Precio final “importes.precioFinal”	Importe del conjunto después de aplicar el descuento	Numérico decimal (formato 0.00)	Sí
Descuento “importes.descuento”	Importe de descuento aplicado al conjunto	Numérico decimal (formato 0.00)	Sí
Grupos “grupos”	Grupos que componen el conjunto	Lista de Tipo Grupo	Sí

Tipo Grupo

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Descripción “descripcion”	Nombre del grupo	Literal (255 caracteres máx.)	Sí
Unidades mínimas “unidadesMinimas”	Unidades mínimas necesarias del grupo	Numérico decimal (formato 0.00)	Sí
Productos distintos mínimos “productosDistintosMinimos”	Número mínimo de productos distintos necesarios del grupo	Numérico entero	No
Porcentaje de descuento “reparto.porcentajeDescuento”	Porcentaje de descuento repartido al grupo	Numérico decimal (formato 0.00)	Sí
Importe neto “reparto.importeNeto”	Importe del grupo una vez aplicado el descuento repartido	Numérico decimal (formato 0.00)	Sí
Descuento neto “reparto.descuentoNeto”	Importe de descuento repartido al grupo	Numérico decimal (formato 0.00)	Sí
Productos “productos”	Productos que componen el grupo	Lista de Tipo Producto de Grupo	Sí

Tipo Producto de Grupo

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Producto “producto”	Producto que participa en el grupo	Bloque Producto	Sí
Unidades mínimas “unidadesMinimas”	Unidades mínimas necesarias del producto	Numérico decimal (formato 0.00)	Sí
Prioridad “prioridad”	Prioridad del producto dentro del grupo	Numérico entero	No
Cantidad “cantidad”	Cantidad del producto que participa en el conjunto	Numérico decimal (formato 0.00)	Sí
Precio “precio”	Precio del producto antes del descuento	Numérico decimal (formato 0.00)	Sí
Descuento “descuento”	Importe de descuento repartido al producto	Numérico decimal (formato 0.00)	Sí

El bundle es un desglose informativo

El descuento de un bundle ya está recogido en el campo descuentos.inmediato de las líneas afectadas y en los importes del documento. La información de bundles es el desglose de cómo se ha repartido ese descuento y no debe volver a aplicarse sobre los importes.

Tipo Regalo

Cada elemento de regalos representa un producto de regalo asociado al albarán.

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Código “producto.codigo”	Código interno del producto de regalo	Literal (50 caracteres máx.)	Sí
Descripción “producto.descripcion”	Descripción corta del producto de regalo	Literal (500 caracteres máx.)	Sí
Descripción larga “producto.descripcionLarga”	Descripción larga del producto de regalo	Literal (255 caracteres máx.)	No
Marca “producto.marca”	Marca del producto de regalo	Literal (100 caracteres máx.)	No
EAN “producto.ean”	Código EAN del producto de regalo	Literal (20 caracteres máx.)	No
Formato “producto.formato”	Formato de presentación del producto	Literal (50 caracteres máx.)	No
Imagen “producto.imagen”	Imagen del producto de regalo	Literal (256 caracteres máx.)	No
Tipo de producto “producto.tipo.codigo”	Identificador del tipo de producto	Numérico entero	No
Nombre del tipo de producto “producto.tipo.descripcion”	Descripción del tipo de producto	Literal (30 caracteres máx.)	No
Cantidad “cantidad”	Cantidad de regalo	Numérico decimal (formato 0.00)	Sí
Unidad medida “unidadMedida”	Unidad de medida en la cual se expresa la cantidad	Literal (10 caracteres máx.)	Sí
Unidad medida del precio unitario “unidadMedidaPrecioUnitario”	Unidad de medida unitaria utilizada para el cálculo del precio	Literal (10 caracteres máx.)	No
Impuesto “impuesto”	Impuesto aplicado al producto de regalo	Bloque Impuesto	Sí
Precio unitario “precioUnitario”	Precio unitario del regalo. Habitualmente 0	Numérico decimal (formato 0.00)	Sí
Precio original “precioOriginal”	Precio del producto antes de aplicarse la promoción de regalo	Numérico decimal (formato 0.00)	Sí
Aceptado “aceptado”	Indicador de si el cliente ha aceptado el regalo	Booleano	Sí
Grupo picking “picking.grupo”	Grupo de picking del producto	Numérico entero	No
Orden picking 1 “picking.orden1”	Orden del producto en la lista de picking dentro de su grupo	Numérico entero	No
Orden picking 2 “picking.orden2”	Orden del producto en la lista de picking dentro de su grupo	Numérico entero	No
Orden picking 3 “picking.orden3”	Orden del producto en la lista de picking dentro de su grupo	Numérico entero	No
Promociones “promociones”	Promoción que ha originado el regalo. Como máximo un elemento	Lista de Bloque Promoción	Sí

Tipo Importes

Los totales del documento se informan dos veces con la misma estructura: en importes.pedido, con los importes correspondientes al pedido original, y en importes.real, con los importes resultantes de la valoración del albarán. Es este último el que refleja lo que se cobra al cliente.

Campo “Nombre campo”	Descripción/Ejemplo	Formato	Oblig.
Total productos “productos”	Importe totalizado de los productos, aplicados los descuentos inmediatos de línea	Numérico decimal (formato 0.00)	Sí
Gastos de envío “envio”	Importe de los gastos de envío	Numérico decimal (formato 0.00)	Sí
Impuesto de envío “impuestoEnvio”	Impuesto correspondiente a los gastos de envío	Numérico decimal (formato 0.00)	Sí
Gastos de manipulación “manipulacion”	Importe de los gastos de manipulación	Numérico decimal (formato 0.00)	Sí
Descuento de cupones “descuentoCupones”	Importe total de descuento aplicado por cupones al total del albarán	Numérico decimal (formato 0.00)	Sí
Importe “importe”	Importe total del albarán	Numérico decimal (formato 0.00)	Sí
Subtotal “subtotal”	Importe de los productos una vez aplicados los descuentos de cupones	Numérico decimal (formato 0.00)	Sí
Total “total”	Importe total del albarán. En el bloque `real` es el importe que se cobra al cliente	Numérico decimal (formato 0.00)	Sí

Gastos de envío y de manipulación

A diferencia del JSON de pedido, que los informa agrupados en un único campo (gastoEntregaOManipulacion), el albarán informa los gastos de envío (envio) y los de manipulación (manipulacion) en campos separados.

ANEXOS. Ejemplos json

Ejemplo albaran

Ejemplo de albarán que incluye una sustitución, un cambio de peso, una entrega parcial, un bundle, un regalo y un código promocional con descuento diferido.

{
  "version": "1.0",
  "documento": {
    "tipo": "ALBARAN",
    "codigo": "ALB-2026-000123",
    "estado": "PREPARADO",
    "fechaCreacion": "2026-08-10T08:30:00Z",
    "fechaRecalculo": "2026-08-10T09:15:00Z",
    "numeroLineas": 6,
    "pedido": {
      "codigo": 99871
    }
  },
  "cliente": {
    "codigoUsuario": "48512",
    "nombre": "María",
    "apellido1": "García",
    "apellido2": "Pérez",
    "email": "maria.garcia@example.com",
    "telefono1": "600111222",
    "telefono2": "961234567",
    "documento": {
      "tipo": "DNI",
      "numero": "12345678Z"
    },
    "direcciones": {
      "usuario": {
        "tipoVia": "CL",
        "nombreVia": "Mayor",
        "numero": "12",
        "escalera": "B",
        "piso": "3",
        "letra": "A",
        "ascensor": true,
        "codigoPostal": "46001",
        "localidad": "Valencia",
        "provincia": "Valencia",
        "codigoPais": 34
      },
      "entrega": {
        "tipoVia": "CL",
        "nombreVia": "Mayor",
        "numero": "12",
        "escalera": "B",
        "piso": "3",
        "letra": "A",
        "codigoPostal": "46001",
        "localidad": "Valencia",
        "provincia": "Valencia"
      },
      "factura": {
        "cif": "B12345678",
        "razonSocial": "Ejemplo Comercio SL",
        "recargoEquivalencia": false,
        "direccion": {
          "tipoVia": "AV",
          "nombreVia": "del Puerto",
          "numero": "5",
          "piso": "1",
          "letra": "C",
          "ascensor": true,
          "codigoPostal": "46021",
          "localidad": "Valencia",
          "provincia": "Valencia",
          "codigoPais": 34
        }
      }
    }
  },
  "entrega": {
    "tipo": "DOMICILIO",
    "domicilio": true,
    "zona": {
      "codigo": 1,
      "nombre": "Valencia Centro",
      "envio": {
        "codigo": "Z01",
        "nombre": "Valencia Área 1"
      }
    },
    "fecha": "2026-08-11T00:00:00Z",
    "franja": {
      "inicio": "10:00",
      "fin": "12:00"
    }
  },
  "pagos": [
    {
      "formaPago": {
        "codigo": 4,
        "descripcion": "Tarjeta de crédito"
      },
      "estado": "COBRADO",
      "codigoAutorizacion": "AUTH-778812",
      "importeCobrado": 36.56,
      "fechaCobro": "2026-08-10T09:20:00Z",
      "datosAdicionales": [
        {
          "nombre": "transactionId",
          "valor": "TX-8891123"
        },
        {
          "nombre": "cardBrand",
          "valor": "VISA"
        },
        {
          "nombre": "cardLastDigits",
          "valor": "4242"
        }
      ]
    }
  ],
  "lineas": [
    {
      "producto": {
        "codigo": "100234",
        "descripcion": "Aceite de oliva virgen extra 1L"
      },
      "unidadMedida": "UN",
      "impuesto": {
        "tipo": 2,
        "porcentaje": 10.0
      },
      "pedido": {
        "cantidad": 2,
        "precioMedio": 6.50,
        "importe": 13.00
      },
      "real": {
        "cantidad": 2,
        "precioMedio": 6.50,
        "importe": 13.00
      },
      "descuentos": {
        "inmediato": 1.30,
        "diferido": 0
      },
      "desviacion": {
        "tipo": "OK"
      },
      "promociones": [
        {
          "tipo": "OFERTA",
          "codigo": "OF-3311",
          "codigoPromocion": "PROMO-10PCT-ACEITE",
          "codigoPromocionExterno": "EXT-441",
          "descripcion": "10% de descuento en aceite de oliva",
          "descuento": {
            "tipo": "PORCENTAJE",
            "valor": 10.0,
            "inmediato": 1.30,
            "diferido": 0
          }
        }
      ]
    },
    {
      "producto": {
        "codigo": "200817",
        "descripcion": "Plátano de Canarias granel"
      },
      "unidadMedida": "KG",
      "impuesto": {
        "tipo": 1,
        "porcentaje": 4.0
      },
      "pedido": {
        "cantidad": 1.000,
        "precioMedio": 2.19,
        "importe": 2.19
      },
      "real": {
        "cantidad": 0.850,
        "precioMedio": 2.19,
        "importe": 1.86
      },
      "descuentos": {
        "inmediato": 0,
        "diferido": 0
      },
      "desviacion": {
        "tipo": "CAMBIO_PESO",
        "descripcion": "Peso real servido 0,850 kg"
      }
    },
    {
      "producto": {
        "codigo": "300455",
        "descripcion": "Leche entera brick 1L pack 6 - Marca Blanca"
      },
      "unidadMedida": "UN",
      "impuesto": {
        "tipo": 1,
        "porcentaje": 4.0
      },
      "pedido": {
        "cantidad": 1,
        "precioMedio": 5.40,
        "importe": 5.40
      },
      "real": {
        "cantidad": 1,
        "precioMedio": 5.75,
        "importe": 5.75
      },
      "descuentos": {
        "inmediato": 0,
        "diferido": 0
      },
      "desviacion": {
        "tipo": "SUSTITUIDO",
        "descripcion": "Producto original sin stock, sustituido por equivalente",
        "productoOriginal": {
          "codigo": "300450",
          "descripcion": "Leche entera brick 1L pack 6 - Central Lechera"
        }
      }
    },
    {
      "producto": {
        "codigo": "400122",
        "descripcion": "Detergente líquido 40 lavados"
      },
      "unidadMedida": "UN",
      "impuesto": {
        "tipo": 3,
        "porcentaje": 21.0
      },
      "pedido": {
        "cantidad": 1,
        "precioMedio": 9.95,
        "importe": 9.95
      },
      "real": {
        "cantidad": 1,
        "precioMedio": 9.95,
        "importe": 9.95
      },
      "descuentos": {
        "inmediato": 1.50,
        "diferido": 0
      },
      "desviacion": {
        "tipo": "OK"
      },
      "promociones": [
        {
          "tipo": "OFERTA",
          "codigo": "OF-9001",
          "codigoPromocion": "PROMO-PACK-LIMPIEZA",
          "descripcion": "Pack limpieza: detergente + suavizante",
          "descuento": {
            "tipo": "IMPORTE",
            "valor": 1.50,
            "inmediato": 1.50,
            "diferido": 0
          }
        }
      ]
    },
    {
      "producto": {
        "codigo": "400987",
        "descripcion": "Suavizante concentrado 1L"
      },
      "unidadMedida": "UN",
      "impuesto": {
        "tipo": 3,
        "porcentaje": 21.0
      },
      "pedido": {
        "cantidad": 1,
        "precioMedio": 4.55,
        "importe": 4.55
      },
      "real": {
        "cantidad": 1,
        "precioMedio": 4.55,
        "importe": 4.55
      },
      "descuentos": {
        "inmediato": 0.70,
        "diferido": 0
      },
      "desviacion": {
        "tipo": "OK"
      },
      "promociones": [
        {
          "tipo": "OFERTA",
          "codigo": "OF-9001",
          "codigoPromocion": "PROMO-PACK-LIMPIEZA",
          "descripcion": "Pack limpieza: detergente + suavizante",
          "descuento": {
            "tipo": "IMPORTE",
            "valor": 0.70,
            "inmediato": 0.70,
            "diferido": 0
          }
        }
      ]
    },
    {
      "producto": {
        "codigo": "500011",
        "descripcion": "Yogur natural pack 4"
      },
      "unidadMedida": "UN",
      "impuesto": {
        "tipo": 1,
        "porcentaje": 4.0
      },
      "pedido": {
        "cantidad": 3,
        "precioMedio": 1.85,
        "importe": 5.55
      },
      "real": {
        "cantidad": 2,
        "precioMedio": 1.85,
        "importe": 3.70
      },
      "descuentos": {
        "inmediato": 0,
        "diferido": 0
      },
      "desviacion": {
        "tipo": "PARCIAL",
        "descripcion": "Servidas 2 de 3 unidades solicitadas"
      }
    }
  ],
  "promociones": [
    {
      "tipo": "OFERTA",
      "codigo": "OF-3311",
      "codigoPromocion": "PROMO-10PCT-ACEITE",
      "codigoPromocionExterno": "EXT-441",
      "descripcion": "10% de descuento en aceite de oliva",
      "descuento": {
        "tipo": "PORCENTAJE",
        "valor": 10.0,
        "inmediato": 1.30,
        "diferido": 0
      }
    },
    {
      "tipo": "OFERTA",
      "codigo": "OF-9001",
      "codigoPromocion": "PROMO-PACK-LIMPIEZA",
      "descripcion": "Pack limpieza: detergente + suavizante",
      "descuento": {
        "tipo": "IMPORTE",
        "valor": 2.20,
        "inmediato": 2.20,
        "diferido": 0
      }
    },
    {
      "tipo": "CUPON",
      "codigo": "SUMMER2",
      "codigoPromocion": "PROMO-2026-08",
      "codigoPromocionExterno": "EXT-552",
      "descripcion": "2 € de descuento en tu compra",
      "descuento": {
        "tipo": "IMPORTE",
        "valor": 2.00,
        "inmediato": 2.00,
        "diferido": 0
      }
    },
    {
      "tipo": "CUPON",
      "codigo": "REGALO-BOLSA",
      "codigoPromocion": "PROMO-REGALO-BOLSA",
      "descripcion": "Bolsa reutilizable de regalo",
      "descuento": {
        "tipo": "IMPORTE",
        "valor": 0,
        "inmediato": 0,
        "diferido": 0
      }
    },
    {
      "tipo": "CODIGO_PROMOCIONAL",
      "codigo": "VERANO26",
      "codigoPromocion": "PROMO-VERANO-2026",
      "descripcion": "5% en monedero para tu próxima compra",
      "descuento": {
        "tipo": "PORCENTAJE",
        "valor": 5.0,
        "inmediato": 0,
        "diferido": 1.77
      }
    }
  ],
  "bundles": [
    {
      "promociones": [
        {
          "tipo": "OFERTA",
          "codigo": "OF-9001",
          "codigoPromocion": "PROMO-PACK-LIMPIEZA",
          "descripcion": "Pack limpieza: detergente + suavizante",
          "descuento": {
            "tipo": "IMPORTE",
            "valor": 2.20,
            "inmediato": 2.20,
            "diferido": 0
          }
        }
      ],
      "importes": {
        "precioOriginal": 14.50,
        "precioFinal": 12.30,
        "descuento": 2.20
      },
      "grupos": [
        {
          "descripcion": "Detergente",
          "unidadesMinimas": 1,
          "productosDistintosMinimos": 1,
          "reparto": {
            "porcentajeDescuento": 15.08,
            "importeNeto": 8.45,
            "descuentoNeto": 1.50
          },
          "productos": [
            {
              "producto": {
                "codigo": "400122",
                "descripcion": "Detergente líquido 40 lavados"
              },
              "unidadesMinimas": 1,
              "prioridad": 1,
              "cantidad": 1,
              "precio": 9.95,
              "descuento": 1.50
            }
          ]
        },
        {
          "descripcion": "Suavizante",
          "unidadesMinimas": 1,
          "productosDistintosMinimos": 1,
          "reparto": {
            "porcentajeDescuento": 15.38,
            "importeNeto": 3.85,
            "descuentoNeto": 0.70
          },
          "productos": [
            {
              "producto": {
                "codigo": "400987",
                "descripcion": "Suavizante concentrado 1L"
              },
              "unidadesMinimas": 1,
              "prioridad": 1,
              "cantidad": 1,
              "precio": 4.55,
              "descuento": 0.70
            }
          ]
        }
      ]
    }
  ],
  "regalos": [
    {
      "producto": {
        "codigo": "900001",
        "descripcion": "Bolsa reutilizable",
        "descripcionLarga": "Bolsa reutilizable de rafia 40x30 cm",
        "marca": "Marca Blanca",
        "ean": "8412345678901",
        "formato": "1 UN",
        "imagen": "https://static.example.com/products/900001.jpg",
        "tipo": {
          "codigo": 1,
          "descripcion": "Producto seco"
        }
      },
      "cantidad": 1,
      "unidadMedida": "UN",
      "unidadMedidaPrecioUnitario": "UN",
      "impuesto": {
        "tipo": 3,
        "porcentaje": 21.0
      },
      "precioUnitario": 0,
      "precioOriginal": 1.20,
      "aceptado": true,
      "picking": {
        "grupo": 4,
        "orden1": 12,
        "orden2": 3,
        "orden3": 1
      },
      "promociones": [
        {
          "tipo": "CUPON",
          "codigo": "REGALO-BOLSA",
          "codigoPromocion": "PROMO-REGALO-BOLSA"
        }
      ]
    }
  ],
  "importes": {
    "pedido": {
      "productos": 37.14,
      "envio": 3.40,
      "impuestoEnvio": 0.59,
      "manipulacion": 0,
      "descuentoCupones": 2.00,
      "importe": 38.54,
      "subtotal": 35.14,
      "total": 38.54
    },
    "real": {
      "productos": 35.31,
      "envio": 3.25,
      "impuestoEnvio": 0.56,
      "manipulacion": 0,
      "descuentoCupones": 2.00,
      "importe": 36.56,
      "subtotal": 33.31,
      "total": 36.56
    }
  }
}

Gestión de versiones

Versión	Cambios
1.0	Versión inicial del JSON de albarán valorado