lh-e-emea-mystock-ui-v1-api

lh-e-emea-mystock-ui-v1-api Documentation

Overview and Purpose of the API

The lh-e-emea-mystock-ui-v1-api provides a comprehensive set of endpoints to manage stock data, production orders, and related functionalities for the myStock application. This API is designed to enable seamless integration and real-time data management for stock availability, plant operations, and production order tracking.

Key Features

• Real-time stock availability monitoring: Retrieve detailed and aggregated stock data.
• Plant and production order management: Search and filter plants and production orders using complex criteria.
• Synchronous stock updates: Update stock blocking status for orders in real-time.
• Advanced filtering capabilities: Apply multiple filters with logical operators for precise data retrieval.

Support

For issues or questions, contact the EMEA Technical Integration team.

Authentication Requirements and Security Details

All endpoints in this API are secured using the following mechanisms:
- JWT Authentication: A valid JSON Web Token (JWT) must be provided in the Authorization header for all requests.
- Client ID Enforcement: A valid client_id must be included in the request headers.

Security Headers

• Authorization: Bearer <JWT_TOKEN>
• client_id: <Your_Client_ID>

Base URL and Environments

The base URL for the API is:

https://{hostname}/api

Base URI Parameters

Supported Protocols

• HTTPS

Media Type

• application/json

Detailed Endpoint Documentation

1. Plants (Search) - /plants/search

Method: POST

Description

Retrieves a filtered list of plants based on complex search criteria.

Use Cases

• Search plants by location, status, or capacity.
• Filter plants by multiple criteria simultaneously.
• Get detailed plant information for reporting.

Request Body

Response

• 200 OK: Plants retrieved successfully.

Example Response

[
  {
    "id": "plant123",
    "name": "Plant A",
    "location": "Germany",
    "status": "Active",
    "capacity": 1000
  }
]

2. Stocks Summary (Search) - /stocks/summary/search

Method: POST

Description

Retrieves an aggregated summary of stock availability using filter criteria.

Note

This endpoint provides summary data only. Use /stocks/search for detailed stock information.

Request Body

Response

• 200 OK: Stock summary retrieved successfully.

Example Response

{
  "totalStock": 5000,
  "locations": [
    {
      "location": "Warehouse A",
      "stock": 3000
    },
    {
      "location": "Warehouse B",
      "stock": 2000
    }
  ]
}

3. Stocks Detail (Search) - /stocks/search

Method: POST

Description

Retrieves detailed stock information using complex filter criteria.

Request Body

Response

• 200 OK: Detailed stock data retrieved successfully.

Example Response

[
  {
    "productId": "prod123",
    "location": "Warehouse A",
    "quantity": 100,
    "status": "Available"
  },
  {
    "productId": "prod124",
    "location": "Warehouse B",
    "quantity": 200,
    "status": "Reserved"
  }
]

4. Production Orders (Search) - /productionorders/search

Method: POST

Description

Retrieves production orders using complex filter criteria.

Request Body

Response

• 200 OK: Production orders retrieved successfully.

Example Response

[
  {
    "orderId": "order123",
    "product": "Product A",
    "quantity": 500,
    "status": "In Progress"
  }
]

5. Orders (Search) - /orders/search

Method: POST

Description

Retrieves orders using complex filter criteria.

Request Body

Response

• 200 OK: Orders retrieved successfully.

Example Response

[
  {
    "orderId": "order123",
    "customer": "Customer A",
    "status": "Open",
    "items": [
      {
        "productId": "prod123",
        "quantity": 10
      }
    ]
  }
]

6. Order Stock Update (Single) - /orders/{id}/stocks

Method: PATCH

Description

Updates stock blocking status for a single order synchronously.

URI Parameters

Request Body

Response

• 200 OK: Stock updated successfully.
• 400 Bad Request: Validation failed.
• 404 Not Found: Order does not exist.
• 500 Internal Server Error: System failure.

Example Response (200 OK)

{
  "message": "Stock updated successfully"
}

Example Response (400 Bad Request)

{
  "error": "Validation failed",
  "details": "Missing required fields"
}

Error Handling and Status Codes

Common Status Codes

Error Resolution

• 400 Bad Request: Ensure all required fields are provided and correctly formatted.
• 404 Not Found: Verify the resource ID and ensure it exists.
• 500 Internal Server Error: Retry the request or contact support with the correlationId.

Best Practices for Implementation

• Always include the Authorization and client_id headers in your requests.
• Use appropriate filtering criteria to optimize data retrieval.
• Handle errors gracefully by checking response codes and providing meaningful feedback to users.
• Use the correlationId from response headers for debugging and support requests.

Sample Code Snippets

Example: Retrieve Plants

const axios = require('axios');

const getPlants = async () => {
  const response = await axios.post('https://api.ea.holcim.com/api/plants/search', {
    filters: {
      location: "Germany",
      status: "Active"
    }
  }, {
    headers: {
      Authorization: 'Bearer <JWT_TOKEN>',
      client_id: '<Your_Client_ID>'
    }
  });

  console.log(response.data);
};

getPlants();

Example: Update Order Stock

const axios = require('axios');

const updateOrderStock = async (orderId) => {
  const response = await axios.patch(`https://api.ea.holcim.com/api/orders/${orderId}/stocks`, {
    stockUpdate: {
      status: "Blocked",
      quantity: 100
    }
  }, {
    headers: {
      Authorization: 'Bearer <JWT_TOKEN>',
      client_id: '<Your_Client_ID>'
    }
  });

  console.log(response.data);
};

updateOrderStock('23456792');

This concludes the documentation for lh-e-emea-mystock-ui-v1-api. For further assistance, contact the EMEA Technical Integration team.