Debido al cierre de Kubbos algunos clientes no están consultando cómo exportar datos más allá de las opciones disponibles en la exportación de PDFs y CSVs o de la exportación completa desde el área de administración. En este artículo vamos a explicar cómo utilizar la API para hacerlo con un ejemplo práctico.

Autenticación

Para autenticarse en la API hay que realizar una petición al endpoint de autenticación con nuestro usuario y contraseña. La respuesta devolverá una cookie HTTP (llamada “auth”) la cual tendremos que guardar y reenviar en las peticiones sucesivas a la API.

A continuación mostramos un ejemplo de autenticación y una petición posterior utilizando la herramienta cURL en Linux. Para otras plataformas o lenguajes de programación habrá que utilizar otras utilidades y/o librerías.

curl --request POST 'https://www.kubbos.com/api/j_security_check' \ --header 'content-type: application/x-www-form-urlencoded; charset=UTF-8' \ --cookie-jar /ruta/a/fichero_de_cookies \ --data-urlencode 'j_username=USUARIO' \ --data-urlencode 'j_password=PASSWORD'

curl --request POST 'https://www.kubbos.com/api/customerInvoices.list.kson' \ --header 'content-type: application/json;charset=utf-8' \
--cookie /ruta/a/fichero_de_cookies \ --data-raw '{"sort":"sentDate","dir":"DESC","limit":20}'

En el primer paso usamos el parámetro “cookie-jar” para pasar la ruta a un fichero donde cURL guardará nuestras cookies (el fichero no tiene que existir previamente, lo crea la herramienta)En el segundo paso usamos el parámetro “cookie”, que usa las cookies de ese mismo fichero para la autenticación, y recuperamos una lista de facturas.

Extracción de entidades secundarias

Vamos a ver un ejemplo de cómo, mediante la API de Kubbos, podemos extraer información de entidades de que no sean diréctamente exportables en los listados la plataforma. Necesitaremos de algunos conocimientos técnicos así como de algún lenguaje de programación que nos permita acceder a la API.

Detectar la entidad

Primero debemos identificar y encontrar la entidad que deseamos exportar.

En este ejemplo trabajaremos con los Componentes de Artículos. En la plataforma no existe un listado exportable de Componentes, sólo podemos acceder a ellos a través de un artículo una vez lo editamos.

Para exportar todos los Componentes mediante API, necesitamos entontrar la URL que devuelve los componentes de un artículo al editarlo. Para ello usamos las herramientas de desarrollo del navegador cuando estamos en la plataforma y accedemos a la edición de un artículo.

Examinando la pestaña de peticiones de red XHR, entre las llamadas realizadas al editar un artículo, encontramos:

La llamada que trae todos los datos del artículo: POST a items.findById.kson?id=XX. Aquí XX será el ID interno del artículo en Kubbos
La llamada que trae los componentes: POST a itemReferences.kson con los datos start=0&limit=50&id=XX donde XX será el mismo ID del artículo que editamos.

A continuación se muestra un ejemplo de la respuesta de itemReferences.kson:

{
    "data":     {
        "result": [        {
            "warehouseName": "Nombre del Almacén",
            "costPriceWarehouse": 10,
            "salePriceWarehouse": 14.29,
            "itemReference": "ref01",
            "version": 0,
            "distributorSalesPrice": 12.5,
            "warehouseId": 5,
            "itemID": 2700,
            "itemUnits": 1,
            "wholesalerSalesPrice": 11.11
        }],
        "total": 1
    },
    "success": true
}

Aquí recibimos todos los componentes del artículo editado.

Volcado de entidades secundarias mediante API

Para volcar los Componentes que tengamos en la plataforma, deberemos seguir los siguientes pasos utilizando cualquier lenguaje de programación con el que estemos familiarizados:

Listado de la entidad principal

Llamar al listado de la entidad, en este caso itemsList.kson. Esto será un listado paginado controlado por los parámetros limit y start al que invocaremos tantas veces sea necesario hasta que el número de resultados que obtengamos sea menor que el tamaño de paginación (limit)

Esta llamada para el caso de Artículos nos dará un resultado similar al siguiente:

{
    "data":     {
        "result": [
             {
                "warehouseName": "Alm 500",
                "enabled": "true",
                "availableItemsUnits": 580,
                "retailPrice": 0,
                "costPriceTaxIncludedWarehouse": 0,
                "stockWarehouse": 580,
                "saleEnabled": "true",
                "categoryName": "Nombre cat",
                "reference": "mesa oficina",
                "externalAccessEnabled": "false",
                "version": 0,
                "brokenDown": false,
                "calculateCostPriceWarehouse": false,
                "calculateSalePriceWarehouse": false,
                "composed": false,
                "countWithSameMetaArticulo": 0,
                "divisible": false,
                "id": "12530",
                "warehouseId": 800,
                "idMetaArticulo": 12530,
                "manageStock": false,
                "costPriceUpdateOption": 2,
                "pendingEntryItemUnits": 0,
                "freight": 0,
                "bookedItemsUnits": 0
            },
            ...
        ],
        "total": 73
    },
    "success": true
}

Extracción de ID de la entidad

Por cada página de resultados, vamos a extraer el ID interno de cada elemento. En este caso es el campo “id” de cada elemento de data/result en la respuesta.

Obtención de la entidad secundaria

Con ese ID que hemos extraído, llamamos al servicio de Componentes como hemos indicado en la sección anterior. Esto también es un listado paginado, así que si nuestro artículo tiene muchos componentes, tendremos que paginar también o bien aumentar el parámetro limit para asegurarnos de que traemos todos los componentes.

Vamos acumulando los componentes que vamos encontrando o los vamos volcando en un fichero, como sea más conveniente.

Pseudo código (python) de ejemplo

all_components = []
limit = 50
start = 0

while True:

    articulos = list_articulos(limit, start)  # 1

    for a in articulos:
        id = extract_id(a)  # 2
        components = list_components(id, limit=100)  # 3

        for c in components:
            all_components.append(c)

        if len(components) == 100:
            print("pueden haber más componentes para el artículo " + id)

    if len(articulos) < 50:
        break

    start += limit

save_components(all_components)  # 4

Aquí describimos las funciones que hemos numerado en el ejemplo y que habrá que implementar:

list_articulos llama a la URL itemsList.kson con límite y offset establecidos, parsea el JSON de la respuesta y devuelve una lista de artículos
extract_id devuelve el ID de un artículo (esto se puede incorporar a list_articulos si se quiere)
list_components Devuelve los componentes de un artículo dado su ID, llamando a la URL itemReferences.kson
save_components vuelca la lista de componentes a un formato deseado (JSON, CSV, etc.)

La implementación de estas funciones queda a cargo del cliente pero esperamos que este artículo puede ayudar a utilizar la API para acceder a toda la funcionalidad de Kubbos de forma programática.

Exportación de datos en Kubbos a través de la API