Introduction

What is an API?

The term API is an abbreviation for Application Programming Interfaces. It is a set of definitions and protocols used to develop and integrate software.

What is this API for?

This API makes it easier for us to provide information and collect data from Natural Systems customers, in an automated manner.

We provide methods to obtain catalog data, stock, units of measure, prices and addresses.

In addition, we give the possibility of modifying data, such as addresses, order recordings or budgets.

How do I start?

Here is our base URL

https://api.naturalsystems.es/api

Authentication

We use API keys to authenticate requests.

You can see, edit, and delete your API keys in your user account, in the developer section.

Your API keys allow access to a lot of your sensitive information, so make sure you keep them very secure. Don’t expose them in public areas like GitHub or through unsecure requests.

API authentication is performed through the HTTP Authorization header via Bearer token, using the access token obtained by executing the /login method with your API Key.

Remember: All requests must be made over HTTPS. If they are done over HTTP, they will fail.

Do you need help with your API Key?

Generate an API key in your user profile

The authentication header should look like the one in this example:

"Authorization: 
    Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkQ29kZSI6IkMwMDAwMCIsImdyb3VwQ29kZSI6MTAwLCJsaXN0TnVtIjoxLCJub0Rpc2NvdW50IjoiTiIsImRpc2NSZWwiOiJIIiwibXVlc3RyYU9jdWx0YXMiOjEsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MzEyMDAwfQ.EJEMPLOdeFIRMAnoVALIDA0123456789abcdefghijk"

Errors

We use conventional HTTP response codes to indicate the success or failure of an API request.

The codes of the 2xx range indicate the correct operation of the call.

The codes of the 4xx range represent errors in the calls made (due to missing fields, incorrect information, unauthenticated user, etc.).

The codes of the 5xx range represent an error in the JSON syntax of the call, or in very rare cases, a connection error with the Natural Systems servers.

In case of getting 5xx server errors, you can contact it@naturalsystems.es by sending the call made and the content sent, so that we can review the problem and find a solution if possible.

Summary of error codes

200 - OK. Everything works as expected.

204 - OK. Everything worked fine, but the call should not return any content.

400 - Error. Error processing the call. The specific error is returned as a response.

401 - Not authorized. Failed to perform successful pre-connection authentication.

403 - Forbidden. The api key does not have permissions to make the call.

413 - Body too large. The request goes over 100 KB. Split the list into smaller batches.

429 - Too many requests. The rate limit has been exceeded. Wait for the window to reset and try again.

500 - Server error. Something went wrong, malformed JSON or server connection error (rare)

Rate limits

To keep the service stable for everyone, the API limits how many requests you can make within a time window. The limits are generous: a normal integration never reaches them.

On the methods that require a token, the quota belongs to your account, not to the IP address you call from: you can spread the integration across several servers without losing quota, and nobody sharing your internet connection can use it up.

Every response includes the RateLimit and RateLimit-Policy headers, with the quota you have left and the seconds remaining until the window resets.

Going over a limit returns 429 Too Many Requests. Wait for the window to reset —the reset value in the header tells you how many seconds are left— and try again. If your integration needs a bigger quota, write to us at it@naturalsystems.es.

Limits at a glance

600 requests / 15 min - Whole API, counted per IP address.

20 attempts / 15 min - Login, counted per IP address.

600 requests / 15 min - Token methods, counted per account.

60 downloads / hour - CSV exports and document PDFs, counted per account.

30 batches / hour - Batch discounts, counted per account.


Headers and response once the limit is exceeded

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

It makes an authentication request, the API key is verified, and if it is correct, it returns the token to be used in the rest of the methods.

The generated token has an expiration of 24 hours.

Endpoint:

POST /login

Method for log in

Here we show you an example call to perform the 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 Category

Returns the complete product category tree in the same order as on the Natural Systems website.

The father: null attribute defines the parent category of the tree, while the rest have the immediately superior category.


Endpoint:

GET /producto/getCategoria

The lang parameter accepts 1 (Spanish), 2 (English), 3 (French) and 4 (German). Any other value returns the texts in Spanish.


Correct answer of obtaining the categories

Here is an example of the correct response obtained:

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

Method to obtain the categories of Natural Systems

Here is an example call to get the category tree:

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

Obtains the Stock of available products.


Endpoint:

GET /producto/getStock

Correct answer of obtaining product stock

Here is an example of the correct response obtained:

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

Method to obtain the stock of the product

Example call:

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 Units of Measure

Returns the sales format of each of the products (box, pallet, unit), with the unit quantity of the product, its weight in kg and measurements in cm.


Endpoint:

GET /producto/getUnidadMedida

Correct answer of obtaining units of measure

Here is an example of the correct response obtained:

[
    {
        "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
    }
]

Method to obtain the sales format of the product

Example call:

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 Price

You get the full price list from the client. These prices include the applied discount. In addition, the PVP price of the product is sent.


Endpoint:

GET /producto/getPrecio

Correct answer of obtaining price of the product

Here is an example of the correct response obtained:

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

Method to obtain the price of the product

Example call:

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 Amount Discount

Returns the discount brackets that the products have based on the quantity purchased. It returns the quantity in units, the discount applied, the final price with discount, and the range of dates on which the promotion is active.


Endpoint:

GET /producto/getDescuentoCantidad

Correct answer of obtaining discounts

Here is an example of the correct response obtained:

[
    {
        "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"
            }
        ]
    }
]

Method to get quantity discounts

Example call:

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 Catalogue CSV

Returns the complete list of items with import-ready items in CSV format.


Endpoint:

GET /producto/getCsv

The lang parameter accepts 1 (Spanish), 2 (English), 3 (French) and 4 (German). Any other value returns the texts in Spanish.


Response obtain catalogue

Here is an example of the correct response obtained:

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

Method to obtain the catalogue in CSV format

Here is a sample call to obtain the catalogue:

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 Catalogue Prestashop

Returns the complete list of items prepared for data import into Prestashop platforms.


Endpoint:

GET /producto/getCsvPrestashop

The lang parameter accepts 1 (Spanish), 2 (English), 3 (French) and 4 (German). Any other value returns the texts in Spanish.


Response obtain catalogue

Here is an example of the correct response obtained:

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

Method to obtain the catalogue adapted to Prestashop

Here is a sample call to obtain the catalogue:

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 Catalogue Woocommerce

Returns the complete list of items ready for importing data into Woocommerce platforms.


Endpoint:

GET /producto/getCsvWoocommerce

The lang parameter accepts 1 (Spanish), 2 (English), 3 (French) and 4 (German). Any other value returns the texts in Spanish.


Response obtain catalogue

Here is an example of the correct response obtained:

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;

Method to obtain the catalogue adapted to Woocommerce

Here is a sample call to obtain the catalogue:

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 Combinations

Returns the complete list of item combinations prepared for import in CSV format.


Endpoint:

GET /producto/getCsvCombinaciones

The lang parameter accepts 1 (Spanish), 2 (English), 3 (French) and 4 (German). Any other value returns the texts in Spanish.


Combinations retrieval response

Here is an example of the correct response obtained:

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

Method to obtain the article combinations

Here we show you an example call to obtain the combinations:

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 Attributes

Returns the complete list of item attributes prepared for import in CSV format.


Endpoint:

GET /producto/getCsvAtributos

The lang parameter accepts 1 (Spanish), 2 (English), 3 (French) and 4 (German). Any other value returns the texts in Spanish.


Attribute retrieval response

Here is an example of the correct response obtained:

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)

Method to obtain the article attributes

Here we show you an example call to obtain the attributes:

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 New Order

Submit a new order or quote. Dropshipping and direct orders are allowed.


Endpoint:

POST /pedido/nuevoPedido

Example object

{
    "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
        }
    ]
}

Correct response obtained

Order successfully grabbed

Method to create new order

Example call:

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 Shipping Address

Gets the shipping addresses registered in the user’s account.


Endpoint:

GET /cuenta/getDireccionEnvio

Correct response obtained

[
{
        "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"
    }
]

Method to obtain the shipping address(es)

Example call:

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 Shipping Address

Create a new shipping address with the call data.


Endpoint:

POST /cuenta/createDireccionEnvio

Example object

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}

Correct response obtained

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

Method to create a new shipping address

Example call:

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 Shipping Address

Update the details of an existing shipping address. Only the “address” field and the fields to be updated are mandatory.


Endpoint:

PATCH /cuenta/updateDireccionEnvio

Correct response obtained

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

Method to update the data of your shipping addresses

Example call:

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 Shipping Address

Removes the shipping address specified in the call. The address must be exact.


Endpoint:

DELETE /cuenta/deleteDireccionEnvio

Example object

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

Correct response obtained

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

Method to remove a shipping address

Example call:

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 Billing Address

Get the billing addresses registered in the user’s account.


Endpoint:

GET /cuenta/getDireccionFacturacion

Correct response obtained

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

Method to obtain the billing address(es)

Example call:

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 Invoices

Returns the list of invoices and credit notes, newest first.

If you trade with both companies of the group, the list covers both and each document states which one it belongs to in empresa.


Endpoint:

GET /documento/getFacturas

Filters and paging

Every parameter is optional and can travel in the query string or in the request body. Default values in brackets.

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)

Successful document list response

Here is an example of the correct response obtained:

The status field is paid, partiallyPaid, open (awaiting payment) or canceled. total is the number of documents matching the filter, not the number in this page.

The payment terms come with their name and with days, the days added to the invoice date; the actual instalments are in 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": ""
        }
    ]
}

Method to get the document list

Example call:

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 Invoice

Returns the full detail of an invoice or a credit note.

The document is identified by docEntry, the internal id returned by the list, or by docNum, the visible document number, together with type (invoice by default, or creditNote) and empresa.

On top of what the list already returns, the detail adds the lines, the tax breakdown and the due dates with the amount paid on each one.


Endpoint:

GET /documento/getFactura

Successful document detail response

Here is an example of the correct response obtained:

{
    "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
            }
        ]
    }
}

Method to get the detail of a document

Example call:

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 Invoice PDF

Downloads the PDF of the invoice or credit note.

The document is identified just like in Get Invoice. The response is a JSON with the PDF in base64, exactly as our ERP prints it: decode it to save it as a file.


Endpoint:

GET /documento/getFacturaPdf

Successful PDF response

{
    "error": false,
    "fileName": "invoice-2001.pdf",
    "base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9GaWx0ZXIvRmxhdGVEZWNvZGUvTGVuZ..."
}
Each PDF is generated on the spot, so this method has its own limit of 60 downloads per hour.

Method to download the PDF of a document

Example call:

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});

Method Collection

To facilitate the use of all these methods we have created a collection for Postman.

You only have to import this file, follow the authentication and login methods and you will have all the necessary data to make requests to our API. This software also allows you to export the necessary code in many technologies.

Download