fm_be/docs/API_GUIDE.md

API Guide STEP 1 & STEP 2

Dokumentasi ringkas untuk endpoint yang paling sering dipakai di backend ini.

Helicopter APIs

1. Create helicopter

• POST /api/v1/helicopters/create
• Fungsi: membuat data helicopter baru.
• Cara pakai: kirim payload create helicopter sesuai schema di Swagger.

2. Update helicopter

• PATCH /api/v1/helicopters/update/{id}
• Fungsi: update sebagian field helicopter berdasarkan id.
• Cara pakai: kirim field yang ingin diubah saja.

3. Delete helicopter

• DELETE /api/v1/helicopters/delete/{id}
• Fungsi: soft delete helicopter.
• Cara pakai: kirim id helicopter di path.

4. Generate next report number

• POST /api/v1/helicopters/{id}/reports/next-number
• Fungsi: generate nomor report berikutnya dengan format <identifier>-NNNN.
• Cara pakai: kirim id helicopter di path.

5. Get helicopter by ID

• GET /api/v1/helicopters/get/{id}
• Fungsi: ambil detail helicopter berdasarkan id.
• Cara pakai: kirim id helicopter di path.

6. Get all helicopters

• GET /api/v1/helicopters/get-all
• Fungsi: list helicopter dengan filter, sort, dan pagination.
• Cara pakai:
  • search atau filter[search]
  • sort
  • page[number], page[size]
  • page, size, limit

7. Get all helicopters (datatable)

• GET /api/v1/helicopters/get-all/dt
• Fungsi: list helicopter untuk datatable.
• Cara pakai: gunakan parameter pagination datatable yang didukung backend.

Bases APIs

1. Create base

• POST /api/v1/bases/create
• Fungsi: membuat base baru.
• Cara pakai: kirim payload base create sesuai Swagger.

2. Update base

• PATCH /api/v1/bases/update/{uuid}
• Fungsi: update sebagian field base.
• Cara pakai: kirim uuid base di path, lalu field yang ingin diubah.

3. Delete base

• DELETE /api/v1/bases/delete/{uuid}
• Fungsi: soft delete base.
• Cara pakai: kirim uuid base di path.

4. Get base by ID

• GET /api/v1/bases/get/{uuid}
• Fungsi: ambil detail base.
• Cara pakai: kirim uuid base di path.

5. Get all bases

• GET /api/v1/bases/get-all
• Fungsi: list base dengan filter, sort, dan pagination.
• Cara pakai:
  • search atau filter[search]
  • sort
  • page[number], page[size]
  • page, size, limit

6. Get all bases (datatable)

• GET /api/v1/bases/get-all/dt
• Fungsi: list base untuk datatable.
• Cara pakai: gunakan parameter pagination datatable yang didukung backend.

Contact APIs

1. Create contact

• POST /api/v1/contacts/create
• Fungsi: membuat user contact baru beserta profile role-specific.
• Cara pakai:
  • data.type harus contact_create
  • role_ids menentukan role
  • setiap role yang dipilih harus punya object profile yang sesuai di attributes

2. Update contact

• PATCH /api/v1/contacts/{user_id}
• Fungsi: update contact.
• Cara pakai:
  • data.type harus contact_update
  • bisa update role_id dan role_ids
  • role_ids: [] akan menghapus semua role
  • hanya satu profile role-specific boleh ada di attributes

3. Get contact

• GET /api/v1/contacts/{user_id}
• Fungsi: ambil detail contact.
• Cara pakai: kirim user_id di path.

4. Get all contacts

• GET /api/v1/contacts/get-all
• Fungsi: list contact dengan filter role, pilot category, sort, dan pagination.
• Cara pakai:
  • filter role / pilot category sesuai kebutuhan frontend
  • sort field seperti name, email, is_active, created_at, updated_at, dan lainnya

5. Get all contacts (datatable)

• GET /api/v1/contacts/get-all/dt
• Fungsi: list contact untuk datatable.
• Cara pakai: gunakan parameter pagination datatable yang didukung backend.

6. Delete contact

• DELETE /api/v1/contacts/{user_id}
• Fungsi: soft delete contact.
• Cara pakai: kirim user_id di path.

7. Update contact active status

• PATCH /api/v1/contacts/{user_id}/status
• Fungsi: update status aktif contact.
• Cara pakai: kirim user_id di path dan payload status.

8. Update contact role

• PATCH /api/v1/contacts/{user_id}/role
• Fungsi: update role contact.
• Cara pakai: kirim user_id di path dan payload role baru.

9. Update pilot category

• PATCH /api/v1/contacts/{user_id}/pilot-category
• Fungsi: update pilot category.
• Cara pakai: kirim user_id di path dan payload kategori.

10. Update contact license fields

• PATCH /api/v1/contacts/{user_id}/license
• Fungsi: update data lisensi contact.
• Cara pakai: kirim user_id di path dan payload field lisensi.

11. Update chief flags

• PATCH /api/v1/contacts/{user_id}/chief-flags
• Fungsi: update flag chief.
• Cara pakai: kirim user_id di path dan payload flag yang ingin diubah.

12. Update responsible complaints flag

• PATCH /api/v1/contacts/{user_id}/responsible-complaints
• Fungsi: update flag responsible complaints.
• Cara pakai: kirim user_id di path dan payload flag yang ingin diubah.

13. Bulk update contacts status

• POST /api/v1/contacts/bulk-update
• Fungsi: update status banyak contact sekaligus.
• Cara pakai: kirim daftar contact yang ingin diupdate.

Flights API

Get all flights

• GET /api/v1/flights/get-all
• Fungsi: list flight dengan pagination, filter, sort, dan step workflow.
• Cara pakai:
  • search atau filter[search]
  • date atau filter[date] untuk filter tanggal flight
  • sort
  • page[number], page[size]
  • page, size, limit

Contoh response

{
  "data": [
    {
      "type": "flight",
      "id": "019e8afa-e602-716c-8d2a-b6b11a89caf0",
      "attributes": {
        "status": "",
        "mission_code": "M-060326-001",
        "date": "2026-06-03",
        "total_draft": 2,
        "takeover": {
          "id": "019e8afa-e5fe-7de0-ac5d-fb5ab95896b0",
          "daily_inspection": {
            "name": "test test",
            "short_name": "",
            "date": "05.06.2026",
            "utc_time": "05:03"
          }
        },
        "steps": [
          {
            "phase": "takeover",
            "position": "takeover",
            "step": 1,
            "complete": true,
            "id": "019e8afa-e5fe-7de0-ac5d-fb5ab95896b0",
            "status": "completed",
            "completed_at": "2026-06-03T00:55:59Z",
            "completed_by": "test test"
          },
          {
            "phase": "mission",
            "step": 2,
            "complete": true,
            "status": "assigned",
            "mission_type": [
              {
                "type": "CAT",
                "draft": 2,
                "completed": 0
              }
            ],
            "completed_at": "",
            "completed_by": ""
          }
        ],
        "draft": [
          {
            "type": "CAT",
            "items": [
              {
                "id": "019e9640-f7af-7940-80e8-1e9a83013afb",
                "type": "CAT",
                "status": "draft",
                "flight_data_id": "019e9640-f7b0-7787-b43c-0b395ff2792a"
              },
              {
                "id": "019e9640-f8cf-72b1-84dc-b50c1a3c2cc6",
                "type": "CAT",
                "status": "draft",
                "flight_data_id": "019e9640-f8d0-7ea2-b250-a7e31bfba95f"
              }
            ]
          }
        ],
        "created_at": "2026-06-03T00:55:59Z",
        "created_by": "test test",
        "updated_at": "2026-06-03T00:55:59Z",
        "updated_by": "test test"
      }
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total": 3
  }
}

Takeover APIs

1. Create takeover

• POST /api/v1/takeovers/create
• Fungsi: membuat takeover secara atomik.
• Cara pakai:
  • base_id, duty_date, helicopter_id
  • inspection
  • roster_detail
  • notes
• Catatan:
  • shift_date dan shift_time sudah tidak dipakai lagi di takeover request.
  • shift diambil dari base.

2. Update takeover

• PATCH /api/v1/takeovers/update/{id}
• Fungsi: replace takeover berdasarkan flight UUID.
• Cara pakai:
  • kirim id takeover / flight di path
  • body mengikuti format takeover update yang sama dengan create

3. Get takeover by ID

• GET /api/v1/takeovers/get/{id}
• Fungsi: ambil takeover detail.
• Cara pakai: kirim id di path.

4. Get all takeovers

• GET /api/v1/takeovers/get-all
• Fungsi: list takeover composite yang dibangun dari flight, reserve AC, duty roster, dan inspection.
• Cara pakai: tidak ada parameter wajib.

5. Delete takeover

• DELETE /api/v1/takeovers/delete/{id}
• Fungsi: delete takeover berdasarkan flight UUID.
• Cara pakai: kirim id di path.

Payload create/update takeover

{
  "data": {
    "attributes": {
      "base_id": "string",
      "duty_date": "string",
      "helicopter_id": "string",
      "inspection": {
        "before": {
          "file_checklist": [
            {
              "helicopter_file_id": "019d7000-aaaa-7bbb-8ccc-111111111111",
              "is_done": true
            }
          ],
          "fuel_added_amount": 0,
          "fuel_amount": 0,
          "fuel_unit": "string",
          "hydraulic_lh_checked": true,
          "hydraulic_rh_checked": true,
          "note": "string",
          "oil_engine_nr1_checked": true,
          "oil_engine_nr2_checked": true,
          "oil_transmission_igb_checked": true,
          "oil_transmission_mgb_checked": true,
          "oil_transmission_tgb_checked": true
        },
        "inspection_date": "2026-04-15",
        "prepare": {
          "file_checklist": [
            {
              "helicopter_file_id": "019d7000-aaaa-7bbb-8ccc-111111111111",
              "is_done": true
            }
          ],
          "notam_briefing": true,
          "operational_flight_plan": true,
          "weather_briefing": true
        }
      },
      "notes": "string",
      "roster_detail": {
        "doctor": [
          {
            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
          }
        ],
        "helper": [
          {
            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
          }
        ],
        "other_person": [
          {
            "email": "guest@example.com",
            "mobile_phone": "+43-1234",
            "name": "Guest Person"
          }
        ],
        "pilot": [
          {
            "co_pilot": true,
            "crew_type": "main",
            "examiner": true,
            "flight_instructor": true,
            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d",
            "line_checker": true,
            "supervisor": true
          }
        ],
        "rescuer": [
          {
            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
          }
        ]
      }
    },
    "type": "takeover_create"
  }
}

Response takeover detail

{
  "data": {
    "type": "takeover",
    "id": "019e8713-aa19-7fb7-a510-a0332dc69697",
    "attributes": {
      "id": "019e8713-aa19-7fb7-a510-a0332dc69697",
      "flight_id": "019e8afa-e602-716c-8d2a-b6b11a89caf0",
      "reserve_ac_id": "019e8713-aa19-7fb7-a510-a0332dc69698",
      "flight_inspection_id": "019e8713-aa19-7fb7-a510-a0332dc69699",
      "shift_start": "05:00:00",
      "shift_end": "13:00:00",
      "base_id": "019d61db-53c6-7280-87ec-e65f205c6d3b",
      "base": {
        "id": "019d61db-53c6-7280-87ec-e65f205c6d3b",
        "name": "Base Name"
      },
      "duty_date": "2026-06-03",
      "helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
      "helicopter": {
        "id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
        "identifier": "D-HYAR",
        "designation": "AIRBUS H145",
        "type": "H145",
        "aog": false,
        "is_active": true
      },
      "notes": "string",
      "roster_detail": {
        "pilot": [],
        "doctor": [],
        "rescuer": [],
        "helper": [],
        "other_person": []
      },
      "inspection": {
        "before": {},
        "prepare": {},
        "inspection_date": "2026-06-03"
      }
    }
  }
}

Notes

• takeover request tidak memakai shift_date dan shift_time.
• flights/get-all menampilkan step takeover, mission, dan after_flight_inspection kalau record after inspection sudah ada.
• mission.step ditampilkan sebagai step: 2.
• complete selalu ada di response step; kalau belum selesai nilainya false.
• mission_type.completed masih angka, karena itu hitungan draft/completed, bukan boolean.