API Reference

API-ul Avizo expune endpoint-uri REST pentru integrarea cu sistemele tale (CI, ERP, automatizări custom).

Autentificare

Generează o cheie din Setări → API keys (necesită Pro sau Fleet).

curl -H "Authorization: Bearer avizo_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://avizo.ro/api/v1/items

Rate limit

• Pro: 1000 request-uri / oră / cheie
• Fleet: 5000 request-uri / oră / cheie

Headere de răspuns:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1709212800

Endpoint-uri

GET /api/v1/items

Listează documentele active.

Parametri query:

• category (slug) — filtrează după categorie
• expiring_within_days (number) — filtrează cele care expiră în ≤ N zile
• archived (true|false) — vezi documente arhivate

Răspuns:

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "RCA Dacia Logan",
        "categoryId": "vehicle_rca",
        "entityName": "B-100-XYZ",
        "expiresAt": "2026-08-15T00:00:00Z",
        "category": { "id": "vehicle_rca", "name": "RCA", "slug": "vehicle_rca" }
      }
    ],
    "total": 12,
    "filtered": 5
  }
}

POST /api/v1/items

Creează document (necesită cookie session, nu Bearer — în Sprint B vom expune și prin Bearer).

DELETE /api/v1/items/:id

Arhivează document.

Format eroare

{
  "ok": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Prea multe request-uri pentru această cheie",
    "details": { ... }
  }
}

Coduri eroare

| Code | HTTP | Sens | |---|---|---| | UNAUTHENTICATED | 401 | Header Bearer lipsă sau cookie session expirat | | INVALID_API_KEY | 401 | Cheie inexistentă sau revocată | | PLAN_GATE | 403 | Featurea necesită plan superior | | RATE_LIMIT_EXCEEDED | 429 | Depășește 1000/5000 req/oră | | VALIDATION_ERROR | 400 | Body invalid (vezi details pentru câmpuri) |

Versionare

Endpoint-urile sunt sub /api/v1/. Schimbări breaking → /api/v2/ cu deprecation period 90 zile pe v1.

Roadmap (Sprint C)

• OpenAPI spec auto-generat
• Postman collection downloadabilă
• Bearer auth pe toate mutations (POST/PUT/DELETE)
• Scope granular (items:read, items:write, team:write)