Перейти до вмісту
Partner API v1.2

Підключення страховика до IZI Polis

Клієнти, які купили ваші поліси через агентів IZI Polis, користуються застосунком INSUREX. Через Partner API ви показуєте їм ваші договори, отримуєте заяви про страхові події з фото й геолокацією, ведете справу до виплати, відповідаєте в чаті й отримуєте фото-огляди.

📄 Договори

Ваші договори в застосунку клієнта: нагадування про продовження, документи, ваші контакти. Push від вас або pull за нашим стандартом.

📝 Заяви (FNOL)

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

💬 Чати

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

📸 Фото-огляди

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

Як працює обмін

Клієнт подає заяву чи пише в застосунку
IZI Polis надсилає вебхук на ваш сервер
Ваша система викликає API: статус, повідомлення, менеджер
Клієнт отримує push і бачить зміни в застосунку

Без вебхука можна працювати опитуванням (updated_since), але заяви через застосунок вмикаються лише з налаштованим вебхуком.

Функції інтеграції — кожна вмикається окремо

Не обов’язково будувати все одразу. Почніть з того, що ваша система вже вміє, — решту ввімкнемо, коли будете готові. Поки функцію не ввімкнено, клієнт бачить ваші контакти (гаряча лінія, email, сайт) і звертається напряму.

ФункціяЩо потрібно від васЩо бачить клієнт
Синхронізація договорівPush: ключ API + POST /policies/batch. Pull: методи за стандартом.Ваші договори в списку полісів, нагадування про продовження
ЧатКлюч API; вебхук бажанийКнопка «Чат зі страховиком» у картці поліса
Страхові випадкиКлюч API + вебхукЗаява з фото й геолокацією, статус справи, листування
Огляд майнаКлюч API + вебхукФото-огляд за підказками; результат надходить вам
Повідомлення клієнтамКлюч API + POST /notificationsPush і запис у «Сповіщеннях» від вашої компанії — лише вашим клієнтам

Які функції ввімкнено для вашої компанії — GET /me → features. Ввімкнути — через менеджера платформи.

Швидкий старт за 15 хвилин

  1. Отримайте тестовий ключ ipk_test_… у вашого менеджера IZI Polis.
  2. Відкрийте тестову консоль і вставте ключ.
  3. Натисніть «Створити тестовий приймач» — або вкажіть адресу свого сервера (https://).
  4. Створіть тестову заяву — подія claim.submitted надійде на вебхук.
  5. Змініть статус заяви через API й перевірте, що підпис вебхука сходиться у вашому коді.
  6. Пройдіть чек-лист і отримайте бойовий ключ ipk_….
# Хто я і в якому режимі ключ
curl https://izipolis.com/api/partner/v1/me \
  -H "Authorization: Bearer ipk_test_xxxxxxxx_…"

# Тестовий вебхук (секрет підпису повернеться один раз)
curl -X PUT https://izipolis.com/api/partner/v1/webhook \
  -H "Authorization: Bearer ipk_test_xxxxxxxx_…" -H "Content-Type: application/json" \
  -d '{"url":"https://dev.insurer.ua/vippolis/webhook"}'

# Імітувати заяву клієнта
curl -X POST https://izipolis.com/api/partner/v1/sandbox/claims \
  -H "Authorization: Bearer ipk_test_xxxxxxxx_…"

# Прийняти заяву
curl -X POST https://izipolis.com/api/partner/v1/claims/{id}/status \
  -H "Authorization: Bearer ipk_test_xxxxxxxx_…" -H "Content-Type: application/json" \
  -d '{"status":"received","case_number":"KV-2026-00153","message":"Заяву прийнято, менеджер зв’яжеться сьогодні."}'

Ключі й режими

Кожен запит — із заголовком Authorization: Bearer <ключ>. Ключі видає IZI Polis; повний ключ показується один раз, у нас зберігається лише його хеш. Новий ключ одразу вимикає попередній.

КлючРежимДаніВебхук
ipk_test_…тестовийЛише тестові заяви, чати й огляди, створені методами /sandboxТестовий (PUT /webhook з тестовим ключем)
ipk_…бойовийРеальні клієнти за вашими полісамиБойовий

Режим повертається в заголовку X-Livemode: true|false і полі livemode в об’єктах і подіях. Тестові дані ніколи не потрапляють до клієнтів і в бойовий режим.

Відповіді й помилки

Успіх — {"data": …} (списки ще з meta). Кожна відповідь містить X-Request-Id — вкажіть його, звертаючись до підтримки.

КодЩо означаєЩо робити
401Ключ невірний або відкликанийПеревірте ключ і режим
403sandbox_only — метод лише для тестового ключаВикористайте ipk_test_…
404Об’єкт не знайдено — або він іншого режиму чи страховикаПеревірте id і ключ
422Помилка валідації: {"message", "errors": {"поле": ["текст"]}}Виправте запит; тексти можна показувати менеджеру
429Понад 300 запитів на хвилинуЗачекайте Retry-After секунд
5xxТимчасова помилка платформиПовторіть із паузою; для повідомлень передавайте external_id

Пагінація й синхронізація

Списки посторінкові: ?page=2&per_page=100 (до 100), у відповіді — meta.current_page, meta.last_page, meta.total.

Резервна синхронізація без вебхуків або після простою: GET /claims?updated_since=2026-11-10T00:00:00+02:00, GET /chats?unread=1, GET /inspections?completed_since=…. Рекомендуємо раз на 5–15 хвилин як страховку до вебхуків.

Синхронізація договорів

Мета — щоб клієнт бачив у INSUREX усі свої договори з вашої компанії, навіть оформлені не через агентів платформи. Формат однаковий для всіх страховиків: ви реалізуєте його один раз, і він не зміниться під іншу компанію.

Кого синхронізуємо

Лише підписаних клієнтів: тих, хто користується застосунком і підтвердив особу. Кожен підписаний має ref (напр. cs_8f2kq1x0b7m3n4p5r6s7t8u9) — ідентифікатор, за яким ви повертаєте його договори. Ми передаємо телефон і, якщо клієнт підтвердив особу за ІПН, — ІПН. Вашу базу цілком ми не запитуємо й не зберігаємо: договори, для яких немає клієнта застосунку, відкидаються.

Два режими

Push — рекомендовано
  1. Вебхук client.subscribed (ref, phone, tax_id) — або опитування GET /policies/subscriptions?since=….
  2. Ви одразу надсилаєте договори клієнта: POST /policies/batch (до 500 за раз).
  3. Далі — при кожній зміні договору: укладення, продовження, розірвання.

Жодних регулярних запитів до вашого сервера.

Pull
  1. Ви реалізуєте POST /policies/lookup — договори для пачки до 100 клієнтів.
  2. За бажання — GET /policies/changes?cursor=…: зміни договорів підписаних клієнтів.
  3. Ви видаєте нам токен; менеджер вносить адресу API й токен в адмінку.

Специфікація: insurer-policies.yaml.

Навантаження при мільйоні клієнтів

  • Push — запити лише тоді, коли договір змінився.
  • Pull — пачки до 100 клієнтів, не більше погодженої кількості запитів на хвилину (за замовчуванням 10). Кожен клієнт — раз на 7 днів у випадковий час доби; з changes — раз на 30 днів як звірка. Орієнтир: 1 000 000 клієнтів ≈ 1 запит на хвилину, без нічних піків.
  • «Оновити» в застосунку — позачергово, не частіше ніж раз на 6 годин для клієнта.
  • 429 + Retry-After — чекаємо, скільки просите. 5xx чи тайм-аут — пауза 1, 2, 4… до 60 хвилин.

Договір

ПолеОбов’язковоЩо це
numberтакНомер договору, унікальний у межах компанії. Повторна відправка — оновлення
typeтакoscpv, kasko, green_card, travel, property, dms, accident, other
statusтакactive, cancelled (розірвано), expired, draft (не оплачено)
start_date, end_dateтакПеріод дії, YYYY-MM-DD
refдля push — бажаноКлієнт із client.subscribed
holder.phone, holder.tax_idбажаноСтрахувальник. Якщо ІПН не збігається з ІПН клієнта — договір не прив’язується
product_name, premium, insured_nameніНазва програми, платіж, застрахований
vehicle.plate, vehicle.name, objectніАвто або об’єкт страхування
document_urlніPDF поліса; посилання має діяти щонайменше 24 год
updated_atбажаноЧас зміни у вашій системі — старіша версія не перезапише новішу
POST /api/partner/v1/policies/batch
{"policies": [{
  "ref": "cs_8f2kq1x0b7m3n4p5r6s7t8u9",
  "number": "ЕР-212094117", "type": "oscpv", "status": "active",
  "start_date": "2026-06-01", "end_date": "2027-05-31", "premium": 1850,
  "holder": {"phone": "+380671234567", "tax_id": "1234567890"},
  "vehicle": {"plate": "AA1234BB", "name": "Skoda Octavia"},
  "updated_at": "2026-11-05T10:00:00+02:00"
}]}

→ {"data": {"results": [{"number": "ЕР-212094117", "result": "created"}], "summary": {"created": 1}}}

Результати: created, updated, stale (старіша версія), no_client (клієнта застосунку не знайдено — не збережено), invalid (з поясненням у error). Тестовий ключ ipk_test_… лише перевіряє формат: valid / invalid.

Клієнт видалив обліковий запис — надходить вебхук client.unsubscribed; більше не надсилайте його договори, ми вже видалили копії.

Вебхуки

IZI Polis надсилає POST з JSON на вашу адресу (лише https://). Відповідайте кодом 2xx протягом 10 секунд; довгу обробку робіть у фоні після відповіді.

ЗаголовокЗначення
X-Signaturesha256= + HMAC-SHA256 рядка {X-Timestamp}.{тіло} секретом вебхука
X-TimestampUnix-час відправки — відхиляйте запити, старші за 5 хвилин
X-Event-IdІдентифікатор події (= event_id), однаковий для всіх повторів
X-Event-TypeТип події, напр. claim.submitted
X-Request-IdІдентифікатор конкретної спроби

Повтори. Якщо ваш сервер не відповів 2xx — повторюємо через 1 хв, 5 хв, 30 хв, 2 год і 12 год (усього 6 спроб). Кожна спроба видна в журналі: GET /webhooks/deliveries або в тестовій консолі; будь-яку подію можна надіслати повторно.

Дублі й порядок. Та сама подія може надійти більше одного разу — обробляйте ідемпотентно за event_id. Порядок доставки не гарантовано: орієнтуйтеся на occurred_at і поточний стан об’єкта в data (за потреби — GET /claims/{id}).

Секрет. Створюється під час першого PUT /webhook і повертається один раз; новий — {"rotate_secret": true}.

Перевірка підпису

$body = file_get_contents('php://input');           // сире тіло, до json_decode
$ts   = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, getenv('VIPPOLIS_WEBHOOK_SECRET'));

if (! hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);
if (alreadyProcessed($event['event_id'])) { http_response_code(200); exit; }   // ідемпотентність
queueForProcessing($event);
http_response_code(200);
Рахуйте підпис від сирого тіла запиту. Якщо спершу розібрати JSON і зібрати знову, порядок ключів чи екранування зміняться — і підпис не зійдеться.

Події

Кожна подія: event_id, type, livemode, occurred_at і data з актуальним станом об’єкта.

ping — Перевірка вебхука

Перевірка вебхука: з тестової консолі, PUT /webhook → POST /webhook/test або з адмінки.

{
    "event_id": "evt_01JCB8Q3N4X5Y6Z7A8B9C0D1E2",
    "type": "ping",
    "livemode": true,
    "occurred_at": "2026-11-10T10:05:01+02:00",
    "data": {
        "company": "СК «Приклад»",
        "message": "Вебхук налаштовано правильно."
    }
}
claim.submitted — Клієнт подав заяву про страхову подію

Клієнт подав заяву про страхову подію в застосунку. Прийміть її у свою систему й поверніть статус received.

{
    "event_id": "evt_01JCB8Q3N4X5Y6Z7A8B9C0D1E2",
    "type": "claim.submitted",
    "livemode": true,
    "occurred_at": "2026-11-10T10:05:01+02:00",
    "data": {
        "claim": {
            "id": "9b2f6c1e-3d4a-4f7b-9a51-0c2d8e7f1a23",
            "livemode": true,
            "status": "submitted",
            "status_label": "Подано",
            "type": "oscpv",
            "type_label": "Автоцивілка (ОСЦПВ)",
            "event_type": "dtp",
            "event_label": "ДТП",
            "occurred_at": "2026-11-10T09:40:00+02:00",
            "location": {
                "address": "м. Київ, просп. Перемоги, 12",
                "lat": 50.4547,
                "lng": 30.4472
            },
            "description": "Зіткнення на перехресті, пошкоджено задній бампер.",
            "answers": [
                {
                    "key": "guilty",
                    "label": "Хто винуватець",
                    "value": "other"
                },
                {
                    "key": "europrotocol",
                    "label": "Оформлено європротокол",
                    "value": true
                }
            ],
            "case_number": null,
            "amount": null,
            "required_files": [],
            "files": [
                {
                    "id": "0f6e2a7b-8c1d-4e5f-9a0b-1c2d3e4f5a6b",
                    "kind": "damage",
                    "kind_label": "Пошкодження",
                    "name": "IMG_2041.jpg",
                    "mime": "image/jpeg",
                    "size": 1843200,
                    "sha256": "b5d4…e91a",
                    "meta": {
                        "taken_at": "2026-11-10T09:52:11+02:00",
                        "lat": 50.4547,
                        "lng": 30.4472
                    },
                    "url": "https://izipolis.com/api/partner/v1/claims/files/0f6e2a7b-8c1d-4e5f-9a0b-1c2d3e4f5a6b"
                }
            ],
            "history": [
                {
                    "id": 1,
                    "type": "status",
                    "status": "submitted",
                    "status_label": "Подано",
                    "message": "Заяву подано через застосунок.",
                    "source": "client",
                    "author_name": null,
                    "files": [],
                    "at": "2026-11-10T10:05:00+02:00"
                }
            ],
            "manager": null,
            "unread": 0,
            "is_open": true,
            "rating": null,
            "policy": {
                "number": "ЕР-219384756",
                "product": "ОСЦПВ"
            },
            "reporter": {
                "name": "Шевченко Олена Петрівна",
                "phone": "+380671112233",
                "email": "[email protected]",
                "ident_code": "3012345678"
            },
            "submitted_at": "2026-11-10T10:05:00+02:00",
            "created_at": "2026-11-10T09:58:00+02:00"
        }
    }
}
claim.files_added — Клієнт додав документи, які просив страховик

Клієнт додав документи після статусу documents_required.

{
    "event_id": "evt_01JCB8Q3N4X5Y6Z7A8B9C0D1E2",
    "type": "claim.files_added",
    "livemode": true,
    "occurred_at": "2026-11-10T10:05:01+02:00",
    "data": {
        "claim": {
            "id": "9b2f6c1e-3d4a-4f7b-9a51-0c2d8e7f1a23",
            "livemode": true,
            "status": "documents_required",
            "status_label": "Потрібні документи",
            "type": "oscpv",
            "type_label": "Автоцивілка (ОСЦПВ)",
            "event_type": "dtp",
            "event_label": "ДТП",
            "occurred_at": "2026-11-10T09:40:00+02:00",
            "location": {
                "address": "м. Київ, просп. Перемоги, 12",
                "lat": 50.4547,
                "lng": 30.4472
            },
            "description": "Зіткнення на перехресті, пошкоджено задній бампер.",
            "answers": [
                {
                    "key": "guilty",
                    "label": "Хто винуватець",
                    "value": "other"
                },
                {
                    "key": "europrotocol",
                    "label": "Оформлено європротокол",
                    "value": true
                }
            ],
            "case_number": null,
            "amount": null,
            "required_files": [],
            "files": [
                {
                    "id": "0f6e2a7b-8c1d-4e5f-9a0b-1c2d3e4f5a6b",
                    "kind": "damage",
                    "kind_label": "Пошкодження",
                    "name": "IMG_2041.jpg",
                    "mime": "image/jpeg",
                    "size": 1843200,
                    "sha256": "b5d4…e91a",
                    "meta": {
                        "taken_at": "2026-11-10T09:52:11+02:00",
                        "lat": 50.4547,
                        "lng": 30.4472
                    },
                    "url": "https://izipolis.com/api/partner/v1/claims/files/0f6e2a7b-8c1d-4e5f-9a0b-1c2d3e4f5a6b"
                }
            ],
            "history": [
                {
                    "id": 1,
                    "type": "status",
                    "status": "submitted",
                    "status_label": "Подано",
                    "message": "Заяву подано через застосунок.",
                    "source": "client",
                    "author_name": null,
                    "files": [],
                    "at": "2026-11-10T10:05:00+02:00"
                }
            ],
            "manager": null,
            "unread": 0,
            "is_open": true,
            "rating": null,
            "policy": {
                "number": "ЕР-219384756",
                "product": "ОСЦПВ"
            },
            "reporter": {
                "name": "Шевченко Олена Петрівна",
                "phone": "+380671112233",
                "email": "[email protected]",
                "ident_code": "3012345678"
            },
            "submitted_at": "2026-11-10T10:05:00+02:00",
            "created_at": "2026-11-10T09:58:00+02:00"
        },
        "comment": "Додав довідку з поліції."
    }
}
claim.message.created — Нове повідомлення клієнта в справі

Нове повідомлення клієнта в справі.

{
    "event_id": "evt_01JCB8Q3N4X5Y6Z7A8B9C0D1E2",
    "type": "claim.message.created",
    "livemode": true,
    "occurred_at": "2026-11-10T10:05:01+02:00",
    "data": {
        "claim": {
            "id": "9b2f6c1e-3d4a-4f7b-9a51-0c2d8e7f1a23",
            "livemode": true,
            "status": "in_review",
            "status_label": "На розгляді",
            "type": "oscpv",
            "type_label": "Автоцивілка (ОСЦПВ)",
            "event_type": "dtp",
            "event_label": "ДТП",
            "occurred_at": "2026-11-10T09:40:00+02:00",
            "location": {
                "address": "м. Київ, просп. Перемоги, 12",
                "lat": 50.4547,
                "lng": 30.4472
            },
            "description": "Зіткнення на перехресті, пошкоджено задній бампер.",
            "answers": [
                {
                    "key": "guilty",
                    "label": "Хто винуватець",
                    "value": "other"
                },
                {
                    "key": "europrotocol",
                    "label": "Оформлено європротокол",
                    "value": true
                }
            ],
            "case_number": null,
            "amount": null,
            "required_files": [],
            "files": [
                {
                    "id": "0f6e2a7b-8c1d-4e5f-9a0b-1c2d3e4f5a6b",
                    "kind": "damage",
                    "kind_label": "Пошкодження",
                    "name": "IMG_2041.jpg",
                    "mime": "image/jpeg",
                    "size": 1843200,
                    "sha256": "b5d4…e91a",
                    "meta": {
                        "taken_at": "2026-11-10T09:52:11+02:00",
                        "lat": 50.4547,
                        "lng": 30.4472
                    },
                    "url": "https://izipolis.com/api/partner/v1/claims/files/0f6e2a7b-8c1d-4e5f-9a0b-1c2d3e4f5a6b"
                }
            ],
            "history": [
                {
                    "id": 1,
                    "type": "status",
                    "status": "submitted",
                    "status_label": "Подано",
                    "message": "Заяву подано через застосунок.",
                    "source": "client",
                    "author_name": null,
                    "files": [],
                    "at": "2026-11-10T10:05:00+02:00"
                }
            ],
            "manager": null,
            "unread": 1,
            "is_open": true,
            "rating": null,
            "policy": {
                "number": "ЕР-219384756",
                "product": "ОСЦПВ"
            },
            "reporter": {
                "name": "Шевченко Олена Петрівна",
                "phone": "+380671112233",
                "email": "[email protected]",
                "ident_code": "3012345678"
            },
            "submitted_at": "2026-11-10T10:05:00+02:00",
            "created_at": "2026-11-10T09:58:00+02:00"
        },
        "message": {
            "id": 57,
            "type": "message",
            "status": "in_review",
            "status_label": "На розгляді",
            "message": "Коли буде огляд?",
            "source": "client",
            "author_name": null,
            "files": [],
            "at": "2026-11-10T13:10:00+02:00"
        }
    }
}
claim.rated — Клієнт оцінив урегулювання

Клієнт оцінив урегулювання (1–5) після закриття справи.

{
    "event_id": "evt_01JCB8Q3N4X5Y6Z7A8B9C0D1E2",
    "type": "claim.rated",
    "livemode": true,
    "occurred_at": "2026-11-10T10:05:01+02:00",
    "data": {
        "claim": {
            "id": "9b2f6c1e-3d4a-4f7b-9a51-0c2d8e7f1a23",
            "livemode": true,
            "status": "paid",
            "status_label": "Виплачено",
            "type": "oscpv",
            "type_label": "Автоцивілка (ОСЦПВ)",
            "event_type": "dtp",
            "event_label": "ДТП",
            "occurred_at": "2026-11-10T09:40:00+02:00",
            "location": {
                "address": "м. Київ, просп. Перемоги, 12",
                "lat": 50.4547,
                "lng": 30.4472
            },
            "description": "Зіткнення на перехресті, пошкоджено задній бампер.",
            "answers": [
                {
                    "key": "guilty",
                    "label": "Хто винуватець",
                    "value": "other"
                },
                {
                    "key": "europrotocol",
                    "label": "Оформлено європротокол",
                    "value": true
                }
            ],
            "case_number": null,
            "amount": 18500,
            "required_files": [],
            "files": [
                {
                    "id": "0f6e2a7b-8c1d-4e5f-9a0b-1c2d3e4f5a6b",
                    "kind": "damage",
                    "kind_label": "Пошкодження",
                    "name": "IMG_2041.jpg",
                    "mime": "image/jpeg",
                    "size": 1843200,
                    "sha256": "b5d4…e91a",
                    "meta": {
                        "taken_at": "2026-11-10T09:52:11+02:00",
                        "lat": 50.4547,
                        "lng": 30.4472
                    },
                    "url": "https://izipolis.com/api/partner/v1/claims/files/0f6e2a7b-8c1d-4e5f-9a0b-1c2d3e4f5a6b"
                }
            ],
            "history": [
                {
                    "id": 1,
                    "type": "status",
                    "status": "submitted",
                    "status_label": "Подано",
                    "message": "Заяву подано через застосунок.",
                    "source": "client",
                    "author_name": null,
                    "files": [],
                    "at": "2026-11-10T10:05:00+02:00"
                }
            ],
            "manager": null,
            "unread": 0,
            "is_open": false,
            "rating": null,
            "policy": {
                "number": "ЕР-219384756",
                "product": "ОСЦПВ"
            },
            "reporter": {
                "name": "Шевченко Олена Петрівна",
                "phone": "+380671112233",
                "email": "[email protected]",
                "ident_code": "3012345678"
            },
            "submitted_at": "2026-11-10T10:05:00+02:00",
            "created_at": "2026-11-10T09:58:00+02:00"
        },
        "rating": 5,
        "comment": "Швидко й без зайвих дзвінків."
    }
}
chat.message.created — Нове повідомлення клієнта в чаті

Нове повідомлення клієнта в чаті щодо полісу.

{
    "event_id": "evt_01JCB8Q3N4X5Y6Z7A8B9C0D1E2",
    "type": "chat.message.created",
    "livemode": true,
    "occurred_at": "2026-11-10T10:05:01+02:00",
    "data": {
        "chat": {
            "id": "4c1a9e2b-7d3f-4b6a-8e5c-2f1d0a9b8c7d",
            "livemode": true,
            "status": "open",
            "policy": {
                "number": "ЕР-219384756",
                "product": "ОСЦПВ",
                "start_date": "2026-03-01",
                "end_date": "2027-02-28",
                "external_id": null
            },
            "client": {
                "name": "Шевченко Олена Петрівна",
                "phone": "+380671112233",
                "email": "[email protected]"
            },
            "unread": 1,
            "last_message_at": "2026-11-10T11:20:00+02:00",
            "created_at": "2026-11-10T11:20:00+02:00"
        },
        "message": {
            "id": 812,
            "sender": "client",
            "author_name": null,
            "text": "Чи покриває мій поліс пошкодження скла?",
            "files": [],
            "external_id": null,
            "created_at": "2026-11-10T11:20:00+02:00"
        }
    }
}
inspection.completed — Клієнт завершив фото-огляд

Клієнт завершив фото-огляд стану авто чи житла. Посилання на фото дійсні 14 днів.

{
    "event_id": "evt_01JCB8Q3N4X5Y6Z7A8B9C0D1E2",
    "type": "inspection.completed",
    "livemode": true,
    "occurred_at": "2026-11-10T10:05:01+02:00",
    "data": {
        "inspection": {
            "id": "e7d6c5b4-a392-4180-9f7e-6d5c4b3a2918",
            "livemode": true,
            "kind": "auto",
            "kind_label": "Огляд авто",
            "subject": "AA1234BB",
            "policy_number": "231456789",
            "status": "completed",
            "completed_at": "2026-11-10T12:00:00+02:00",
            "sent_to_insurer": true,
            "files": [
                {
                    "id": "1a2b3c4d-…",
                    "kind": "front",
                    "kind_label": "Спереду (з номерним знаком)",
                    "name": "front.jpg",
                    "mime": "image/jpeg",
                    "size": 1320000,
                    "taken_at": "2026-11-10T11:55:03+02:00",
                    "lat": 50.45,
                    "lng": 30.52,
                    "sha256": "9c1f…",
                    "url": "https://izipolis.com/api/client/inspection-files/1a2b3c4d-…/insurer?expires=…&signature=…"
                }
            ],
            "client": {
                "name": "Коваль Андрій",
                "phone": "+380501234567"
            },
            "created_at": "2026-11-10T11:50:00+02:00"
        }
    }
}

Життєвий цикл заяви

Заяву створює клієнт (submitted), далі статуси встановлює страховик через POST /claims/{id}/status. Кожна зміна — push клієнту.

СтатусНазва для клієнтаКоли використовувати
submittedПоданоКлієнт подав заяву (встановлюється автоматично)
receivedОтримано страховикомЗаяву зареєстровано у вашій системі — передайте case_number
in_reviewНа розглядіСправа в роботі
documents_requiredПотрібні документиПотрібні документи — обов’язково required_files; клієнт додасть їх, ви отримаєте claim.files_added
inspection_scheduledПризначено оглядПризначено огляд — дату й адресу напишіть у message
decisionУхвалено рішенняРішення ухвалено, amount — сума
paidВиплаченоВиплату здійснено — справа закривається, клієнт може оцінити урегулювання
rejectedВідмовленоВідмова — причину вкажіть у message
closedЗакритоЗакрито без виплати (відкликано, дубль тощо)

Файли

У заявах і чатах файли мають url для завантаження з вашим ключем (GET /claims/files/{id}, GET /files/{id}), sha256 для перевірки цілісності й meta з часом і координатами зйомки. Фото оглядів — за підписаними посиланнями, дійсними 14 днів.

Надсилаючи файли клієнту, використовуйте multipart/form-data з полем files[]: jpg, png, webp, heic, pdf, mp4, mov — до 30 МБ у заявах (до 10 файлів) і до 20 МБ у чатах (до 5).

Тестове середовище

З тестовим ключем доступні методи, що імітують клієнта. Кожен створює тестові дані й надсилає ту саму подію, що й справжній клієнт:

МетодЩо відбуваєтьсяПодія
POST /sandbox/claimsКлієнт подає заяву з фото (можна вказати type: oscpv, kasko, property…)claim.submitted
POST /sandbox/claims/{id}/client-messageКлієнт пише в справі (with_file — з фото)claim.message.created
POST /sandbox/claims/{id}/client-documentsКлієнт додає запитані документиclaim.files_added
POST /sandbox/claims/{id}/client-ratingКлієнт оцінює закриту справуclaim.rated
POST /sandbox/chatsКлієнт починає чатchat.message.created
POST /sandbox/chats/{id}/client-messageКлієнт відповідає в чатіchat.message.created
POST /sandbox/inspectionsКлієнт проходить фото-огляд (kind: auto | home)inspection.completed
DELETE /sandbox/dataВидалити всі тестові дані—

Решта методів (статуси, повідомлення, менеджер, файли, журнал вебхуків) працюють однаково в обох режимах. Усе це можна натиснути в тестовій консолі без жодного коду.

Чек-лист перед запуском

  • ☐ Підпис вебхука перевіряється від сирого тіла; запити старші за 5 хвилин відхиляються.
  • ☐ Повторні події з тим самим event_id не створюють дублів справ.
  • ☐ Вебхук відповідає 2xx швидше ніж за 10 секунд, обробка — у фоні.
  • ☐ Після claim.submitted система повертає received з case_number.
  • ☐ Для documents_required передаються required_files.
  • ☐ Відповіді в чаті надсилаються з external_id.
  • ☐ Є резервна синхронізація updated_since на випадок простою вебхука.
  • ☐ Договори: push — обробляєте client.subscribed і надсилаєте зміни; pull — POST /policies/lookup відповідає на порожній список {"results": []} і витримує погоджений ліміт.
  • ☐ Ключі й секрет зберігаються в сховищі секретів, не в коді.
  • ☐ Повідомте менеджеру IZI Polis бойову адресу вебхука (або встановіть її самі PUT /webhook бойовим ключем) і контакти чергового.

Зміни

ВерсіяЩо нового
1.7 · грудень 2026Повідомлення про ДТП від компаній-клієнтів: вебхук corp.claim.reported — номер договору, авто, місце й час, швидкість за GPS-трекером, посилання на відео з реєстратора, контакт. Премодерація повідомлень клієнтам: POST /notifications повертає status: moderation, рішення — вебхук notification.moderated і поля moderation, rejection_reason; схвалений як шаблон текст іде одразу. Попередження про квоту тарифу: вебхук billing.quota_warning (meter, threshold_percent — 80 чи 100, included, used, remaining, on_exceed, billing_url) — раз на поріг і місяць.
1.6 · листопад 2026Запити компаній на страхування: GET /corp-requests, POST /corp-requests/{uuid}/offers, вебхук corp.quote.requested.
1.5 · листопад 2026Корпоративні клієнти: договори юросіб — holder.tax_id приймає ЄДРПОУ (8 цифр); у підписках з'являються компанії з holder_type: legal і ЄДРПОУ в tax_id. Договір потрапляє до автопарку компанії в застосунку.
1.4 · листопад 2026Тарифи й ліміти: GET /me/usage (тариф, використання за місяць, залишки квот і пакетів); POST /notifications може відповісти 402 quota_exceeded, якщо вичерпано ліміт рекламних повідомлень; заголовок X-Quota-Remaining.
1.3 · листопад 2026Повідомлення клієнтам: POST /notifications (push конкретним клієнтам за ref, номером договору, ІПН чи телефоном; до 1000 за раз; ідемпотентність за external_id), GET /notifications/{id}; функція notifications у GET /me.
1.2 · листопад 2026Синхронізація договорів (push: POST /policies/batch, GET /policies/subscriptions; pull — стандарт методів страховика), події client.subscribed і client.unsubscribed, окремі функції інтеграції в GET /me → features.
1.1 · листопад 2026Тестове середовище й ключі ipk_test_…, методи /sandbox, GET /me, налаштування вебхука через API, журнал доставок і повторна відправка, GET /inspections, поле livemode, заголовки X-Event-Id і X-Livemode.
1.0 · листопад 2026Чати з клієнтами, заяви про страхові події, вебхуки з підписом.

Зміни в межах v1 лише доповнюють API: нові поля й події можуть з’являтися — ігноруйте невідомі.