lh-e-holcimplusweb-online-v1-api

(0 reviews)

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

Parameter	Description
hostname	The hostname of the API server. This should be replaced with the appropriate server address for the environment being used.

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

Parameter	Type	Description	Required
`id`	String	The unique identifier of the truck.	Yes

Headers

The following headers are required:

Header Name	Description	Required
`Authorization`	Bearer token for JWT authentication.	Yes
`x-client-id`	Client ID for application authentication.	Yes
`x-correlation-id`	Unique identifier for request tracking.	Yes
`x-country`	Country code of the request origin (e.g., `US`).	Yes
`x-origin`	Origin of the request (e.g., `CustomerPortal`).	Yes

Responses

Status Code	Description
200	Truck position data.
401	Unauthorized access.
403	Forbidden access.
404	Truck not found.
500	Internal server error.

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:

Status Code	Meaning	Description
200	OK	The request was successful, and the response contains the requested data.
401	Unauthorized	Authentication failed due to missing or invalid credentials.
403	Forbidden	The client does not have permission to access the requested resource.
404	Not Found	The requested resource (e.g., truck ID) was not found.
500	Internal Server Error	An unexpected error occurred on the server.

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:

Secure API Keys and Tokens: Do not expose your JWT tokens or client IDs in public repositories or client-side code.
Use Correlation IDs: Always include a unique correlation ID in your requests to facilitate debugging and tracking.
Handle Errors Gracefully: Implement robust error-handling mechanisms to manage various HTTP status codes.
Optimize Requests: Avoid making unnecessary API calls by caching data where appropriate.
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.

home