NAV
php javascript

Introduction

This documentation aims to provide a full Rest API documentation for NexoPOS. This relies on Oauth 2.0 or JWT authentication. As NexoPOS uses Laravel and then Laravel Sanctum, it has a dedicated area to generate tokens on the user profile.

For a documentation on the library API, you can refer to NexoPOS website.

Authentication

Generating Token

One of the requirement to get started is to have a running instance of NexoPOS. If you don't know yet how to install NexoPOS, you can refer to this documentation. Now, we'll head to your profile (the authenticated user) to generate a token.

generate-token

The generated token will appear on a popup. Note that the token will only be displayed once. If that token is lost, you'll need to generate a new one.

token-generated

We'll now use this token on our header like this.

Authorization: Bearer [token]

Testing Token

Testing Token

# With Laravel Http Client
use Illuminate\Support\Facades\Http;

$client   = Http::withToken( '[yourtoken]' )->acceptJson()->get( '/api/user' );


// using Axios with Javascript.
const axios = require('axios');
const API_URL = 'https://example.com/api/user';
const TOKEN = 'your_jwt_token_here'; // Replace with your actual JWT token

async function authenticate() {
    try {
        const response = await axios.get(API_URL, {
            headers: {
                'Authorization': `Bearer ${TOKEN}`,
                'Content-Type': 'application/json'
            }
        });

        console.log('Response:', response.data);
    } catch (error) {
        console.error('Error:', error.response ? error.response.data : error.message);
    }
}

authenticate();

NexoPOS token doesn't expires until they are manually revoked by the user. This behavior is likely to change in the future, therefore you should implement mecanism for testing authentication token.

Categories

Use these endpoint to interact with the products categories.

Get Categories

This endpoint will returns a not paginated array of categories. You might use the CRUD approach to get a paginated list of categories.

get
api/categories

Response

[
    {
        "id": 1,
        "name": "Condiments",
        "parent_id": null,
        "media_id": 0,
        "preview_url": "https://example.com/modules/nsgastro/images/categories/condiments/creamer-packet.jpeg",
        "displays_on_pos": 1,
        "total_items": 13,
        "description": "Additional condiments that can be added to meals",
        "author": 8,
        "uuid": null,
        "created_at": "2025-02-08T12:55:26.000000Z",
        "updated_at": "2025-02-08T12:55:32.000000Z",
    },
]

You might want to retrieve the categories that belongs to a parent category using the query argument ?parent={id} where {id} is the identifier of the parent category.

Get Single Category

Use this endpoint to retrieve a single category using his ID. Replace {id} with the actual ID of the category.

get
api/categories/{id}

Response

{
    "id": 1,
    "name": "Condiments",
    "parent_id": null,
    "media_id": 0,
    "preview_url": "https://example.com/modules/nsgastro/images/categories/condiments/creamer-packet.jpeg",
    "displays_on_pos": 1,
    "total_items": 13,
    "description": "Additional condiments that can be added to meals",
    "author": 8,
    "uuid": null,
    "created_at": "2025-02-08T12:55:26.000000Z",
    "updated_at": "2025-02-08T12:55:32.000000Z",
}

Get Category Products

Use this endpoint to get all products that are assigned to the category. Replace {id} with the actual ID of the category.

get
api/categories/{id}/products

Response

[
    {
        "id": 1,
        "name": "Creamer Packet",
        "tax_type": "inclusive",
        "tax_group_id": 1,
        "tax_value": 0,
        "product_type": "product",
        "type": "dematerialized",
        "accurate_tracking": false,
        "auto_cogs": false,
        "status": "available",
        "stock_management": "disabled",
        "barcode": "8795063144717",
        "barcode_type": "ean13",
        "sku": "Sb4X001sJ1u8i7K",
        "description": "Created via tests",
        "thumbnail_id": null,
        "category_id": 1,
        "parent_id": 0,
        "unit_group": 1,
        "on_expiration": "prevent_sales",
        "expires": 0,
        "searchable": 1,
        "author": 8,
        "uuid": null,
        "created_at": "2025-02-08T12:55:26.000000Z",
        "updated_at": "2025-02-08T12:55:26.000000Z"
    }
]

Create Category

Use this endpoint to create a product category

post
api/categories

Request

{
    "name": "[string]",
    "parent_id": "[integer]", // optional
    "description": "[string]",
    "media_id": "[url]"
}

Response

{
    "status": "success",
    "message": "The category has been correctly saved",
    "data": {
        "category": {
            "name": "FooBar",
            "description": "For API purpose.",
            "author": 8,
            "updated_at": "2025-02-13T08:32:23.000000Z",
            "created_at": "2025-02-13T08:32:23.000000Z",
            "id": 11
        }
    }
}

Update Category

Use this to update an existing category using his ID {id}.

put
api/categories/{id}

Request

{
    "name": "[string]",
    "parent_id": "[integer]", // optional
    "description": "[string]",
    "media_id": "[url]"
}

Response

{
    "status": "success",
    "message": "The category has been updated",
    "data": {
        "category": {
            "name": "FooBar",
            "description": "For API purpose.",
            "author": 8,
            "updated_at": "2025-02-13T08:32:23.000000Z",
            "created_at": "2025-02-13T08:32:23.000000Z",
            "id": 11
        }
    }
}

Delete A Category

Use this endpoint to delete a category using his ID. Replace {id} with the actual ID of the category. If the category doesn't exist, the proceed might fail with a fail response.

delete
api/categories/{id}

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

Category Exploration

Use this endpoint to explore category as exploring folder in computing. At the root of each category, is no other category exists, the products are displayed. The products of intermediary categories aren't visible.

If {id} is not provided, all parent categories are displayed first. If {id} is provided, all it's child categories are listed. If no child categories exists, the products are retrieved.

get
api/categories/pos/{id?}

Response with Parent Category

{
    "products": [],
    "previousCategory": false,
    "currentCategory": false,
    "categories": [
        {
            "id": 1,
            "name": "Condiments",
            "parent_id": null,
            "media_id": 0,
            "preview_url": "https://example.com/modules/nsgastro/images/categories/condiments/creamer-packet.jpeg",
            "displays_on_pos": 1,
            "total_items": 13,
            "description": "Additional condiments that can be added to meals",
            "author": 8,
            "uuid": null,
            "created_at": "2025-02-08T12:55:26.000000Z",
            "updated_at": "2025-02-08T12:55:32.000000Z",
            "wc_category_id": null
        }
    ]
}

Response with Products

{
  "products": [
    {
      "id": 1,
      "name": "Creamer Packet",
      "tax_type": "inclusive",
      "tax_group_id": 1,
      "tax_value": 0,
      "product_type": "product",
      "type": "dematerialized",
      "accurate_tracking": false,
      "auto_cogs": false,
      "status": "available",
      "stock_management": "disabled",
      "barcode": "8795063144717",
      "barcode_type": "ean13",
      "sku": "Sb4X001sJ1u8i7K",
      "description": "Created via tests",
      "thumbnail_id": null,
      "category_id": 1,
      "parent_id": 0,
      "unit_group": 1,
      "on_expiration": "prevent_sales",
      "expires": 0,
      "searchable": 1,
      "author": 8,
      "uuid": null,
      "created_at": "2025-02-08T12:55:26.000000Z",
      "updated_at": "2025-02-08T12:55:26.000000Z",
      "galleries": [
        {
          "id": 1,
          "name": null,
          "product_id": 1,
          "media_id": null,
          "url": "https://example.com/modules/nsgastro/images/categories/condiments/creamer-packet.jpeg",
          "order": 0,
          "featured": true,
          "author": 8,
          "uuid": null,
          "created_at": "2025-02-08T12:55:26.000000Z",
          "updated_at": "2025-02-08T12:55:26.000000Z"
        }
      ],
      "tax_group": {
        "id": 1,
        "name": "GST",
        "description": null,
        "author": 8,
        "uuid": null,
        "created_at": "2025-02-08T12:55:26.000000Z",
        "updated_at": "2025-02-08T12:55:26.000000Z",
        "taxes": [
          {
            "id": 1,
            "name": "SGST",
            "description": null,
            "rate": 8,
            "tax_group_id": 1,
            "author": 8,
            "uuid": null,
            "created_at": "2025-02-08T12:55:26.000000Z",
            "updated_at": "2025-02-08T12:55:26.000000Z"
          },
          {
            "id": 2,
            "name": "CGST",
            "description": null,
            "rate": 8,
            "tax_group_id": 1,
            "author": 8,
            "uuid": null,
            "created_at": "2025-02-08T12:55:26.000000Z",
            "updated_at": "2025-02-08T12:55:26.000000Z"
          }
        ]
      }
    }
  ],
  "categories": [],
  "previousCategory": null,
  "currentCategory": {
    "id": 1,
    "name": "Condiments",
    "parent_id": null,
    "media_id": 0,
    "preview_url": "https://example.com/modules/nsgastro/images/categories/condiments/creamer-packet.jpeg",
    "displays_on_pos": 1,
    "total_items": 13,
    "description": "Additional condiments that can be added to meals",
    "author": 8,
    "uuid": null,
    "created_at": "2025-02-08T12:55:26.000000Z",
    "updated_at": "2025-02-08T12:55:32.000000Z",
    "sub_categories": []
  }
}

Customers

Create Customer

Use this endpoint to create a customer.

post
api/customers

Request

{
  "general" : {
    "first_name": "[string]",
    "last_name": "[string]",
    "email": "[string]",
    "phone": "[string]",
    "address_1": "[string]",
    "address_2": "[string]",
    "country": "[string]",
    "city": "[string]",
    "pobox": "[string]",
    "company": "[string]",
    "uuid": "[string]",
    "author": "[number]"
  },
  "address": {
    "billing": {
      "first_name": "[string]",
      "last_name": "[string]",
      "email": "[string]",
      "phone": "[string]",
      "address_1": "[string]",
      "address_2": "[string]",
      "country": "[string]",
      "city": "[string]",
      "pobox": "[string]",
      "company": "[string]",
      "uuid": "[string]",
    },
    "shipping": {
      "first_name": "[string]",
      "last_name": "[string]",
      "email": "[string]",
      "phone": "[string]",
      "address_1": "[string]",
      "address_2": "[string]",
      "country": "[string]",
      "city": "[string]",
      "pobox": "[string]",
      "company": "[string]",
      "uuid": "[string]",
    }
  }
}

Response 

{
  "status": "[success|error]",
  "message": "[string]"
}

Update Customer

Use this endpoint to update the customer. You'll replace {customer_id} with the ID of the customer you would like to update.

put
api/customers/{customer_id}

Request

{
  "general" : {
    "first_name": "[string]",
    "last_name": "[string]",
    "email": "[string]",
    "phone": "[string]",
    "address_1": "[string]",
    "address_2": "[string]",
    "country": "[string]",
    "city": "[string]",
    "pobox": "[string]",
    "company": "[string]",
    "uuid": "[string]",
    "author": "[number]"
  },
  "address": {
    "billing": {
      "first_name": "[string]",
      "last_name": "[string]",
      "email": "[string]",
      "phone": "[string]",
      "address_1": "[string]",
      "address_2": "[string]",
      "country": "[string]",
      "city": "[string]",
      "pobox": "[string]",
      "company": "[string]",
      "uuid": "[string]",
    },
    "shipping": {
      "first_name": "[string]",
      "last_name": "[string]",
      "email": "[string]",
      "phone": "[string]",
      "address_1": "[string]",
      "address_2": "[string]",
      "country": "[string]",
      "city": "[string]",
      "pobox": "[string]",
      "company": "[string]",
      "uuid": "[string]",
    }
  }
}

Response

{
  "status": "[success|error]",
  "message": "[string]"
}

Retreive Single Customer

Use this endpoint to details for a specific customer. You'll make sure to replace {customer_id} with the ID of the customer for which you would like to get information.

get
api/customers/{customer_id}

Response

{
  "id": 1792,
  "username": "dooley.linnea",
  "active": 1,
  "author": 1723,
  "email": "nmetz@funk.com",
  "password": "$2y$10$3q81nABSmQzwiGaWUBD6Y.UHguEtBJ2PGH/l4Sy5FPW9FfPV5Lx0a",
  "group_id": 9,
  "first_name": "Rita",
  "last_name": "Batz",
  "gender": "male",
  "phone": "+1.660.362.3086",
  "pobox": "32287",
  "activation_expiration": null,
  "total_sales_count": 0,
  "total_sales": 0,
  "birth_date": null,
  "purchases_amount": 216.00000464,
  "owed_amount": 0,
  "credit_limit_amount": 0,
  "account_amount": 0,
  "activation_token": null,
  "remember_token": null,
  "created_at": "2025-01-26T23:19:41.000000Z",
  "updated_at": "2025-01-30T10:55:11.000000Z",
  "origin_store_id": null,
  "wc_customer_id": null,
  "group": {
    "id": 9,
    "name": "Virtual optimal throughput",
    "description": null,
    "reward_system_id": null,
    "minimal_credit_payment": 27,
    "author": 9,
    "uuid": null,
    "created_at": "2025-01-26T23:19:40.000000Z",
    "updated_at": "2025-01-26T23:19:40.000000Z"
  },
  "billing": null,
  "shipping": null
}

Delete Customer

Use this endpoint to delete a specific customer. Note that this might fail if the customer is still attached to orders or any other resources that enforce data integrity. Make sure to replace {customer_id} with the ID of the customer you would like to delete.

delete
api/customers/{customer_id}

Retreive Customers

This endpoint will retreive all registered customers. The output is not paginated, you might therefore consider using the CRUD approach.

get
api/customers

Response

[
  {
    "id": 1792,
    "username": "dooley.linnea",
    "active": 1,
    "author": 1723,
    "email": "xxx@xxx.com",
    "password": "$2y$10$3q81nABSmQzwiGaWUBD6Y.UHguEtBJ2PGH/l4Sy5FPW9FfPV5Lx0a",
    "group_id": 9,
    "first_name": "Rita",
    "last_name": "Batz",
    "gender": "male",
    "phone": "+1.000.000.000",
    "pobox": "00000",
    "activation_expiration": null,
    "total_sales_count": 0,
    "total_sales": 0,
    "birth_date": null,
    "purchases_amount": 216.00000464,
    "owed_amount": 0,
    "credit_limit_amount": 0,
    "account_amount": 0,
    "activation_token": null,
    "remember_token": null,
    "created_at": "2025-01-26T23:19:41.000000Z",
    "updated_at": "2025-01-30T10:55:11.000000Z",
    "origin_store_id": null,
    "wc_customer_id": null,
    "billing": null,
    "shipping": null
  }
]

Response 

{
  "status": "[success|error]",
  "message": "[string]"
}

Recently Active Customers

This endpoint will give a list of the customers that has recently been active.

get
api/customers/recently-active

Response

[
  {
    "id": 1796,
    "username": "hudson.keshawn",
    "active": 1,
    "author": 1722,
    "email": "karli39@yahoo.com",
    "password": "$2y$10$xJTDtiBtOtsMWU8MqnHa6eaRjZRisOgxXWkujnpSlFoIynvONjyba",
    "group_id": 9,
    "first_name": "Adrienne",
    "last_name": "Gerhold",
    "gender": "male",
    "phone": "+1.734.246.6288",
    "pobox": "31266",
    "activation_expiration": null,
    "total_sales_count": 0,
    "total_sales": 0,
    "birth_date": null,
    "purchases_amount": 880.00003056,
    "owed_amount": 0,
    "credit_limit_amount": 0,
    "account_amount": 0,
    "activation_token": null,
    "remember_token": null,
    "created_at": "2025-01-26T23:19:41.000000Z",
    "updated_at": "2025-01-30T11:14:43.000000Z",
    "origin_store_id": null,
    "wc_customer_id": null,
    "billing": null,
    "shipping": null,
    "group": {
      "id": 9,
      "name": "Virtual optimal throughput",
      "description": null,
      "reward_system_id": null,
      "minimal_credit_payment": 27,
      "author": 9,
      "uuid": null,
      "created_at": "2025-01-26T23:19:40.000000Z",
      "updated_at": "2025-01-26T23:19:40.000000Z"
    }
  }
]

Customer Latest Orders

Use this endpoint to retreive latest orders placed by a specific customer.

get
api/customers/{customer_id}/orders

Response

[
  {
    "id": 20,
    "description": null,
    "code": "250130-016",
    "title": null,
    "type": "takeaway",
    "payment_status": "paid",
    "process_status": "not-available",
    "delivery_status": "not-available",
    "discount": 0,
    "discount_type": null,
    "support_instalments": true,
    "discount_percentage": 0,
    "shipping": 0,
    "shipping_rate": 0,
    "shipping_type": null,
    "total_without_tax": 100,
    "subtotal": 100,
    "total_with_tax": 100,
    "total_coupons": 0,
    "total_cogs": 0,
    "total": 100,
    "tax_value": 0,
    "products_tax_value": 13.793104,
    "total_tax_value": 0,
    "tax_group_id": 1,
    "tax_type": "exclusive",
    "tendered": 100,
    "change": 0,
    "final_payment_date": null,
    "total_instalments": 0,
    "customer_id": 1796,
    "note": null,
    "note_visibility": "hidden",
    "author": 8,
    "uuid": null,
    "register_id": null,
    "voidance_reason": null,
    "created_at": "2025-01-30 11:14:41",
    "updated_at": "2025-01-30 11:14:41",
    "human_status": "Paid",
    "human_delivery_status": "Not Available"
  },
]

Customer's Address

Use this endpoint to retreive the billing and shipping address for a specific customers.

get
api/customers/{customer_id}/addresses

Response

[
  {
    "id": 3,
    "customer_id": 1796,
    "type": "shipping",
    "email": "contact@nexopos.com",
    "first_name": "Blair",
    "last_name": null,
    "phone": null,
    "address_1": "Yaoundé, Fougerolle",
    "address_2": null,
    "country": "Cameroon",
    "city": "Yaoundé",
    "pobox": null,
    "company": null,
    "uuid": null,
    "author": 8,
    "created_at": "2025-01-31T19:46:51.000000Z",
    "updated_at": "2025-01-31T19:46:51.000000Z"
  },
  {
    "id": 4,
    "customer_id": 1796,
    "type": "billing",
    "email": "contact@nexopos.com",
    "first_name": "Blair",
    "last_name": null,
    "phone": null,
    "address_1": "Yaoundé, Fougerolle",
    "address_2": null,
    "country": "Cameroon",
    "city": "Yaoundé",
    "pobox": null,
    "company": null,
    "uuid": null,
    "author": 8,
    "created_at": "2025-01-31T19:46:51.000000Z",
    "updated_at": "2025-01-31T19:46:51.000000Z"
  }
]

Customer's Group

Use this endpoint to retrieve the customer group to which a specific customer is attached. Make sure to replace {customer_id} with the customer ID you would like to retrieve the group.

get
api/customers/{customer_id}/group

Response

{
  "id": 9,
  "name": "Virtual optimal throughput",
  "description": null,
  "reward_system_id": null,
  "minimal_credit_payment": 27,
  "author": 9,
  "uuid": null,
  "created_at": "2025-01-26T23:19:40.000000Z",
  "updated_at": "2025-01-26T23:19:40.000000Z"
}

Customer's Coupons

Use this endpoint to retrieve the coupons that has been generated for a specific customer. Replace the {customer_id} with the ID of the customer for which you would like to retrieve the coupons.

get
api/customers/{customer_id}/coupons

Response

[
  {
    "id": 1,
    "name": "Sample Coupon",
    "usage": 0,
    "limit_usage": 0,
    "active": true,
    "code": "578408-310141",
    "coupon_id": 1,
    "customer_id": 1796,
    "author": 8,
    "created_at": "2025-01-31T20:48:00.000000Z",
    "updated_at": "2025-01-31T20:48:00.000000Z",
    "coupon": {
      "id": 1,
      "name": "A",
      "code": "578408",
      "type": "percentage_discount",
      "discount_value": 10,
      "valid_until": "2025-01-31 20:34:04",
      "minimum_cart_value": 0,
      "maximum_cart_value": 0,
      "valid_hours_start": "2025-01-31 20:34:04",
      "valid_hours_end": "2025-01-31 20:34:04",
      "limit_usage": 0,
      "groups_id": null,
      "customers_id": null,
      "author": 8,
      "created_at": "2025-01-31T20:34:19.000000Z",
      "updated_at": "2025-01-31T20:34:19.000000Z"
    }
  }
]

Load Customer Coupon

Use this endpoint to load customer coupon.

post
api/customers/coupons/{coupon}

Request

{
  "customer_id": "[number]"
}

Response

{
  ""
}

Customer's Reward System

Use this endpoint to retreive all the reward system the customer is assigned to. Note that reward system must first be assigned to the customers group. You'll replace {customer_id} with the ID of the customer for which you woud like to get the rewards. The response is a CRUD Type reponse, which is paginated.

get
api/customers/{customer_id}/rewards

Response

{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "customer_id": 1796,
      "reward_id": 1,
      "reward_name": "Basic",
      "points": 0,
      "target": 10,
      "created_at": "2025-01-31T20:46:48.000000Z",
      "updated_at": "2025-01-31T20:48:00.000000Z"
    }
  ],
  "first_page_url": "https://example.com/api/customers/1796/rewards?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://example.com/api/customers/1796/rewards?page=1",
  "links": [
    {
      "url": null,
      "label": "« Previous",
      "active": false
    },
    {
      "url": "https://example.com/api/customers/1796/rewards?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next »",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://example.com/api/customers/1796/rewards",
  "per_page": 20,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

Customer's Account History

Use this endpoint to retrieve an history of all the transactions that has occured on the customer wallet account. Replace {customer_id} with the ID of the customer for which you would like to retreive the account history. Note that the response is a CRUD Type response, this means it's paginated.

post
api/customers/{customer_id}/rewards

Response

{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "customer_id": 1796,
      "order_id": null,
      "previous_amount": 0,
      "amount": 1000,
      "next_amount": 1000,
      "operation": "add",
      "author": 8,
      "description": null,
      "created_at": "2025-01-31T20:54:19.000000Z",
      "updated_at": "2025-01-31T20:54:19.000000Z"
    }
  ],
  "first_page_url": "https://nexocloud.dev/api/customers/1796/account-history?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://nexocloud.dev/api/customers/1796/account-history?page=1",
  "links": [
    {
      "url": null,
      "label": "« Previous",
      "active": false
    },
    {
      "url": "https://nexocloud.dev/api/customers/1796/account-history?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next »",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://nexocloud.dev/api/customers/1796/account-history",
  "per_page": 20,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

Create Account History

Use this endpoint to create a new wallet entry for a specific customer. Make sure to replace {customer_id} with the ID of the customer you would like to create a new wallet entry.

post
api/customers/{customer_id}/crud/account-history

Request

{
  "general": {
    "operation": "[add|remove]",
    "amount": "[number]",
    "description": "[string]"
  }
}

Customers Groups

Create Group

Use this endpoint to create customers group.

post
api/customers-groups

Request

{
    "name": "[string]",
    "reward_system_id": "[number]",
    "description": "[string]"
}

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

List Groups

Use this endpoint to list available customers groups. Note that here, we'll pull all customers groups, regardless of if they are assigned or not.

get
api/customers-groups

Response

[
    {
        "id": 1,
        "name": "Reduced motivating methodology",
        "description": null,
        "reward_system_id": null,
        "minimal_credit_payment": 35,
        "author": 9,
        "uuid": null,
        "created_at": "2025-01-26T23:19:36.000000Z",
        "updated_at": "2025-01-26T23:19:36.000000Z"
    }
]

Update Group

Use this endpoint to update a specific customer group. Make sure to replace {group_id} with the ID of the group you would like to update.

put
api/customers-groups/{group_id}

Request

{
    "name": "[string]",
    "reward_system_id": "[number]",
    "description": "[string]"
}

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

Delete Customer Group

Use this endpoint to delete a specific customer group. Note this request might fail if the customer group is still attached to customers. Make sure to replace {group_id} with the ID of the customer group you would like to delete.

delete
api/customers-groups/{group_id}

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

Customer Group's Customers

Use this endpoint to list all cutomers that are assigned to a specific customer group. Replace {group_id} with the ID of the group for which you would like to retrieve the customers.

get
api/customers-groups/{group_id}/customers

Response

[
  {
    "id": 1710,
    "username": "alysson.ferry",
    "active": 1,
    "author": 8,
    "email": "ndouglas@hotmail.com",
    "password": "$2y$10$UF1x4/8xOUUcrefMF.aINOQAPCkcujDfy/dubBXWClgtKoOBnWBDe",
    "group_id": 1,
    "first_name": "Ben",
    "last_name": "Schmitt",
    "gender": "",
    "phone": "+1-484-334-4839",
    "pobox": "40440",
    "activation_expiration": null,
    "total_sales_count": 0,
    "total_sales": 0,
    "birth_date": null,
    "purchases_amount": 0,
    "owed_amount": 0,
    "credit_limit_amount": 0,
    "account_amount": 0,
    "activation_token": null,
    "remember_token": null,
    "created_at": "2025-01-26T23:19:36.000000Z",
    "updated_at": "2025-01-26T23:19:36.000000Z",
    "origin_store_id": null,
    "wc_customer_id": null
  }
]

Transfers Customers

Use this endpoint to move customers from one group to another group. Where from is the source group id and to is the destination group id. You can specific the IDs (in an array) that are targeted with ids or use a wilcard "*" to transfers all customers.

post
api/customers-groups/transfer-customers

Request

{
    "from": "[number]",
    "to": "[number]",
    "ids": [ 1, 2, 3 ]
}

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

Crud

CRUD which stands for "Create Read Update Delete" is an acronym mostly used to define a feature that allows interacting with data. NexoPOS comes with a built-in CRUD feature that is widely used through the following API.

For further instruction how how to interact with the Crud API, refer to the documentation.

Get Table Entries

Use this endpoint to retreive the configuration of a table. By table we mean that UI component that is used to displays a list of entries.

post
api/crud/{namespace}

Response

{
  "current_page": 1,
  "data": [
    {
      "id": 95,
      "name": "Spaghetti Carbonara",
      "tax_type": "inclusive",
      "tax_group_id": 1,
      "tax_value": 0,
      "product_type": "product",
      "type": "<strong class=\"text-info-tertiary \">Dematerialized Product</strong>",
      "accurate_tracking": 0,
      "auto_cogs": 0,
      "status": "Available",
      "stock_management": "Enabled",
      "barcode": "8408756723372",
      "barcode_type": "ean13",
      "sku": "im5sDd0r2tIhrR6",
      "description": "Created via tests",
      "thumbnail_id": null,
      "category_id": 9,
      "parent_id": 0,
      "unit_group": 1,
      "on_expiration": "prevent_sales",
      "expires": 0,
      "searchable": 1,
      "author": 8,
      "uuid": null,
      "created_at": "2025-02-02 09:33:08",
      "updated_at": "2025-02-02 09:43:07",
      "user_username": "admin",
      "category_name": "Pastas",
      "parent_name": null,
      "taxes_groups_id": 1,
      "taxes_groups_name": "GST",
      "taxes_groups_description": null,
      "taxes_groups_author": 8,
      "taxes_groups_uuid": null,
      "taxes_groups_created_at": "2025-02-02 09:32:48",
      "taxes_groups_updated_at": "2025-02-02 09:32:48",
      "$checked": false,
      "$toggled": false,
      "$id": 95,
      "rawType": "dematerialized",
      "rawStockManagement": "enabled",
      "$actions": {
        "edit": {
          "label": "<i class=\"mr-2 las la-edit\"></i> Edit",
          "identifier": "edit",
          "url": "https://example.com/dashboard/products/edit/95",
          "confirm": null,
          "type": "GOTO",
          "permissions": []
        },
        "ns.quantities": {
          "label": "<i class=\"mr-2 las la-eye\"></i> Preview",
          "identifier": "ns.quantities",
          "url": "https://example.com/dashboard/products/edit/95",
          "confirm": null,
          "type": "POPUP",
          "permissions": []
        },
        "units": {
          "label": "<i class=\"mr-2 las la-balance-scale-left\"></i> See Quantities",
          "identifier": "units",
          "url": "https://example.com/dashboard/products/95/units",
          "confirm": null,
          "type": "GOTO",
          "permissions": []
        },
        "history": {
          "label": "<i class=\"mr-2 las la-history\"></i> See History",
          "identifier": "history",
          "url": "https://example.com/dashboard/products/95/history",
          "confirm": null,
          "type": "GOTO",
          "permissions": []
        },
        "delete": {
          "label": "<i class=\"mr-2 las la-trash\"></i> Delete",
          "identifier": "delete",
          "url": "https://example.com/api/crud/ns.products/95",
          "confirm": {
            "message": "Would you like to delete this ?"
          },
          "type": "DELETE",
          "permissions": []
        }
      }
    }
  ],
  "first_page_url": "https://example.com/api/crud/ns.products?page=1",
  "from": 1,
  "last_page": 8,
  "last_page_url": "https://example.com/api/crud/ns.products?page=8",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=2",
      "label": "2",
      "active": false
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=3",
      "label": "3",
      "active": false
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=4",
      "label": "4",
      "active": false
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=5",
      "label": "5",
      "active": false
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=6",
      "label": "6",
      "active": false
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=7",
      "label": "7",
      "active": false
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=8",
      "label": "8",
      "active": false
    },
    {
      "url": "https://example.com/api/crud/ns.products?page=2",
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": "https://example.com/api/crud/ns.products?page=2",
  "path": "https://example.com/api/crud/ns.products",
  "per_page": 20,
  "prev_page_url": null,
  "to": 20,
  "total": 146
}

Get Table Columns

Use this endpoint to retrieve the list of available columns.

get
api/crud/{namespace}/columns

Response

{
  "name": {
    "label": "Name",
    "$direction": "",
    "$sort": false
  },
  "type": {
    "label": "Type",
    "$direction": "",
    "width": "150px",
    "$sort": false
  },
  "sku": {
    "label": "Sku",
    "$direction": "",
    "$sort": false
  },
  "category_name": {
    "label": "Category",
    "width": "150px",
    "$direction": "",
    "$sort": false
  },
  "status": {
    "label": "Status",
    "$direction": "",
    "$sort": false
  },
  "user_username": {
    "label": "Author",
    "$direction": "",
    "$sort": false
  },
  "created_at": {
    "label": "Date",
    "width": "150px",
    "$direction": "",
    "$sort": false
  }
}

Get Table Configuration

This will retreive the current table configuration of a crud component.

get
api/crud/{namespace}/config

Response

{
  "columns": {
    "name": {
      "label": "Name",
      "$direction": "",
      "$sort": false
    },
    "gastro_item_type": {
      "label": "Item Type",
      "$direction": "",
      "width": "120px",
      "$sort": false
    },
    "type": {
      "label": "Type",
      "$direction": "",
      "width": "150px",
      "$sort": false
    },
    "sku": {
      "label": "Sku",
      "$direction": "",
      "$sort": false
    },
    "category_name": {
      "label": "Category",
      "width": "150px",
      "$direction": "",
      "$sort": false
    },
    "status": {
      "label": "Status",
      "$direction": "",
      "$sort": false
    },
    "user_username": {
      "label": "Author",
      "$direction": "",
      "$sort": false
    },
    "created_at": {
      "label": "Date",
      "width": "150px",
      "$direction": "",
      "$sort": false
    }
  },
  "queryFilters": [],
  "labels": {
    "list_title": "Products List",
    "list_description": "Display all products.",
    "no_entry": "No products has been registered",
    "create_new": "Add a new product",
    "create_title": "Create a new product",
    "create_description": "Register a new product and save it.",
    "edit_title": "Edit product",
    "edit_description": "Modify  Product.",
    "back_to_list": "Return to Products"
  },
  "links": {
    "list": "https://example.com/dashboard/products",
    "create": "https://example.com/dashboard/products/create"
  },
  "bulkActions": [
    {
      "label": "Delete Selected Groups",
      "identifier": "delete_selected",
      "confirm": "Would you like to delete selected entries ?",
      "url": "https://example.com/api/crud/ns.products/bulk-actions"
    }
  ],
  "prependOptions": true,
  "showOptions": true,
  "showCheckboxes": true,
  "headerButtons": [],
  "namespace": "ns.products"
}

Get Form Configuration

Use this endpoint to retrieve the shape of the form. When {id} is provided, the model defined on the CRUD will be loaded and it's property loaded on each fields. The way data are loaded is defined on the method getForm() of each CRUD instance.

get
api/crud/{namespace}/form-config/{id?}

Response

{
  "form": {
    "main": {
      "label": "Name",
      "name": "name",
      "value": "",
      "description": "Provide a name to the resource.",
      "validation": "required"
    },
    "tabs": {
      "general": {
        "label": "General",
        "fields": [
          {
            "type": "media",
            "label": "Preview",
            "name": "preview_url",
            "description": "Provide a preview url to the category.",
            "value": ""
          },
          {
            "type": "switch",
            "label": "Displays On POS",
            "name": "displays_on_pos",
            "description": "If clicked to no, all products assigned to this category or all sub categories, won't appear at the POS.",
            "options": [],
            "validation": "required",
            "value": 1
          },
          {
            "type": "select",
            "options": [],
            "name": "parent_id",
            "label": "Parent",
            "description": "If this category should be a child category of an existing category",
            "value": ""
          },
          {
            "type": "ckeditor",
            "name": "description",
            "label": "Description",
            "value": ""
          }
        ]
      }
    }
  },
  "labels": {
    "list_title": "Category Products List",
    "list_description": "Display all category products.",
    "no_entry": "No category products has been registered",
    "create_new": "Add a new category product",
    "create_title": "Create a new category product",
    "create_description": "Register a new category product and save it.",
    "edit_title": "Edit category product",
    "edit_description": "Modify  Category Product.",
    "back_to_list": "Return to Category Products"
  },
  "links": {
    "list": "https://example.com/dashboard/products/categories",
    "create": "https://example.com/dashboard/products/categories/create",
    "edit": "https://example.com/dashboard/products/categories/edit",
    "post": "https://example.com/api/crud/ns.products-categories",
    "put": "https://example.com/api/crud/ns.products-categories/{id}"
  },
  "submitMethod": "post",
  "namespace": "ns.products",
  "optionAttributes": {
    "label": "name",
    "value": "id"
  },
  "queryParams": [],
  "title": "Create a new category product",
  "description": "Register a new category product and save it.",
  "src": "https://example.com/api/crud/ns.products-categories/form-config",
  "returnUrl": "https://example.com/dashboard/products/categories",
  "submitUrl": "https://example.com/api/crud/ns.products-categories"
}

Create Entry

The structure of a POST request varies from my CRUD component to another. Generally speaking, as CRUD component are composed of tabs, we're sending a multi-hierarchical object. For more details on the structure of a refer to the "Get From Configuration".

post
api/crud/{namespace}

Response

{
    "name": "[string]",
    "general": {
        "field_1": "[mixed]",
        "field_2": "[mixed]"
    }
}

The entry general that keeps field_1 and field_2, is not persistent on the database and is only used for grouping fields. It can therefore be anything you want.

Update Entry

Use this endpoint to update a CRUD entry. The only difference with the "Create Entry", is the required {id} parameter that is provided. Make sure to replace both {namespace} and {id} with their respective values.

put
api/crud/{namespace}/{id}

Request

{
    "name": "[string]",
    "general": {
        "field_1": "[mixed]",
        "field_2": "[mixed]"
    }
}

Export Entries

Use this endpoint to extract as a CSV document all the entries of a CRUD component.

get
api/crud/{namespace}/export

Available Components

Here is a list of the component that are currently available on the CRUD API. Those files are located on the directory app/Crud.

Name Class
Coupons App\Models\CouponCrud
Coupon Usage App\Models\CouponOrderHistoryCrud
Customer Wallet App\Models\CustomerAccountCrud
Customer Coupons App\Models\CustomerCouponCrud
Customer Coupon Usage App\Models\CustomerCouponHistoryCrud
Customers App\Models\CustomerCrud
Customers Group App\Models\CustomerGroupCrud
Customer's Orders App\Models\CustomerOrderCrud
Customers Rewards App\Models\CustomerRewardCrud
Products History App\Models\GlobalProductHistoryCrud
Hold Orders App\Models\HoldOrderCrud
Orders Instalments App\Models\OrderInstalmentCrud
Partially Paid Orders App\Models\PartiallyPaidOrderCrud
Payment Types App\Models\PaymentTypeCrud
Procurements App\Models\ProcurementCrud
Procurements Products App\Models\ProcurementProductCrud
Products Categories App\Models\ProductCategoryCrud
Products App\Models\ProductCrud
Products History App\Models\ProductHistoryCrud
Products Unit Quantities App\Models\ProductUnitQuantitiesCrud
Providers App\Models\ProviderCrud
Providers Procurements App\Models\ProviderProcurementsCrud
Provider Products App\Models\ProviderProductsCrud
Registers App\Models\RegisterCrud
Registers History App\Models\RegisterHistoryCrud
Rewards System App\Models\RewardSystemCrud
Roles App\Models\RolesCrud
Taxes App\Models\TaxCrud
Tax Groups App\Models\TaxesGroupCrud
Transaction Accounts App\Models\TransactionAccountCrud
Transactions App\Models\TransactionCrud
Transactions History App\Models\TransactionHistoryCrud
Units App\Models\UnitCrud
Units Groups App\Models\UnitGroupCrud
Unpaid Orders UnpaidOrderCrud
Users App\Models\UserCrud

Fields

The Fields endpoint give you access to a structure of defined fields. The way fields are defined varies from one instance of FieldsService class to another. Fields are defined on the directory app/Fields;

Get Fields

Use this endpoint to get the shape of a fields. You can optionnally provide an identifier that will be used by the FieldsService class. For example, this is used to retrieve the login, registration fields etc. We'll use the login fields as an example.

get
api/fields/{resource}/{identifier?}

Response 

[
  {
    "label": "Username",
    "description": "Provide your username.",
    "validation": "required",
    "name": "username",
    "type": "text"
  },
  {
    "label": "Password",
    "description": "Provide your password.",
    "validation": "required",
    "name": "password",
    "type": "password"
  }
]

Available Fields

Here is a list of available fields and their identifier.

Name Class Identifier
Authentication Fields App\Fields\AuthLoginFields ns.login
Registration Fields App\Fields\AuthRegisterFields ns.register
Cash Register Cash In App\Fields\CashRegisterCashingFields ns.cash-registers-cashing
Cash Register Cash out App\Fields\CashRegisterCashoutFields ns.cash-registers-cashout
Cash Register Closing App\Fields\CashRegisterClosingFields ns.cash-registers-closing
Cash Register Opening App\Fields\CashRegisterOpeningFields ns.cash-registers-opening
Customer Account Fields App\Fields\CustomerAccountFields ns.customers-account
Direct Transaction App\Fields\DirectTransactionFields ns.direct-transaction
Entity Transaction App\Fields\EntityTransactionFields ns.entity-transaction
Layaway Fields App\Fields\LayawayFields ns.layaway
New Password Fields App\Fields\NewPasswordFields ns.new-password
Order Payment Fields App\Fields\OrderPaymentFields ns.order-payments
Password Lost Fields App\Fields\PasswordLostFields ns.password-lost
POS Order Settings App\Fields\PosOrderSettingsFields ns.pos-order-settings
Procurement Fields App\Fields\ProcurementFields ns.procurement-fields
Recurring Transaction Fields App\Fields\RecurringTransactionFields ns.recurring-transaction
Refund Product Fields App\Fields\RefundProductFields ns.refund-product
Reset Fields App\Fields\ResetFields ns.reset
Scheduled Transaction Fields App\Fields\ScheduledTransactionFields ns.scheduled-transaction
Units Fields App\Fields\UnitFields ns.units-fields
Units Group Fields App\Fields\UnitGroupFields ns.units-group-fields

Forms

Unlike fields, forms provide a more complex structure of fields. This usually consist of a tabbed form. This is currently used by the settings.

Get Form

Use this endpoint to retrieve the shape of a declared form. You'll replace {resource} by the identifier of the Form and {identifier?} (optional) to provide more context to the Form. Note that the context might be needed or not by the Form, you should refer to the Form or it's declared documentation to understand how to use it.

get
api/forms/{resource}/{identifier?}

Response

We'll use ns.user-profile to retrieve the form in use on the user profile section.

{
  "tabs": {
    "attribute": {
      "label": "General",
      "fields": [
        {
          "label": "Theme",
          "name": "theme",
          "value": "dark",
          "type": "select",
          "options": [
            {
              "label": "Dark",
              "value": "dark"
            },
            {
              "label": "Light",
              "value": "light"
            }
          ],
          "description": "Define what is the theme that applies to the dashboard."
        },
        {
          "label": "Avatar",
          "name": "avatar_link",
          "value": "",
          "type": "media",
          "data": {
            "user_id": 8,
            "type": "url"
          },
          "description": "Define the image that should be used as an avatar."
        },
        {
          "label": "Language",
          "name": "language",
          "value": "en",
          "type": "select",
          "options": [
            {
              "label": "English",
              "value": "en"
            },
            {
              "label": "Deutsch",
              "value": "de"
            },
            {
              "label": "Français",
              "value": "fr"
            },
            {
              "label": "Espanol",
              "value": "es"
            },
            {
              "label": "Italian",
              "value": "it"
            },
            {
              "label": "Arabic",
              "value": "ar"
            },
            {
              "label": "Portuguese",
              "value": "pt"
            },
            {
              "label": "Türkçe",
              "value": "tr"
            },
            {
              "label": "ភាសាខ្មែរ",
              "value": "km"
            },
            {
              "label": "Vietnamese",
              "value": "vi"
            },
            {
              "label": "Shqiptare",
              "value": "sq"
            }
          ],
          "description": "Choose the language for the current account."
        }
      ]
    },
    "shipping": {
      "label": "Shipping",
      "fields": [
        {
          "type": "text",
          "name": "first_name",
          "value": "",
          "label": "First Name",
          "description": "Provide the billing first name."
        },
        {
          "type": "text",
          "name": "last_name",
          "value": "",
          "label": "Last Name",
          "description": "Provide the billing last name."
        },
        {
          "type": "text",
          "name": "phone",
          "value": "",
          "label": "Phone",
          "description": "Billing phone number."
        },
        {
          "type": "text",
          "name": "address_1",
          "value": "",
          "label": "Address 1",
          "description": "Billing First Address."
        },
        {
          "type": "text",
          "name": "address_2",
          "value": "",
          "label": "Address 2",
          "description": "Billing Second Address."
        },
        {
          "type": "text",
          "name": "country",
          "value": "",
          "label": "Country",
          "description": "Billing Country."
        },
        {
          "type": "text",
          "name": "city",
          "value": "",
          "label": "City",
          "description": "City"
        },
        {
          "type": "text",
          "name": "pobox",
          "value": "",
          "label": "PO.Box",
          "description": "Postal Address"
        },
        {
          "type": "text",
          "name": "company",
          "value": "",
          "label": "Company",
          "description": "Company"
        },
        {
          "type": "text",
          "name": "email",
          "value": "",
          "label": "Email",
          "description": "Email"
        }
      ]
    },
    "billing": {
      "label": "Biling",
      "fields": [
        {
          "type": "text",
          "name": "first_name",
          "value": "",
          "label": "First Name",
          "description": "Provide the billing first name."
        },
        {
          "type": "text",
          "name": "last_name",
          "value": "",
          "label": "Last Name",
          "description": "Provide the billing last name."
        },
        {
          "type": "text",
          "name": "phone",
          "value": "",
          "label": "Phone",
          "description": "Billing phone number."
        },
        {
          "type": "text",
          "name": "address_1",
          "value": "",
          "label": "Address 1",
          "description": "Billing First Address."
        },
        {
          "type": "text",
          "name": "address_2",
          "value": "",
          "label": "Address 2",
          "description": "Billing Second Address."
        },
        {
          "type": "text",
          "name": "country",
          "value": "",
          "label": "Country",
          "description": "Billing Country."
        },
        {
          "type": "text",
          "name": "city",
          "value": "",
          "label": "City",
          "description": "City"
        },
        {
          "type": "text",
          "name": "pobox",
          "value": "",
          "label": "PO.Box",
          "description": "Postal Address"
        },
        {
          "type": "text",
          "name": "company",
          "value": "",
          "label": "Company",
          "description": "Company"
        },
        {
          "type": "text",
          "name": "email",
          "value": "",
          "label": "Email",
          "description": "Email"
        }
      ]
    },
    "security": {
      "label": "Security",
      "fields": [
        {
          "label": "Old Password",
          "name": "old_password",
          "type": "password",
          "description": "Provide the old password."
        },
        {
          "label": "Password",
          "name": "password",
          "type": "password",
          "description": "Change your password with a better stronger password.",
          "validation": "sometimes|min:6"
        },
        {
          "label": "Password Confirmation",
          "name": "password_confirm",
          "type": "password",
          "description": "Change your password with a better stronger password.",
          "validation": "same:security.password"
        }
      ]
    },
    "token": {
      "label": "API Token",
      "component": "nsToken",
      "fields": []
    }
  }
}

Available Forms

Here is a list of available form and their identifier.

Name Class Identifier
Order Address App\Forms\POSAddressForm ns.pos-addresses
Procurement Form App\Forms\ProcurementForm ns.procurement
User Profile App\Forms\UserProfileForm ns.user-profile

Medias

The medias endpoint helps interacting with the media library.

Upload Media

You'll use this endpoint to upload a media file to the library.

post
api/medias

Request

{
    "file": "[binary]"
}

Response

{
    "status": "[error|success]",
    "message": "[string]"
}

List Medias

Use this endpoint to get a paginated list of medias. You can navigate through page by adding the query ?page=x, where "x" is the page you would like to load.

get
api/medias

Response

{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "name": "capture-decran-2024-12-13-152535",
      "extension": "png",
      "slug": "2025/02/capture-decran-2024-12-13-152535",
      "user_id": 8,
      "created_at": "2025-02-06 11:40:55",
      "updated_at": "2025-02-06 11:40:55",
      "sizes": {
        "original": "https://example.com/storage/2025/02/capture-decran-2024-12-13-152535.png",
        "thumb": "https://example.com/storage/2025/02/capture-decran-2024-12-13-152535-thumb.png"
      },
      "user": {
        "id": 8,
        "username": "admin",
        "active": true,
        "author": 8,
        "email": "contact@nexopos.com",
        "group_id": null,
        "first_name": null,
        "last_name": null,
        "gender": null,
        "phone": null,
        "pobox": null,
        "activation_expiration": null,
        "total_sales_count": 68,
        "total_sales": 7207.9,
        "birth_date": null,
        "purchases_amount": 0,
        "owed_amount": 0,
        "credit_limit_amount": 0,
        "account_amount": 0,
        "activation_token": null,
        "created_at": "2025-01-13T22:52:01.000000Z",
        "updated_at": "2025-02-03T20:32:58.000000Z",
        "origin_store_id": null,
        "wc_customer_id": null
      }
    }
  ],
  "first_page_url": "https://example.com/api/medias?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://example.com/api/medias?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "https://example.com/api/medias?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://example.com/api/medias",
  "per_page": 20,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

Update Media

This update allow updating the name of a media. It can't be used to replace the previously uploaded image. Make sure to replace {id} with the actual media ID.

put
api/medias/{id}

Request

{
    "name": "[string]"
}

Response

{
    "status": "[error|success]",
    "message": "[string]"
}

Delete Media

Use this endpoint to delete an existing media. You'll replace {id} with the ID of the media you would like to delete.

delete
api/medias/{id}

Response

{
    "status": "[error|success]",
    "message": "[string]"
}

Bulk Delete Medias

Use this endpoint to bulk-delete your medias. This requires ids to be provided and to be an array of media's ID.

post
api/medias/bulk-delete

Request

{
    "ids": []
}

Response

{
    "status": "[error|success]",
    "message": "[string]"
}

Modules

This section allows you to interact with existing module.

List Modules

Use this endpoint to receive a list of available modules.

get
api/modules

Response

{
  "modules": {
    "NsGastro": {
      "namespace": "NsGastro",
      "version": "5.3",
      "author": "Blair Jersyer",
      "name": "Gastro - Restaurant Extension",
      "description": "Gastro provides a restaurant features on top of NexoPOS to ease restaurant management.",
      "core": {
        "min-version": "5.2.6",
        "max-version": "5.3.0"
      },
      "recommends": {
        "dependency": "Nexo Print Adapter"
      },
      "requires": [],
      "files": [
        ".gitignore",
        "NsGastroModule.php",
        "README.md",
        "commands.txt",
        "config.xml",
        "index.php",
        "package-lock.json",
        "package.json",
        "phpunit.ci.xml",
        "phpunit.xml",
        "phpunit.xml.bak",
        "postcss.config.cjs",
        "tailwind.config.cjs",
        "todo",
        "tsconfig.json",
        "vite.config.js"
      ],
      "api-file": "/var/www/html/default/modules/NsGastro/Routes/api.php",
      "composer-installed": false,
      "controllers-path": "/var/www/html/default/modules/NsGastro/Http/Controllers",
      "controllers-relativePath": "NsGastro/Http/Controllers",
      "enabled": true,
      "has-languages": true,
      "lang-relativePath": "modules/NsGastro/Lang",
      "index-file": "/var/www/html/default/modules/NsGastro/NsGastroModule.php",
      "path": "/var/www/html/default/modules/NsGastro/",
      "relativePath": "modules/NsGastro/",
      "requires-composer": false,
      "routes-file": "/var/www/html/default/modules/NsGastro/Routes/web.php",
      "views-path": "/var/www/html/default/modules/NsGastro/Resources/Views",
      "views-relativePath": "modules/NsGastro/Views",
      "autoloaded": false,
      "entry-class": "Modules\\NsGastro\\NsGastroModule",
      "providers": [
        "NsGastro/Providers/ModuleServiceProvider.php"
      ],
      "actions": [],
      "filters": [],
      "commands": [],
      "psr-4-compliance": true,
      "langFiles": {
        "ar": "NsGastro/Lang/ar.json",
        "de": "NsGastro/Lang/de.json",
        "en": "NsGastro/Lang/en.json",
        "es": "NsGastro/Lang/es.json",
        "fr": "NsGastro/Lang/fr.json",
        "it": "NsGastro/Lang/it.json",
        "nl": "NsGastro/Lang/nl.json",
        "pt": "NsGastro/Lang/pt.json",
        "sq": "NsGastro/Lang/sq.json",
        "tr": "NsGastro/Lang/tr.json",
        "vi": "NsGastro/Lang/vi.json"
      },
      "migrations": [],
      "all-migrations": [
        "NsGastro/Migrations/UpdateToV5Migration.php"
      ]
    },
  },
  "total_enabled": 1,
  "total_disabled": 0,
  "total_invalid": 0
}

Enable Module

This endpoint shoudl be used to enable a module using it's identifier. You'll replace {identifier} with the module's identifier you want to enable.

put
api/modules/{identifier}/enable

Response

{
  "status": "success",
  "message": "The module has correctly been enabled.",
  "data": {
    "code": "module_enabled",
    "module": {
      "namespace": "NsGastro",
      "version": "5.3",
      "author": "Blair Jersyer",
      "name": "Gastro - Restaurant Extension",
      "description": "Gastro provides a restaurant features on top of NexoPOS to ease restaurant management.",
      "core": {
        "min-version": "5.2.6",
        "max-version": "5.3.0"
      },
      "recommends": {
        "dependency": "Nexo Print Adapter"
      },
      "requires": [],
      "files": [
        ".gitignore",
        "NsGastroModule.php",
        "README.md",
        "commands.txt",
        "config.xml",
        "index.php",
        "package-lock.json",
        "package.json",
        "phpunit.ci.xml",
        "phpunit.xml",
        "phpunit.xml.bak",
        "postcss.config.cjs",
        "tailwind.config.cjs",
        "todo",
        "tsconfig.json",
        "vite.config.js"
      ],
      "api-file": "/var/www/html/default/modules/NsGastro/Routes/api.php",
      "composer-installed": false,
      "controllers-path": "/var/www/html/default/modules/NsGastro/Http/Controllers",
      "controllers-relativePath": "NsGastro/Http/Controllers",
      "enabled": false,
      "has-languages": true,
      "lang-relativePath": "modules/NsGastro/Lang",
      "index-file": "/var/www/html/default/modules/NsGastro/NsGastroModule.php",
      "path": "/var/www/html/default/modules/NsGastro/",
      "relativePath": "modules/NsGastro/",
      "requires-composer": false,
      "routes-file": "/var/www/html/default/modules/NsGastro/Routes/web.php",
      "views-path": "/var/www/html/default/modules/NsGastro/Resources/Views",
      "views-relativePath": "modules/NsGastro/Views",
      "autoloaded": false,
      "entry-class": "Modules\\NsGastro\\NsGastroModule",
      "providers": [
        "NsGastro/Providers/ModuleServiceProvider.php"
      ],
      "actions": [],
      "filters": [],
      "commands": [],
      "psr-4-compliance": true,
      "migrations": [],
      "all-migrations": [
        "NsGastro/Migrations/UpdateToV5Migration.php"
      ]
    },
    "migrations": []
  }
}

Disable Module

This endpoint is used to disable a module using it's identifier. You'll replace {identifier} by the module's identifer you want to disable.

Please refer to this guide to disable a module when you're locked out of the dashboard.

put
api/modules/{identifier}/disable

Response 

{
  "status": "success",
  "code": "module_disabled",
  "message": "The Module has been disabled.",
  "module": {
    "namespace": "NsGastro",
    "version": "5.3",
    "author": "Blair Jersyer",
    "name": "Gastro - Restaurant Extension",
    "description": "Gastro provides a restaurant features on top of NexoPOS to ease restaurant management.",
    "core": {
      "min-version": "5.2.6",
      "max-version": "5.3.0"
    },
    "recommends": {
      "dependency": "Nexo Print Adapter"
    },
    "requires": [],
    "files": [
      ".gitignore",
      "NsGastroModule.php",
      "README.md",
      "commands.txt",
      "config.xml",
      "index.php",
      "package-lock.json",
      "package.json",
      "phpunit.ci.xml",
      "phpunit.xml",
      "phpunit.xml.bak",
      "postcss.config.cjs",
      "tailwind.config.cjs",
      "todo",
      "tsconfig.json",
      "vite.config.js"
    ],
    "api-file": "/var/www/html/default/modules/NsGastro/Routes/api.php",
    "composer-installed": false,
    "controllers-path": "/var/www/html/default/modules/NsGastro/Http/Controllers",
    "controllers-relativePath": "NsGastro/Http/Controllers",
    "enabled": true,
    "has-languages": true,
    "lang-relativePath": "modules/NsGastro/Lang",
    "index-file": "/var/www/html/default/modules/NsGastro/NsGastroModule.php",
    "path": "/var/www/html/default/modules/NsGastro/",
    "relativePath": "modules/NsGastro/",
    "requires-composer": false,
    "routes-file": "/var/www/html/default/modules/NsGastro/Routes/web.php",
    "views-path": "/var/www/html/default/modules/NsGastro/Resources/Views",
    "views-relativePath": "modules/NsGastro/Views",
    "autoloaded": false,
    "entry-class": "Modules\\NsGastro\\NsGastroModule",
    "providers": [
      "NsGastro/Providers/ModuleServiceProvider.php"
    ],
    "actions": [],
    "filters": [],
    "commands": [],
    "psr-4-compliance": true,
    "langFiles": {
      "ar": "NsGastro/Lang/ar.json",
      "de": "NsGastro/Lang/de.json",
      "en": "NsGastro/Lang/en.json",
      "es": "NsGastro/Lang/es.json",
      "fr": "NsGastro/Lang/fr.json",
      "it": "NsGastro/Lang/it.json",
      "nl": "NsGastro/Lang/nl.json",
      "pt": "NsGastro/Lang/pt.json",
      "sq": "NsGastro/Lang/sq.json",
      "tr": "NsGastro/Lang/tr.json",
      "vi": "NsGastro/Lang/vi.json"
    },
    "migrations": [],
    "all-migrations": [
      "NsGastro/Migrations/UpdateToV5Migration.php"
    ]
  }
}

Remove Module

This endpoint will remove the module from NexoPOS using the provided identifier. This will also delete all tables that might have been created by the module. You'll replace {identifier} with the module's identifier.

delete
api/modules/{identifier}/delete

Response

{
    "status": "[success|error]",
    "message": "[string]",
    "code": "[string]",
    "module": "{}"
}

Upload Module

Use this endpoint to upload a module as a zip file. This endpoint will perform install and update if necessary.

post
api/modules

Request

{
    "module": "[zip binary]"
}

Response

{
    "status": "[error|success]",
    "message": "[string]"
}

Notifications

Use this route to handle the notification of the logged user.

Get Notifications

Use this endpoint to retrieve all notifications available for the logged user.

get
api/notifications

Response

[
    {
        "id": 53,
        "user_id": 8,
        "identifier": "nspa-no-jobs",
        "title": "Kitchen Print Failure",
        "description": "No valid print jobs can be generated for the order 250210-001. Make sure the category of the products included are assigned to existing kitchen and that valid printers are assigned\"",
        "url": "#",
        "source": "system",
        "dismissable": 1,
        "created_at": "2025-02-10 11:58:12",
        "updated_at": "2025-02-10 11:58:12"
    }
]

Delete Notification

Use this endpoint to delete a notification using it's ID. You'll replace {id} with the ID that match the notification you want to delete.

delete
api/notifications/{id}

Response

{
  "status": "success",
  "message": "The notification has been successfully deleted"
}

Delete All Notifications

Use this endpoint to delete all notifications that was created for the logged user.

delete
api/notifications/all

Response

{
  "status": "success",
  "message": "All the notifications have been cleared"
}

Products

Retrieving Products

GET
api/products
[
  {
    "id": 1,
    "name": "Creamer Packet",
    "tax_type": "inclusive",
    "tax_group_id": 1,
    "tax_value": 0,
    "product_type": "product",
    "type": "dematerialized",
    "accurate_tracking": false,
    "auto_cogs": false,
    "status": "available",
    "stock_management": "disabled",
    "barcode": "2897183678939",
    "barcode_type": "ean13",
    "sku": "nwPUboV8ML3oVUW",
    "description": "Created via tests",
    "thumbnail_id": null,
    "category_id": 1,
    "parent_id": 0,
    "unit_group": 1,
    "on_expiration": "prevent_sales",
    "expires": 0,
    "searchable": 1,
    "author": 8,
    "uuid": null,
    "created_at": "2025-01-26T23:19:42.000000Z",
    "updated_at": "2025-01-26T23:19:42.000000Z",
  }
]

This endpoing will list all products available. However, it won't include any other related table (for the sake of performance).

Create Product

POST
api/products

Will create a product using the provided data structure.

Request

{
    "name": "[name]",
    "variations": [
        {
            "identification": {
                "category_id": 1,
                "barcode": "[barcode]",
                "sku": "[string]",
                "barcode_type": "[ean8|ean13|codabar|code128|code39|code11|upca|upce]",
                "type": "materialized",
                "status": "[available|unavailable]",
                "author": "[id]",
                "stock_management": "[enable|disabled]"
            },
            "units": {
                "unit_group_id": "[number]",
                "accurate_tracking": "[boolean]",
                "auto_cogs": "[boolean]",
                "selling_group": [
                    {
                        "unit_id": 1,
                        "sale_price": "[number]",
                        "wholesale_price": "[number]",
                        "cogs": "[number]",
                        "stock_alert": "[boolean]",
                        "convert_unit": "[unit_id]",
                        "visible": "[boolean]",
                        "low_quantity": "[number]",
                        "preview_url": "[url]"
                    }
                ]
            },
            "expiry": {
                "on_expiration": "[allow_sales|prevent_sales]",
                "expires": "[boolean]"
            },
            "taxes": {
                "tax_group_id": "[number]",
                "tax_type": "[inclusive|exclusive]"
            },
            "images": [
                {
                    "featured": "[boolean]",
                    "url": "[url]"
                }
            ],
        }
    ]
}

Response

{
    "status": "[success|error|info|warning]",
    "message": "[string]",
    "data": {
        "product": {
            // created product
        },
        "editUrl": "[url]"
    }
}

Retreive Product

This wil retreive a product using it's ID. You'll make sure to replace "{product_id}" with the actual product ID.

GET
api/products/{product_id}

Response

{
  "id": 1,
  "name": "Creamer Packet",
  "tax_type": "inclusive",
  "tax_group_id": 1,
  "tax_value": 0,
  "product_type": "product",
  "type": "dematerialized",
  "accurate_tracking": false,
  "auto_cogs": false,
  "status": "available",
  "stock_management": "disabled",
  "barcode": "2897183678939",
  "barcode_type": "ean13",
  "sku": "nwPUboV8ML3oVUW",
  "description": "Created via tests",
  "thumbnail_id": null,
  "category_id": 1,
  "parent_id": 0,
  "unit_group": 1,
  "on_expiration": "prevent_sales",
  "expires": 0,
  "searchable": 1,
  "author": 8,
  "uuid": null,
  "created_at": "2025-01-26T23:19:42.000000Z",
  "updated_at": "2025-01-26T23:19:42.000000Z",
}

Update Product

put
api/products/{product_id}

Request

{
    "name": "[name]",
    "variations": [
        {
            "identification": {
                "category_id": 1,
                "barcode": "[barcode]",
                "sku": "[string]",
                "barcode_type": "[ean8|ean13|codabar|code128|code39|code11|upca|upce]",
                "type": "materialized",
                "status": "[available|unavailable]",
                "author": "[id]",
                "stock_management": "[enable|disabled]"
            },
            "units": {
                "unit_group_id": "[number]",
                "accurate_tracking": "[boolean]",
                "auto_cogs": "[boolean]",
                "selling_group": [
                    {
                        "unit_id": 1,
                        "sale_price": "[number]",
                        "wholesale_price": "[number]",
                        "cogs": "[number]",
                        "stock_alert": "[boolean]",
                        "convert_unit": "[unit_id]",
                        "visible": "[boolean]",
                        "low_quantity": "[number]",
                        "preview_url": "[url]"
                    }
                ]
            },
            "expiry": {
                "on_expiration": "[allow_sales|prevent_sales]",
                "expires": "[boolean]"
            },
            "taxes": {
                "tax_group_id": "[number]",
                "tax_type": "[inclusive|exclusive]"
            },
            "images": [
                {
                    "featured": "[boolean]",
                    "url": "[url]"
                }
            ],
        }
    ]
}

Response

{
    "status": "[success|failure|info|warning]",
    "message": "[string]",
    "data": {
        "product": {
            // updated product
        },
        "editUrl": "[url]"
    }
}

You'll use this endpoint to update an existing product. You'll replace "{product_id}" by the actual id of the product you would like to update.

Delete Product

You'll use this to delete a product with all it's related tables. This endpoint is proctected by a permission check. You might also get an error if the product is currently used.

delete
api/products/{product_id}

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

Get Product History

This endpoint will provide a full list of stock movement that has occured on a specific product. You'll replace {product_id} with the ID of the product for which you would like to get the history. Note that this is not paginated, for a product having a very long history, you might consider increasig the execution time or refer to the CRUD approach which is paginated.

get
api/products/{product_id}/history

Response

[
  {
    "id": 7,
    "product_id": 124,
    "procurement_id": 4,
    "procurement_product_id": 7,
    "order_id": null,
    "order_product_id": null,
    "operation_type": "procured",
    "unit_id": 7,
    "before_quantity": 0,
    "quantity": 5,
    "after_quantity": 5,
    "unit_price": 1.23,
    "total_price": 6.15,
    "description": null,
    "author": 8,
    "uuid": null,
    "created_at": "2025-01-29T12:54:07.000000Z",
    "updated_at": "2025-01-29T12:54:07.000000Z",
    "unit": {
      "id": 7,
      "name": "teaspoon",
      "identifier": "teaspoon",
      "description": null,
      "author": 8,
      "group_id": 4,
      "value": 1,
      "preview_url": null,
      "base_unit": true,
      "uuid": null,
      "created_at": "2025-01-26T23:23:20.000000Z",
      "updated_at": "2025-01-26T23:23:20.000000Z"
    }
  }
]

Get Product Variations

While this feature is not yet fully used on NexoPOS as a single variation is enforced for now, you can use it in the future to retreive products variations.

get
api/products/{product_id}/variations
[]

Reset Product

Use this to erase the product inventory. This will be used to have a fresh start with the product. Requires to have the privilege for editing products.

get
api/products/{product_id}/reset
{
  "status": "success",
  "message": "The product has been reset.",
  "data": {
    "product": {
      "id": 1,
      "name": "Creamer Packet",
      "tax_type": "inclusive",
      "tax_group_id": 1,
      "tax_value": 0,
      "product_type": "product",
      "type": "dematerialized",
      "accurate_tracking": false,
      "auto_cogs": false,
      "status": "available",
      "stock_management": "disabled",
      "barcode": "2897183678939",
      "barcode_type": "ean13",
      "sku": "nwPUboV8ML3oVUW",
      "description": "Created via tests",
      "thumbnail_id": null,
      "category_id": 1,
      "parent_id": 0,
      "unit_group": 1,
      "on_expiration": "prevent_sales",
      "expires": 0,
      "searchable": 1,
      "author": 8,
      "uuid": null,
      "created_at": "2025-01-26T23:19:42.000000Z",
      "updated_at": "2025-01-26T23:19:42.000000Z",
    }
  }
}

Product Units

Used to retreive all units attached to a products.

get
api/products/{product_id}/units

Response

[
  {
    "id": 4,
    "product_id": 2,
    "type": "product",
    "preview_url": "https://nexocloud.dev/modules/nsgastro/images/categories/condiments/sugar-packet.jpeg",
    "expiration_date": null,
    "unit_id": 1,
    "barcode": "3962888485645-4",
    "quantity": 0,
    "low_quantity": 0,
    "stock_alert_enabled": 0,
    "sale_price": 0,
    "sale_price_edit": 0,
    "sale_price_without_tax": 0,
    "sale_price_with_tax": 0,
    "sale_price_tax": 0,
    "wholesale_price": 0,
    "wholesale_price_edit": 0,
    "wholesale_price_with_tax": 0,
    "wholesale_price_without_tax": 0,
    "wholesale_price_tax": 0,
    "custom_price": 0,
    "custom_price_edit": 0,
    "custom_price_with_tax": 0,
    "custom_price_without_tax": 0,
    "custom_price_tax": 0,
    "visible": 1,
    "convert_unit_id": null,
    "cogs": 0,
    "uuid": null,
    "created_at": "2025-01-26T23:19:42.000000Z",
    "updated_at": "2025-01-26T23:19:42.000000Z",
    "unit": {
      "id": 1,
      "name": "Piece",
      "identifier": "piece",
      "description": "",
      "author": 8,
      "group_id": 1,
      "value": 1,
      "preview_url": "",
      "base_unit": true,
      "uuid": null,
      "created_at": "2025-01-26T23:19:36.000000Z",
      "updated_at": "2025-01-26T23:19:42.000000Z"
    }
  },
  {
    "id": 5,
    "product_id": 2,
    "type": "product",
    "preview_url": "https://nexocloud.dev/modules/nsgastro/images/categories/condiments/sugar-packet.jpeg",
    "expiration_date": null,
    "unit_id": 2,
    "barcode": "3962888485645-5",
    "quantity": 0,
    "low_quantity": 0,
    "stock_alert_enabled": 0,
    "sale_price": 0,
    "sale_price_edit": 0,
    "sale_price_without_tax": 0,
    "sale_price_with_tax": 0,
    "sale_price_tax": 0,
    "wholesale_price": 0,
    "wholesale_price_edit": 0,
    "wholesale_price_with_tax": 0,
    "wholesale_price_without_tax": 0,
    "wholesale_price_tax": 0,
    "custom_price": 0,
    "custom_price_edit": 0,
    "custom_price_with_tax": 0,
    "custom_price_without_tax": 0,
    "custom_price_tax": 0,
    "visible": 1,
    "convert_unit_id": null,
    "cogs": 0,
    "uuid": null,
    "created_at": "2025-01-26T23:19:42.000000Z",
    "updated_at": "2025-01-26T23:19:42.000000Z",
    "unit": {
      "id": 2,
      "name": "Small Box",
      "identifier": "small-box",
      "description": "",
      "author": 8,
      "group_id": 1,
      "value": 6,
      "preview_url": null,
      "base_unit": true,
      "uuid": null,
      "created_at": "2025-01-26T23:19:36.000000Z",
      "updated_at": "2025-01-26T23:19:36.000000Z"
    }
  },
  {
    "id": 6,
    "product_id": 2,
    "type": "product",
    "preview_url": "https://nexocloud.dev/modules/nsgastro/images/categories/condiments/sugar-packet.jpeg",
    "expiration_date": null,
    "unit_id": 3,
    "barcode": "3962888485645-6",
    "quantity": 0,
    "low_quantity": 0,
    "stock_alert_enabled": 0,
    "sale_price": 0,
    "sale_price_edit": 0,
    "sale_price_without_tax": 0,
    "sale_price_with_tax": 0,
    "sale_price_tax": 0,
    "wholesale_price": 0,
    "wholesale_price_edit": 0,
    "wholesale_price_with_tax": 0,
    "wholesale_price_without_tax": 0,
    "wholesale_price_tax": 0,
    "custom_price": 0,
    "custom_price_edit": 0,
    "custom_price_with_tax": 0,
    "custom_price_without_tax": 0,
    "custom_price_tax": 0,
    "visible": 1,
    "convert_unit_id": null,
    "cogs": 0,
    "uuid": null,
    "created_at": "2025-01-26T23:19:42.000000Z",
    "updated_at": "2025-01-26T23:19:42.000000Z",
    "unit": {
      "id": 3,
      "name": "Box",
      "identifier": "box",
      "description": "",
      "author": 8,
      "group_id": 1,
      "value": 12,
      "preview_url": null,
      "base_unit": true,
      "uuid": null,
      "created_at": "2025-01-26T23:19:36.000000Z",
      "updated_at": "2025-01-26T23:19:36.000000Z"
    }
  }
]

Product Unit Quantity

You'll use this endpoint to retreive a single product unit quantity. You'll replace "{product_id}" and "{unit_id}" by their relevant values.

get
api/products/{product_id}/units/{unit_id}/quantity

Response

{
  "id": 4,
  "product_id": 2,
  "type": "product",
  "preview_url": "https://nexocloud.dev/modules/nsgastro/images/categories/condiments/sugar-packet.jpeg",
  "expiration_date": null,
  "unit_id": 1,
  "barcode": "3962888485645-4",
  "quantity": 0,
  "low_quantity": 0,
  "stock_alert_enabled": 0,
  "sale_price": 0,
  "sale_price_edit": 0,
  "sale_price_without_tax": 0,
  "sale_price_with_tax": 0,
  "sale_price_tax": 0,
  "wholesale_price": 0,
  "wholesale_price_edit": 0,
  "wholesale_price_with_tax": 0,
  "wholesale_price_without_tax": 0,
  "wholesale_price_tax": 0,
  "custom_price": 0,
  "custom_price_edit": 0,
  "custom_price_with_tax": 0,
  "custom_price_without_tax": 0,
  "custom_price_tax": 0,
  "visible": 1,
  "convert_unit_id": null,
  "cogs": 0,
  "uuid": null,
  "created_at": "2025-01-26T23:19:42.000000Z",
  "updated_at": "2025-01-26T23:19:42.000000Z",
}

Product Procurements

Use this endpoint to retreive all purchases that was made for a specific product.

get
api/products/{product_id}/procurements

Response

[
  {
    "id": 7,
    "name": "Basil leaves",
    "gross_purchase_price": 1.23,
    "net_purchase_price": 1.23,
    "procurement_id": 4,
    "product_id": 124,
    "purchase_price": 1.23,
    "quantity": 5,
    "available_quantity": 5,
    "tax_group_id": 0,
    "barcode": "RFYAd3rApW-007-007",
    "expiration_date": null,
    "tax_type": "inclusive",
    "tax_value": 0,
    "total_purchase_price": 6.15,
    "unit_id": 7,
    "convert_unit_id": null,
    "author": 8,
    "uuid": null,
    "created_at": "2025-01-29T12:54:06.000000Z",
    "updated_at": "2025-01-29T12:54:06.000000Z",
    "procurement": {
      "name": "00004"
    }
  }
]

Use this to have perform a strict retreival of product having as barcode the provided term. This endpoint is used on the POS to get product using a Barcode reader. You'll replace "{barcode}" with the barcode you would like to use as search term.

get
api/products/search/using-barcode/{barcode}

Response

{
  "type": "product",
  "product": {
    "id": 2,
    "name": "Sugar Packet",
    "tax_type": "inclusive",
    "tax_group_id": 1,
    "tax_value": 0,
    "product_type": "product",
    "type": "dematerialized",
    "accurate_tracking": false,
    "auto_cogs": false,
    "status": "available",
    "stock_management": "disabled",
    "barcode": "3962888485645",
    "barcode_type": "ean13",
    "sku": "q3sKTj7sdfGD3Qt",
    "description": "Created via tests",
    "thumbnail_id": null,
    "category_id": 1,
    "parent_id": 0,
    "unit_group": 1,
    "on_expiration": "prevent_sales",
    "expires": 0,
    "searchable": 1,
    "author": 8,
    "uuid": null,
    "created_at": "2025-01-26T23:19:42.000000Z",
    "updated_at": "2025-01-26T23:19:42.000000Z",
    "unit_quantities": [
      {
        "id": 4,
        "product_id": 2,
        "type": "product",
        "preview_url": "https://nexocloud.dev/modules/nsgastro/images/categories/condiments/sugar-packet.jpeg",
        "expiration_date": null,
        "unit_id": 1,
        "barcode": "3962888485645-4",
        "quantity": 0,
        "low_quantity": 0,
        "stock_alert_enabled": 0,
        "sale_price": 0,
        "sale_price_edit": 0,
        "sale_price_without_tax": 0,
        "sale_price_with_tax": 0,
        "sale_price_tax": 0,
        "wholesale_price": 0,
        "wholesale_price_edit": 0,
        "wholesale_price_with_tax": 0,
        "wholesale_price_without_tax": 0,
        "wholesale_price_tax": 0,
        "custom_price": 0,
        "custom_price_edit": 0,
        "custom_price_with_tax": 0,
        "custom_price_without_tax": 0,
        "custom_price_tax": 0,
        "visible": 1,
        "convert_unit_id": null,
        "cogs": 0,
        "uuid": null,
        "created_at": "2025-01-26T23:19:42.000000Z",
        "updated_at": "2025-01-26T23:19:42.000000Z",
        "unit": {
          "id": 1,
          "name": "Piece",
          "identifier": "piece",
          "description": "",
          "author": 8,
          "group_id": 1,
          "value": 1,
          "preview_url": "",
          "base_unit": true,
          "uuid": null,
          "created_at": "2025-01-26T23:19:36.000000Z",
          "updated_at": "2025-01-26T23:19:42.000000Z"
        }
      },
      {
        "id": 5,
        "product_id": 2,
        "type": "product",
        "preview_url": "https://nexocloud.dev/modules/nsgastro/images/categories/condiments/sugar-packet.jpeg",
        "expiration_date": null,
        "unit_id": 2,
        "barcode": "3962888485645-5",
        "quantity": 0,
        "low_quantity": 0,
        "stock_alert_enabled": 0,
        "sale_price": 0,
        "sale_price_edit": 0,
        "sale_price_without_tax": 0,
        "sale_price_with_tax": 0,
        "sale_price_tax": 0,
        "wholesale_price": 0,
        "wholesale_price_edit": 0,
        "wholesale_price_with_tax": 0,
        "wholesale_price_without_tax": 0,
        "wholesale_price_tax": 0,
        "custom_price": 0,
        "custom_price_edit": 0,
        "custom_price_with_tax": 0,
        "custom_price_without_tax": 0,
        "custom_price_tax": 0,
        "visible": 1,
        "convert_unit_id": null,
        "cogs": 0,
        "uuid": null,
        "created_at": "2025-01-26T23:19:42.000000Z",
        "updated_at": "2025-01-26T23:19:42.000000Z",
        "unit": {
          "id": 2,
          "name": "Small Box",
          "identifier": "small-box",
          "description": "",
          "author": 8,
          "group_id": 1,
          "value": 6,
          "preview_url": null,
          "base_unit": true,
          "uuid": null,
          "created_at": "2025-01-26T23:19:36.000000Z",
          "updated_at": "2025-01-26T23:19:36.000000Z"
        }
      },
      {
        "id": 6,
        "product_id": 2,
        "type": "product",
        "preview_url": "https://nexocloud.dev/modules/nsgastro/images/categories/condiments/sugar-packet.jpeg",
        "expiration_date": null,
        "unit_id": 3,
        "barcode": "3962888485645-6",
        "quantity": 0,
        "low_quantity": 0,
        "stock_alert_enabled": 0,
        "sale_price": 0,
        "sale_price_edit": 0,
        "sale_price_without_tax": 0,
        "sale_price_with_tax": 0,
        "sale_price_tax": 0,
        "wholesale_price": 0,
        "wholesale_price_edit": 0,
        "wholesale_price_with_tax": 0,
        "wholesale_price_without_tax": 0,
        "wholesale_price_tax": 0,
        "custom_price": 0,
        "custom_price_edit": 0,
        "custom_price_with_tax": 0,
        "custom_price_without_tax": 0,
        "custom_price_tax": 0,
        "visible": 1,
        "convert_unit_id": null,
        "cogs": 0,
        "uuid": null,
        "created_at": "2025-01-26T23:19:42.000000Z",
        "updated_at": "2025-01-26T23:19:42.000000Z",
        "unit": {
          "id": 3,
          "name": "Box",
          "identifier": "box",
          "description": "",
          "author": 8,
          "group_id": 1,
          "value": 12,
          "preview_url": null,
          "base_unit": true,
          "uuid": null,
          "created_at": "2025-01-26T23:19:36.000000Z",
          "updated_at": "2025-01-26T23:19:36.000000Z"
        }
      }
    ],
    "tax_group": {
      "id": 1,
      "name": "GST",
      "description": null,
      "author": 8,
      "uuid": null,
      "created_at": "2025-01-26T23:19:42.000000Z",
      "updated_at": "2025-01-26T23:19:42.000000Z",
      "taxes": [
        {
          "id": 1,
          "name": "SGST",
          "description": null,
          "rate": 8,
          "tax_group_id": 1,
          "author": 8,
          "uuid": null,
          "created_at": "2025-01-26T23:19:42.000000Z",
          "updated_at": "2025-01-26T23:19:42.000000Z"
        },
        {
          "id": 2,
          "name": "CGST",
          "description": null,
          "rate": 8,
          "tax_group_id": 1,
          "author": 8,
          "uuid": null,
          "created_at": "2025-01-26T23:19:42.000000Z",
          "updated_at": "2025-01-26T23:19:42.000000Z"
        }
      ]
    }
  }
}

Product: Search Using Term

Use this endpoint to search product using a term. As a response you'll have an array of possible product matching the term provided. You might also use additional argument to circumscribe more your search using the entry "arguments" which is optional.

post
api/products/search

Request

{
    "search": "iPhone 16",
    "arguments": {
        "updated_at": {
            "comparison": "like",
            "value": "2024-12-12"
        }
    }
}

Product: Stock Adjustment

Use this endpoint to batch edit product inventory. You'll use as adjustment action the following list:

post
api/products/adjusments

Request

{
    "products": [
        {
            "id": "[product_id]",
            "adjust_unit": {
                "unit_id": "[number]",
                "sale_price": "[number]",
            },
            "unit": {
                "name": "[string]"
            },
            "adjust_quantity": "[number]",
            "adjust_action": "[action]",
            "adjust_reason": "[text]",
            "procurement_product_id": "[number]",
        }
    ]
}

Response

{
    "status": "[success|error]",
    "message": "[text]",
    "data": []
}

Product: Unit Conversion

This endpoint should be used to perform a unit conversion for a specific product. Make sure to replace {product_id} with the ID of the product for which you would like to convert the units.

post
api/products/{product_id}/units/conversion

Request

{
    "from": "[unit_id]",
    "to": "[unit_id]",
    "quantity": "[number]"
}

Response

{
    "status": "[success|error]",
    "message": "[text]"
}

Delete Unit Quantity

Use this to delete a unit quantity attached to a product. This implies all the inventory assigned to that product using the selected unit, will also be deleted (and can't be retreived). You'll replace "{unit_quantity_id}" with the id you would like to delete.

delete
api/products/units/quantity/{unit_quantity_id}

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

Delete All Products

Use this to remove all products created so far. Depending on your products, you might need to increase the PHP Execution time as this will not only clear products but all related tables.

delete
api/products

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

Products Categories

Create Category

Use this endpoint to create a new product category.

post
api/categories

Request

{
    "name": "[string]",
    "parent_id": "[number]",
    "displays_on_pos": "[boolean]",
    "description": "[string]",
    "media_id": "[number]"
}

Response

{
    "status": "[success|error]",
    "message": "[string]",
    "data": {
        "category": {
            "id": 1,
            "name": "Condiments",
            "parent_id": null,
            "media_id": 0,
            "preview_url": "https://exmaple.com/image.jpg",
            "displays_on_pos": 1,
            "total_items": 13,
            "description": "Additional condiments that can be added to meals",
            "author": 8,
            "uuid": null,
            "created_at": "2025-01-26T23:19:42.000000Z",
            "updated_at": "2025-01-26T23:19:45.000000Z"
        }
    }
}

Single Category

Use this endpoint to retrieve a single category. You'll replace {category_id} by the actual category you would like to get.

get
api/categories/{category_id}

Response

{
    "id": 1,
    "name": "Condiments",
    "parent_id": null,
    "media_id": 0,
    "preview_url": "https://exmaple.com/image.jpg",
    "displays_on_pos": 1,
    "total_items": 13,
    "description": "Additional condiments that can be added to meals",
    "author": 8,
    "uuid": null,
    "created_at": "2025-01-26T23:19:42.000000Z",
    "updated_at": "2025-01-26T23:19:45.000000Z"
}

Get Categories

Use this endpoint to retrieve all defined product categories.

get
api/categories

Response

[
  {
    "id": 1,
    "name": "Condiments",
    "parent_id": null,
    "media_id": 0,
    "preview_url": "https://exmaple.com/image.jpg",
    "displays_on_pos": 1,
    "total_items": 13,
    "description": "Additional condiments that can be added to meals",
    "author": 8,
    "uuid": null,
    "created_at": "2025-01-26T23:19:42.000000Z",
    "updated_at": "2025-01-26T23:19:45.000000Z"
  }
]

Update Category

Use this endpoint to update an existing category using {category_id}, that needs to be replaced with the actual ID of the category you would like to udpate.

put
api/categories/{category_id}

Request

{
    "name": "[string]",
    "parent_id": "[number]",
    "displays_on_pos": "[boolean]",
    "description": "[string]",
    "media_id": "[number]"
}

Response

{
    "status": "[success|error]",
    "message": "[string]",
    "data": {
        "category": {
            "id": 1,
            "name": "Condiments",
            "parent_id": null,
            "media_id": 0,
            "preview_url": "https://exmaple.com/image.jpg",
            "displays_on_pos": 1,
            "total_items": 13,
            "description": "Additional condiments that can be added to meals",
            "author": 8,
            "uuid": null,
            "created_at": "2025-01-26T23:19:42.000000Z",
            "updated_at": "2025-01-26T23:19:45.000000Z"
        }
    }
}

Delete Category

Use this endpoint to delete an existing category. Note that you might encounter an error if the category is still assigned to product. You'll replace {category_id} with the ID of the category you would like to delete.

delete
api/categories/{category_id}

Response

{
    "status": "[success|error]",
    "message": "[string]"
}

Category's Products

Use this endpoint to retreive all the product that are assigned to a category. You'll replace {category_id} by the ID of the category you would like to get the products.

get
api/categories/{category_id}/products

Response

[
  {
    "id": 1,
    "name": "Creamer Packet",
    "tax_type": "inclusive",
    "tax_group_id": 1,
    "tax_value": 0,
    "product_type": "product",
    "type": "dematerialized",
    "accurate_tracking": false,
    "auto_cogs": false,
    "status": "available",
    "stock_management": "disabled",
    "barcode": "2897183678939",
    "barcode_type": "ean13",
    "sku": "nwPUboV8ML3oVUW",
    "description": "Created via tests",
    "thumbnail_id": null,
    "category_id": 1,
    "parent_id": 0,
    "unit_group": 1,
    "on_expiration": "prevent_sales",
    "expires": 0,
    "searchable": 1,
    "author": 8,
    "uuid": null,
    "created_at": "2025-01-26T23:19:42.000000Z",
    "updated_at": "2025-01-26T23:19:42.000000Z"
  }
]

User

The user endpoint give an overview of the logged user. With this you'll be able to retreive the logged user email, id and more (The password is encrypted).

GET
api/user

Response

{
  "id": 8,
  "username": "admin",
  "active": true,
  "author": 8,
  "email": "contact@nexopos.com",
  "group_id": null,
  "first_name": null,
  "last_name": null,
  "gender": null,
  "phone": null,
  "pobox": null,
  "activation_expiration": null,
  "total_sales_count": 45,
  "total_sales": 4805.85,
  "birth_date": null,
  "purchases_amount": 0,
  "owed_amount": 0,
  "credit_limit_amount": 0,
  "account_amount": 0,
  "activation_token": null,
  "created_at": "2025-01-13T22:52:01.000000Z",
  "updated_at": "2025-01-27T09:42:33.000000Z",
}
php javascript