# Cleavr Connect API - LLM Documentation

This documentation is optimized for Large Language Models (LLMs) like GPT-4, Claude, and others. Use this structured format to build Cleavr Connect integrations with AI assistance.

## API Overview

**Base URL**: `https://api.cleavr.fr`
**Authentication**: OAuth 2.0 Bearer Token
**Content-Type**: `application/json`
**API Version**: `2026-01-02` (via header)

## Quick Integration Template

```javascript
// Complete Cleavr Connect Integration Template
class CleavrConnectIntegration {
  constructor(config) {
    this.clientId = config.clientId;
    this.clientSecret = config.clientSecret;
    this.webhookSecret = config.webhookSecret;
    this.baseUrl = 'https://api.cleavr.fr';
  }

  // 1. OAuth Authentication
  async authenticate(code) {
    const response = await fetch(`${this.baseUrl}/oauth/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        code: code,
        client_id: this.clientId,
        client_secret: this.clientSecret
      })
    });
    return response.json();
  }

  // 2. Create User
  async createUser(userData) {
    const response = await fetch(`${this.baseUrl}/v1/users`, {
      method: 'POST',
      headers: this.getHeaders(),
      body: JSON.stringify({
        email: userData.email,
        company: {
          name: userData.companyName,
          siret: userData.siret
        },
        contact: {
          first_name: userData.firstName,
          last_name: userData.lastName,
          phone: userData.phone
        },
        platform: {
          callback_url: userData.callbackUrl
        }
      })
    });
    return response.json();
  }

  // 3. Submit Receivable
  async submitReceivable(receivableData) {
    const response = await fetch(`${this.baseUrl}/v1/receivables`, {
      method: 'POST',
      headers: this.getHeaders(),
      body: JSON.stringify({
        user_id: receivableData.userId,
        invoice: {
          numbers: receivableData.invoiceNumbers,
          issue_date: receivableData.issueDate,
          due_date: receivableData.dueDate,
          amount: receivableData.amount,
          service_description: receivableData.description
        },
        debtor: {
          company_name: receivableData.debtorName,
          contacts: [{
            email: receivableData.debtorEmail,
            phone: receivableData.debtorPhone,
            level: 0
          }]
        }
      })
    });
    return response.json();
  }

  // 4. Handle Webhook
  verifyWebhook(payload, signature) {
    const crypto = require('crypto');
    const expected = crypto
      .createHmac('sha256', this.webhookSecret)
      .update(payload)
      .digest('hex');
    return signature === expected;
  }

  getHeaders() {
    return {
      'Authorization': \`Bearer \${this.accessToken}\`,
      'Content-Type': 'application/json',
      'Cleavr-Version': '2026-01-02'
    };
  }
}
```

[Content continues with all schemas, workflows, error codes, etc...]