Holcim EMEA UK Bradstone V1

1.0.x
(0 reviews)

Overview and Purpose of the API

The Bradstone UK Experience API provides a RESTful interface for managing customer delivery orders within Bradstone UK's digital channels, including web, mobile, and B2B portals. Its primary function is to enable clients to submit new product delivery orders, ensuring seamless integration with Bradstone UK's order management systems.

Authentication Requirements and Security Details

All endpoints are protected by:

  • JWT Bearer Token: Signed JWT tokens issued by the Anypoint Platform identity provider must be included in the Authorization header as a Bearer token.
  • Client ID Enforcement: Requests must include client_id and client_secret in the request headers for client identification and authorization.

Base URL and Environments

The API is hosted at the following base URL:

https://{hostname}/api
  • Replace {hostname} with the specific server hostname, e.g., api.ea.holcim.com.

Supported protocols:

  • HTTPS only

Endpoints

/orders

Manage customer delivery orders

POST /orders

Create Delivery Order

Description:

Submits a new product delivery order to Bradstone UK. The request must adhere to specific validation rules, including valid customer details, available materials, and future delivery times.

Security & Headers:

  • Secured by JWT Bearer Token and Client ID enforcement.

  • Required headers include:

    • Authorization: Bearer {access_token}
    • client_id: {client_id}
    • client_secret: {client_secret}

Request Headers Example:

Authorization: Bearer {access_token}
client_id: {client_id}
client_secret: {client_secret}
Content-Type: application/json

Request

Request Method:

POST /orders

Request Body Schema:

{
  "earliestDeliveryTime": "2024-04-06T10:00:00Z",
  "soldto": {
    "customerId": "string",
    "name": "string",
    "address": "string"
  },
  "shipto": {
    "customerId": "string",
    "name": "string",
    "address": "string"
  },
  "material": "string",
  "plant": "string",
  "quantity": 0
}

Example Request Body:

{
  "earliestDeliveryTime": "2024-04-06T10:00:00Z",
  "soldto": {
    "customerId": "CUST12345",
    "name": "John Doe",
    "address": "123 Elm Street, London"
  },
  "shipto": {
    "customerId": "CUST67890",
    "name": "Jane Smith",
    "address": "456 Oak Avenue, Manchester"
  },
  "material": "BRADSTONE-123",
  "plant": "PLANT01",
  "quantity": 10
}

Responses

Status CodeDescriptionResponse Body Example
201Order created successfully. Returns order ID and confirmation details.json<br>{<br> "orderId": "ORD123456789",<br> "confirmationNumber": "CONF987654321"<br>}
500Internal server error or upstream service unavailable.json<br>{<br> "error": "Internal Server Error",<br> "message": "Unable to process the request at this time."<br>}

Response Headers

  • Content-Type: application/json

Usage Example

cURL:

curl -X POST https://api.ea.holcim.com/api/orders \
-H "Authorization: Bearer {access_token}" \
-H "client_id: {client_id}" \
-H "client_secret: {client_secret}" \
-H "Content-Type: application/json" \
-d '{
  "earliestDeliveryTime": "2024-04-06T10:00:00Z",
  "soldto": {
    "customerId": "CUST12345",
    "name": "John Doe",
    "address": "123 Elm Street, London"
  },
  "shipto": {
    "customerId": "CUST67890",
    "name": "Jane Smith",
    "address": "456 Oak Avenue, Manchester"
  },
  "material": "BRADSTONE-123",
  "plant": "PLANT01",
  "quantity": 10
}'

Sample Response:

{
  "orderId": "ORD123456789",
  "confirmationNumber": "CONF987654321"
}

Error Handling and Status Codes

  • 400 Bad Request: Invalid request payload or missing required fields.
  • 401 Unauthorized: Missing or invalid JWT token or client credentials.
  • 403 Forbidden: Insufficient permissions.
  • 500 Internal Server Error: Server or upstream service failure.

All error responses include a JSON body with error details, for example:

{
  "error": "InvalidRequest",
  "message": "The 'material' field is required."
}

Best Practices for Implementation

  • Always include valid Authorization, client_id, and client_secret headers.
  • Validate earliestDeliveryTime to ensure it is today or a future date.
  • Confirm customer IDs (soldto and shipto) are registered Bradstone UK customers.
  • Verify that material is active and available at the specified plant.
  • Ensure quantity is greater than zero.
  • Handle error responses gracefully and implement retries for transient errors.

Sample Code Snippets

Example in Python (using requests library):

import requests

url = "https://api.ea.holcim.com/api/orders"
headers = {
    "Authorization": "Bearer {access_token}",
    "client_id": "{client_id}",
    "client_secret": "{client_secret}",
    "Content-Type": "application/json"
}
payload = {
    "earliestDeliveryTime": "2024-04-06T10:00:00Z",
    "soldto": {
        "customerId": "CUST12345",
        "name": "John Doe",
        "address": "123 Elm Street, London"
    },
    "shipto": {
        "customerId": "CUST67890",
        "name": "Jane Smith",
        "address": "456 Oak Avenue, Manchester"
    },
    "material": "BRADSTONE-123",
    "plant": "PLANT01",
    "quantity": 10
}

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 201:
    print("Order created successfully:", response.json())
else:
    print("Error:", response.json())

This concludes the detailed documentation for the lh-e-uk-bradstone-v1-api asset, focusing on the POST /orders endpoint for creating delivery orders.

Reviews