Endpoints para Albarán

En el contexto de nuestra API, un albarán representa una entidad importante. Ha sido diseñado para identificar y registrar información clave sobre los albaranes. Este registro permite asignar compañías, clientes, temporadas y pedidos de forma eficiente y precisa.

Características Comunes de los Albaranes

Identificación Única: Cada albarán tiene un identificador único id que los distingue de otros albaranes en el sistema.
Datos de Albarán: Un albarán incluye información sobre el envío de un determinado pedido. Incluye datos como transportista, cantidad enviada, impuestos, peso, etc.
Compañía: Un albarán debe tener una compañía relacionada.
Cliente: Debe haber un cliente asociado con cada albarán. El cliente es un socio comercial con el rol de Client.
Agente: Además, un albarán debe tener un agente asociado. Este es el representante de la la empresa que ha realizado la venta. Un agente es un socio comercial con el rol de Sales Representative.
Temporada: Así mismo, un albarán debe tener una Temporada relacionada. Esto sirve para obtener informes de albaranes por temporada.
Descuentos: Un albarán puede tener descuentos asociados.
Líneas: Un albarán está formado por líneas. Cada línea del albarán se corresponde al producto o servicio solicitado. Las líneas almacenan información sobre la cantidad y precio de cada producto o servicio entregado.

Endpoints

GET/DeliveryNote/getDeliveryNote

Obtención de una Lista Paginada con todos los Albaranes en el sistema.

Descripción

Este endpoint recupera una lista paginada con todos los albaranes existenetes en el sistema. Permite a los clientes obtener datos de albaranes basados en parámetros de paginación como el número de página (page) y el número de ítems por página (pageSize). La respuesta incluye información detallada sobre cada albarán, incluyendo su id remoto y local, representante, marca de tiempo de última actualización e información de la compañía, del cliente, del pedido, de la temporada y del descuento.

Parámetros

Nombre	Descripción	Tipo	Valor Predeterminado
`page`	Número de página	Integer	1
`pageSize`	Número de ítems por página	Integer	10

Respuestas

JSON

  {
      "data": [
          {
          "id": "string",
          "idRemote": "string",
          "company": {
              "id": "string",
              "idRemote": "string",
              "companyName": "string"
          },
          "client": {
              "id": "string",
              "idRemote": "string",
              "contactName": "string"
          },
          "agent": "string",
          "order": {
              "id": "string",
              "idRemote": "string"
          },
          "season": {
              "id": "string",
              "idRemote": "string",
              "description": "string",
              "seasonPos": 0,
              "seasonType": "string",
              "active": true
          },
          "discount": [
            {
              "id": "string",
              "idRemote": "string",
              "discountType": {
                "id": "string",
                "name": "string",
                "code": "string",
                "description": "string"
              },
              "sequence": 0,
              "discount": 0,
              "amountDiscount": 0,
              "isHeader": true
            }
          ],
          "lines": [
            {
              "id": "string",
              "idRemote": "string",
              "product": {
                  "id": "string",
                  "idRemote": "string",
                  "reference": "string"
              },
              "order":{
                  "id": "string",
                  "idRemote": "string"
              },
              "discount": [
                  {
                  "id": "string",
                  "idRemote": "string",
                  "discount": "string",
                  "amountDiscount": "string"
                  }
              ],
              "lineAmount": 0,
              "quantity": 0,
              "price": 0
            }
          ],
          "shipper": "string",
          "packs": 0,
          "grossAmount": 0,
          "baseAmount": 0,
          "shippingAmount": 0,
          "taxAmount": 0,
          "taxrecAmount": 0,
          "totalAmount": 0,
          "totalQuantity": 0,
          "totalWeight": 0,
          "updatedAt": "string",
          "createdAt": "string",
          }
      ],
      "pagination": {
          "totalItems": 0,
          "itemsPerPage": 0,
          "currentPage": 0,
          "totalPages": 0,
          "nextPageUrl": "string"
      }
  }

XML

<?xml version="1.0" encoding="UTF-8"?>
<export>
  <data>
    <item>
      <id>string</id>
      <idRemote>string</idRemote>
      <company>
        <id>string</id>
        <idRemote>string</idRemote>
        <companyName>string</companyName>
      </company>
      <client>
        <id>string</id>
        <idRemote>string</idRemote>
        <contactName>string</contactName>
      </client>
      <agent>string</agent>
      <order>
        <id>string</id>
        <idRemote>string</idRemote>
      </order>
      <season>
        <id>string</id>
        <idRemote>string</idRemote>
        <description>string</description>
        <seasonPos>0</seasonPos>
        <seasonType>string</seasonType>
        <active>true</active>
      </season>
      <discount>
        <id>string</id>
        <idRemote>string</idRemote>
        <discountType>
          <id>string</id>
          <name>string</name>
          <code>string</code>
          <description>string</description>
        </discountType>
        <sequence>0</sequence>
        <discount>0</discount>
        <amountDiscount>0</amountDiscount>
        <isHeader>true</isHeader>
      </discount>
      <lines>
        <id>string</id>
        <idRemote>string</idRemote>
        <product>
          <id>string</id>
          <idRemote>string</idRemote>
          <reference>string</reference>
        </product>
        <order>
          <id>string</id>
          <idRemote>string</idRemote>
        </order>
        <discount>
          <id>string</id>
          <idRemote>string</idRemote>
          <discount>string</discount>
          <amountDiscount>string</amountDiscount>
        </discount>
        <lineAmount>0</lineAmount>
        <quantity>0</quantity>
        <price>0</price>
      </lines>
      <shipper>string</shipper>
      <packs>0</packs>
      <grossAmount>0</grossAmount>
      <baseAmount>0</baseAmount>
      <shippingAmount>0</shippingAmount>
      <taxAmount>0</taxAmount>
      <taxrecAmount>0</taxrecAmount>
      <totalAmount>0</totalAmount>
      <totalQuantity>0</totalQuantity>
      <totalWeight>0</totalWeight>
      <updatedAt>string</updatedAt>
      <createdAt>string</createdAt>
    </item>
  </data>
  <pagination>
    <totalItems>0</totalItems>
    <itemsPerPage>0</itemsPerPage>
    <currentPage>0</currentPage>
    <totalPages>0</totalPages>
    <nextPageUrl>string</nextPageUrl>
  </pagination>
</export>  

👉Prueba este endpoint🌱

POST/DeliveryNote/create

Factores a tener en cuenta

Este endpoint sirve para crear un nuevo albarán a través de los datos adjuntos en el cuerpo de la solicitud. Antes de crear un nuevo albarán debes tener en cuenta los siguientes factores:

Compañía: Antes de registrar un albarán, asegúrese de que exista la Compañía que va a asignarle. Si la compañía asignada no existe, la respuesta devolverá un error.
Para obtener más información sobre cómo crear una Compañía siga este enlace: 👉Crear una Compañía🌱
Socio Comercial Cliente: Asegúrese de que el Socio Comercial que va a asignar al albarán en el parámetro clientId tiene el rol Client y pertenece a la misma Compañía que la emisora del Albarán. En caso de adjuntar un Socio Comercial cliente erróneo, la respuesta devolverá un error. Para obtener más información sobre cómo crear un Socio Comercial siga este enlace: 👉Crear un Socio Comercial🌱
Socio Comercial Agente (Representante): Es crucial que se asegure de que el Socio Comercial que va a asignar al albarán en el parámetro agentId tiene el rol Sales Representative y pertenece a la misma Compañía que la emisora del Albarán. En caso de adjuntar un agente erróneo, la respuesta devolverá un error. Para obtener más información sobre cómo crear un Socio Comercial siga este enlace: 👉Crear un Socio Comercial🌱
Pedido: Es necesario asegurarse de que el Pedido que va a asociar al albarán a través del parámetro orderId esté registrado en el sistema. Además la orden a asociar con el nuevo registro, debe pertenecer a la misma Compañía y Temporada que el albarán que desea crear. De lo contrario la respuesta devolverá una excepción. Para obtener más información acerca de la creación de Pedidos siga el siguiente enlace: 👉Crear un Pedido🌱
Temporada: Debe adjuntar una referencia correcta a una Temporada a través del parámetro seasonId. Puede encontrar información sobre como obtener las Temporadas existentes, o como registrar una nueva Temporada en el sistema a través de este enlace: 👉Crear una Temporada🌱
Descuentos: Los descuentos no son un parámetro obligatorio. Para introducir en el sistema un albarán sin descuentos, basta con adjuntar un array vacío. Puede establecer un idRemote para cada descuento. El sistema creará automáticamente un id local para cada nuevo descuento que cree de esta forma.
Líneas: El albarán está formado por líneas. Éstas incluyen información sobre el producto o servicio que se envía al cliente. Es por esto el Producto asociado con cada línea a través del parámetro productId debe existir en el sistema. Además cada línea se relaciona con un Pedido (orderId). A través de la creación de líneas puede asignar un idRemote a cada una. El sistema creará un id local automáticamente. Así mismo, puede asociar descuentos con cada línea del Albarán. El proceso de creación de descuentos para cada línea se corresponde con el proceso de creación de descuentos para el Albarán.

Parámetros obligatorios:

Nombre	Descripción	Tipo
`idRemote`	Identificador del nuevo Albarán	String
`companyId`	Identificador de la Compañía relacionada con el nuevo Albarán	String
`clientId`	Identificador del Socio Comercial con rol cliente relacionado con el nuevo Albarán	String
`agentId`	Identificador del Socio Comercial con rol agente relacionado con el nuevo Albarán	String
`orderId`	Identificador del Pedido asociado al nuevo Albarán	String
`lines`	Líneas del Albarán. Incluyen información detallada del contenido del nuevo Albarán	Array
`shipper`	Nombre de la empresa que realizará el envío	String
`packs`	Número de bultos	Integer
`grossAmount`	Importe bruto	Decimal
`baseAmount`	Importe base	Decimal
`totalAmount`	Importe total	Decimal
`totalQuantity`	Cantidad total de productos	Decimal

Si quieres añadir Descuentos al Albarán debes tener en cuenta que todos los parámetros son obligatorios.

Todos los parámetros de las líneas del Albarán son obligatorios a excepción de los Descuentos de Línea.

[
  {
  "idRemote": "string",
  "companyId": "string",
  "clientId": "string",
  "agentId": "string",
  "orderId": "string",
  "seasonId": "string",
  "discount": [
    {
      "idRemote": "string",
      "discountType": "string",
      "sequence": 0,
      "discount": 0,
      "amountDiscount": 0,
      "isHeader": true
    }
  ],
  "lines": [
    {
      "idRemote": "string",
      "productId": "string",
      "orderId": "string",
      "discount": [
          {
          "idRemote": "string",
          "discount": 0,
          "amountDiscount": 0
          }
      ],
      "lineAmount": 0,
      "quantity": 0,
      "price": 0
    }
  ],
  "shipper": "string",
  "packs": 0,
  "grossAmount": 0,
  "baseAmount": 0,
  "shippingAmount": 0,
  "taxAmount": 0,
  "taxrecAmount": 0,
  "totalAmount": 0,
  "totalQuantity": 0,
  "totalWeight": 0
  }
]

Es posible añadir varios albaranes a través de la misma solicitud separándolos con comas dentro del array en el cuerpo de la solicitud.

Respuestas

Con el fin de no saturar al servidor, este endpoint envía un mensaje a un consumidor encargado de procesar la petición. Para comprobar el estado de la solicitud enviada es necesario acceder a la url adjunta en la respuesta. Una respuesta correctamente enviada al consumidor debe parecerse a esta:

{
    "code": 201,
    "message": "Delivery note message created successfully and dispatched to the queue.",
    "statusUrl": "http://host/api/database/v1/message/status/messageId"
}  

El campo statusUrl nos redirige a una respuesta más detallada sobre el estado de la petición. Una solicitud correctamente procesada por el consumidor tiene el siguiente aspecto:

{
  "data": [
      {
        "status": "completed",
        "errorMessage": null
      }
    ],
      "pagination": {
      "totalItems": 1,
      "itemsPerPage": 10,
      "currentPage": 1,
      "totalPages": 1,
      "nextPageUrl": null
    }
}

En caso de producirse cualquier error durante el procesado del mensaje, la respuesta tendrá un aspecto similar a este:

{
"code": 400,
"error": "Invalid delivery note data format, a required parameter is missing"
}

👉Prueba este endpoint🌱

PUT/DeliveryNote/update/{id}

Actualización de Albaranes.

Descripción

Este endpoint permite a los clientes actualizar los datos de albaranes utilizando el parámetro id. Este id puede ser tanto el identificador generado por la base de datos del B2B como el idRemote que usted nos proporciona al registrar los albaranes. Esta flexibilidad asegura que pueda integrar y sincronizar fácilmente los datos existentes en su sistema con nuestra plataforma, garantizando una gestión eficiente y precisa de la información de los albaranes. A través de este endpoint puedes actualizar Descuentos o Líneas ya existentes en el Albarán objeto de actualización. Para ello basta con adjuntar el idRemote de la Línea o Descuento que desees modificar.

Parámetros

Nombre	Descripción	Tipo
`id`	Identificador de Albarán	String

No es necesario incluir toda la estructura JSON, solo debes incluir los atributos que quieras modificar.

Cuerpo de la solicitud

Una actualización de todos los campos de un Albarán debe lucir de así:

  {
      "companyId": "string",
      "clientId": "string",
      "agentId": "string",
      "orderId": "string",
      "seasonId": "string",
      "discount": [
        {
          "idRemote": "string",
          "discountType": "string",
          "sequence": 0,
          "discount": 0,
          "amountDiscount": 0,
          "isHeader": true
        }
      ],
      "lines": [
      {
          "idRemote": "string",
          "productId": "string",
          "orderId": "string",
          "discount": [
          {
              "idRemote": "string",
              "discount": 0,
              "amountDiscount": 0
          }
          ],
          "lineAmount": 0,
          "quantity": 0,
          "price": 0
      }
      ],
      "shipper": "string",
      "packs": 0,
      "grossAmount": 0,
      "baseAmount": 0,
      "shippingAmount": 0,
      "taxAmount": 0,
      "taxrecAmount": 0,
      "totalAmount": 0,
      "totalQuantity": 0,
      "totalWeight": 0
  }

👉Prueba este endpoint🌱

DELETE/DeliveryNote/delete/{id}

Eliminación de un Albarán.

Descripción

Este endpoint permite la eliminación de albaranes utilizando su identificador único, que puede ser tanto el id propio del sistema B2B como el idRemote proporcionado por usted al registrar los albaranes en nuestra plataforma. Eliminar un albarán, borra en cascada todas sus líneas y descuentos relacionados. Una vez eliminado, el Albarán se registra en el Historial de Eliminados.

⚠️No se podrá eliminar un Albarán si está relacionado con un Pedido o una Factura activa.

Parámetros

Nombre	Descripción	Tipo
`id`	Identificador de Albarán	String

👉Prueba este endpoint🌱

Posibles Errores en la Respuesta

Error	Código	Respuesta
Este error ocurre cuando no se puede establecer una conexión con la base de datos. Es un problema interno del servidor.	500	`{"code": 500,"error": "Database connection failed."}`
Este error ocurre cuando no puede insertar o actualizar y en la dbs de pruebas.	500	`{"code": 500,"error": "Invalid connection name, you cannot insert in default"}`
Este error indica que falta un parametro.	400	`{"code": 400,"error": "Parameter $parameter is required"}`
Este error indica que no está autorizado.	401	`{"code": 401,"error": "Unauthorized"}`
Este error indica que no ha sido posible encontrar el Albarán.	404	`{"code": 404,"error": "No entity found for Delivery Note with $id."}`
Este error ocurre cuando intenta insertar un albarán que ya existe.	409	`{"code": 409,"error": "Duplicate entry"}`
Este error ocurre cuando intenta enviar demasiadas solicitudes en un corto periodo de tiempo.	429	`{"code": 429,"error": "Too Many Requests"}`

Endpoints para Albarán

Características Comunes de los Albaranes​

Endpoints​

GET/DeliveryNote/getDeliveryNote​

Descripción​

Parámetros​

Respuestas​

JSON​

XML​

POST/DeliveryNote/create​

Factores a tener en cuenta​

Parámetros obligatorios:​

Respuestas​

PUT/DeliveryNote/update/{id}​

Descripción​

Parámetros​

Cuerpo de la solicitud​

DELETE/DeliveryNote/delete/{id}​

Descripción​

Parámetros​

Posibles Errores en la Respuesta​

Características Comunes de los Albaranes

Endpoints

GET/DeliveryNote/getDeliveryNote

Descripción

Parámetros

Respuestas

JSON

XML

POST/DeliveryNote/create

Factores a tener en cuenta

Parámetros obligatorios:

Respuestas

PUT/DeliveryNote/update/{id}

Descripción

Parámetros

Cuerpo de la solicitud

DELETE/DeliveryNote/delete/{id}

Descripción

Parámetros

Posibles Errores en la Respuesta