Documentations repository

Appearance

CRM Integration API - Документація з використання ​

Зміст ​

  1. Огляд
  2. Автентифікація
  3. API Ендпоінти
  4. Приклади використання
  5. Обробка помилок

Огляд ​

CRM Integration API надає REST API для синхронізації даних між платформою D-Internal Portal та зовнішніми CRM системами. API дозволяє отримувати та оновлювати інформацію про:

  • Замовлення (Orders)
  • Події (Events)
  • Реєстрації на події (Event Registrations)
  • Запити на реєстрацію (Event Requests)

Базовий URL: https://your-domain.com/api/v1/crm_integration/

Автентифікація ​

Використання API ключа ​

API ключ можна передавати одним з двох способів:

1. Через Authorization заголовок ​

http
Authorization: Api-Key YOUR_API_KEY_HERE

2. Через X-API-Key заголовок ​

http
X-API-Key: YOUR_API_KEY_HERE

Приклад cURL з автентифікацією ​

bash
curl -H "Authorization: Api-Key YOUR_API_KEY_HERE" \
     https://your-domain.com/api/v1/crm_integration/orders/

API Ендпоінти ​

1. Замовлення (Orders) ​

Список замовлень ​

http
GET /crm_integration/orders/

Параметри фільтрації:

  • status - статус замовлення
  • payment_status - статус оплати
  • crm_sync_state - стан синхронізації (pending/synced/failed)
  • area - регіон

Параметри пошуку:

  • search - пошук по email, імені, прізвищу, телефону, номеру замовлення

Сортування:

  • ordering - поля для сортування: created_at, updated_at, crm_sync_date

Приклад запиту:

bash
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     "https://your-domain.com/api/v1/crm_integration/orders/?status=completed&search=john@example.com"

Деталі замовлення ​

http
GET /crm_integration/orders/{id}/
PUT /crm_integration/orders/{id}/

Приклад відповіді:

json
{
    "id": 123,
    "public_identifier": "ORD-2023-001",
    "user": 456,
    "user_email": "user@example.com",
    "total_price": "150.00",
    "first_name": "Іван",
    "last_name": "Петренко", 
    "email": "ivan@example.com",
    "phone": "+380671234567",
    "settlement": "Київ",
    "area": 1,
    "area_name": "Київська область",
    "institution": "КНУ",
    "status": "completed",
    "payment_status": "paid",
    "crm_record_id": "CRM-123",
    "crm_sync_state": "synced",
    "crm_sync_date": "2023-12-01T10:00:00Z",
    "created_at": "2023-11-01T09:00:00Z",
    "updated_at": "2023-12-01T10:00:00Z"
}

2. Події (Events) ​

Список подій ​

http
GET /crm_integration/events/

Параметри фільтрації:

  • entity - тип сутності
  • event_type - тип події
  • level - рівень
  • past - минулі події (true/false)
  • hide - приховані події (true/false)
  • crm_sync_state - стан синхронізації

Приклад запиту:

bash
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     "https://your-domain.com/api/v1/crm_integration/events/?past=false&entity=event"

Деталі події ​

http
GET /crm_integration/events/{id}/
PUT /crm_integration/events/{id}/

3. Реєстрації на події (Event Registrations) ​

Список реєстрацій ​

http
GET /crm_integration/registrations/

Параметри фільтрації:

  • event - ID події
  • lesson - ID уроку
  • area - регіон
  • crm_sync_state - стан синхронізації
  • pass_test - пройшов тест (true/false)

Приклад запиту:

bash
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     "https://your-domain.com/api/v1/crm_integration/registrations/?event=123&pass_test=true"

Деталі реєстрації ​

http
GET /crm_integration/registrations/{id}/
PUT /crm_integration/registrations/{id}/

4. Запити на реєстрацію (Event Requests) ​

Список запитів ​

http
GET /crm_integration/requests/

Параметри фільтрації:

  • event - ID eventi
  • lesson - ID уроку
  • area - регіон
  • status - статус запиту
  • registration_status - статус реєстрації
  • crm_sync_state - стан синхронізації

Деталі запиту ​

http
GET /crm_integration/requests/{id}/
PUT /crm_integration/requests/{id}/

5. Ручна синхронізація ​

http
POST /crm_integration/sync/

Тіло запиту:

json
{
    "model_type": "order",
    "object_id": 123,  
    "action": "sync"
}

Доступні model_type:

  • order - Замовлення
  • event - Подія
  • event_registration - Реєстрація на подію
  • event_request - Запит на реєстрацію

Доступні action:

  • create - Створити
  • update - Оновити
  • sync - Синхронізувати

6. Статус синхронізації ​

http
GET /crm_integration/status/

Приклад відповіді:

json
{
    "orders": {
        "total": 1500,
        "synced": 1450,
        "pending": 30,
        "failed": 20
    },
    "events": {
        "total": 150,
        "synced": 140,
        "pending": 5,
        "failed": 5
    },
    "event_registrations": {
        "total": 5000,
        "synced": 4800,
        "pending": 150,
        "failed": 50
    },
    "event_requests": {
        "total": 2000,
        "synced": 1900,
        "pending": 80,
        "failed": 20
    }
}

Приклади використання ​

1. Отримати всі нові замовлення за останню добу ​

bash
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     "https://your-domain.com/api/v1/crm_integration/orders/?crm_sync_state=pending&ordering=-created_at"

2. Оновити стан замовлення в CRM ​

bash
curl -X PUT \
     -H "Authorization: Api-Key YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"crm_record_id": "CRM-456", "crm_sync_state": "synced"}' \
     "https://your-domain.com/api/v1/crm_integration/orders/123/"

3. Знайти всі реєстрації для конкретної події ​

bash
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     "https://your-domain.com/api/v1/crm_integration/registrations/?event=123&ordering=-created_at"

4. Запустити ручну синхронізацію замовлення ​

bash
curl -X POST \
     -H "Authorization: Api-Key YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model_type": "order", "object_id": 123, "action": "sync"}' \
     "https://your-domain.com/api/v1/crm_integration/sync/"

5. Перевірити статус синхронізації ​

bash
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     "https://your-domain.com/api/v1/crm_integration/status/"

Обробка помилок ​

Коди відповідей HTTP ​

  • 200 OK - Успішний запит
  • 400 Bad Request - Невалідні дані
  • 401 Unauthorized - Відсутній або невалідний API ключ
  • 403 Forbidden - Недостатньо прав доступу
  • 404 Not Found - Ресурс не знайдено
  • 500 Internal Server Error - Внутрішня помилка сервера

Приклади помилок ​

Невалідний API ключ ​

json
{
    "code": 401,
    "message": "Unauthorized",
    "errors": [
        {
            "message": "Incorrect authentication credentials.",
            "domain": "request",
            "reason": "form_value_invalid",
            "state": {
                "message": "Невалідний API ключ",
                "reason": "authentication_failed"
            }
        }
    ]
}