Smart Customer Management API

API Version

Smart Customer Management v1.0.0 (beta)
API based on OpenAPI 3.1.0 with AI-enhanced metadata

Overview

The Smart Customer Management API is an AI-enhanced service for intelligent business customer management. It uses machine learning algorithms to optimize CRUD operations and provide predictive insights on customer data.

API Version

Current version: 1.0.0
OpenAPI: 3.1.0
AI-Enhanced: With AI metadata for every endpoint

Key Features

• Intelligent customer management with AI validation
• Native AI extensions for every operation
• Standardized URL pattern multi-tenant
• Automatic validation of customer data
• Intent recognition for automatic categorization

Available Endpoints

Base URL Pattern

/api/{product}/{version}/company/{companyId}/customer

Global Parameters

Parameter	Type	Description
product	string	TSE product identifier
version	string	API version (e.g. "v1")
companyId	string	Unique company ID

API Operations

1. Create a new customer

Endpoint: POST /api/\{product\}/\{version\}/company/\{companyId\}/customer

AI Metadata:

• Purpose: customer_creation
• Entity: Customer
• Intent: create

Request Body

{
  "first-name": "John",
  "last-name": "Smith", 
  "email": "john.smith@example.com",
  "vat-number": "IT12345678901"
}

Data Schema

Field	Type	Required	Description
first-name	string	Required	Customer first name
last-name	string	Required	Customer last name
email	string	Required	Email (valid format)
vat-number	string	Required	Customer VAT number

Responses

Code	Description
201	Customer created successfully
400	Invalid request

JavaScript Example

const createCustomer = async (companyId, customerData) => {
  try {
    const response = await fetch(`/api/tse/v1/company/${companyId}/customer`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify(customerData)
    });
    
    if (response.status === 201) {
      console.log('Customer created successfully');
      return await response.json();
    }
    throw new Error(`Error ${response.status}`);
  } catch (error) {
    console.error('Customer creation error:', error);
  }
};

// Usage
const newCustomer = {
  "first-name": "John",
  "last-name": "Smith",
  "email": "john.smith@example.com", 
  "vat-number": "IT12345678901"
};

await createCustomer("company123", newCustomer);

2. Retrieve all customers

Endpoint: GET /api/\{product\}/\{version\}/company/\{companyId\}/customer

AI Metadata:

• Purpose: customer_listing
• Entity: Customer
• Intent: retrieve

Parameters

Only global path parameters (product, version, companyId).

Responses

Code	Description
200	Customer list returned successfully
404	Customers not found

3. Retrieve a specific customer

Endpoint: GET /api/\{product\}/\{version\}/company/\{companyId\}/customer/\{customerId\}

AI Metadata:

• Purpose: customer_detail
• Entity: Customer
• Intent: retrieve

Additional Parameters

Parameter	Type	Description
customerId	string	Unique customer ID

Responses

Code	Description
200	Customer details returned successfully
404	Customer not found

4. Delete a customer

Endpoint: DELETE /api/\{product\}/\{version\}/company/\{companyId\}/customer/\{customerId\}

AI Metadata:

• Purpose: customer_deletion
• Entity: Customer
• Intent: delete

Parameters

Parameter	Type	Description
customerId	string	ID of customer to delete

Responses

Code	Description
204	Customer deleted successfully
404	Customer not found

JavaScript Example with confirmation

const deleteCustomer = async (companyId, customerId) => {
  // Confirm deletion
  const confirmed = confirm(`Are you sure you want to delete customer ${customerId}?`);
  if (!confirmed) return false;

  try {
    const response = await fetch(`/api/tse/v1/company/${companyId}/customer/${customerId}`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (response.status === 204) {
      console.log(`Customer ${customerId} deleted successfully`);
      return true;
    } else if (response.status === 404) {
      console.warn(`Customer ${customerId} not found`);
      return false;
    }
    
    throw new Error(`Error ${response.status}`);
  } catch (error) {
    console.error('Customer deletion error:', error);
    return false;
  }
};

// Usage
const deleted = await deleteCustomer("company123", "456");

Centralized error handling

const handleApiError = (response) => {
  switch(response.status) {
    case 400:
      throw new Error('Invalid request data');
    case 401:
      throw new Error('Invalid authentication token');
    case 404:
      throw new Error('Resource not found');
    case 500:
      throw new Error('Internal server error');
    default:
      throw new Error(`API Error: ${response.status}`);
  }
};

Best Practices

1. Client-side validation

const validateCustomerData = (customer) => {
  const errors = [];
  
  if (!customer['first-name']?.trim()) {
    errors.push('First name required');
  }
  
  if (!customer['email']?.includes('@')) {
    errors.push('Invalid email');
  }
  
  if (!customer['vat-number']?.match(/^[A-Z]{2}\d{11}$/)) {
    errors.push('Invalid VAT number format');
  }
  
  return errors;
};

2. Retry logic for resilience

const apiCallWithRetry = async (apiCall, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

3. Intelligent caching

const customerCache = new Map();

const getCachedCustomer = async (companyId, customerId) => {
  const cacheKey = `${companyId}:${customerId}`;
  
  if (customerCache.has(cacheKey)) {
    const cached = customerCache.get(cacheKey);
    if (Date.now() - cached.timestamp < 300000) { // 5 minutes
      return cached.data;
    }
  }
  
  const customer = await getCustomerDetails(companyId, customerId);
  customerCache.set(cacheKey, {
    data: customer,
    timestamp: Date.now()
  });
  
  return customer;
};

Related Links

• Getting Started - Initial setup
• Authentication - Token configuration
• SDK Overview - Client libraries
• AI Services Overview - Other AI services

Support

For specific questions about Smart Customer API:

• Email: smart-services@tse.it
• Documentation: TSE Smart Services Hub
• Bug Report: GitHub Issues