Contazen API Documentation

Overview

The Contazen API supports localization for error messages and responses. Currently, the API supports:

English (en) - Default
Romanian (ro)

Setting the Language

There are three ways to specify your preferred language:

1. Accept-Language Header (Recommended)

Use the standard HTTP Accept-Language header:

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

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

import requests

response = requests.get(
    'https://api.contazen.ro/v1/clients',
    headers={
        'Authorization': 'Bearer sk_live_YOUR_API_KEY',
        'Accept-Language': 'ro'
    }
)

$ch = curl_init('https://api.contazen.ro/v1/clients');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer sk_live_YOUR_API_KEY',
    'Accept-Language: ro'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

2. Query Parameter

Include the locale parameter in the URL:

curl https://api.contazen.ro/v1/clients?locale=ro \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

3. Request Body

For POST and PUT requests, include locale in the JSON body:

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

Priority

If multiple methods are used, the API follows this priority order:

Query parameter (?locale=ro)
Request body ("locale": "ro")
Accept-Language header
Default to English (en)

Response Header

The API includes a Content-Language header in all responses to indicate the language used:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: ro

Localized Elements

The following elements are localized:

Error Messages

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "type": "validation_error",
    "errors": {
      "cui": "CUI/CIF is required for B2B clients",
      "address": "Address is required"
    }
  }
}

{
  "success": false,
  "error": {
    "message": "Validarea a eșuat",
    "type": "validation_error",
    "errors": {
      "cui": "CUI/CIF este obligatoriu pentru clienții B2B",
      "address": "Adresa este obligatorie"
    }
  }
}

Field Labels

Field validation messages are localized based on the context:

English	Romanian
Name is required	Numele este obligatoriu
Invalid email format	Format email invalid
Invoice not found	Factura nu a fost găsită
Client not found	Clientul nu a fost găsit
Due date cannot be before invoice date	Data scadentă nu poate fi înainte de data facturii

Examples

Creating an Invoice with Romanian Errors

Request:

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

Response:

{
  "success": false,
  "error": {
    "message": "Validarea a eșuat",
    "type": "validation_error",
    "code": "invalid_request",
    "status": 400,
    "errors": {
      "items": "Cel puțin un articol este necesar",
      "client_id": "Clientul este obligatoriu"
    }
  },
  "meta": {
    "version": "v1",
    "response_time": "12.34ms"
  }
}

Retrieving Non-existent Client

Request:

curl https://api.contazen.ro/v1/clients/invalid_id?locale=ro \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Response:

{
  "success": false,
  "error": {
    "message": "Clientul nu a fost găsit",
    "type": "not_found_error",
    "code": "resource_not_found",
    "status": 404
  },
  "meta": {
    "version": "v1",
    "response_time": "8.91ms"
  }
}

Language Detection

If no language preference is specified, the API attempts to detect the language from the Accept-Language header:

If the header contains ro (e.g., ro-RO, ro), Romanian is used
Otherwise, English is used as the default

Best Practices

Consistency - Use the same language setting method throughout your application
User Preference - Store user language preferences and apply them to all API requests
Fallback Handling - Always handle English responses as a fallback
Header Method - Prefer the Accept-Language header for RESTful compliance

Notes

Success messages and data field names remain in English regardless of the locale setting. Only error messages and validation messages are localized.

Not all error messages may be translated. If a translation is missing, the English version will be returned as a fallback.

Getting Started

Core Concepts

Localization

Overview

Setting the Language

1. Accept-Language Header (Recommended)

2. Query Parameter

3. Request Body

Priority

Response Header

Localized Elements

Error Messages

Field Labels

Examples

Creating an Invoice with Romanian Errors

Retrieving Non-existent Client

Language Detection

Best Practices

Notes

​Overview

​Setting the Language

​1. Accept-Language Header (Recommended)

​2. Query Parameter

​3. Request Body

​Priority

​Response Header

​Localized Elements

​Error Messages

​Field Labels

​Examples

​Creating an Invoice with Romanian Errors

​Retrieving Non-existent Client

​Language Detection

​Best Practices

​Notes

Overview

Setting the Language

1. Accept-Language Header (Recommended)

2. Query Parameter

3. Request Body

Priority

Response Header

Localized Elements

Error Messages

Field Labels

Examples

Creating an Invoice with Romanian Errors

Retrieving Non-existent Client

Language Detection

Best Practices

Notes