lh-e-holcimplusweb-online-v1-api

lh-e-holcimplusweb-online-v1 API Documentation

Overview and Purpose of the API

The lh-e-holcimplusweb-online-v1 API is designed to provide data retrieval capabilities for Holcim Plus. It allows users to access specific information, such as truck positions, through a secure and structured interface. This API is intended to support customer portals and other applications requiring real-time or near-real-time data related to Holcim's logistics and operations.

Authentication Requirements and Security Details

The API enforces strict security measures to ensure data integrity and confidentiality. The following security mechanisms are implemented:

• JWT Authentication: The API requires a valid JSON Web Token (JWT) for accessing its endpoints.
• Client ID Enforcement: Requests must include a valid client ID to authenticate the application making the request.
• Correlation ID: A correlation ID is required for tracking and tracing requests.
• Country and Origin Headers: These headers are mandatory to specify the country and origin of the request.

Ensure that all requests include the necessary security credentials and headers to successfully interact with the API.

Base URL and Environments

The base URL for the API is structured as follows:

https://{hostname}/api

Base URI Parameters

Protocols Supported

• HTTPS

Media Type

• application/json

Detailed Endpoint Documentation

1. Get Truck Position

Endpoint

GET /trucks/{id}/position

Description

This endpoint retrieves the position of a specific truck based on its unique identifier.

Security

This endpoint is secured by:
- JWT Authentication
- Client ID Enforcement

Path Parameters

Headers

The following headers are required:

Responses

Response Example (200)

{
  "truckId": "12345",
  "latitude": 40.712776,
  "longitude": -74.005974,
  "timestamp": "2025-09-12T14:30:00Z"
}

Error Handling and Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request. Below is a summary of the possible status codes:

For error responses, the API returns a JSON object with details about the error, including an error code and message.

Error Response Example (401)

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token."
}

Best Practices for Implementation

To ensure optimal use of the API, follow these best practices:

1. Secure API Keys and Tokens: Do not expose your JWT tokens or client IDs in public repositories or client-side code.
2. Use Correlation IDs: Always include a unique correlation ID in your requests to facilitate debugging and tracking.
3. Handle Errors Gracefully: Implement robust error-handling mechanisms to manage various HTTP status codes.
4. Optimize Requests: Avoid making unnecessary API calls by caching data where appropriate.
5. Monitor API Usage: Regularly monitor your API usage and adhere to any rate limits or quotas.

Sample Code Snippets

Example: Fetching Truck Position (Node.js)

const axios = require('axios');

const getTruckPosition = async (truckId) => {
  const url = `https://your-api-hostname/api/trucks/${truckId}/position`;
  const headers = {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'x-client-id': 'YOUR_CLIENT_ID',
    'x-correlation-id': 'UNIQUE_CORRELATION_ID',
    'x-country': 'US',
    'x-origin': 'CustomerPortal'
  };

  try {
    const response = await axios.get(url, { headers });
    console.log('Truck Position:', response.data);
  } catch (error) {
    console.error('Error fetching truck position:', error.response.data);
  }
};

getTruckPosition('12345');

This concludes the documentation for the lh-e-holcimplusweb-online-v1 API. For further assistance, please contact the API support team.