Contazen API Documentation

Overview

The Contazen API supports multi-work-point (multi-branch) access, allowing you to manage data across all locations of your business using a single API key. This is particularly useful for businesses with multiple offices, stores, or branches.

How It Works

When you authenticate with an API key, you automatically gain access to:

The work point where the API key was created
All other work points belonging to the same parent company

Work Point = A physical business location or branch Parent Company = The legal entity that owns multiple work points

Accessing Specific Work Points

By default, API requests operate on the work point where the API key was created. To access data from a different work point, include the work_point_id parameter in your request.

Getting Work Point IDs

First, retrieve the list of available work points:

curl https://api.contazen.ro/v1/settings \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

const response = await fetch('https://api.contazen.ro/v1/settings', {
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.work_points); // List of available work points

$client = new Contazen\Client('sk_live_YOUR_API_KEY');
$settings = $client->settings->get();

foreach ($settings->work_points as $workPoint) {
    echo $workPoint->id . ': ' . $workPoint->name . PHP_EOL;
}

Working with Multiple Work Points

List Invoices from All Work Points

To retrieve invoices from all work points, omit the work_point_id parameter:

curl https://api.contazen.ro/v1/invoices \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

const response = await fetch('https://api.contazen.ro/v1/invoices', {
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY'
  }
});

const invoices = await response.json();
// Returns invoices from all accessible work points

List Invoices from Specific Work Point

To retrieve invoices from a specific work point:

curl https://api.contazen.ro/v1/invoices?work_point_id=wp_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

const response = await fetch('https://api.contazen.ro/v1/invoices?work_point_id=wp_abc123', {
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY'
  }
});

$client = new Contazen\Client('sk_live_YOUR_API_KEY');

// Configure default work point for all requests
$client = Contazen\Client::create('sk_live_YOUR_API_KEY')
    ->withWorkPointId('wp_abc123')
    ->build();

// Or specify per request
$invoices = $client->invoices->list([
    'work_point_id' => 'wp_abc123'
]);

Create Invoice for Specific Work Point

When creating resources, specify the target work point:

curl -X POST https://api.contazen.ro/v1/invoices \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "work_point_id": "wp_abc123",
    "client_id": "cli_xyz789",
    "items": [...]
  }'

const invoice = await fetch('https://api.contazen.ro/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    work_point_id: 'wp_abc123',
    client_id: 'cli_xyz789',
    items: [
      {
        description: 'Professional Services',
        quantity: 1,
        price: 1000
      }
    ]
  })
});

$client = new Contazen\Client('sk_live_YOUR_API_KEY');

$invoice = $client->invoices->create([
    'work_point_id' => 'wp_abc123',
    'client_id' => 'cli_xyz789',
    'items' => [
        [
            'description' => 'Professional Services',
            'quantity' => 1,
            'price' => 1000
        ]
    ]
]);

Common Use Cases

Consolidated Reporting

Generate reports across all business locations:

async function getConsolidatedRevenue(apiKey, startDate, endDate) {
  const response = await fetch('https://api.contazen.ro/v1/invoices', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  const invoices = await response.json();
  
  // Group by work point
  const revenueByLocation = {};
  invoices.data.forEach(invoice => {
    const wpId = invoice.work_point_id;
    if (!revenueByLocation[wpId]) {
      revenueByLocation[wpId] = 0;
    }
    revenueByLocation[wpId] += invoice.total;
  });
  
  return revenueByLocation;
}

Centralized Client Management

Share client data across all locations:

async function findClientAcrossAllLocations(apiKey, searchTerm) {
  const response = await fetch(
    `https://api.contazen.ro/v1/clients?search=${searchTerm}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );
  
  const clients = await response.json();
  return clients.data; // Returns clients from all work points
}

Location-Specific Operations

Process operations for a specific branch:

class BranchManager {
  constructor(apiKey, workPointId) {
    this.apiKey = apiKey;
    this.workPointId = workPointId;
  }
  
  async createInvoice(clientId, items) {
    const response = await fetch('https://api.contazen.ro/v1/invoices', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        work_point_id: this.workPointId,
        client_id: clientId,
        items: items
      })
    });
    
    return response.json();
  }
  
  async getProducts() {
    const response = await fetch(
      `https://api.contazen.ro/v1/products?work_point_id=${this.workPointId}`,
      {
        headers: {
          'Authorization': `Bearer ${this.apiKey}`
        }
      }
    );
    
    return response.json();
  }
}

// Usage
const bucharest = new BranchManager('sk_live_KEY', 'wp_bucharest');
const cluj = new BranchManager('sk_live_KEY', 'wp_cluj');

Best Practices

Set Default Work Point

Configure a default work point in your SDK client to avoid specifying it for every request:

$client = Contazen\Client::create('sk_live_KEY')
    ->withWorkPointId('wp_default')
    ->build();

Cache Work Point List

Work points don’t change frequently. Cache the list to reduce API calls:

let workPointCache = null;

async function getWorkPoints(apiKey) {
  if (!workPointCache) {
    const response = await fetch('https://api.contazen.ro/v1/settings', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });
    const data = await response.json();
    workPointCache = data.work_points;
  }
  return workPointCache;
}

Handle Work Point Permissions

Always handle cases where a work point might not be accessible:

try {
  const invoice = await createInvoice(workPointId, data);
} catch (error) {
  if (error.code === 'work_point_not_found') {
    console.error('Work point not accessible or does not exist');
  }
}

Limitations

API keys can only access work points within the same parent company
Some operations may be restricted to specific work points based on permissions
Work point IDs are immutable and cannot be changed once created

Authentication - Learn about API key management
Settings API - Retrieve work point information
PHP SDK - SDK with built-in multi-work-point support

Getting Started

Core Concepts

Multi-Work-Point Access

Overview

How It Works

Accessing Specific Work Points

Getting Work Point IDs

Working with Multiple Work Points

List Invoices from All Work Points

List Invoices from Specific Work Point

Create Invoice for Specific Work Point

Common Use Cases

Consolidated Reporting

Centralized Client Management

Location-Specific Operations

Best Practices

Limitations

​Overview

​How It Works

​Accessing Specific Work Points

​Getting Work Point IDs

​Working with Multiple Work Points

​List Invoices from All Work Points

​List Invoices from Specific Work Point

​Create Invoice for Specific Work Point

​Common Use Cases

​Consolidated Reporting

​Centralized Client Management

​Location-Specific Operations

​Best Practices

​Limitations

​Related Resources

Overview

How It Works

Accessing Specific Work Points

Getting Work Point IDs

Working with Multiple Work Points

List Invoices from All Work Points

List Invoices from Specific Work Point

Create Invoice for Specific Work Point

Common Use Cases

Consolidated Reporting

Centralized Client Management

Location-Specific Operations

Best Practices

Limitations

Related Resources