experience | zonda | v1

Experience | Zonda | v1 API Documentation

Overview and Purpose of the API

The Experience | Zonda | v1 API provides a set of endpoints to manage and interact with various business functionalities, such as credit checks, price simulations, stock checks, truck position tracking, cost calculations, and health monitoring. This API is designed to integrate seamlessly with legacy systems and modern applications, enabling efficient communication and data exchange. It ensures secure and reliable operations for business-critical processes.

Authentication Requirements and Security Details

The API enforces strict security measures to ensure data integrity and confidentiality:
- Authentication Mechanisms:
- JWT (JSON Web Token) authentication is required for most endpoints.
- Client ID enforcement is mandatory for all secured endpoints.
- Security Schemes:
- Endpoints are secured using library-common-fragments.jwt and library-common-fragments.clientIdEnforcement.
- Correlation ID:
- Some endpoints require a correlation ID for tracking requests.

Base URL and Environments

The API is accessible over HTTPS and supports the following base URL structure:

https://{hostname}/api

• Base URI Parameters:

  • hostname: The hostname of the API server.

• Media Type: application/json

• Protocols Supported: HTTPS

Detailed Endpoint Documentation

1. Credit Check

Endpoint: POST /customerorders/check
Description: Perform a credit check against the credit management system. This endpoint is used to create a Credit Application when an order goes on hold due to credit limits.

Request Body

• Media Type: application/json
• Schema: library-credit.creditCheckRequest
• Example:

  {
  // Example content from "examples/credit-check-request.json"
  }

Response

• Status Code: 200 OK
• Media Type: application/json
• Schema: library-credit.creditCheckResponse
• Example:

  {
  // Example content from "examples/credit-check-response.json"
  }

2. Price Simulation

Endpoint: POST /prices/simulation
Description: Perform a price simulation to retrieve pricing data.

Headers

Request Body

• Media Type: application/json
• Schema: library-pricing.salesOrderRequest
• Example:

  {
  // Example content from "examples/pricing-request.json"
  }

Response

• Status Code: 200 OK
• Media Type: application/json
• Schema: library-pricing.salesOrderResponse
• Example:

  {
  // Example content from "examples/pricing-response.json"
  }

3. Stock Check

Endpoint: POST /stocks/check
Description: Check stock availability.

Request Body

• Media Type: application/json
• Schema: library-stocks.stockCheckRequest
• Example:

  {
  // Example content from "examples/stocks-check-request.json"
  }

Response

• Status Code: 200 OK
• Media Type: application/json
• Schema: library-stocks.stockCheckResponse
• Example:

  {
  // Example content from "examples/stocks-check-response.json"
  }

4. Get Truck Position

Endpoint: GET /trucks/{id}/position
Description: Retrieve the position of a specific truck.

Path Parameters

Response

• Status Code: 200 OK
• Media Type: application/json
• Schema: library-trucks.truck-position
• Example:

  {
  // Example content from "examples/truck-position.json"
  }

5. Send Costs Calculation to E1

Endpoint: POST /costs/send
Description: Send cost calculation data to the E1 system.

Request Body

• Media Type: application/json
• Schema: object

Response

• Status Codes:
  • 200 OK: Success
  • 500 Internal Server Error: Error

6. Health Check

Endpoint: GET /health
Description: Check the health status of the API.

Response

• Status Code: 200 OK
• Media Type: application/json
• Example:

  {
  "status": "UP"
  }

Error Handling and Status Codes

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

Best Practices for Implementation

• Authentication: Ensure that all requests include valid JWT tokens and client IDs where required.
• Correlation ID: Use correlation IDs for tracking and debugging requests.
• Error Handling: Implement robust error handling to manage API responses gracefully.
• Validation: Validate request payloads and headers to avoid unnecessary errors.
• Testing: Test endpoints in a staging environment before deploying to production.

Sample Code Snippets

Example: Credit Check

const axios = require('axios');

const performCreditCheck = async () => {
  const url = 'https://{hostname}/api/customerorders/check';
  const requestBody = {
    // Example content from "examples/credit-check-request.json"
  };

  const headers = {
    Authorization: 'Bearer <your-jwt-token>',
    'Content-Type': 'application/json',
  };

  try {
    const response = await axios.post(url, requestBody, { headers });
    console.log('Credit Check Response:', response.data);
  } catch (error) {
    console.error('Error performing credit check:', error.response.data);
  }
};

performCreditCheck();

Example: Health Check

const axios = require('axios');

const checkHealth = async () => {
  const url = 'https://{hostname}/api/health';

  try {
    const response = await axios.get(url);
    console.log('Health Check Response:', response.data);
  } catch (error) {
    console.error('Error checking health:', error.response.data);
  }
};

checkHealth();

This concludes the documentation for the Experience | Zonda | v1 API. For further assistance, please refer to the API support team.