Documentație API

REST API OAuth2 pentru asigurători și platforme care consumă sau trimit constatări amiabile.

Getting started

Amiabila expune un REST API stabil, versionat sub /api/v1, autentificat prin OAuth2 client_credentials. Nu e necesar nimic instalat — orice HTTP client funcționează.

  1. Scrie la innovationsdandd@gmail.com ca să primești credențiale sandbox (client_test_* + amiab_test_*).
  2. Schimbă credențialele pe un access token de 1h via POST /api/oauth/token.
  3. Trimiți token-ul ca Bearer în header-ul Authorization la orice endpoint /api/v1.
  4. Când ești gata, promovezi la live — primești client_live_* alături; sandbox-ul rămâne activ.

URL-uri de bază

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

Autentificare (OAuth2)

Pas 1 — schimbi perechea client_id + client_secret pe un 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 ..." }

Pas 2 — folosești token-ul la orice request:

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

Medii — test / live

Fiecare client Amiabila aparține unui mediu. Prefixul spune imediat care:

  • client_test_* + amiab_test_* + amiat_test_* — date sandbox, complet izolate, wipeable oricând.
  • client_live_* + amiab_live_* + amiat_live_* — producție, date reale.

Serverul respinge credențiale mixte (ex. client_test_* cu amiab_live_*). Rapoartele create via un token test nu sunt vizibile via un token live și invers.

Scopes

Fiecare endpoint cere un scope:

  • reports:write — trimitere rapoarte noi
  • reports:read — citire rapoarte (toate, nu doar ale tale)
  • reports:read:own — citire doar rapoarte unde asigurătorul tău apare ca parte
  • reports:attachments:write — upload poze / PDF-uri la rapoarte existente
  • webhooks:read — primire webhook-uri pentru evenimente raport
  • webhooks:manage — rotire webhook_url + webhook_secret
  • persons:read — căutare istorie șofer după IDNP
  • vehicles:read — căutare istorie vehicul după placă

Endpoints

POST/api/v1/reportsscope: reports:write

Creezi un raport nou

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

Listă rapoarte (paginare prin cursor)

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

Detaliu raport + metadata atașamente

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

Upload multipart (imagine sau PDF)

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

Listă atașamente cu URL-uri signed (15 min)

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

Sumar istoric accident pentru un șofer

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

Sumar istoric accident pentru un vehicul

Webhooks

Pentru fiecare eveniment relevant (creare raport, semnare, schimbare status) trimitem un POST la webhook_url-ul tău. Payload-ul e semnat HMAC-SHA256 peste întregul body cu secret-ul tău, în header-ul X-Amiabila-Signature.

Verificarea semnăturii (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))
}

Evenimente

  • report.created — raport nou, status draft
  • report.signed — ambele părți au semnat; PDF-ul oficial e disponibil
  • report.delivered_to_insurance — raportul a fost trimis la asigurător
  • report.disputed — una dintre părți contestă
  • report.status_changed — orice altă schimbare de status

Retry

Dacă răspunzi cu un status non-2xx sau dacă POST-ul expiră (30s), încercăm din nou după 1m / 5m / 15m / 1h / 6h / 24h. După 6 încercări eșuate, delivery e marcat abandoned.

Rate limits

Default: 100 request-uri/minut. Cu quota zilnică/lunară opțională. Depășire = HTTP 429 cu:

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

Erori

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

request_id e în header-ul X-Request-Id și util când contactezi suportul.

Suport

Pentru întrebări tehnice: innovationsdandd@gmail.com. Răspuns garantat în 1 zi lucrătoare.

Status platformă: /status