Підключення страховика до IZI Polis
Клієнти, які купили ваші поліси через агентів IZI Polis, користуються застосунком INSUREX. Через Partner API ви показуєте їм ваші договори, отримуєте заяви про страхові події з фото й геолокацією, ведете справу до виплати, відповідаєте в чаті й отримуєте фото-огляди.
Ваші договори в застосунку клієнта: нагадування про продовження, документи, ваші контакти. Push від вас або pull за нашим стандартом.
Подія, місце, час, відповіді за вашим шаблоном, фото з часом і координатами зйомки. Статуси, запит документів, менеджер, сума виплати.
Питання клієнтів щодо конкретного поліса — з файлами, статусом прочитання й захистом від дублів.
Огляд стану авто чи житла перед страхуванням або пролонгацією: ракурси за списком, час і координати кожного фото.
Як працює обмін
Без вебхука можна працювати опитуванням (updated_since), але заяви через застосунок вмикаються лише з налаштованим вебхуком.
Функції інтеграції — кожна вмикається окремо
Не обов’язково будувати все одразу. Почніть з того, що ваша система вже вміє, — решту ввімкнемо, коли будете готові. Поки функцію не ввімкнено, клієнт бачить ваші контакти (гаряча лінія, email, сайт) і звертається напряму.
| Функція | Що потрібно від вас | Що бачить клієнт |
|---|---|---|
| Синхронізація договорів | Push: ключ API + POST /policies/batch. Pull: методи за стандартом. | Ваші договори в списку полісів, нагадування про продовження |
| Чат | Ключ API; вебхук бажаний | Кнопка «Чат зі страховиком» у картці поліса |
| Страхові випадки | Ключ API + вебхук | Заява з фото й геолокацією, статус справи, листування |
| Огляд майна | Ключ API + вебхук | Фото-огляд за підказками; результат надходить вам |
| Повідомлення клієнтам | Ключ API + POST /notifications | Push і запис у «Сповіщеннях» від вашої компанії — лише вашим клієнтам |
Які функції ввімкнено для вашої компанії — GET /me → features. Ввімкнути — через менеджера платформи.
Швидкий старт за 15 хвилин
- Отримайте тестовий ключ
ipk_test_…у вашого менеджера IZI Polis. - Відкрийте тестову консоль і вставте ключ.
- Натисніть «Створити тестовий приймач» — або вкажіть адресу свого сервера (
https://). - Створіть тестову заяву — подія
claim.submittedнадійде на вебхук. - Змініть статус заяви через API й перевірте, що підпис вебхука сходиться у вашому коді.
- Пройдіть чек-лист і отримайте бойовий ключ
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":"Заяву прийнято, менеджер зв’яжеться сьогодні."}'
$api = Http::withToken(env('VIPPOLIS_KEY'))->baseUrl('https://izipolis.com/api/partner/v1');
$claims = $api->get('/claims', ['status' => 'submitted'])->json('data');
foreach ($claims as $claim) {
$caseNumber = $crm->createCase($claim); // ваша система
$api->post("/claims/{$claim['id']}/status", [
'status' => 'received',
'case_number' => $caseNumber,
'insurer_claim_id' => $caseNumber,
])->throw();
}
const api = (path, init = {}) => fetch(`https://izipolis.com/api/partner/v1${path}`, {
...init,
headers: { Authorization: `Bearer ${process.env.VIPPOLIS_KEY}`, 'Content-Type': 'application/json', ...init.headers },
}).then(r => r.json());
const { data } = await api('/claims?status=submitted');
for (const claim of data) {
await api(`/claims/${claim.id}/status`, {
method: 'POST',
body: JSON.stringify({ status: 'received', case_number: await crm.createCase(claim) }),
});
}
Ключі й режими
Кожен запит — із заголовком Authorization: Bearer <ключ>. Ключі видає IZI Polis; повний ключ показується один раз,
у нас зберігається лише його хеш. Новий ключ одразу вимикає попередній.
| Ключ | Режим | Дані | Вебхук |
|---|---|---|---|
ipk_test_… | тестовий | Лише тестові заяви, чати й огляди, створені методами /sandbox | Тестовий (PUT /webhook з тестовим ключем) |
ipk_… | бойовий | Реальні клієнти за вашими полісами | Бойовий |
Режим повертається в заголовку X-Livemode: true|false і полі livemode в об’єктах і подіях. Тестові дані ніколи не потрапляють до клієнтів і в бойовий режим.
Відповіді й помилки
Успіх — {"data": …} (списки ще з meta). Кожна відповідь містить X-Request-Id — вкажіть його, звертаючись до підтримки.
| Код | Що означає | Що робити |
|---|---|---|
| 401 | Ключ невірний або відкликаний | Перевірте ключ і режим |
| 403 | sandbox_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) — ідентифікатор, за яким ви повертаєте його договори. Ми передаємо телефон і,
якщо клієнт підтвердив особу за ІПН, — ІПН. Вашу базу цілком ми не запитуємо й не зберігаємо: договори, для яких немає клієнта застосунку, відкидаються.
Два режими
- Вебхук
client.subscribed(ref,phone,tax_id) — або опитуванняGET /policies/subscriptions?since=…. - Ви одразу надсилаєте договори клієнта:
POST /policies/batch(до 500 за раз). - Далі — при кожній зміні договору: укладення, продовження, розірвання.
Жодних регулярних запитів до вашого сервера.
- Ви реалізуєте
POST /policies/lookup— договори для пачки до 100 клієнтів. - За бажання —
GET /policies/changes?cursor=…: зміни договорів підписаних клієнтів. - Ви видаєте нам токен; менеджер вносить адресу 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-Signature | sha256= + HMAC-SHA256 рядка {X-Timestamp}.{тіло} секретом вебхука |
X-Timestamp | Unix-час відправки — відхиляйте запити, старші за 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);
import crypto from 'node:crypto';
import express from 'express';
app.post('/vippolis/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-Timestamp');
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.VIPPOLIS_WEBHOOK_SECRET)
.update(`${ts}.${req.body}`).digest('hex');
const given = req.get('X-Signature') || '';
const ok = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
const event = JSON.parse(req.body);
queue.add(event); // обробка у фоні, дублі — за event.event_id
res.sendStatus(200);
});
import hmac, hashlib, time, os, json
from flask import request, abort
@app.post("/vippolis/webhook")
def webhook():
body = request.get_data() # bytes, до json.loads
ts = request.headers.get("X-Timestamp", "")
expected = "sha256=" + hmac.new(os.environ["VIPPOLIS_WEBHOOK_SECRET"].encode(),
ts.encode() + b"." + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Signature", "")) or abs(time.time() - int(ts or 0)) > 300:
abort(401)
event = json.loads(body)
enqueue(event) # дублі — за event["event_id"]
return "", 200
var body = await new StreamReader(Request.Body).ReadToEndAsync();
var ts = Request.Headers["X-Timestamp"].ToString();
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{ts}.{body}"));
var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();
var given = Request.Headers["X-Signature"].ToString();
if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(given)))
return Unauthorized();
Події
Кожна подія: 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: нові поля й події можуть з’являтися — ігноруйте невідомі.