Stock Endpoints

The Stock entity represents the quantity of products of the same type that are in a warehouse. Each stock includes a series of attributes that describe it.

Common Stock Characteristics

1. Unique Identification: Each stock has a unique identifier id that distinguishes them from other stocks in the system.

2. Stock Data: A Stock has associated information such as quantity, associated product data, associated warehouse data and other details.

3. Activities and Logging: Activities performed by a stock within the system, such as creation of resources, may be logged.

4. Product: Basic information about the product to which the stock is associated is stored, such as idRemote and the product reference.

5. Warehouse: Basic information about the warehouse where each product is located is saved, such as idRemote.

Endpoints

GET/Stock/getStock

Retrieve a paginated list of stocks.

Description

This endpoint retrieves a paginated list of stocks from the system. It allows clients to fetch stocks data based on pagination parameters such as page number (page) and items per page (pageSize). The response includes detailed information about each stock, including its ID, quantity, product and warehouse information, and last updated timestamp.

Parameters

Name	Description	Type	Default Value
idProduct	Product ID	String optional	idProduct
idWarehouse	Warehouse ID	String optional	idWarehouse
page	Page number	Integer	1
pageSize	Number of items per page	Integer	10

Responses

JSON

  {
      "data": [
          {
          "id": "string",
          "product": {
              "id": "string",
              "idRemote": "string",
              "reference": "string"
          },
          "warehouse": {
              "id": "string",
              "idRemote": "string"
          },
          "quantity": 0,
          "createdAt": "string",
          "updatedAt": "string"
          }
      ],
      "pagination": {
          "totalItems": 0,
          "itemsPerPage": 0,
          "currentPage": 0,
          "totalPages": 0,
          "nextPageUrl": "string"
      }
  }

XML

  <?xml version="1.0" encoding="UTF-8"?>
  <export>
      <data>
          <item>
              <id>string</id>
              <product>
                  <id>string</id>
                  <idRemote>string</idRemote>
                  <reference>string</reference>
              </product>
              <warehouse>
                  <id>string</id>
                  <idRemote>string</idRemote>
              </warehouse>
              <quantity>0</quantity>
              <createdAt>string</createdAt>
              <updatedAt>string</updatedAt>
          </item>
      </data>
      <pagination>
          <totalItems>0</totalItems>
          <itemsPerPage>0</itemsPerPage>
          <currentPage>0</currentPage>
          <totalPages>0</totalPages>
          <nextPageUrl>string</nextPageUrl>
      </pagination>
  </export>      

👉Try it out🌱

GET/Stock/updatedFrom

Retrieve stocks from a modification date

Description

This endpoint retrieves a paginated list of stocks from the system, starting from a specific modification date using the parameter date. It allows clients to fetch locations data based on pagination parameters such as page number (page) and items per page (pageSize). The response includes detailed information about each stock, including its ID, quantity, product and warehouse information, and last updated timestamp.

Parameters

Name	Description	Type	Default Value
date	Updated Date	String required	1999-01-01 01:00:00
page	Page number	Integer	1
pageSize	Number of items per page	Integer	10

Responses

JSON

  {
      "data": [
          {
          "id": "string",
          "product": {
              "id": "string",
              "idRemote": "string",
              "reference": "string"
          },
          "warehouse": {
              "id": "string",
              "idRemote": "string"
          },
          "quantity": 0,
          "createdAt": "string",
          "updatedAt": "string"
          }
      ],
      "pagination": {
          "totalItems": 0,
          "itemsPerPage": 0,
          "currentPage": 0,
          "totalPages": 0,
          "nextPageUrl": "string"
      }
  }

XML

  <?xml version="1.0" encoding="UTF-8"?>
  <export>
      <data>
          <item>
              <id>string</id>
              <product>
                  <id>string</id>
                  <idRemote>string</idRemote>
                  <reference>string</reference>
              </product>
              <warehouse>
                  <id>string</id>
                  <idRemote>string</idRemote>
              </warehouse>
              <quantity>0</quantity>
              <createdAt>string</createdAt>
              <updatedAt>string</updatedAt>
          </item>
      </data>
      <pagination>
          <totalItems>0</totalItems>
          <itemsPerPage>0</itemsPerPage>
          <currentPage>0</currentPage>
          <totalPages>0</totalPages>
          <nextPageUrl>string</nextPageUrl>
      </pagination>
  </export>      

👉Try it out🌱

GET/Stock/getStockMovementType

Retrieve a paginated list of stocks movement type.

Description

This endpoint retrieves a paginated list of stocks movement type from the system. It allows clients to obtain the types of stock movements based on pagination parameters such as the page number (page) and the number of items per page (pageSize). The response includes the ID and name of each movement type.

Parameters

Name	Description	Type	Default Value
page	Page number	Integer	1
pageSize	Number of items per page	Integer	10

Responses

JSON

  {
    "data": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "pagination": {
      "totalItems": 0,
      "itemsPerPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "nextPageUrl": "string"
    }
  }

XML

  <?xml version="1.0" encoding="UTF-8"?>
  <export>
    <data>
      <item>
        <id>string</id>
        <name>string</name>
      </item>
    </data>
    <pagination>
      <totalItems>0</totalItems>
      <itemsPerPage>0</itemsPerPage>
      <currentPage>0</currentPage>
      <totalPages>0</totalPages>
      <nextPageUrl>string</nextPageUrl>
    </pagination>
  </export>     

👉Try it out🌱

POST/Stock/create

Stock Registration in the API: Using the POST Method

Currently, our POST method in the API exclusively handles JSON format. To effectively register stocks, it is crucial to follow a process that ensures data integrity and proper system functionality.

Registration Process:

1. Creation of Product: Creating a product is essential because it is where a stock with a zero quantity will be recorded for the first time. Then, the stock quantity corresponding to that product is recorded in this endpoint. 👉Register Product🌱

2. Creation of Warehouse: A warehouse must exist in order to create a product and therefore to create a stock. The warehouse that is associated with the product is the one that is associated with the corresponding stock. 👉Register Warehouse🌱

3. Movement Type: The movement type is already created and can be IN, OUT or CORRECTION. In the IN type, the quantity entered in the JSON will be added to the quantity of the corresponding stock. For the OUT type, it will be subtracted and for the CORRECTION type, it will be updated. As the stock is recorded when the product is created, there will always be one associated with this product in order to add, subtract or update the quantity.

Details of the POST Method:

In this case, we will use the POST method to update stocks since they have been registered in the Product POST method. It is necessary to send structured data in JSON format that includes essential information such as the product ID, the warehouse ID and the quantity we want to register. The process ensures that each stock has a unique identity and is correctly configured to interact with the platform in a safe and efficient manner. The system will automatically create a local id.

All parameters in the request body are required.

The request must follow the following scheme:

[
  {
      "productId": "string",
      "warehouseId": "string",
      "quantity": 0,
      "movementTypeId": "string"
  }
]

It is possible to add multiple stocks through the same request by separating them with commas within the array in the body of the request.

Responses

To avoid overloading the server, this endpoint sends a message to a consumer responsible for processing the request. To check the status of the submitted request, you need to access the URL provided in the response. A successfully sent message to the consumer should look like this:

{
    "code": 201,
    "message": "Stock message created successfully and dispatched to the queue.",
    "statusUrl": "http://host/api/database/v1/message/status/66bf382938941"
}

The statusUrl field redirects us to a more detailed response about the request's status. A request successfully processed by the consumer will look like this:

{
  "data": [
      {
        "status": "completed",
        "errorMessage": null
      }
  ],
  "pagination": {
      "totalItems": 1,
      "itemsPerPage": 10,
      "currentPage": 1,
      "totalPages": 1,
      "nextPageUrl": null
  }
}

If any error occurs during message processing, the response will look something like this:

{
  "code": 400,
  "error": "Invalid stock data format, a required parameter is missing"
}

👉Try it out🌱

Possible Response Errors

Error	Response Status	Response Body
This error occurs when a connection to the database cannot be established. It is an internal server problem.	500	{"code": 500,"error": "Database connection failed."}
This error occurs when you cannot insert or update items into the database.	500	{"code": 500,"error": "Invalid connection name, you cannot insert in default"}
This error occurs when a parameter is missing.	400	{"code": 400,"error": "Parameter $parameter is required"}
This error occurs when you are not authorized.	401	{"code": 401,"error": "Unauthorized."}
This error occurs when the Stock could not be found.	404	{"code": 404,"error": "No entity found for Stock with $id."}
This error occurs when you try to insert a Stock that already exists.	409	{"code": 409,"error": "Duplicate entry"}
This error occurs when you try to send too many requests in a short period of time.	429	{"code": 429,"error": "Too Many Requests"}