Документация API

REST API OAuth2 для страховых и платформ, потребляющих или отправляющих европротоколы.

Начало работы

Amiabila предоставляет стабильный REST API с версионированием под /api/v1, аутентифицированный через OAuth2 client_credentials. Ничего устанавливать не нужно — подходит любой HTTP-клиент.

  1. Напишите на innovationsdandd@gmail.com чтобы получить учётные данные sandbox (client_test_* + amiab_test_*).
  2. Обменяйте учётные данные на access token на 1ч через POST /api/oauth/token.
  3. Отправляйте токен как Bearer в заголовке Authorization на любой endpoint /api/v1.
  4. Когда готовы, переходите в live — получаете client_live_* параллельно; sandbox остаётся активным.

Базовые URL

https://amiabila.md/api/oauth/token   # schimb de credențiale pe token
https://amiabila.md/api/v1/...         # endpoint-uri resource

Аутентификация (OAuth2)

Шаг 1 — обменяйте пару client_id + client_secret на access token:

curl -X POST https://amiabila.md/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=client_test_xxx" \
  -d "client_secret=amiab_test_yyy"

# → { "access_token": "amiat_test_...", "token_type": "Bearer",
#      "expires_in": 3600, "scope": "reports:read reports:write ..." }

Шаг 2 — используйте токен в запросах:

curl https://amiabila.md/api/v1/reports \
  -H "Authorization: Bearer amiat_test_..."

Среды — test / live

Каждый клиент Amiabila принадлежит одной среде. Префикс сразу показывает какой:

  • client_test_* + amiab_test_* + amiat_test_* — данные sandbox, полностью изолированные, удаляются в любой момент.
  • client_live_* + amiab_live_* + amiat_live_* — production, реальные данные.

Сервер отклоняет смешанные учётные данные (например, client_test_* с amiab_live_*). Отчёты, созданные через тестовый токен, не видны через live токен и наоборот.

Scopes

Каждый endpoint требует scope:

  • reports:write — создание отчётов
  • reports:read — чтение всех отчётов
  • reports:read:own — чтение только отчётов, где ваш страховщик — сторона
  • reports:attachments:write — загрузка фото / PDF к существующим отчётам
  • webhooks:read — получение webhook-ов о событиях
  • webhooks:manage — ротация webhook_url + webhook_secret
  • persons:read — поиск истории водителя по IDNP
  • vehicles:read — поиск истории автомобиля по номеру

Endpoints

POST/api/v1/reportsscope: reports:write

Создание нового отчёта

GET/api/v1/reports?from=&to=&status=&limit=scope: reports:read / reports:read:own

Список отчётов (пагинация через курсор)

GET/api/v1/reports/:idscope: reports:read / reports:read:own

Детали отчёта + метаданные вложений

POST/api/v1/reports/:id/attachmentsscope: reports:attachments:write

Multipart загрузка (изображение или PDF)

GET/api/v1/reports/:id/attachmentsscope: reports:read / reports:read:own

Список вложений с подписанными URL (15 мин)

GET/api/v1/persons/:idnpscope: persons:read

Сводка истории ДТП для водителя

GET/api/v1/vehicles/:idnvscope: vehicles:read

Сводка истории ДТП для автомобиля

Webhooks

На каждое значимое событие (создание отчёта, подписание, смена статуса) мы отправляем POST на ваш webhook_url. Payload подписан HMAC-SHA256 по всему телу с вашим секретом в заголовке X-Amiabila-Signature.

Проверка подписи (Node.js)

import crypto from 'crypto'

function verify(body, signatureHeader, secret) {
  const [algo, sig] = signatureHeader.split('=')
  if (algo !== 'sha256') return false
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}

События

  • report.created — новый отчёт, статус draft
  • report.signed — обе стороны подписали; доступен официальный PDF
  • report.delivered_to_insurance — отчёт отправлен страховщику
  • report.disputed — одна из сторон оспаривает
  • report.status_changed — любое другое изменение статуса

Retry

Если вы отвечаете non-2xx или если POST истекает (30с), повторяем через 1м / 5м / 15м / 1ч / 6ч / 24ч. После 6 неудачных попыток доставка помечается как abandoned.

Rate limits

По умолчанию: 100 запросов/мин. Опционально — дневная/месячная квота. Превышение — HTTP 429 с:

Retry-After: 60
X-RateLimit-Limit: 100
X-Quota-Daily-Used: <n>

Ошибки

{
  "error": "invalid_token",          // or: insufficient_scope, rate_limited, …
  "error_description": "…",
  "request_id": "8107bffe00c561ee"
}

request_id в заголовке X-Request-Id полезен при обращении в поддержку.

Поддержка

По техническим вопросам: innovationsdandd@gmail.com. Ответ гарантирован в течение 1 рабочего дня.

Статус платформы: /status