Introducción

¿Qué es una API?

El término API es una abreviatura de Application Programming Interfaces, que en español significa interfaz de programación de aplicaciones. Se trata de un conjunto de definiciones y protocolos que se usan para desarrollar e integrar software.

¿Para qué sirve esta API?

Esta API nos facilita el suministro de información y recogida de datos de los clientes de Natural Systems, de manera automatizada.

Proporcionamos métodos para obtener datos de catálogo, stock, unidades de medida, precios y direcciones.

Además, damos la posibilidad de modificar datos, cómo direcciones, grabaciones de pedidos o presupuestos.

¿Cómo empiezo?

Aquí tienes nuestra URL de base

https://api.naturalsystems.es/api

Autenticación

Utilizamos API keys para autenticar las peticiones.

Puedes ver, editar, y borrar tus API keys en tu cuenta de usuario, en la sección para desarrolladores.

Tu claves API permiten acceso a mucha de tu información sensible, así que asegúrate de mantenerlas muy seguras. No las expongas en áreas públicas como GitHub o a través de peticiones no seguras.

La autenticación de la API se realiza mediante la cabecera HTTP Authorization vía Bearer token, usando como token de acceso, el obtenido al ejecutar el metodo /login con tu API Key.

Recuerda: Todas las peticiones deben realizarse sobre HTTPS. Si se realizan sobre HTTP, fallarán.

¿Necesitas ayuda con tu API Key?

Genera una API key en tu perfil de usuario

La cabecera de autenticación debería verse cómo la de este ejemplo:

"Authorization: 
    Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk"

Errores

Utilizamos códigos de respuesta convencionales de HTTP, para indicar el éxito o fracaso de una solicitud API.

Los códigos del rango 2xx indican el correcto funcionamiento de la llamada.

Los códigos del rango 4xx representan errores en las llamadas realizadas (por falta de campos, información incorrecta, usuario no autenticado, etc.).

Los códigos del rango 5xx representan un error en la sintaxis JSON de la llamada, o en casos muy poco frecuentes, un error de conexión con los servidores de Natural Systems.

En caso de obtener errores 5xx de servidor, puedes contactar con it@naturalsystems.es enviando la llamada realizada y el contenido enviado, para que podamos revisar el problema y en buscar una solución en caso de ser posible.

Resumen de códigos de error

200 - OK. Todo funciona de la manera esperada.

204 - OK. Todo funcionó correctamente, pero la llamada no debe devolver ningún contenido.

400 - Error. Error al procesar la llamada. Se devuelve el error concreto como respuesta.

401 - No autorizado. No se ha realizado una autenticación correcta previa a la conexión.

403 - Prohibido. La api key no dispone de permisos para realizar la llamada.

413 - Cuerpo demasiado grande. La petición supera los 100 KB. Parte la lista en lotes más pequeños.

429 - Demasiadas peticiones. Se ha superado el límite de uso. Espera a que se reinicie la ventana y reinténtalo.

500 - Error de servidor. Algo salió mal, JSON malformado o error de conexión con el servidor (poco frecuente)

Límites de uso

Para que el servicio sea estable para todos, la API limita el número de peticiones por ventana de tiempo. Los límites son amplios: una integración normal no los alcanza.

En los métodos que necesitan token, el cupo es de tu cliente y no de la IP desde la que llames: puedes repartir la integración entre varios servidores sin perder cupo, y nadie que comparta salida a internet contigo te lo consume.

Todas las respuestas incluyen las cabeceras RateLimit y RateLimit-Policy, con el cupo que te queda y los segundos que faltan para que se reinicie la ventana.

Si superas un límite recibirás un 429 Too Many Requests. Espera a que se reinicie la ventana —el valor reset de la cabecera dice cuántos segundos faltan— y reinténtalo. Si tu integración necesita más cupo, escríbenos a it@naturalsystems.es.

Resumen de límites

600 peticiones / 15 min - Toda la API, contadas por IP.

20 intentos / 15 min - Login, contados por IP.

600 peticiones / 15 min - Métodos con token, contadas por cliente.

60 descargas / hora - Exportaciones CSV y PDF de documentos, contadas por cliente.

30 lotes / hora - Descuentos por lote, contados por cliente.


Cabeceras y respuesta al superar el límite

RateLimit: limit=600, remaining=594, reset=782
RateLimit-Policy: 600;w=900

HTTP/1.1 429 Too Many Requests

{
    "errorMessage": "Too many requests. Please try again later."
}

Login

Realiza una petición de autenticación, se verifica la API key, y en caso de ser correcta, devuelve el token que se ha de usar en el resto de métodos.

El token generado tiene una caducidad de 24h.

Endpoint:

POST /login

Método para log in

Aquí os mostramos una llamada de ejemplo para realizar el log in:

1var axios = require('axios');
2var data = JSON.stringify({"apiKey":"$2b$12$EJEMPLOdeAPIKEYnoVALIDA0123456789abcdefghijklmnopqrst"});
3 
4var config = {
5  method: 'post',
6  url: 'https://api.naturalsystems.es/api/login',
7  headers: { 
8    'Content-Type': 'application/json'
9  },
10  data : data
11};
12 
13axios(config)
14.then(function (response) {
15  console.log(JSON.stringify(response.data));
16})
17.catch(function (error) {
18  console.log(error);
19});
20

Get Categoria

Devuelve el árbol completo de categorías de los productos con el mismo orden que en el website de Natural Systems.

El atributo father: null, define la categoría padre del árbol, mientras que el resto, dispone de la categoría inmediatamente superior.


Endpoint:

GET /producto/getCategoria

El parámetro lang admite 1 (español), 2 (inglés), 3 (francés) y 4 (alemán). Con cualquier otro valor, los textos se devuelven en español.


Respuesta correcta de obtención de las categorías

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

[
    {
        "id": 1,
        "name": "",
        "father": null,
        "position": "1"
    },
    {
        "id": 2828,
        "name": "Sustratos",
        "father": 1,
        "position": "1"
    },
   {
        "id": 3770,
        "name": "Iluminación",
        "father": 1,
        "position": "9"
    }
]

Método para obtener las categorías de Natural Systems

Aquí os mostramos una llamada de ejemplo para obtener el árbol de categorías:

1var axios = require('axios');
2var data = JSON.stringify({"lang":1});
3 
4var config = {
5  method: 'get',
6  url: 'https://api.naturalsystems.es/api/producto/getCategoria',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk', 
9    'Content-Type': 'application/json'
10  },
11  data : data
12};
13 
14axios(config)
15.then(function (response) {
16  console.log(JSON.stringify(response.data));
17})
18.catch(function (error) {
19  console.log(error);
20});
21

Get Stock

Obtiene el Stock de productos disponibles.


Endpoint:

GET /producto/getStock

Respuesta correcta de obtención de stock del producto

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

[
    {
        "itemCode": "ACCE0032",
        "stock": 99999
    },
    {
        "itemCode": "ACCE0033",
        "stock": 15
    },
    {
        "itemCode": "ACCE0034",
        "stock": 22
    },
    {
        "itemCode": "ACCE0036",
        "stock": 99999
    }
]

Método para obtener el stock del producto

Llamada de ejemplo:

1var axios = require('axios');
2    
3var config = {
4  method: 'get',
5  url: 'https://api.naturalsystems.es/api/producto/getStock',
6  headers: { 
7    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
8  }
9};
10
11axios(config)
12.then(function (response) {
13  console.log(JSON.stringify(response.data));
14})
15.catch(function (error) {
16  console.log(error);
17});

Get Unidades Medida

Devuelve el formato de venta de cada uno de los productos (caja, palet, unidad), con la cantidad unitaria de producto, su peso en kg y medidas en cm.


Endpoint:

GET /producto/getUnidadMedida

Respuesta correcta de obtención de unidades de medida

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

[
    {
        "itemCode": "ABRA0004",
        "uomCode": "Unidad",
        "quantity": 1,
        "weight": 0.04,
        "width": 12,
        "height": 12,
        "length": 1,
        "volume": 144
    },
    {
        "itemCode": "ABRA0004",
        "uomCode": "Caja",
        "quantity": 50,
        "weight": 2,
        "width": 14,
        "height": 15,
        "length": 40,
        "volume": 8400
    },
    {
        "itemCode": "ABRA0004",
        "uomCode": "Palet",
        "quantity": 11200,
        "weight": 0,
        "width": 0,
        "height": 0,
        "length": 0,
        "volume": 0
    }
]

Método para obtener el formato de venta del producto

Llamada de ejemplo:

1var axios = require('axios');
2var data = '';
3 
4var config = {
5  method: 'get',
6  url: 'https://api.naturalsystems.es/api/producto/getUnidadMedida',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
9  },
10  data : data
11};
12 
13axios(config)
14.then(function (response) {
15  console.log(JSON.stringify(response.data));
16})
17.catch(function (error) {
18  console.log(error);
19});
20

Get Precio

Obtiene la tarifa completa de precios del cliente. Estos precios incluyen el descuento aplicado. Además se envía el precio PVP del producto.


Endpoint:

GET /producto/getPrecio

Respuesta correcta de obtención de precio del producto

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

[
    {
        "itemCode": "ABRA0004",
        "price": 0.5,
        "pvp": 1.07
    },
    {
        "itemCode": "ABRA0005",
        "price": 0.54,
        "pvp": 1.16
    },
    {
        "itemCode": "ABRA0006",
        "price": 0.58,
        "pvp": 1.24
    }
]

Método para obtener el precio del producto

Llamada de ejemplo:

1var axios = require('axios');
2 
3var config = {
4  method: 'get',
5  url: 'https://api.naturalsystems.es/api/producto/getPrecio',
6  headers: { 
7    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
8  }
9};
10 
11axios(config)
12.then(function (response) {
13  console.log(JSON.stringify(response.data));
14})
15.catch(function (error) {
16  console.log(error);
17});

Get Descuento Cantidad

Devuelve los tramos de descuentos que tienen los productos en función de la cantidad comprada. Se obtiene la cantidad en unidades, el descuento aplicado, el precio final con descuento, y el rango de fechas en la que se encuentra activa la promoción.


Endpoint:

GET /producto/getDescuentoCantidad

Respuesta correcta de obtención de descuentos

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

[
    {
        "itemCode": "ACFU0046",
        "discounts": [
            {
                "quantity": 600,
                "discount": 10,
                "specialPrice": 0.14,
                "fromDate": "2019-11-26T00:00:00.000Z",
                "toDate": "2021-03-09T10:10:11.873Z"
            },
            {
                "quantity": 3000,
                "discount": 20,
                "specialPrice": 0.12,
                "fromDate": "2019-11-26T00:00:00.000Z",
                "toDate": "2021-03-09T10:10:11.873Z"
            },
            {
                "quantity": 12000,
                "discount": 30,
                "specialPrice": 0.11,
                "fromDate": "2019-11-26T00:00:00.000Z",
                "toDate": "2021-03-09T10:10:11.873Z"
            },
            {
                "quantity": 60000,
                "discount": 25,
                "specialPrice": 0.11,
                "fromDate": "2019-11-26T00:00:00.000Z",
                "toDate": "2021-03-09T10:10:11.873Z"
            }
        ]
    }
]

Método para obtener descuentos por cantidad

Llamada de ejemplo:

1var axios = require('axios');
2 
3var config = {
4  method: 'get',
5  url: 'https://api.naturalsystems.es/api/producto/getDescuentoCantidad',
6  headers: { 
7    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
8  }
9};
10 
11axios(config)
12.then(function (response) {
13  console.log(JSON.stringify(response.data));
14})
15.catch(function (error) {
16  console.log(error);
17});

Get Catálogo CSV

Devuelve la lista completa de artículos con preparados para la importación en formato CSV.


Endpoint:

GET /producto/getCsv

El parámetro lang admite 1 (español), 2 (inglés), 3 (francés) y 4 (alemán). Con cualquier otro valor, los textos se devuelven en español.


Respuesta obtención catálogo

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

REFERENCE;PRODUCT;BRAND;TAX;STOCK;SHORT_DESCRIPTION;DESCRIPTION;IMAGES;CATEGORY_PATH;ID_CATEGORY_PATH;BASE_PRICE;PVP;WEIGHT;WIDTH;HEIGHT;DEPTH;ID_CATEGORY_DEFAULT;REFERENCE_PARENT;ATTR;ATTR2
ABRA0004;"Abrazadera Metálica Sin Fin";;21;99999;"";"";https://newapi.naturalsystems.es/p/ABRA0004/ABRA0004-00.png;Control de Clima > Conductos de ventilación;3772 > 3866;0.75;0.94;0.04;12;12;1;3866;;465
ABRA0005;"Abrazadera Metálica Sin Fin";;21;99999;"";"";https://newapi.naturalsystems.es/p/ABRA0005/ABRA0005-00.png;Control de Clima > Conductos de ventilación;3772 > 3866;0.8;1;0.01;14;14;1;3866;ABRA0004;466

Método para obtener el catálogo en formato CSV

Aquí os mostramos una llamada de ejemplo para obtener el catálogo:

1var axios = require('axios');
2var data = JSON.stringify({"lang":1});
3 
4var config = {
5  method: 'get',
6  url: 'https://api.naturalsystems.es/api/producto/getCsv',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
9  },
10  data : data
11};
12 
13axios(config)
14.then(function (response) {
15  console.log(JSON.stringify(response.data));
16})
17.catch(function (error) {
18  console.log(error);
19});

Get Catálogo Prestashop

Devuelve la lista completa de artículos con preparados para la importación de datos en las plataformas Prestashop.


Endpoint:

GET /producto/getCsvPrestashop

El parámetro lang admite 1 (español), 2 (inglés), 3 (francés) y 4 (alemán). Con cualquier otro valor, los textos se devuelven en español.


Respuesta obtención catálogo

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

REFERENCE;PRODUCT;BRAND;TAX;WEIGHT;STOCK;SHORT_DESCRIPTION;DESCRIPTION;IMAGES;CATEGORY_PATH;ID_CATEGORY_PATH;PRICE_CLIENTE;PVP;WIDTH;HEIGHT;DEPTH;ID_CATEGORY_DEFAULT;REFERENCE_PARENT;ATTR;ATTR2
ABRA0004;"Abrazadera Metálica Sin Fin";;21;0.04;99999;"";"";https://newapi.naturalsystems.es/p/ABRA0004/ABRA0004-00.png;Control de Clima > Conductos de ventilación;3772 > 3866;0.75;0.94;12;12;1;3866;;465
ABRA0005;"Abrazadera Metálica Sin Fin";;21;0.01;99999;"";"";https://newapi.naturalsystems.es/p/ABRA0005/ABRA0005-00.png;Control de Clima > Conductos de ventilación;3772 > 3866;0.8;1;14;14;1;3866;ABRA0004;466

Método para obtener el catálogo adaptado a Prestashop

Aquí os mostramos una llamada de ejemplo para obtener el catálogo:

1var axios = require('axios');
2var data = JSON.stringify({"lang":1});
3 
4var config = {
5  method: 'get',
6  url: 'https://api.naturalsystems.es/api/producto/getCsvPrestashop',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
9  },
10  data : data
11};
12 
13axios(config)
14.then(function (response) {
15  console.log(JSON.stringify(response.data));
16})
17.catch(function (error) {
18  console.log(error);
19});

Get Catálogo Woocommerce

Devuelve la lista completa de artículos con preparados para la importación de datos en las plataformas Woocommerce.


Endpoint:

GET /producto/getCsvWoocommerce

El parámetro lang admite 1 (español), 2 (inglés), 3 (francés) y 4 (alemán). Con cualquier otro valor, los textos se devuelven en español.


Respuesta obtención catálogo

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

Tipo;SKU;Nombre;Publicado;"¿Está destacado?";"Visibilidad en el catálogo";"Descripción corta";Descripción;"Día en que empieza el precio rebajado";"Día en que termina el precio rebajado";"Estado del impuesto";"Clase de impuesto";"¿En inventario?";Inventario;"Cantidad de bajo inventario";"¿Permitir reservas de productos agotados?";"¿Vendido individualmente?";"Peso (kg)";"Longitud (cm)";"Anchura (cm)";"Altura (cm)";"¿Permitir valoraciones de clientes?";"Nota de compra";"Precio rebajado";"Precio normal";Categorías;Etiquetas;"Clase de envío";Imágenes;"Límite de descargas";"Días de caducidad de la descarga";Superior;"Productos agrupados";"Ventas dirigidas";"Ventas cruzadas";URL externa";"Texto del botón";Posición;meta:Brand;"Nombre del atributo 1";"Valor(es) del atributo 1";"Atributo visible 1";"Atributo global 1";"Nombre del atributo 2";"Valor(es) del atributo 2";"Atributo visible 2";"Atributo global 2";"Nombre del atributo 3";"Valor(es) del atributo 3";"Atributo visible 3";"Atributo global 3";"Nombre del atributo 4";"Valor(es) del atributo 4";"Atributo visible 4";"Atributo global 4";"Nombre del atributo 5";"Valor(es) del atributo 5";"Atributo visible 5"
simple;ABRA0004;"Abrazadera Metálica Sin Fin";1;0;visible;"";"";0;0;taxable;;1;99999;;0;0;0.04;1;12;12;1;;;0.75;Control de Clima > Conductos de ventilación;;;https://newapi.naturalsystems.es/p/ABRA0004/ABRA0004-00.png;;;;;;;;;;;100 95mm-105mm;465;1;
simple;ABRA0005;"Abrazadera Metálica Sin Fin";1;0;visible;"";"";0;0;taxable;;1;99999;;0;0;0.01;1;14;14;1;;;0.8;Control de Clima > Conductos de ventilación;;;https://newapi.naturalsystems.es/p/ABRA0005/ABRA0005-00.png;;;;;;;;;;;125 119mm-131mm;466;1;

Método para obtener el catálogo adaptado a Woocommerce

Aquí os mostramos una llamada de ejemplo para obtener el catálogo:

1var axios = require('axios');
2var data = JSON.stringify({"lang":1});
3 
4var config = {
5  method: 'get',
6  url: 'https://api.naturalsystems.es/api/producto/getCsvWoocommerce',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
9  },
10  data : data
11};
12 
13axios(config)
14.then(function (response) {
15  console.log(JSON.stringify(response.data));
16})
17.catch(function (error) {
18  console.log(error);
19});

Get Combinaciones

Devuelve la lista completa de combinaciones de artículos preparados para la importación en formato CSV.


Endpoint:

GET /producto/getCsvCombinaciones

El parámetro lang admite 1 (español), 2 (inglés), 3 (francés) y 4 (alemán). Con cualquier otro valor, los textos se devuelven en español.


Respuesta de obtención de combinaciones

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

ID_COMB;ITEMCODE
2707;ADNU0003
2707;ADNU0026
2707;ADNU0102
2707;ADNU0101
2708;ADNU0177
2708;ADNU0250

Método para obtener las combinaciones de artículo

Aquí os mostramos una llamada de ejemplo para obtener las combinaciones:

1var axios = require('axios');
2var data = JSON.stringify({"lang":1});
3 
4var config = {
5  method: 'get',
6  url: 'https://api.naturalsystems.es/api/producto/getCsvCombinaciones',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
9  },
10  data : data
11};
12 
13axios(config)
14.then(function (response) {
15  console.log(JSON.stringify(response.data));
16})
17.catch(function (error) {
18  console.log(error);
19});

Get Atributos

Devuelve la lista completa de atributos de artículos preparados para la importación en formato CSV.


Endpoint:

GET /producto/getCsvAtributos

El parámetro lang admite 1 (español), 2 (inglés), 3 (francés) y 4 (alemán). Con cualquier otro valor, los textos se devuelven en español.


Respuesta obtención atributos

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

ID_ATTRIBUTE_GROUP;NAME_ATTRIBUTE_GROUP;ID_ATTRIBUTE;NAME_ATTRIBUTE
4;Liquidos;44;30 ml
15;Macetas;1580;24.7x24.7x26.1cm (11L)
6;Extractores;1605;3250m3/h (2 Boca Entrada 250mm - 1 Boca Salida 315mm)

Método para obtener los atributos de artículo

Aquí os mostramos una llamada de ejemplo para obtener los atributos:

1var axios = require('axios');
2var data = JSON.stringify({"lang":1});
3 
4var config = {
5  method: 'get',
6  url: 'https://api.naturalsystems.es/api/producto/getCsvAtributos',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
9  },
10  data : data
11};
12 
13axios(config)
14.then(function (response) {
15  console.log(JSON.stringify(response.data));
16})
17.catch(function (error) {
18  console.log(error);
19});

Create Nuevo Pedido

Envía un nuevo pedido o presupuesto. Se permiten pedidos directos y de dropshipping.


Endpoint:

POST /pedido/nuevoPedido

Objeto de ejemplo

{
    "isQuote": "Y",
    "isDropship": "Y",
    "shipInstructions": "C/ Ejemplo 1, 00000 Ciudad de ejemplo, España",
    "shipAddress": "Almacén de ejemplo",
    "billAddress": "Almacén de ejemplo",
    "orderIntructions": "No enviar documentación",
    "remarks": "Comentarios del pedido",
    "items": [
        {
            "itemCode": "TONE0011",
            "quantity": 80
        },
        {
            "itemCode": "LUMI0017",
            "quantity": 5
        },
        {
            "itemCode": "SUST0110",
            "quantity": 2
        }
    ]
}

Respuesta correcta obtenida

Order successfully grabbed

Método para crear nuevo pedido

Llamada de ejemplo:

1var axios = require('axios');
2var data = JSON.stringify({"isQuote":"Y","isDropship":"Y","shipInstructions":"C/ Ejemplo 1, 00000 Ciudad de ejemplo, España","shipAddress":"Almacén de ejemplo","billAddress":"Almacén de ejemplo","orderIntructions":"No enviar documentación","remarks":"Comentarios del pedido","items":[{"itemCode":"TONE0011","quantity":80},{"itemCode":"LUMI0017","quantity":5},{"itemCode":"SUST0110","quantity":2}]});
3 
4var config = {
5  method: 'post',
6  url: 'https://api.naturalsystems.es/api/pedido/nuevoPedido',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk', 
9    'Content-Type': 'application/json'
10  },
11  data : data
12};
13 
14axios(config)
15.then(function (response) {
16  console.log(JSON.stringify(response.data));
17})
18.catch(function (error) {
19  console.log(error);
20});

Get Direccion Envio

Obtiene las direcciones de envío registradas en la cuenta del usuario.


Endpoint:

GET /cuenta/getDireccionEnvio

Respuesta correcta obtenida

[
{
        "address": "Almacén de ejemplo",
        "street": "C/ Ejemplo 1",
        "city": "Ciudad de ejemplo",
        "zipCode": "00000",
        "state": "Provincia de ejemplo",
        "country": "Provincia de ejemplo",
        "contactPerson": "Juan Ejemplo",
        "phone": "+34 6xx xx xx xx",
        "schedule": "De 9 a 14",
        "remark": "Observaciones de transporte"
    }
]

Método para obtener la/s direccion/es de envío

Llamada de ejemplo:

1var axios = require('axios');
2 
3var config = {
4  method: 'get',
5  url: 'https://api.naturalsystems.es/api/cuenta/getDireccionEnvio',
6  headers: { 
7    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
8  }
9};
10 
11axios(config)
12.then(function (response) {
13  console.log(JSON.stringify(response.data));
14})
15.catch(function (error) {
16  console.log(error);
17});

Create Direccion Envio

Crea una nueva dirección de envío con los datos de la llamada.


Endpoint:

POST /cuenta/createDireccionEnvio

Objeto de ejemplo

1{
2    "name": "Almacén de ejemplo 2",
3    "street": "C/ Ejemplo 1",
4    "zipCode": "00000",
5    "city": "Ciudad de ejemplo",
6    "state": "Provincia de ejemplo",
7    "country": "ES",
8    "contactPerson": "Juan Ejemplo",
9    "phone": "+34 6xx xx xx xx",
10    "phoneShipping": "+34 6xx xx xx xx",
11    "shippingRemarks": "Observaciones de transporte"
12}

Respuesta correcta obtenida

Address 'Almacén de ejemplo 2' created successfully.

Método para crear una nueva dirección de envío

Llamada de ejemplo:

1var axios = require('axios');
2var data = JSON.stringify({
3    "name": "Almacén de ejemplo 2",
4    "street": "C/ Ejemplo 1",
5    "zipCode": "00000",
6    "city": "Ciudad de ejemplo",
7    "state": "Provincia de ejemplo",
8    "country": "ES",
9    "contactPerson": "Juan Ejemplo",
10    "phone": "+34 6xx xx xx xx",
11    "phoneShipping": "+34 6xx xx xx xx",
12    "shippingRemarks": "Observaciones de transporte"
13});
14 
15var config = {
16  method: 'post',
17  url: 'https://api.naturalsystems.es/api/cuenta/updateDireccionEnvio',
18  headers: { 
19    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk', 
20    'Content-Type': 'application/json'
21  },
22  data : data
23  };
24 
25axios(config)
26.then(function (response) {
27  console.log(JSON.stringify(response.data));
28})
29.catch(function (error) {
30  console.log(error);
31});
32

Update Direccion Envio

Actualiza los datos de una dirección de envío ya existente. Sólo es obligatorio el campo “address” y los campos a actualizar.


Endpoint:

PATCH /cuenta/updateDireccionEnvio

Respuesta correcta obtenida

Address 'Almacén de ejemplo 2' updated successfully.

Método para actualizar los datos de tus direcciones de envío

Llamada de ejemplo:

1var axios = require('axios');
2var data = JSON.stringify({"address":"Almacén de ejemplo","country":"ES","zipCode":"","phone":"+34 6xx xx xx xx","phoneShipping":"+34 6xx xx xx xx xx "});
3 
4var config = {
5  method: 'patch',
6  url: 'https://api.naturalsystems.es/api/cuenta/updateDireccionEnvio',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk', 
9    'Content-Type': 'application/json'
10  },
11  data : data
12};
13 
14axios(config)
15.then(function (response) {
16  console.log(JSON.stringify(response.data));
17})
18.catch(function (error) {
19  console.log(error);
20});

Delete Direccion Envio

Elimina la dirección de envío especificada en la llamada. La dirección debe ser exacta.


Endpoint:

DELETE /cuenta/deleteDireccionEnvio

Objeto de ejemplo

1{
2    "address": "Almacén de ejemplo"
3}

Respuesta correcta obtenida

Address 'Almacén de ejemplo 2' deleted successfully.

Método para eliminar una dirección de envío

Llamada de ejemplo:

1var axios = require('axios');
2var data = JSON.stringify({  "address": "Almacén de ejemplo" });
3 
4var config = {
5  method: 'delete',
6  url: 'https://api.naturalsystems.es/api/cuenta/deleteDireccionEnvio',
7  headers: { 
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk', 
9    'Content-Type': 'application/json'
10  },
11  data : data
12};
13 
14axios(config)
15.then(function (response) {
16  console.log(JSON.stringify(response.data));
17})
18.catch(function (error) {
19  console.log(error);
20});

Get Direccion Facturacion

Obtiene las direcciones de facturación registradas en la cuenta del usuario.


Endpoint:

GET /cuenta/getDireccionFacturacion

Respuesta correcta obtenida

[
    {
        "address": "Oficina de ejemplo",
        "street": "C/ Ejemplo 1",
        "city": "Ciudad de ejemplo",
        "zipCode": "00000",
        "state": "Provincia de ejemplo",
        "country": "Provincia de ejemplo"
    }
]

Método para obtener la/s direccion/es de facturación

Llamada de ejemplo:

1var axios = require('axios');
2 
3var config = {
4  method: 'get',
5  url: 'https://api.naturalsystems.es/api/cuenta/getDireccionFacturacion',
6  headers: { 
7    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
8  }
9};
10 
11axios(config)
12.then(function (response) {
13  console.log(JSON.stringify(response.data));
14})
15.catch(function (error) {
16  console.log(error);
17});

Get Facturas

Devuelve el listado de facturas y abonos del cliente, de más reciente a más antiguo, con sus fechas, importes, impuestos, forma de pago y estado de cobro.

Solo se devuelven documentos propios: el cliente se toma del token, nunca de la llamada. Si tienes cuenta en las dos empresas del grupo, el listado incluye las dos y cada documento indica en empresa a cuál pertenece.


Endpoint:

GET /documento/getFacturas

Filtros y paginación

Todos los parámetros son opcionales y se pueden enviar en la query string o en el cuerpo de la llamada. Entre paréntesis, el valor por defecto.

GET /documento/getFacturas?type=invoice&dateFrom=2026-01-01&dateTo=2026-01-31&status=open&limit=50&offset=0

type            invoice | creditNote | all      (all)
empresa         1 (Natural Systems) | 2         (todas las del cliente)
dateFrom        YYYY-MM-DD
dateTo          YYYY-MM-DD
status          open | paid | all               (all)
includeCanceled true | false                    (false)
limit           1 - 200                         (50)
offset          >= 0                            (0)

Respuesta correcta de obtención de documentos

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

El campo status vale paid (cobrada), partiallyPaid (cobrada en parte), open (pendiente de cobro) o canceled (anulada). total es el número de documentos que cumplen el filtro, para poder paginar.

La condición de pago viene con su nombre y con days, el plazo en días que se suma a la fecha de la factura; los vencimientos concretos están en dueDates.

{
    "error": false,
    "total": 143,
    "limit": 50,
    "offset": 0,
    "documents": [
        {
            "empresa": 1,
            "company": "NATURALSL",
            "type": "invoice",
            "docEntry": 1001,
            "docNum": 2001,
            "series": "Facturas",
            "seriesPrefix": "F",
            "docDate": "2026-01-15",
            "dueDate": "2026-02-15",
            "taxDate": "2026-01-15",
            "customerReference": "PED-0001",
            "status": "open",
            "canceled": false,
            "currency": "EUR",
            "exchangeRate": 1,
            "netAmount": 100,
            "discountPercent": 0,
            "discountAmount": 0,
            "shippingAmount": 5,
            "taxAmount": 21,
            "equivalenceSurcharge": 0,
            "withholdingTax": 0,
            "rounding": 0,
            "total": 121,
            "totalForeignCurrency": 0,
            "paidAmount": 0,
            "dueAmount": 121,
            "paymentTerms": {
                "name": "30 dias fecha factura",
                "days": 30
            },
            "paymentMethod": {
                "name": "Recibo domiciliado"
            },
            "comments": ""
        }
    ]
}

Método para obtener el listado de documentos

Llamada de ejemplo:

1var axios = require('axios');
2
3var config = {
4  method: 'get',
5  url: 'https://api.naturalsystems.es/api/documento/getFacturas?type=invoice&limit=50',
6  headers: {
7    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
8  }
9};
10
11axios(config)
12.then(function (response) {
13  console.log(JSON.stringify(response.data));
14})
15.catch(function (error) {
16  console.log(error);
17});

Get Factura

Devuelve el detalle completo de una factura o de un abono.

El documento se identifica con docEntry —el identificador interno que devuelve el listado— o con docNum, el número visible del documento, acompañados de type (invoice por defecto, o creditNote) y de empresa.

Además de la cabecera, la respuesta trae las líneas (referencia, descripción, cantidad, precio de tarifa, descuento aplicado, precio neto e impuestos de cada una), el desglose de impuestos por tipo y los vencimientos, con lo cobrado de cada plazo.


Endpoint:

GET /documento/getFactura

Respuesta correcta de obtención del documento

A continuación, te mostramos un ejemplo de respuesta correcta obtenida:

{
    "error": false,
    "document": {
        "empresa": 1,
        "company": "NATURALSL",
        "type": "invoice",
        "docEntry": 1001,
        "docNum": 2001,
        "docDate": "2026-01-15",
        "dueDate": "2026-02-15",
        "customerReference": "PED-0001",
        "status": "open",
        "currency": "EUR",
        "netAmount": 100,
        "taxAmount": 21,
        "total": 121,
        "paidAmount": 0,
        "dueAmount": 121,
        "paymentTerms": { "name": "30 dias fecha factura", "days": 30 },
        "paymentMethod": { "name": "Recibo domiciliado" },
        "documentType": "items",
        "billingAddress": "C/ Ejemplo 1\n00000 Ciudad de ejemplo\nProvincia de ejemplo",
        "billingAddressCode": "FACTURACION",
        "shippingAddress": "C/ Ejemplo 2\n00000 Ciudad de ejemplo",
        "shippingAddressCode": "ALMACEN",
        "lines": [
            {
                "lineNum": 0,
                "itemCode": "ABRA0004",
                "description": "Sustrato profesional 50 L",
                "quantity": 10,
                "unitOfMeasure": "Ud",
                "itemsPerUnit": 1,
                "listPrice": 12,
                "discountPercent": 16.67,
                "unitPrice": 10,
                "netTotal": 100,
                "netTotalForeignCurrency": 0,
                "taxCode": "S1",
                "taxPercent": 21,
                "taxAmount": 21,
                "equivalenceSurchargePercent": 0,
                "equivalenceSurcharge": 0,
                "grossTotal": 121
            }
        ],
        "taxes": [
            {
                "code": "S1",
                "rate": 21,
                "base": 100,
                "amount": 21,
                "equivalenceSurchargePercent": 0,
                "equivalenceSurcharge": 0
            }
        ],
        "dueDates": [
            {
                "installment": 1,
                "dueDate": "2026-02-15",
                "percent": 100,
                "amount": 121,
                "paidAmount": 0
            }
        ]
    }
}

Método para obtener el detalle de un documento

Llamada de ejemplo:

1var axios = require('axios');
2
3var config = {
4  method: 'get',
5  url: 'https://api.naturalsystems.es/api/documento/getFactura?docEntry=1001&type=invoice',
6  headers: {
7    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
8  }
9};
10
11axios(config)
12.then(function (response) {
13  console.log(JSON.stringify(response.data));
14})
15.catch(function (error) {
16  console.log(error);
17});

Get PDF Factura

Descarga el PDF de la factura o del abono, tal y como lo imprime nuestro ERP.

El documento se identifica igual que en Get Factura. La respuesta es siempre un JSON con el PDF en base64, tal y como lo genera nuestro ERP: la API no lo transforma, así que puedes guardarlo como fichero, incrustarlo o reenviarlo como prefieras.


Endpoint:

GET /documento/getFacturaPdf

Respuesta correcta de obtención del PDF

{
    "error": false,
    "fileName": "invoice-2001.pdf",
    "base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9GaWx0ZXIvRmxhdGVEZWNvZGUvTGVuZ..."
}
Cada PDF se genera en el momento, así que este método tiene un límite propio de 60 descargas por hora.

Método para descargar el PDF de un documento

Llamada de ejemplo:

1var axios = require('axios');
2var fs = require('fs');
3
4var config = {
5  method: 'get',
6  url: 'https://api.naturalsystems.es/api/documento/getFacturaPdf?docEntry=1001',
7  headers: {
8    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk'
9  }
10};
11
12axios(config)
13.then(function (response) {
14  // El PDF llega en base64 tal y como lo genera el ERP
15  fs.writeFileSync(response.data.fileName, Buffer.from(response.data.base64, 'base64'));
16})
17.catch(function (error) {
18  console.log(error);
19});

Colección métodos

Para facilitar el uso de todos estos métodos hemos creado una colección para Postman.

Sólo tienes que importar este archivo, seguir los métodos de autenticación y login y ya dispondrás de todos los datos necesarios para realizar las peticiones a nuestra API. Este software también permite exportar el código necesario en muchas tecnologías.

Descargar