Постачальники послуг

Що таке Поставщик послуг?

Поставщик послуг - це підприємство з повними юридичними реквізитами, зареєстроване в офіційній базі даних юридичних осіб країни, де воно працює.

Обмеження бази даних

На жаль, база даних постачальників послуг може бути неповною. Не всі компанії з Єдиного державного реєстру України можуть бути присутні в системі.

Кастомні контрагенти

Кастомні контрагенти - це створені користувачем записи для компаній, яких немає в офіційній базі постачальників послуг. Ви можете вручну ввести всю необхідну інформацію.

Доступні поля

Правила валідації

Доступ користувача

Ви можете керувати своїми кастомними контрагентами на спеціальній сторінці:

REST API

API для поставщиків послуг (тільки читання)

Постачальники послуг з офіційної бази даних доступні через API-ендпоінти тільки для читання:

Кінцеві точки API

GET /api/v1/service-providers              # List all active providers
GET /api/v1/service-providers/{id}         # Get specific provider details

Параметри запиту

• page (integer, optional) - Page number, starts from 1. Default: 1
• limit (integer, optional) - Items per page, max 100. Default: 50
• search (string, optional) - Search by company name or EDRPOU code
• region (string, optional) - Filter by region (exact match)

Приклади

Список об'єктів

Отримати список всіх об'єктів нерухомості

GET /api/v1/service-providers

Деталі об'єкта

Отримати деталі конкретного об'єкта

GET /api/v1/service-providers?search=Kyiv Energy Company

Створення об'єкта

Створити новий об'єкт нерухомості

GET /api/v1/service-providers?search=00131305

Оновлення об'єкта

Оновити існуючий об'єкт

GET /api/v1/service-providers?region=Kyiv&page=1&limit=20

Видалення об'єкта

Видалити об'єкт нерухомості

GET /api/v1/service-providers/1

Відповідь списку

{
  "items": [
    {
      "id": 1,
      "edrpou": "00131305",
      "name": "Public Joint Stock Company Kyiv Energy",
      "short_name": "Kyiv Energy JSC",
      "legal_address": "Kyiv, Sakharov St, 139",
      "region": "Kyiv",
      "website": "https://kyivenergo.ua",
      "description": "Electricity distribution company serving Kyiv",
      "phone": "+380 44 467 0067",
      "email": "[email protected]",
      "is_active": true,
      "country": {
        "id": 1,
        "code": "UA",
        "name": {
          "uk": "Україна",
          "en": "Ukraine",
          "ru": "Украина",
          "pl": "Ukraina",
          "de": "Ukraine"
        }
      }
    }
  ],
  "total": 1234,
  "pages": 25
}

Поля відповіді:

• items - Масив об'єктів
• total - Загальна кількість записів
• pages - Загальна кількість сторінок

Відповідь деталей

{
  "id": 1,
  "edrpou": "00131305",
  "name": "Public Joint Stock Company Kyiv Energy",
  "website": "https://kyivenergo.ua",
  "description": "Electricity distribution company serving Kyiv",
  "phone": "+380 44 467 0067",
  "country": {
    "id": 1,
    "code": "UA",
    "name": {
      "uk": "Україна",
      "en": "Ukraine",
      "ru": "Украина",
      "pl": "Ukraina",
      "de": "Ukraine"
    }
  },
  "created_at": "2024-01-15T10:30:00+02:00",
  "updated_at": "2024-06-20T14:45:00+02:00"
}

Додаткові поля:

• created_at - Дата створення (ISO 8601)
• updated_at - Дата останнього оновлення (ISO 8601)

Коди помилок

404 Not Found - Повертається коли об'єкт не знайдено

{
  "error": "Service provider not found"
}

Наприклад, при запиті GET /api/properties/999999

API для кастомних контрагентів (повний CRUD)

Кастомні контрагенти підтримують повні CRUD-операції з суворою валідацією:

Кінцеві точки API

GET    /api/v1/user/custom-contragents           # List all user contragents
POST   /api/v1/user/custom-contragents           # Create new contragent
GET    /api/v1/user/custom-contragents/{id}      # Get contragent details
PUT    /api/v1/user/custom-contragents/{id}      # Update contragent
DELETE /api/v1/user/custom-contragents/{id}      # Delete contragent

Потрібна аутентифікація: Всі ендпоінти вимагають аутентифікації користувача. Ви можете керувати тільки своїми контрагентами.

Приклади

Приклад 1: Отримати список ваших контрагентів

Випадок використання: відображення всіх користувацьких контрагентів у випадаючому списку форми витрат або на сторінці управління.

GET /api/v1/user/custom-contragents

Приклад 2: Створити нового контрагента

Випадок використання: користувач додає нову компанію, якої немає в офіційній базі даних. Обов'язкове тільки поле назви, всі інші поля опціональні, але валідуються якщо надані.

POST /api/v1/user/custom-contragents
Content-Type: application/json

{
  "name": "Example Company LLC",
  "short_name": "Example Co",
  "legal_form": "LLC",
  "tax_number": "12345678",
  "vat_number": "123456789012",
  "iban": "UA123456789012345678901234567",
  "bank_name": "PrivatBank",
  "bank_mfo": "305299",
  "swift": "PBANUA2X",
  "email": "[email protected]",
  "phone": "+380 44 123 4567",
  "website": "https://example.com",
  "director_name": "John Doe",
  "legal_address": "Kyiv, Khreshchatyk St, 1",
  "registration_date": "2020-01-15"
}

Приклад 3: Отримати деталі контрагента

Випадок використання: відображення повної інформації про конкретного контрагента на сторінці деталей.

GET /api/v1/user/custom-contragents/01a06b0b-5f36-7d8b-b211-b03c9c7d9a24

Приклад 4: Оновити контрагента

Випадок використання: користувач редагує інформацію контрагента. Надсилайте тільки поля, які потрібно оновити. Всі правила валідації застосовуються.

PUT /api/v1/user/custom-contragents/01a06b0b-5f36-7d8b-b211-b03c9c7d9a24
Content-Type: application/json

{
  "phone": "+380 44 999 8888",
  "email": "[email protected]",
  "website": "https://new-website.com"
}

Приклад 5: Видалити контрагента

Випадок використання: користувач видаляє контрагента, який більше не потрібен. Неможливо видалити, якщо контрагент використовується у витратах.

DELETE /api/v1/user/custom-contragents/01a06b0b-5f36-7d8b-b211-b03c9c7d9a24

Відповідь списку

{
  "contragents": [
    {
      "id": 1,
      "name": "Example Company LLC",
      "short_name": "Example Co",
      "legal_form": "LLC",
      "tax_number": "12345678",
      "vat_number": "123456789012",
      "iban": "UA123456789012345678901234567",
      "bank_name": "PrivatBank",
      "bank_mfo": "305299",
      "swift": "PBANUA2X",
      "email": "[email protected]",
      "phone": "+380 44 123 4567",
      "website": "https://example.com",
      "director_name": "John Doe",
      "contact_person": "Jane Smith",
      "legal_address": "Kyiv, Khreshchatyk St, 1",
      "actual_address": "Kyiv, Khreshchatyk St, 1",
      "registration_date": "2020-01-15",
      "notes": "Primary utility provider",
      "created_at": "2024-01-15T10:30:00+02:00",
      "updated_at": "2024-06-20T14:45:00+02:00"
    }
  ]
}

Відповідь на створення/оновлення

{
  "id": 1,
  "name": "Example Company LLC",
  "message": "Contragent created successfully"
}

Відповідь на видалення

{
  "message": "Contragent deleted successfully"
}

Відповідь з помилками валідації

Повертається з HTTP 400, коли валідація не пройдена. Містить назви полів та повідомлення про помилки.

{
  "error": "Validation failed",
  "violations": {
    "name": "Name must be at least 3 characters long",
    "tax_number": "Tax number must be 8-12 digits",
    "iban": "Invalid IBAN format",
    "email": "Invalid email address"
  }
}

403 Заборонено - Доступ заборонено

Повертається при спробі доступу або зміни контрагента, який належить іншому користувачу.

{
  "error": "Access denied"
}

404 Не знайдено - Контрагент не знайдено

Повертається, коли контрагент з вказаним ID не існує.

{
  "error": "Contragent not found"
}

409 Конфлікт - Неможливо видалити

Повертається при спробі видалити контрагента, який використовується у витратах або інших записах.

{
  "error": "Cannot delete contragent. It is used in 5 expense records."
}

Swagger / OpenAPI

Повна документація API доступна в Swagger UI: