Endpoints para Factura

Esta API ofrece endpoints para consultar, crear o eliminar facturas. Una factura almacena información detallada sobre una transacción de venta, incluyendo datos del cliente, agente que efectúa la venta, productos o servicios vendidos, y montos correspondientes.

Características comunes de las facturas

1. Identificador único: La entidad Invoice consta de un identificador único que sirve para distinguirlo de las demás facturas y referenciarla con facilidad. Además cuenta con un campo idRemote, que hace referencia al id que puede estar almacenado en la base de datos del ERP del cliente.

2. Compañía: Es necesario relacionar la factura con la compañía que emite la factura.

3. Cliente: Debe haber un cliente asociado con cada factura. El cliente es un socio comercial con el rol de Client.

4. Agente: Además, una factura debe tener un agente asociado. Este es el representante de la empresa que ha realizado la venta. Un agente es un socio comercial con el rol de Representant.

5. Temporada: Así mismo, una factura debe tener una Temporada relacionada. Esto sirve para obtener informes de facturas por temporada.

6. Descuento: Una factura puede tener descuentos asociados.

7. Líneas: Una factura 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. Las líneas tienen un estado en el que se especifica si está en stock, si está enviado o no, o si ha sido eliminado. Las líneas a su vez incluyen información sobre los productos y posibles descuentos.

Endpoints

GET/Invoice/getInvoice

Recuperar una lista paginada con las facturas existentes en la base de datos.

Descripción

Permite obtener una lista con las facturas organizadas según los parámetros de paginación:

Parámetros

Nombre	Descripción	Tipo	Valor por defecto
page	Número de página	Integer	1
pageSize	Elementos 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",
      "status": "string",
      "order": {
        "id": "string",
        "idRemote": "string"
      },
      "season": {
        "id": "string",
        "idRemote": "string",
        "description": "string",
        "seasonPos": 0,
        "seasonType": "string",
        "active": true
      },
      "billingAddress": "string",
      "discount": [
        {
          "id": "string",
          "idRemote": "string",
          "discountType": {
            "id": "string",
            "name": "string",
            "code": "string",
            "description": "string"
          },
          "sequence": 0,
          "discount": 0,
          "amountDiscount": 0,
          "isHeader": true
        }
      ],
      "dueDate": [
        {
          "id": "string",
          "idRemote": "string",
          "due_date": 0,
          "amount": 0
        }
      ],
      "lines": [
        {
          "id": "string",
          "idRemote": "string",
          "lineStatus": "string",
          "discount": [
            {
              "id": "string",
              "idRemote": "string",
              "discount": 0,
              "amountDiscount": 0
            }
          ],
          "observations": "string",
          "deliveryDate": "string",
          "cancellationDate": "string",
          "lineAmount": 0,
          "quantity": 0,
          "lineDetail": [
            {
              "productId": "string",
              "quantity": 0,
              "price": 0
            }
          ]
        }
      ],
      "invoiceDate": "string",
      "valueDate": "string",
      "grossAmount": 0,
      "baseAmount": 0,
      "shippingAmount": 0,
      "taxAmount": 0,
      "taxrecAmount": 0,
      "totalAmount": 0,
      "totalQuantity": 0,
      "totalWeight": 0,
      "totalPacks": 0,
      "baseCommission": 0,
      "percentCommission": 0,
      "totalCommission": 0,
      "invoicePaid": true,
      "invoiceSettled": true,
      "pendingAmount": 0,
      "unpaidAmount": 0,
      "paymentDate": "string",
      "createdAt": "string",
      "updatedAt": "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>
      <status>string</status>
      <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>
      <billingAddress>string</billingAddress>
      <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>
      <dueDate>
        <id>string</id>
        <idRemote>string</idRemote>
        <due_date>0</due_date>
        <amount>0</amount>
      </dueDate>
      <lines>
        <id>string</id>
        <idRemote>string</idRemote>
        <lineStatus>string</lineStatus>
        <discount>
          <id>string</id>
          <idRemote>string</idRemote>
          <discount>0</discount>
          <amountDiscount>0</amountDiscount>
        </discount>
        <observations>string</observations>
        <deliveryDate>string</deliveryDate>
        <cancellationDate>string</cancellationDate>
        <lineAmount>0</lineAmount>
        <quantity>0</quantity>
        <lineDetail>
          <productId>string</productId>
          <quantity>0</quantity>
          <price>0</price>
        </lineDetail>
      </lines>
      <invoiceDate>string</invoiceDate>
      <valueDate>string</valueDate>
      <grossAmount>0</grossAmount>
      <baseAmount>0</baseAmount>
      <shippingAmount>0</shippingAmount>
      <taxAmount>0</taxAmount>
      <taxrecAmount>0</taxrecAmount>
      <totalAmount>0</totalAmount>
      <totalQuantity>0</totalQuantity>
      <totalWeight>0</totalWeight>
      <totalPacks>0</totalPacks>
      <baseCommission>0</baseCommission>
      <percentCommission>0</percentCommission>
      <totalCommission>0</totalCommission>
      <invoicePaid>true</invoicePaid>
      <invoiceSettled>true</invoiceSettled>
      <pendingAmount>0</pendingAmount>
      <unpaidAmount>0</unpaidAmount>
      <paymentDate>string</paymentDate>
      <createdAt>string</createdAt>
      <updatedAt>string</updatedAt>
    </item>
  </data>
  <pagination>
    <totalItems>0</totalItems>
    <itemsPerPage>0</itemsPerPage>
    <currentPage>0</currentPage>
    <totalPages>0</totalPages>
    <nextPageUrl>string</nextPageUrl>
  </pagination>
</export>

👉Prueba este endpoint🌱

GET/Invoice/getInvoice/Status

Recupera una lista paginada con los identificadores y descripción de los estados disponibles para asignar a las facturas.

Descripción

Se muestran de manera paginada los identificadores local y remoto junto con la descripción del estado. Se puede modificar la paginación a través de estos parámetros:

Parámetros

Nombre	Descripción	Tipo	Valor por defecto
page	Número de página	Integer	1
pageSize	Elementos por página	Integer	10

Respuestas

JSON

  {
    "data": [
        {
        "id": "string",
        "idRemote": "string",
        "description": true
        }
    ],
    "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>
      <description>true</description>
    </item>
  </data>
  <pagination>
    <totalItems>0</totalItems>
    <itemsPerPage>0</itemsPerPage>
    <currentPage>0</currentPage>
    <totalPages>0</totalPages>
    <nextPageUrl>string</nextPageUrl>
  </pagination>
</export>

👉Prueba este endpoint🌱

GET/Invoice/getInvoice/Line/Status

Recupera una lista paginada con los identificadores y descripción de los estados disponibles para las líneas de las facturas.

Descripción

Se muestran de manera paginada los identificadores local y remoto junto con la descripción del estado. Se puede modificar la paginación a través de estos parámetros:

Parámetros

Nombre	Descripción	Tipo	Valor por defecto
page	Número de página	Integer	1
pageSize	Elementos por página	Integer	10

Respuestas

JSON

  {
    "data": [
        {
        "id": "string",
        "idRemote": "string",
        "description": true
        }
    ],
    "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>
      <description>true</description>
    </item>
  </data>
  <pagination>
    <totalItems>0</totalItems>
    <itemsPerPage>0</itemsPerPage>
    <currentPage>0</currentPage>
    <totalPages>0</totalPages>
    <nextPageUrl>string</nextPageUrl>
  </pagination>
</export>

👉Prueba este endpoint🌱

POST/Invoice/create

Factores a tener en cuenta

Para la creación de una nueva factura debe tener en cuenta los siguientes factores:

1. Compañía: Antes de registrar una factura, 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🌱

2. Socio Comercial Cliente: Asegúrese de que el Socio Comercial que va a asignar a la factura en el parámetro clientId tiene el rol Client y pertenece a la misma Compañía que la emisora de la factura. 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🌱

3. Socio Comercial Agente: Es crucial que se asegure de que el Socio Comercial que va a asignar a la factura en el parámetro agentId tiene el rol Representant y pertenece a la misma Compañía que la emisora de la Factura. 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🌱

4. Pedido: Es necesario asegurarse de que el Pedido que va a asociar a la Factura 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 la Factura 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🌱

5. 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 link: 👉Crear una Temporada🌱

6. Estado de la Factura: La referencia al Estado de la factura debe existir en el sistema. Para ver los estados disponibles para las Facturas puede utilizar el endpoint descrito más arriba en esta documentación.

7. Dirección de facturación Debe adjuntar la dirección de facturación en el momento de creación de una nueva factura. Este campo es un id que referencia a una entidada Localización. Debe adjuntar un id existente en el sistema, que además pertenezca al Socio Comercial al que va dirigida la factura. Además la Localización que corresponde con la dirección de facturación debe tener el campo billingAddress configurado a true. Las localizaciones pueden ser configuradas a través de los endpoints para Localizaciones o en el momento de creación de un nuevo Socio Comercial. 👉Creación de socio comercial🌱 👉Endpoints para localizaciones🌱

8. Descuentos: Los descuentos no son un parámetro obligatorio. Para introducir en el sistema una factura 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.

9. Fecha de vencimiento: Se pueden establecer fechas de vencimiento para las facturas. La fecha debe introducirse en un formato válido. Por ejemplo: 2024-10-10 01:01:01.

10. Líneas: Una factura está formada por líneas. Las líneas se relacionan con el producto objeto de venta a través del campo lineDetails, en el que hay que adjuntar un Producto existente en el sistema. Además cada línea se relaciona con un Estado (lineStatusId) y con un Albarán (deliveryNoteId). 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 una factura descrito anteriormente.

Parámetros obligatorios

Nombre	Descripción	Tipo
idRemote	Identificador de la nueva Factura	String
reference	Referencia de la nueva Factura	String
companyId	Identificador de la Compañía a la que pertenece la nueva Factura	String
clientId	Identificador del Socio Comercial con rol cliente	String
agentId	Identificador del Socio Comercial con rol agente	String
orderId	Identificador del Pedido asociado a la nueva factura	String
billingAddressId	Identificador de la Localización para facturación de la Factura	String
invoiceStatusId	Identificador del estado de la Factura	String
lines	Líneas que forman la Factura. Contienen información detallada sobre la misma	Array
invoiceDate	Fecha de emisión de la factura. Debe estar en formato 2024-10-10 01:01:01	String
valueDate	Debe estar en formato 2024-10-10 01:01:01	String
grossAmount	Importe bruto de la Factura	Decimal
baseAmount	Importe bruto de la factura	Decimal
shippingAmount	Importe de los gastos de envío de la Factura	Decimal
taxAmount	Importe de los impuestos de la Factura	Decimal
taxrecAmount		Decimal
totalAmount	Importe total de la Factura	Decimal
totalQuantity	Cantidad total de productos en la Factura	Decimal
totalWeight	Peso total de los bultos a facturar	Decimal
totalPacks	Número total de bultos a facturar	Decimal
baseCommission	Comisión base	Decimal
percentCommission	Porcentaje de comisión	Decimal
totalCommission	Total comisión	Decimal
invoicePaid	Determina si la Factura está pagada o no	Boolean
invoiceSettled	Determina si la Factura ha sido establecida o no	Boolean
pendingAmount	Importe pendiente de pago de la factura	Decimal
unpaidAmount	Importe sin pagar de la factura	Decimal

Parámetros obligatorios en las Líneas

El programa está diseñado para inicializar algunos atributos si no se adjuntan valores para los mismos. Puedes asociar las líneas a un Albarán para relacionar la Factura con un Albarán.

Nombre	Descripción	Tipo
lineStatusId	Identificador del Estado de la Linea de la Factura	String

Las líneas pueden contener Descuentos y Detalles de Línea.

Todos los atributos del Detalle de línea son opcionales, a excepción del productId

El cuerpo de una solicitud de creación de Factura completo debe seguir el siguiente esquema:

[
  {
      "idRemote": "string",
      "companyId": "string",
      "clientId": "string",
      "agentId": "string",
      "orderId": "string",
      "seasonId": "string",
      "invoiceStatusId": "string",
      "billingAddressId": "string",
      "reference": "string",
      "discount": [
      {
          "idRemote": "string",
          "discountType": "string",
          "sequence": 0,
          "discount": 0,
          "amountDiscount": 0,
          "isHeader": true
      }
      ],
      "dueDate": [
      {
          "idRemote": "string",
          "due_date": 0,
          "amount": 0
      }
      ],
      "lines": [
        {
          "idRemote": "string",
          "lineStatusId": "string",
          "deliveryNoteId": "string",
          "discount": [
          {
              "idRemote": "string",
              "discount": 0,
              "amountDiscount": 0
          }
          ],
          "observations": "string",
          "deliveryDate": "string",
          "cancellationDate": "string",
          "lineAmount": 0,
          "quantity": 0,
          "lineDetail": [
            {
              "productId": "string",
              "quantity": 0,
              "price": 0
            }
          ]
        }
      ],
      "invoiceDate": "string",
      "valueDate": "string",
      "grossAmount": 0,
      "baseAmount": 0,
      "shippingAmount": 0,
      "taxAmount": 0,
      "taxrecAmount": 0,
      "totalAmount": 0,
      "totalQuantity": 0,
      "totalWeight": 0,
      "totalPacks": 0,
      "shipper": "string",
      "baseCommission": 0,
      "percentCommission": 0,
      "totalCommission": 0,
      "invoicePaid": true,
      "invoiceSettled": true,
      "pendingAmount": 0,
      "unpaidAmount": 0,
      "paymentDate": "string"
  }
]

Es posible añadir varias facturas 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": "Invoice 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 invoice data format, a required parameter is missing"
}

👉Prueba este endpoint🌱

DELETEInvoice/delete/{id}

Eliminar una factura.

Descripción

Elimina una factura de la base de datos a través del identificador facilitado en los parámetros. Este campo id puede ser tanto el identificador generado por la base de datos del B2B como el idRemote que usted nos proporciona al registrar las facturas. La acción de eliminar una Factura elimina todas las líneas, descuentos, y fechas de vencimiento asociadas. Una vez eliminada, la Factura se registra en el Historial de Eliminados.

⚠️No se podrá eliminar una Factura que tenga líneas asociadas con un Albarán.

Parámetros

Nombre	Descripción	Tipo
id	Identificador de la orden	String

👉Prueba este enpoint🌱

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 registro.	404	{"code": 404,"error": "No entity found for Invoice with $id."}
Este error ocurre cuando intenta insertar un registro que ya existe	409	{"code": 409,"error": "Duplicate entry => Care with email and username"}
Este error ocurre cuando intenta enviar demasiadas solicitudes en un corto periodo de tiempo.	429	{"code": 429,"error": "Too Many Requests"}