Legacy Agency API → Agency V2 Migration Guide
Use this guide when moving an OTA, GDS, Reslynx, or Fiche Client integration from the previous /api/client/add payload or the temporary /api/oag/* compatibility surface to the current Agency V2 contract.
Terminology: “Legacy OAGAPI” on this page means the old Reslynx/Fiche Client application API. It is separate from the configured OAG flight-information provider and the OAG webhook.
Current target
Agency V2
/api/v2/agency/*
CURRENT
Authentication
Bearer API key
Authorization: Bearer <api_key>
Do not send the legacy ClientId in V2 requests.
Interactive contract
Agency API Reference
Open the current OpenAPI documentation
Request and response schemas are generated from the running routes.
1. Endpoint migration
| Previous endpoint | Current endpoint | Required change |
|---|---|---|
| POST /api/client/add | POST /api/client/add or POST /api/v2/agency/book | Existing Reslynx/Formulaire clients keep the VER-JSONAPI path and payload. New partners should use Agency V2 snake_case with a Bearer API key. |
| POST /api/oag/postjson | POST /api/v2/agency/book | The compatibility endpoint still writes data but is deprecated. Move authentication, field names, date formats, and response handling to V2. |
| POST /api/oag/addpax | POST /api/v2/agency/book | Use a stable external_id for create/update behavior instead of a legacy passenger-index workflow. |
| GET /api/oag/RegistrationFicheClient GET /api/oag/NotificationFicheClient | GET /api/v2/agency/bookings/{trip_id} | The old FNB calls now return empty arrays. Read the stored booking and its current normalized flight status from Agency V2. |
| POST /api/oag/updatestatut POST /api/oag/modifieragence POST /api/oag/StatutDossierUpdate | No external write replacement | These compatibility calls are no-ops. Booking updates use POST /api/v2/agency/book with the same external_id; claim and back-office status changes remain internal workflows. |
2. Authentication migration
| Surface | Credentials | Audience |
|---|---|---|
| AGENCY V2 | Authorization: Bearer <api_key> | Current external travel-agency integrations. |
| LEGACY COMPATIBILITY | X-ClientId: <client_id>X-ApiKey: <api_key>The aliases ClientId and ApiKey are also accepted. | Only the seven compatibility paths listed in section 5. |
| STAFF ONLY | Microsoft Entra staff JWT | All other current /api/oag/* management and reporting routes. They are not partner endpoints. |
3. Booking payload field mapping
| Legacy field | Agency V2 field | Conversion |
|---|---|---|
| locator | locator | Still required. Maximum 50 characters. |
| No equivalent | external_id | Required non-empty string, maximum 100 characters. Keep one stable agency reference for corrections or updates. |
| pax[].firstname / surname | passengers[].first_name / last_name | Both names are required for every supplied passenger. |
| Passenger type | passengers[].passenger_type | Required adult or minor. Infant/baby is not supported; minors never create user accounts. phone_type is not a V2 field. |
| Ticket number | flights[].ticket_number | Optional ticket number for each flight segment. |
| pax[].dob | passengers[].date_of_birth | Convert YYYYMMDD to YYYY-MM-DD. |
| pax[].cellphone | passengers[].phone_number | The V2 field accepts the agency-provided phone format. |
| pax[].email | passengers[].email | Every adult requires an email; minors do not. A complete booking requires an adult, and the first adult becomes the voyage owner. |
| segments[].carrier | flights[].iata_code | Send the IATA code if the flight number lacks a carrier prefix. The server resolves the airline name; do not send airline. |
| segments[].fltnum | flights[].flight_number | Required string, maximum 20 characters. |
| segments[].gateway / dest | flights[].departure_airport / arrival_airport | Send airport IATA codes. Validated provider data may correct them. |
| segments[].depdate | flights[].flight_date | Convert YYYYMMDD to YYYY-MM-DD. |
| segments[].deptime | flights[].departure_time | Convert HHmm to HH:mm or HH:mm:ss. |
| agent.firstname / name / email | travel_agent.first_name / last_name / email | The whole travel_agent object is optional; all three fields are required when it is supplied. |
4. Booking outcomes and retry rules
| Situation | HTTP | Stored result and client action |
|---|---|---|
| Both passengers and flights empty | 400 | The attributable submission attempt is retained, but no booking record is created. Correct the payload and resend the same external_id. |
| Passengers only or flights only | 201 / 200 | Accepted as an incomplete booking record. The normalized passengers and flights in the response remain empty until a complete resubmission succeeds. |
| Passengers and flights with a valid owner email and all required fields | 201 / 200 | Creates or updates normalized voyage, passenger, flight, and optional travel-agent data. |
| Adult passenger without email | 400 | The submission is retained. Add the booking-owner email and resend the same external_id. |
| Flight identity is unknown to an external provider | 201 / 200 | Agency APIs do not query OAG, AeroDataBox, or another provider before persistence. The travel agency is responsible for confirming that each flight exists. |
| Missing departure airport, arrival airport or departure time | 400 | Supply all required flight details. Skipping the external existence lookup does not waive these schema requirements. |
| Update after any stored flight has departed | 400 | The update is rejected and retained for operations review. |
| Update when the booking already has a claim | 409 | The update is rejected to protect the claim snapshot. |
Error handling: authenticated, parseable Agency V2 submissions include
error.external_id, error.submission_id, and error.persisted=true when the failed attempt was retained. Malformed JSON or a request that cannot be attributed to an authenticated agency may return persisted=false. Do not generate a new external_id merely to retry a correction.5. Legacy external compatibility paths
These routes remain mounted so existing integrations can transition without an immediate cutover. They keep the legacy X-ClientId + X-ApiKey authentication contract.
| Path | Current behavior | Migration target |
|---|---|---|
| GET /api/oag/RegistrationFicheClient | COMPATIBILITY Returns an empty array; FNB registration is disconnected. | GET /api/v2/agency/bookings/{trip_id} |
| GET /api/oag/NotificationFicheClient | COMPATIBILITY Returns an empty array; the legacy notification query is disconnected. | GET /api/v2/agency/bookings/{trip_id} |
| POST /api/oag/postjson | COMPATIBILITY Persists a legacy booking when the first passenger email already belongs to a user. | POST /api/v2/agency/book |
| POST /api/oag/updatestatut | COMPATIBILITY Static success response; no database write. | No external replacement. |
| POST /api/oag/modifieragence | COMPATIBILITY Static success response; no database write. | No external replacement. |
| POST /api/oag/StatutDossierUpdate | COMPATIBILITY Static success response; no database write. | No external replacement. |
| POST /api/oag/addpax | COMPATIBILITY Creates voyage, passenger, and optional flight data using legacy fields. | POST /api/v2/agency/book |
6. Removed legacy paths
| Legacy path | Runtime status | Current alternative |
|---|---|---|
| POST /api/oag/SendSMSFicheClient POST /api/oag/SaveLogSMS GET /api/oag/GetLogSMSByCellphone GET /api/oag/GetLogSMSByBagageAndEmbarquement GET /api/oag/GetRepondPaxForExcel GET /api/oag/GetRecuWelcomeForExcel | REMOVED (404) | No direct external Agency V2 equivalent. Product notifications are managed by the current notification workflows. |
| GET /api/oag/file GET /api/oag/file/download DELETE /api/oag/file/delete POST /api/oag/file/upload | REMOVED (404) | Authenticated mobile users upload profile pictures and claim evidence through the dedicated Mobile API endpoints. |
7. Staff-only legacy routes
Remaining /api/oag/* passenger, segment, note, report, message, and URL-configuration routes are the old back-office API and should be retired. They require a staff JWT and are not a travel-agency contract. Do not add new integrations against them.
Cutover checklist
- Obtain the Agency V2 API key and switch to the Authorization Bearer header.
- Generate and persist one stable external_id reference per agency booking.
- Convert legacy names, dates, times, passengers, flights, and travel-agent fields.
- Handle accepted incomplete records separately from normalized bookings.
- Implement the 400 / 409 / 422 retry rules above.
- Verify create, correction, duplicate external_id, and provider-outage scenarios in the target environment.