Поставщики услуг

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

Поставщики услуг - это компании, предоставляющие коммунальные и другие услуги для недвижимости (управляющие компании, поставщики электроэнергии, воды, интернета и т.д.).

Ограничения базы данных

База данных содержит основные поставщики услуг, но может быть неполной для вашего города/района.

Пользовательские контрагенты

Пользовательские контрагенты - это компании и физические лица, с которыми вы работаете (арендаторы, поставщики услуг, подрядчики и т.д.).

Поля контрагента

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

Доступ к контрагентам

Создание и управление контрагентами

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)

Примеры запросов

Пример 1: Получить первых 50 активных поставщиков

Случай использования: начальная загрузка списка поставщиков услуг

GET /api/v1/service-providers

Пример 2: Поиск по названию компании

Случай использования: пользователь вводит название компании в поле поиска. Возвращает поставщиков, соответствующих поисковому запросу в полях названия или короткого названия.

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

Пример 3: Поиск по коду ЕДРПОУ

Случай использования: пользователь вводит 8-значный код ЕДРПОУ из платежки. Возвращает точное совпадение, если поставщик существует в базе данных.

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

Пример 4: Фильтр по region с пагинацией

Случай использования: показать поставщиков только из конкретного региона, 20 на страницу. Полезно для фильтрации местных коммунальных компаний.

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

Пример 5: Получить детали конкретного поставщика

Случай использования: пользователь нажимает на поставщика из списка, чтобы увидеть полную информацию. Возвращает полную информацию включая временные метки.

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 - Массив объектов поставщиков (максимум 100 элементов на страницу)
• total - Общее количество поставщиков, соответствующих вашим критериям
• pages - Общее количество страниц (вычисляется как: ceil(total / limit))

Пример детального ответа

{
  "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"
}

Случай использования: неверный ID или поставщик был деактивирован в базе данных

API для контрагентов

Полная документация по работе с API контрагентов доступна в интерактивной документации Swagger.

Конечные точки 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: