API Integration Guide: Automating ACES/PIES Data Conversion

The CatalogBridge API enables seamless integration of ACES/PIES conversion capabilities directly into your existing systems. Whether you're building an automated workflow, integrating with your ERP, or creating a custom solution, our RESTful API provides the flexibility and power you need.

Getting Started with the API

API Access and Authentication

To begin using the CatalogBridge API, you'll need:

1. API Key: Generated from your dashboard
2. Base URL: https://api.catalogbridge.com/v2
3. Authentication: Bearer token in headers

# Example authentication header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.catalogbridge.com/v2/account

Quick Start Example

Here's a simple conversion request:

// Node.js example
const axios = require('axios');

async function convertFile() {
  try {
    const response = await axios.post(
      'https://api.catalogbridge.com/v2/convert',
      {
        fileUrl: 'https://your-server.com/parts-data.csv',
        outputFormats: ['aces', 'pies'],
        options: {
          validationLevel: 'standard',
          includeReport: true
        }
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Conversion ID:', response.data.conversionId);
    console.log('Status:', response.data.status);
  } catch (error) {
    console.error('Conversion failed:', error.response.data);
  }
}

Core API Endpoints

1. Single File Conversion

Endpoint: POST /v2/convert

Convert a single CSV or Excel file to ACES/PIES XML:

// Request
{
  "fileUrl": "https://example.com/parts.csv",
  "outputFormats": ["aces", "pies"],
  "options": {
    "validationLevel": "strict",
    "brandMapping": {
      "OldBrand": "NewBrand"
    },
    "includeReport": true,
    "webhookUrl": "https://your-server.com/webhook"
  }
}

// Response
{
  "conversionId": "conv_abc123",
  "status": "processing",
  "estimatedCompletion": "2025-06-22T10:30:00Z",
  "trackingUrl": "https://api.catalogbridge.com/v2/status/conv_abc123"
}

2. Batch Processing

Endpoint: POST /v2/batch

Process multiple files in a single request:

// Request
{
  "files": [
    {
      "url": "https://example.com/brake-parts.csv",
      "name": "brake-parts.csv"
    },
    {
      "url": "https://example.com/engine-parts.xlsx",
      "name": "engine-parts.xlsx"
    }
  ],
  "options": {
    "outputFormats": ["aces", "pies"],
    "validationLevel": "standard",
    "continueOnError": true
  }
}

// Response
{
  "batchId": "batch_xyz789",
  "totalFiles": 2,
  "status": "queued",
  "trackingUrl": "https://api.catalogbridge.com/v2/batch/batch_xyz789"
}

3. Conversion Status

Endpoint: GET /v2/status/{conversionId}

Check the status of a conversion:

// Response
{
  "conversionId": "conv_abc123",
  "status": "completed",
  "progress": 100,
  "results": {
    "acesUrl": "https://api.catalogbridge.com/v2/download/conv_abc123/aces.xml",
    "piesUrl": "https://api.catalogbridge.com/v2/download/conv_abc123/pies.xml",
    "reportUrl": "https://api.catalogbridge.com/v2/download/conv_abc123/report.pdf"
  },
  "statistics": {
    "totalParts": 1500,
    "successfulConversions": 1485,
    "errors": 15,
    "warnings": 47
  }
}

4. Validation Only

Endpoint: POST /v2/validate

Validate data without converting:

// Request
{
  "fileUrl": "https://example.com/parts.csv",
  "validationProfile": "strict",
  "returnDetails": true
}

// Response
{
  "validationId": "val_123456",
  "isValid": false,
  "score": 85,
  "errors": [
    {
      "type": "MISSING_REQUIRED_FIELD",
      "field": "partType",
      "rows": [45, 67, 89],
      "message": "Part type is required for ACES compliance"
    }
  ],
  "warnings": [
    {
      "type": "MISSING_OPTIONAL_FIELD",
      "field": "longDescription",
      "count": 234,
      "message": "Long descriptions improve search visibility"
    }
  ]
}

Advanced Integration Patterns

Webhook Integration

Configure webhooks for asynchronous processing:

// Webhook configuration
{
  "fileUrl": "https://example.com/large-catalog.csv",
  "options": {
    "webhookUrl": "https://your-server.com/catalogbridge-webhook",
    "webhookEvents": ["started", "progress", "completed", "failed"],
    "webhookSecret": "your_webhook_secret"
  }
}

// Webhook payload example
{
  "event": "conversion.completed",
  "timestamp": "2025-06-22T11:45:00Z",
  "data": {
    "conversionId": "conv_abc123",
    "status": "completed",
    "results": {
      "acesUrl": "...",
      "piesUrl": "...",
      "statistics": {...}
    }
  },
  "signature": "sha256=..."
}

Streaming Large Files

For files over 50MB, use our streaming endpoint:

# Python example with streaming
import requests

def stream_large_file(file_path, api_key):
    url = 'https://api.catalogbridge.com/v2/convert/stream'
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'text/csv'
    }
    
    with open(file_path, 'rb') as file:
        response = requests.post(
            url,
            data=file,
            headers=headers,
            stream=True
        )
    
    return response.json()

Error Handling and Retries

Implement robust error handling:

class CatalogBridgeClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.maxRetries = 3;
    this.retryDelay = 1000;
  }

  async convertWithRetry(fileUrl, options) {
    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
      try {
        const response = await this.convert(fileUrl, options);
        return response;
      } catch (error) {
        if (error.response?.status === 429) {
          // Rate limited - wait and retry
          const delay = this.retryDelay * attempt;
          console.log(`Rate limited. Waiting ${delay}ms before retry...`);
          await this.sleep(delay);
        } else if (error.response?.status >= 500) {
          // Server error - retry
          if (attempt < this.maxRetries) {
            await this.sleep(this.retryDelay);
            continue;
          }
        }
        throw error;
      }
    }
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

SDK and Library Support

Official SDKs

We provide official SDKs for popular languages:

Node.js/JavaScript:

npm install @catalogbridge/sdk

const CatalogBridge = require('@catalogbridge/sdk');

const client = new CatalogBridge('YOUR_API_KEY');

// Simple conversion
const result = await client.convert({
  file: './parts.csv',
  formats: ['aces', 'pies']
});

Python:

pip install catalogbridge

from catalogbridge import Client

client = Client('YOUR_API_KEY')

# Convert with options
result = client.convert(
    file_path='parts.csv',
    output_formats=['aces', 'pies'],
    validation_level='strict'
)

PHP:

composer require catalogbridge/php-sdk

use CatalogBridge\Client;

$client = new Client('YOUR_API_KEY');

$result = $client->convert([
    'file' => 'https://example.com/parts.csv',
    'formats' => ['aces', 'pies']
]);

Rate Limits and Quotas

API Rate Limits

Different plans have different rate limits:

| Plan | Requests/Minute | Concurrent Conversions | Max File Size | |------|----------------|----------------------|---------------| | Free | 10 | 1 | 10MB | | Professional | 60 | 5 | 50MB | | Enterprise | 300 | 20 | 500MB |

Handling Rate Limits

The API returns rate limit information in headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1624867200

Best Practices

1. Optimize File Uploads

Instead of uploading files with each request, use pre-signed URLs:

// Get upload URL
const { uploadUrl } = await client.getUploadUrl();

// Upload file directly to storage
await uploadFile(uploadUrl, fileData);

// Convert using file reference
const result = await client.convert({
  fileId: uploadUrl.fileId,
  formats: ['aces', 'pies']
});

2. Implement Caching

Cache conversion results when appropriate:

const crypto = require('crypto');

function getCacheKey(fileContent, options) {
  const hash = crypto.createHash('sha256');
  hash.update(fileContent);
  hash.update(JSON.stringify(options));
  return hash.digest('hex');
}

async function convertWithCache(file, options) {
  const cacheKey = getCacheKey(file, options);
  
  // Check cache first
  const cached = await cache.get(cacheKey);
  if (cached) return cached;
  
  // Convert if not cached
  const result = await client.convert(file, options);
  await cache.set(cacheKey, result, 3600); // Cache for 1 hour
  
  return result;
}

3. Monitor API Usage

Track your API usage programmatically:

// Get usage statistics
const usage = await client.getUsage({
  startDate: '2025-06-01',
  endDate: '2025-06-30'
});

console.log('Total conversions:', usage.totalConversions);
console.log('Total parts processed:', usage.totalParts);
console.log('API calls:', usage.apiCalls);

Common Integration Scenarios

ERP Integration

Integrate CatalogBridge with your ERP system:

class ERPIntegration {
  async syncCatalog() {
    // Export from ERP
    const catalogData = await erp.exportProducts();
    
    // Convert to ACES/PIES
    const result = await catalogBridge.convert({
      data: catalogData,
      format: 'json',
      outputFormats: ['aces', 'pies']
    });
    
    // Update ERP with results
    await erp.updateProducts({
      acesData: result.aces,
      piesData: result.pies
    });
  }
}

E-commerce Platform Integration

Auto-convert product uploads:

// WooCommerce example
add_action('woocommerce_product_import_inserted_product_object', function($product) {
    $catalogBridge = new CatalogBridgeClient(API_KEY);
    
    // Extract product data
    $productData = [
        'part_number' => $product->get_sku(),
        'description' => $product->get_description(),
        'price' => $product->get_price()
    ];
    
    // Convert to ACES/PIES
    $result = $catalogBridge->convertSingleProduct($productData);
    
    // Store results
    update_post_meta($product->get_id(), '_aces_data', $result['aces']);
    update_post_meta($product->get_id(), '_pies_data', $result['pies']);
});

Troubleshooting

Common API Errors

401 Unauthorized:

• Verify API key is correct
• Check key hasn't expired
• Ensure proper Authorization header format

413 Request Too Large:

• File exceeds size limit
• Use streaming endpoint for large files
• Consider batch processing

422 Validation Error:

• Review error details in response
• Check file format requirements
• Validate data before submission

429 Too Many Requests:

• Implement exponential backoff
• Check rate limit headers
• Consider upgrading plan

Security Best Practices

API Key Management

• Never expose API keys in client-side code
• Use environment variables
• Rotate keys regularly
• Implement key-specific permissions

Webhook Security

Verify webhook signatures:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

Getting Help

Resources

• API Reference: api.catalogbridge.com/docs
• SDK Documentation: github.com/catalogbridge
• Status Page: status.catalogbridge.com
• Support: support@catalogbridge.com

Support Channels

• Email: API-specific support
• Slack: Developer community
• GitHub: Report SDK issues
• Office Hours: Weekly developer Q&A

Conclusion

The CatalogBridge API provides powerful automation capabilities for ACES/PIES conversion. Whether you're processing a few files or thousands, our API scales with your needs while maintaining data quality and compliance.

Ready to automate your conversions? Get your API key and start building today. For high-volume or custom integration needs, contact our enterprise team for tailored solutions.