Passenger Data Correction

Корректировка имени / документа пассажира после OCI до boarding.

Correction flow — для исправления опечатки в имени или обновления документа пассажира после check-in, но до boarding. Дешевле чем full exchange, но имеет ограничения.

Когда использовать:

Сценарий	Решение
Опечатка "Jonh" → "John"	✅ Correction (~1500 KGS)
Старый паспорт → новый паспорт (после renewal)	✅ Correction
Сменил фамилию (брак)	⚠️ Correction если ≤ 3 символа отличия, иначе через support авиакомпании
Заменить полностью другого пассажира	❌ Это новая бронь
Изменить пол	❌ Только через support (требуются легальные документы)
Изменить дату рождения	❌ Требуется approval авиакомпании

Endpoints

Endpoint	Назначение
`POST /{id}/correction/availability`	Preview — что можно изменить + расчёт fee
`POST /{id}/correction/apply`	Применить + списать fee

Окно correction

OCI открыт (T-24h) → coupon=OPEN
     │
     ├─ Correction доступен  ✓
     │  (только пока coupon не COMPLETED+boarded или < 30 мин до вылета)
     │
     ▼
Boarding (T-30m) → coupon=COMPLETED
     │
     ▼
< 30 мин до вылета → Correction ЗАБЛОКИРОВАН
     (обратитесь к агенту в аэропорту)
     │
     ▼
Boarded → Correction ЗАБЛОКИРОВАН (физически на борту)

POST `/{booking_id}/correction/availability`

Preview — проверить что correction возможен и сколько стоит. Не изменяет данные.

curl -X POST \
  -H "X-API-Key: $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "corrections": [
      {
        "passenger_id": "uuid",
        "changes": {
          "first_name": "John",
          "document_number": "AN9876543"
        }
      }
    ]
  }' \
  "https://api.nurcore.kg/api/v1/bookings/$BOOKING_ID/correction/availability"

Request body:

{
  "corrections": [
    {
      "passenger_id": "uuid",
      "changes": {"first_name": "John"}
    }
  ]
}

Поле	Описание
`corrections[]`	Один или несколько patches (1-9, на каждого пассажира свой patch)
`passenger_id`	UUID пассажира из этой брони
`changes`	dict: `{field: new_value}`

Response 200 — allowed:

{
  "allowed": true,
  "total_fee": 3000,
  "currency": "KGS",
  "items": [
    {
      "passenger_id": "uuid",
      "passenger_name": "Jonh Doe",
      "changes": [
        {"field": "first_name", "old": "Jonh", "new": "John", "fee": 1500},
        {"field": "document_number", "old": "AN1234567", "new": "AN9876543", "fee": 1500}
      ],
      "subtotal": 3000
    }
  ],
  "minutes_to_departure": 180
}

Response 200 — blocked:

{
  "allowed": false,
  "blocked_reason": "first_name: слишком сильно отличается от текущего значения (correction для исправления опечатки)",
  "total_fee": 0,
  "currency": "KGS"
}

Errors:

Code	Сценарий
400	Бронь CANCELLED/EXPIRED, пассажир boarded, < 30 мин до вылета
400	Поле в списке RESTRICTED (gender, date_of_birth, passenger_type)
400	passenger_id не принадлежит брони
404	Бронь не найдена

POST `/{booking_id}/correction/apply`

Применить correction + списать fee.

curl -X POST \
  -H "X-API-Key: $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "corrections": [
      {
        "passenger_id": "uuid",
        "changes": {"first_name": "John"}
      }
    ],
    "pay_with_balance": false
  }' \
  "https://api.nurcore.kg/api/v1/bookings/$BOOKING_ID/correction/apply"

Request body: identical to /availability плюс:

Поле	Описание
`pay_with_balance`	true → списать с partner wallet (B2B). false → вернуть `payment_url` для отдельной оплаты

Response 200:

{
  "applied": true,
  "total_fee": 1500,
  "currency": "KGS",
  "payment_required": true,
  "payment_url": "/booking/correction-pay?bid=uuid&amount=1500",
  "applied_changes": [
    {"passenger_id": "uuid", "field": "first_name", "old": "Jonh", "new": "John", "fee": 1500}
  ]
}

Семантика:

applied: true — данные пассажира обновлены в БД немедленно
payment_required — если true, fee ещё не списан. UI редиректит на payment_url для оплаты
payment_required: false — fee автоматически списан (free correction или pay_with_balance)

Важно: correction применяется до payment. Если пассажир не оплатит — fee останется как debt на брони (Sprint 4 feature). Для MVP — оплата на доверии.

Поля и их fee

Field	Fee (KGS)	Constraints
`first_name`	1500	1-50 символов, Levenshtein ≤ 3 vs текущее
`last_name`	1500	1-50 символов, Levenshtein ≤ 3 vs текущее
`middle_name`	0	1-50 символов (если задан)
`document_number`	1500	`[A-Z0-9\-\s]+`
`document_expiry`	1500	ISO 8601, не в прошлом
`document_type`	1500	passport / id_card / birth_certificate / driver_license
`nationality`	0	ISO 3-letter код

Restricted (нельзя через correction):

gender — только через support авиакомпании
date_of_birth — требуется approval авиакомпании (легальные документы)
passenger_type — exchange (adult ↔ child переход)

BCBP reissue после correction

Если у пассажира уже выпущен boarding pass, после correction его нужно перевыпустить. Текущая реализация:

⚠️ Не делается автоматически — агент в аэропорту вручную выпускает новый BP
Sprint 4: интеграция с check-in service для авто-перевыпуска

В UI рекомендуется показать пассажиру предупреждение:

«После изменения данных нужно перевыпустить посадочный талон. Подойдите к стойке регистрации или kiosk».

Примеры use cases

Опечатка в имени

# 1. Preview
curl -X POST .../correction/availability \
  -d '{"corrections":[{"passenger_id":"u1","changes":{"first_name":"John"}}]}'
# → total_fee: 1500

# 2. Apply
curl -X POST .../correction/apply \
  -d '{"corrections":[{"passenger_id":"u1","changes":{"first_name":"John"}}]}'
# → applied: true, payment_required: true, payment_url: ...

Новый паспорт (renewal)

curl -X POST .../correction/apply \
  -d '{
    "corrections": [{
      "passenger_id": "u1",
      "changes": {
        "document_number": "AN9876543",
        "document_expiry": "2036-05-01"
      }
    }]
  }'
# → fee: 1500 (один charge даже за 2 поля document_*)

Бесплатная correction (middle_name + nationality)

curl -X POST .../correction/apply \
  -d '{
    "corrections": [{
      "passenger_id": "u1",
      "changes": {
        "middle_name": "Andreyevich",
        "nationality": "KGZ"
      }
    }]
  }'
# → fee: 0, payment_required: false

Errors

Code	Сценарий
400	Окно correction закрыто (boarded / < 30 мин / cancelled)
400	Validation: недопустимое поле / формат / Levenshtein > 3
400	Нет изменений (changes пустой или равен текущим значениям)
401	Нет auth (требуется API key)
404	Бронь не найдена

Связанные документы

Exchange API — для смены рейса (не correction)
Bookings API — структура passengers

Passenger Data Correction

On this page