RoviBoot

Flux conversație (informativ)

Consumer nou

1. Autentificare

Toate request-urile catre API trebuie sa contina un header de autorizare:

Authorization: Bearer <API_TOKEN>

Token-ul se genereaza din panoul de administrare RoviBoot, sectiunea API Consumers. Fiecare token este legat de un business specific.

2. Endpoint principal

Base URL: https://api.roviboot.ro (se configureaza la deploy)

3. Payload — Exemplu complet (POST /api/v1/commerce/events)

{
  "api_version": "2026-04-27",
  "event": {
    "id": "evt_20260427_000001",
    "type": "order.paid",
    "subtype": "rovinieta.issued",
    "occurred_at": "2026-04-27T09:30:00+03:00",
    "idempotency_key": "RV-123456"
  },
  "business": {
    "id": "roviniete_ro"
  },
  "customer": {
    "phone": "+40722123456",
    "phone_country": "RO",
    "first_name": "Ion",
    "last_name": "Popescu",
    "email": "ion.popescu@example.ro"
  },
  "order": {
    "external_order_id": "RV-123456",
    "status": "paid",
    "currency": "RON",
    "total_amount": 96.00
  },
  "line_items": [
    {
      "id": "line_1",
      "product_vertical": "road_tax",
      "product_code": "rovinieta_ro_A_12_months",
      "title": "Rovinieta Romania categoria A - 12 luni",
      "attributes": {
        "registration_country": "RO",
        "registration_number": "B123ABC",
        "vin": "WVWZZZ1KZ6W000001",
        "vehicle_category": "A",
        "validity_period": "12_months",
        "valid_from": "2026-04-28",
        "valid_until": "2027-04-27"
      }
    }
  ],
  "documents": [
    {
      "id": "doc_1",
      "type": "issued_certificate",
      "format": "pdf",
      "filename": "rovinieta_B123ABC_RV-123456.pdf",
      "url": "https://roviniete.ro/secure/documents/rv-123456.pdf?token=temporary-token"
    }
  ],
  "notification": {
    "channel": "whatsapp",
    "template_id": "rovinieta_confirmare_comanda",
    "language": "ro"
  },
  "callback": {
    "status_callback_url": "https://roviniete.ro/api/roviboot/status"
  }
}

4. Campuri obligatorii

5. Campuri optionale

6. Raspunsuri API

Succes (202 Accepted)

{
  "status": "accepted",
  "event_id": "evt_20260427_000001",
  "message": "Event received and processing started"
}

Duplicat (200 OK)

{
  "status": "duplicate",
  "event_id": "evt_20260427_000001",
  "message": "Event already processed",
  "deliveries": [...]
}

Erori

7. Verificare status livrare

Dupa trimiterea unui eveniment, partenerul poate verifica statusul livrarii:

GET /api/v1/commerce/events/{event_id}
Authorization: Bearer <API_TOKEN>

Raspuns:

{
  "event": {
    "id": "evt_20260427_000001",
    "type": "order.paid",
    "status": "completed",
    "created_at": "2026-04-27T09:30:01Z"
  },
  "deliveries": [
    {
      "type": "whatsapp_template",
      "status": "delivered",
      "whatsapp_message_id": "wamid.HBg...",
      "created_at": "2026-04-27T09:30:02Z",
      "updated_at": "2026-04-27T09:30:15Z"
    }
  ]
}

Statusuri posibile pentru delivery: queued → sent → delivered → read (sau failed)

8. Callback automat (optional)

Daca in payload includeti callback.status_callback_url, RoviBoot va trimite automat un POST catre acel URL cand statusul livrarii se schimba:

POST https://roviniete.ro/api/roviboot/status
Content-Type: application/json

{
  "event_type": "commerce.notification.delivered",
  "event_id": "evt_20260427_000001",
  "external_order_id": "RV-123456",
  "delivery_type": "whatsapp_template",
  "status": "delivered",
  "whatsapp_message_id": "wamid.HBg...",
  "occurred_at": "2026-04-27T09:35:14+03:00"
}

Statusuri trimise prin callback: sent, delivered, read, failed

9. Idempotency

API-ul este idempotent pe baza campului event.id. Daca trimiteti acelasi eveniment de mai multe ori, sistemul va returna statusul existent fara a retrimite mesajul WhatsApp.

Acest mecanism protejeaza impotriva trimiterii duplicate in caz de timeout sau retry din partea sistemului partener.

10. Exemplu cURL complet

curl -X POST https://api.roviboot.ro/api/v1/commerce/events \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_version": "2026-04-27",
    "event": {
      "id": "evt_20260427_000001",
      "type": "order.paid",
      "subtype": "rovinieta.issued"
    },
    "business": { "id": "roviniete_ro" },
    "customer": {
      "phone": "+40722123456",
      "first_name": "Ion",
      "last_name": "Popescu"
    },
    "order": {
      "external_order_id": "RV-123456",
      "status": "paid",
      "total_amount": 96.00
    },
    "line_items": [{
      "id": "line_1",
      "product_vertical": "road_tax",
      "product_code": "rovinieta_ro_A_12_months",
      "title": "Rovinieta cat. A 12 luni",
      "attributes": {
        "registration_number": "B123ABC",
        "vehicle_category": "A",
        "valid_from": "2026-04-28",
        "valid_until": "2027-04-27"
      }
    }],
    "documents": [{
      "id": "doc_1",
      "type": "issued_certificate",
      "format": "pdf",
      "filename": "rovinieta_B123ABC.pdf",
      "url": "https://roviniete.ro/docs/rv-123456.pdf?token=xyz"
    }],
    "notification": {
      "channel": "whatsapp",
      "template_id": "rovinieta_confirmare_comanda",
      "language": "ro"
    },
    "callback": {
      "status_callback_url": "https://roviniete.ro/api/roviboot/status"
    }
  }'

11. Note importante

• Template ID — este numele template-ului din Meta WhatsApp Manager (ex: rovinieta_confirmare_comanda), NU ID-ul numeric din URL.
• Document URL — trebuie sa fie un URL public accesibil (sau cu token temporar) de unde RoviBoot poate descarca PDF-ul. URL-ul trebuie sa fie valid cel putin 5 minute dupa trimiterea evenimentului.
• Numar telefon — poate fi in format international (+40722123456) sau local (0722123456). Se normalizeaza automat.
• business.id — trebuie sa corespunda cu business-ul asociat token-ului API. Daca nu corespunde, se returneaza 403.
• Rate limit — maxim 100 request-uri/minut per token.