# Gateway Bisku OTA Bus Partner API

OTA adalah singkatan dari Online Travel Agent. Dokumen ini menjelaskan cara menggunakan layanan OTA Bus Gateway Bisku. Swagger tersedia di `/docs/reference`, sedangkan halaman `/docs` berisi panduan integrasi dan alur penggunaan endpoint.

## Akses Service

- Base URL lokal: `http://localhost:8084`
- Dokumentasi partner: `GET /docs`
- Swagger UI: `GET /docs/reference`
- OpenAPI YAML: `GET /docs/openapi.yaml`

Semua endpoint di bawah `/v1/ota` membutuhkan header:

```http
X-API-Key: <partner-api-key>
Content-Type: application/json
```

## Alur Integrasi

1. Ambil titik keberangkatan melalui `GET /v1/ota/points/origins`.
2. Ambil titik tujuan melalui `GET /v1/ota/points/destinations?origin_point_id=...`.
3. Cari jadwal perjalanan melalui `POST /v1/ota/schedule/search`.
4. Lanjutkan proses ke pemilihan kursi, booking tiket, dan konfirmasi pembayaran sesuai kebutuhan transaksi.
5. Jika diperlukan, ambil ketersediaan kursi melalui `POST /v1/ota/seats/search`.
6. Buat booking tiket melalui `POST /v1/ota/bookings`.
7. Kirim konfirmasi pembayaran melalui `POST /v1/ota/payments`.

## Contoh Points

```json
{
  "data": [
    {
      "point_id": "04daa442-4fe4-45ba-a63f-7eeff417aee7",
      "point_code": "OTA-456A6910",
      "point_name": "MRT Senayan",
      "point_detail": "Jakarta Pusat, DKI Jakarta, Indonesia",
      "point_address": "Senayan Jakarta Selatan",
      "point_lat": "-6.2229",
      "point_lng": "106.8006"
    }
  ],
  "meta": {
    "pagination": false,
    "total": 1
  }
}
```

## Endpoint Utama

| Method | Endpoint | Fungsi |
| --- | --- | --- |
| GET | `/v1/ota/points/origins` | Menampilkan titik keberangkatan yang tersedia untuk akun API. |
| GET | `/v1/ota/points/destinations` | Menampilkan titik tujuan berdasarkan titik keberangkatan. |
| POST | `/v1/ota/schedule/search` | Mencari jadwal perjalanan. |
| POST | `/v1/ota/seats/search` | Mengambil peta atau ketersediaan kursi. |
| POST | `/v1/ota/bookings` | Membuat booking tiket. |
| POST | `/v1/ota/payments` | Mengirim konfirmasi pembayaran. |

## Contoh Payment

```json
{
  "booking_reference": "BKG-20261015-0001",
  "payment_reference": "PAY-20261015-0001",
  "amount": 510000,
  "currency": "IDR",
  "paid_at": "2026-10-15T10:15:00+07:00",
  "payment_method": "bank_transfer",
  "attributes": {
    "traject_id": 818
  }
}
```

## Attributes

`attributes` digunakan untuk membawa data tambahan dari response sebelumnya yang mungkin dibutuhkan pada langkah berikutnya, misalnya `traject_id`, `bus_id`, atau data operasional lain. Kirim atribut sesuai kebutuhan endpoint yang digunakan.

Contoh:

```json
{
  "schedule_id": "ofr_82ec263ab6dc24263f42df2e",
  "departure_date": "2026-10-15",
  "attributes": {
    "traject_id": 818,
    "bus_id": 5091
  }
}
```

## Error Umum

| HTTP | Code | Keterangan |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Request tidak valid atau field wajib belum lengkap. |
| 401 | `UNAUTHORIZED` | API key tidak valid atau sudah expired. |
| 503 | `SERVICE_UNAVAILABLE` | Layanan sedang tidak tersedia sementara. Silakan coba kembali beberapa saat lagi. |
| 500 | `INTERNAL_ERROR` | Terjadi kesalahan pada layanan. Silakan coba kembali atau hubungi tim support jika masalah berlanjut. |