fm_be/docs/contacts_module.md

Contacts Module (HEMS)

Endpoint listing

• GET /api/v1/contacts?role=pilot
• GET /api/v1/contacts?role=pilot&pilot_category=freelance
• GET /api/v1/contacts?role=pilot&pilot_category=dry_lease
• GET /api/v1/contacts?role=doctor
• GET /api/v1/contacts?role=air_rescuer
• GET /api/v1/contacts?role=technician
• GET /api/v1/contacts?role=flight_assistant
• GET /api/v1/contacts?role=staff

Sensitive action flow (PIN)

1. Client memanggil endpoint sensitif.
2. API balas 202 dan memberi tahu action PIN yang dibutuhkan.
3. Client verifikasi PIN ke /api/v1/auth/pin/verify.
4. Backend mengembalikan token verifikasi singkat.
5. Client kirim ulang request sensitif dengan header X-PIN-Verification-Token.

Contoh payload

1) Create pilot

{
  "data": {
    "type": "contact_pilot_create",
    "attributes": {
      "role_id": "<ROLE_ID_PILOT>",
      "email": "pilot1@hems.local",
      "username": "pilot1",
      "first_name": "Marco",
      "last_name": "Pilot",
      "mobile_phone": "+62811111111",
      "timezone": "Asia/Jakarta",
      "pilot": {
        "pilot_category": "freelance",
        "short_name": "M. Pilot",
        "license_no": "LIC-P-1001",
        "has_ifr_qualification": true,
        "total_flight_minutes": 12500,
        "location": "Jakarta"
      }
    }
  }
}

2) Update doctor

{
  "data": {
    "type": "contact_doctor_update",
    "attributes": {
      "is_active": true,
      "doctor": {
        "short_name": "dr. Ana",
        "medical_license_no": "DOC-7788",
        "specialization": "Anesthesiology",
        "is_chief_physician": false
      }
    }
  }
}

Rule:

• data.type wajib mengikuti role, mis. contact_pilot_create, contact_air_rescuer_create, contact_staff_update.
• Hanya satu object profile role yang boleh dikirim, dan harus sesuai dengan data.type.

3) PIN verify sebelum aksi sensitif

{
  "data": {
    "type": "auth_pin_verify",
    "attributes": {
      "pin": "123456",
      "action": "31f8bb88-a95f-43be-8fd8-129e1355d6a5"
    }
  }
}

4) Response 202 saat PIN dibutuhkan

{
  "data": {
    "type": "pin_verification_required",
    "attributes": {
      "required": true,
      "action": "31f8bb88-a95f-43be-8fd8-129e1355d6a5",
      "method": "pin",
      "status": 202
    }
  }
}

5) List response ringkas

{
  "data": {
    "type": "contacts",
    "attributes": {
      "items": [
        {
          "id": "0195f43e-5030-7d2a-8b8a-020063f5ab03",
          "role_code": "pilot",
          "role_name": "pilot",
          "pilot_category": "dry_lease",
          "username": "pilot_dl_1",
          "email": "pilot.dl1@hems.local",
          "first_name": "Rama",
          "last_name": "Wijaya",
          "short_name": "R. Wijaya",
          "license_no": "LIC-P-9988",
          "location": "Surabaya",
          "mobile_phone": "+62822222222",
          "is_active": true
        }
      ],
      "meta": {
        "total": 1,
        "limit": 20,
        "offset": 0
      }
    }
  }
}