Référence API

Points d'accès API

FerryGate expose deux protocoles API : REST API (points d'accès HTTP traditionnels) et MCP (Model Context Protocol pour agents IA). Les deux utilisent la même authentification par jeton Bearer et se connectent aux mêmes 35+ opérateurs ferry.

REST API

Authentification

Vous devrez inclure un jeton d'accès dans chaque requête que vous faites à l'API.

Pour créer un jeton d'accès, rendez-vous sur votre Tableau de bord. Lorsque vous créez un jeton d'accès, vous pourrez choisir de lui donner un accès en lecture seule ou en lecture-écriture.

Envoyez votre jeton d'accès dans l'en-tête de requête Authorization en utilisant le schéma d'authentification "Bearer" :

Shell

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Versionnage

Vous pouvez optionnellement envoyer un en-tête x-client-version avec chaque requête pour spécifier quelle version de l'API vous souhaitez utiliser.

Shell

x-client-version: 2

Note :

L'en-tête x-client-version est accepté pour la rétrocompatibilité mais n'est plus requis. Toutes les requêtes utilisent automatiquement la dernière version de l'API.

Types MIME

Toutes les réponses de l'API sont au format JSON avec encodage UTF-8. Un en-tête Accept est requis avec chaque requête :

Shell

Accept: application/json

Tous les corps de requête envoyés à l'API doivent être au format JSON. Un en-tête Content-Type est requis chaque fois que vous envoyez un corps de requête (c'est-à-dire pour les requêtes POST et PUT) :

Shell

Content-Type: application/json

Compression

Nous recommandons d'activer la compression pour les réponses renvoyées par l'API, car elles peuvent être très volumineuses. Pour activer la compression, envoyez un en-tête Accept-Encoding :

Shell

Accept-Encoding: gzip

Vous devrez configurer votre client HTTP pour décompresser les réponses. La plupart des clients disposent de cette fonctionnalité intégrée.

Identifiant de requête

Toutes les réponses contiendront un en-tête x-request-id . La valeur de cet en-tête identifie de manière unique la requête/réponse.

Shell

x-request-id: 5e58ca8b-51eb-4e7c-88bc-32e2bb227b14

Nous vous recommandons de garder une trace de cet en-tête à des fins de débogage. Lors de vos interactions avec l'équipe de support de l'API Ferrygate, fournir cet en-tête permettra à l'équipe de vous apporter un support rapide et personnalisé.

Identifiant de corrélation client

Parfois, vous pouvez vouloir envoyer votre propre identifiant dans les en-têtes afin de pouvoir corréler les requêtes et les réponses envoyées depuis Ferrygate.

Nous fournissons également un en-tête nommé x-client-correlation-id à cet effet.

Toutes les réponses contiendront un en-tête x-client-correlation-id . La valeur de cet en-tête vous permet de définir votre propre identifiant client par requête/réponse.

Shell

x-client-correlation-id: Fs1ffv5QZAgVh6kATEST

Lorsque votre client API ne définit pas cet en-tête, il aura la même valeur que x-request-id dans la réponse.

Support linguistique

Vous pouvez spécifier votre langue préférée pour les réponses de l'API en envoyant un en-tête Accept-Language . Cela affecte le contenu localisé comme les messages d'erreur et les noms de lieux.

Shell

Accept-Language: fr

Exemple de requête complet

Voici un exemple complet montrant tous les en-têtes requis dans une requête API typique pour vérifier la disponibilité des ferries.

Cet exemple démontre :

Tous les en-têtes d'authentification et de versionnage
Structure de la requête avec les détails du trajet aller
Informations passager (adulte, 25 ans)
Détails du véhicule (Peugeot 208)
Configuration de trajet aller simple

À propos de cet exemple :

Itinéraire : Sète (SET) vers Tanger Med (TGM)
Compagnie : Grandi Navi Veloci
Date : 28 décembre 2025 à 19h00
Type de trajet : Aller simple (aller uniquement)

Réservations aller-retour : Pour créer une réservation aller-retour, remplissez les champs ret_journey_id, ret_at, et ret_time avec les détails du trajet retour.

Exemples de code

curl --location 'https://api.ferrygate.com/api/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-client-correlation-id: Fs1ffv5QZAgVh6kATEST' \
  --header 'Accept-Language: fr' \
  --header 'x-client-version: 2' \
  --header 'Authorization: Bearer YOUR_API_TOKEN_HERE' \
  --data '{
    "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
        "out_at": "2025-12-28",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
    },
    "passengers": [
        {
            "order": 1,
            "type": "Adult",
            "param": "A",
            "gender": "Male",
            "age": 25
        }
    ],
    "vehicle": {
        "code": "PEUGEOT__208"
    }
}'

const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("x-client-correlation-id", "Fs1ffv5QZAgVh6kATEST");
myHeaders.append("Accept-Language", "fr");
myHeaders.append("x-client-version", "2");
myHeaders.append("Authorization", "Bearer YOUR_API_TOKEN_HERE");

const raw = JSON.stringify({
  "request": {
    "company": "grandinaviveloci",
    "depart_code": "SET",
    "arrive_code": "TGM",
    "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
    "out_at": "2025-12-28",
    "out_time": "19:00",
    "out_is_open": false,
    "ret_journey_id": "",
    "ret_at": "",
    "ret_time": "",
    "ret_is_open": false
  },
  "passengers": [
    {
      "order": 1,
      "type": "Adult",
      "param": "A",
      "gender": "Male",
      "age": 25
    }
  ],
  "vehicle": {
    "code": "PEUGEOT__208"
  }
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api.ferrygate.com/api/availability", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.ferrygate.com/api/availability',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
        "out_at": "2025-12-28",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
    },
    "passengers": [
        {
            "order": 1,
            "type": "Adult",
            "param": "A",
            "gender": "Male",
            "age": 25
        }
    ],
    "vehicle": {
        "code": "PEUGEOT__208"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Content-Type: application/json',
    'x-client-correlation-id: Fs1ffv5QZAgVh6kATEST',
    'Accept-Language: fr',
    'x-client-version: 2',
    'Authorization: Bearer YOUR_API_TOKEN_HERE'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Bonnes pratiques de sécurité

Gardez votre jeton API sécurisé et ne l'exposez jamais dans du code côté client ou des dépôts publics
Renouvelez vos jetons régulièrement et immédiatement s'ils sont compromis
Utilisez des variables d'environnement pour stocker les jetons dans votre application
Utilisez des jetons en lecture seule lorsque l'accès en écriture n'est pas nécessaire

Flux de réservation

Recherche de disponibilité

POST/api/availability

Description

Recherchez les traversées ferry disponibles en fonction des itinéraires, dates, passagers et informations véhicule optionnelles. C'est la première étape du flux de réservation. Le point d'accès renvoie une liste de traversées disponibles avec les tarifs, les options d'hébergement (cabines, sièges), les options de repas et les détails de la traversée incluant les heures de départ/arrivée, les informations sur la compagnie ferry et les noms de navires.

Paramètres de requête

Paramètre	Type	Requis	Description
request (object)
company	string	Oui	Identifiant de la compagnie ferry
depart_code	string	Oui	Code du port de départ
arrive_code	string	Oui	Code du port d'arrivée
out_journey_id	string	Oui	UUID du trajet aller
out_at	string	Oui	Date de départ (AAAA-MM-JJ)
out_time	string	Oui	Heure de départ (HH:MM)
out_is_open	boolean	Non	Billet ouvert (date flexible)
ret_journey_id	string	Non	UUID du trajet retour
ret_at	string	Non	Date de retour (AAAA-MM-JJ)
ret_time	string	Non	Heure de retour (HH:MM)
ret_is_open	boolean	Non	Billet retour ouvert
passengers (array)
order	integer	Oui	Numéro d'ordre du passager
type	string	Oui	Adulte, Enfant, Nourrisson
param	string	Oui	Code paramètre (A, C, I)
gender	string	Oui	Homme, Femme
age	integer	Oui	Âge du passager
vehicle (object) — Optionnel
code	string	Oui	Code véhicule (MARQUE__MODELE)

Champs de réponse

Champ	Type	Description
id	string	Identifiant unique de disponibilité
group_id	integer	Numéro de groupe de disponibilité
direction	string	Aller ou Retour
journey_id	string	UUID du trajet
sailing_id	string	Identifiant de la traversée
depart_name	string	Nom du port de départ
arrive_name	string	Nom du port d'arrivée
depart_at	string	Date et heure de départ (ISO 8601)
arrive_at	string	Date et heure d'arrivée (ISO 8601)
company	object	Détails de la compagnie ferry
tariffs	array	Options tarifaires (Ticket, Presale, Option). Chaque tarif peut inclure roundtrip_locked (booléen) : à true, il s'agit d'un tarif aller-retour réduit valable uniquement en aller-retour chez le même transporteur — ne combinez pas ce trajet avec un autre transporteur (le tarif aller simple serait différent). Absent/false = combinable.
places	array	Options d'hébergement (Siège, Cabine, Suite)
ship_name	string	Nom du ferry
duration	integer	Durée du trajet en heures
stops	array	Codes des ports intermédiaires

Exemples de code

Requête

curl --location 'https://api.ferrygate.com/api/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN_HERE' \
  --data '{
    "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
        "out_at": "2025-12-28",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
    },
    "passengers": [
        {
            "order": 1,
            "type": "Adult",
            "param": "A",
            "gender": "Male",
            "age": 25
        }
    ],
    "vehicle": {
        "code": "PEUGEOT__208"
    }
}'

const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer YOUR_API_TOKEN_HERE");

const raw = JSON.stringify({
  "request": {
    "company": "grandinaviveloci",
    "depart_code": "SET",
    "arrive_code": "TGM",
    "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
    "out_at": "2025-12-28",
    "out_time": "19:00",
    "out_is_open": false,
    "ret_journey_id": "",
    "ret_at": "",
    "ret_time": "",
    "ret_is_open": false
  },
  "passengers": [
    {
      "order": 1,
      "type": "Adult",
      "param": "A",
      "gender": "Male",
      "age": 25
    }
  ],
  "vehicle": {
    "code": "PEUGEOT__208"
  }
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api.ferrygate.com/api/availability", requestOptions)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.ferrygate.com/api/availability',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
        "out_at": "2025-12-28",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
    },
    "passengers": [
        {
            "order": 1,
            "type": "Adult",
            "param": "A",
            "gender": "Male",
            "age": 25
        }
    ],
    "vehicle": {
        "code": "PEUGEOT__208"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_API_TOKEN_HERE'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Réponse (200 OK)

JSON - Tableau d'objets de disponibilité

[
  {
    "id": "5e58ca8b-51eb-4e7c-88bc-32e2bb227b14#8e49e3...",
    "group_id": 1,
    "direction": "Outward",
    "journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
    "sailing_id": "41640",
    "depart_name": "SETE",
    "depart_code": "SET",
    "arrive_name": "TANGER MED",
    "arrive_code": "TGM",
    "is_open": false,
    "depart_at": "2025-12-28T19:00:00+00:00",
    "arrive_at": "2025-12-30T18:45:00+00:00",
    "company": {
      "id": "21588986-ebd0-4339-ad7e-e60f7529d513",
      "name": "grandinaviveloci",
      "logo": "https://res.cloudinary.com/..."
    },
    "provider": {
      "id": "4cf00c5c-0411-40b4-8aa0-0faa0aea7ba4",
      "name": "grandinaviveloci"
    },
    "gateway": {
      "id": "966f4747-640a-492a-91f2-15714a380080",
      "code": "P999",
      "provider": "grandinaviveloci"
    },
    "tariffs": [
      {
        "id": "68e596c744a0c",
        "type": "Ticket",
        "amount": 84,
        "balance_amount": 0,
        "currency": "Eur",
        "date": 1759876807,
        "expiration_date": 1759878007,
        "roundtrip_locked": false
      },
      {
        "id": "68e596c744a1e",
        "type": "Presale",
        "amount": 50,
        "balance_amount": 34,
        "currency": "Eur",
        "expiration_date": 1764369607,
        "date": 1759876807
      },
      {
        "id": "68e596c744a26",
        "type": "Option",
        "amount": 0,
        "balance_amount": 84,
        "currency": "Eur",
        "date": 1759876807,
        "expiration_date": 1760049607
      }
    ],
    "places": [
      {
        "id": "68e596c7449ee",
        "index": 1,
        "code": "POL",
        "count": 1,
        "type": "Seat",
        "gender": "Any",
        "capacity": 1,
        "use": "Exclusive",
        "name": "Fauteuil",
        "in_board": {
          "adults": 1,
          "childs": 0,
          "babies": 0,
          "has_shower": true,
          "has_toilet": true,
          "has_window": true,
          "passengers": [...]
        }
      }
    ],
    "passenger_count": 1,
    "vehicle": [],
    "meals": [],
    "animals": null,
    "stops": ["BCN"],
    "ship_name": "Excellent",
    "duration": 47
  },
  // ... more availability options
]

Créer la réservation

POST/api/booking

Description

Créez une nouvelle réservation ferry avec les détails des passagers, la disponibilité sélectionnée et les informations véhicule optionnelles. Ce point d'accès crée une réservation et renvoie un identifiant de réservation qui peut être utilisé pour confirmer la réservation. La réservation sera en état d'attente jusqu'à sa confirmation.

Données d'entrée

Paramètre	Type	Requis
availabilities	array	Oui
passengers	array	Oui
reservation_type	string	Non
vehicle	object	Non

Données de sortie

Champ	Type	Description
booking_id	string	ID de réservation
booking_reference	string	Référence
status	string	Statut
total_price	number	Prix total
currency	string	Code de devise ISO 4217
stage	string	État agrégé de la réservation (généralement payment_due juste après la création)
possible_actions	object	Table des actions autorisées pour l'étape courante (Pay, Issue, Cancel, Retry, Download)

Exemple de code

cURL

curl -X POST "https://api.ferrygate.com/api/booking" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "reservation_type": "OPTION",
    "availabilities": [
      {
        "availability_id": "AVL123456",
        "tariff_id": "TRF001",
        "place_id": "PLC123"
      }
    ],
    "passengers": [
      {
        "order": 1,
        "type": "Adult",
        "first_name": "John",
        "last_name": "Doe",
        "age": 35,
        "gender": "M",
        "birth_date": "1990-04-12",
        "nationality": "FR",
        "doc_type": "Passport",
        "doc_number": "12345678X",
        "doc_expiration": "2030-12-31"
      }
    ],
    "vehicle": {
      "code": "CAR",
      "vehicule_code": "C1",
      "brand": "Citroen",
      "model": "C3",
      "identification": "AB-123-CD"
    },
    "contact": { "name": "John Doe", "email": "john.doe@example.com", "prefix": "+33", "phone": "612345678" }
  }'

# Response (201 Created)
{
  "booking_id": "BKG789012",
  "booking_reference": "FG-2025-789012",
  "stage": "payment_due",
  "possible_actions": {
    "Pay":    { "type": "mandatory", "timeLimit": "2026-06-20T08:00:00+00:00", "requestedItems": {} },
    "Cancel": { "type": "optional",  "timeLimit": null, "requestedItems": {} }
  },
  "status": "Blocked",
  "total_price": 145.50,
  "currency": "EUR"
}

Confirmer la réservation

POST/api/booking/confirm

Description

Confirmez et finalisez une réservation ferry. Cette étape verrouille la réservation, traite le paiement et génère les billets. Une fois confirmée, la réservation ne peut pas être modifiée sans frais d'annulation.

Données d'entrée

Paramètre	Type	Requis
id	string	Oui

Données de sortie

Champ	Type	Description
booking_id	string	ID de réservation
status	string	Statut (confirmé)
ticket_id	string	ID ticket
ticket_number	string	Référence du billet

Exemple de code

cURL

curl -X POST "https://api.ferrygate.com/api/booking/confirm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{"id": "BKG789012"}'

# Response (201 Created)
{
  "booking_id": "BKG789012",
  "status": "confirmed",
  "ticket_id": "TKT345678",
  "ticket_number": "FG-TKT-345678"
}

Obtenir les détails de la réservation

GET/api/booking/{'{'}id{'}'}

Description

Récupérez les détails complets d'une réservation existante incluant les informations passagers, les détails du trajet, les tarifs et le statut actuel. Utilisez ce point d'accès pour vérifier le statut de la réservation ou récupérer les informations de réservation.

Données d'entrée

Paramètre	Type	Requis
id	string	Oui

Données de sortie

Champ	Type	Description
booking_id	string	Identifiant logique regroupant tous les trajets de la réservation
booking_reference	string	Référence FerryGate
stage	string	État agrégé de la réservation (payment_due, issuance_due, in_progress, ticketed, voided, lapsed, rejected, partially_ticketed, partially_voided)
possible_actions	object	Table des actions autorisées pour l'étape courante (Pay, Issue, Cancel, Retry, Download)
status	string	Statut de suivi au niveau de la réservation
payment_status	string	paid, partially_paid ou unpaid
all_tickets_paid	boolean	Vrai lorsque tous les trajets sont payés
ticket_count	integer	Nombre de trajets (billets)
total_price	number	Somme de tous les trajets (sans double comptage A/R)
currency	string	Code de devise ISO 4217
expire_at	string \| null	Échéance d'option/d'émission la plus proche parmi les trajets (ISO 8601)
pricing	object \| null	Ventilation du point de vue du lecteur (received / kept / reverse / balance). Null si l'appelant n'a aucun rôle reconnu
tickets	array	Objets billet par trajet (passagers, véhicule, disponibilité, statut, ticket_number, pdf_url)

Exemple de code

cURL

curl -X GET "https://api.ferrygate.com/api/booking/BKG789012" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "booking_id": "BKG789012",
  "booking_reference": "FG-2025-789012",
  "stage": "ticketed",
  "possible_actions": {
    "Cancel":   { "type": "optional", "timeLimit": null, "requestedItems": {} },
    "Download": { "type": "optional", "timeLimit": null, "requestedItems": {} }
  },
  "status": "Issued",
  "payment_status": "paid",
  "all_tickets_paid": true,
  "ticket_count": 1,
  "total_price": 295.89,
  "currency": "EUR",
  "expire_at": null,
  "pricing": {
    "viewer_role": "seller",
    "currency": "EUR",
    "received": { "amount": 295.89, "currency": "EUR", "from_label": "Client", "from_kind": "client" },
    "kept": {
      "total": 32.50,
      "lines": [
        { "key": "markup",     "label": "Markup",     "amount": 20.00 },
        { "key": "commission", "label": "Commission", "amount": 12.50 }
      ]
    },
    "reverse": { "amount": 263.39, "currency": "EUR", "to_label": "Parent Org", "to_kind": "organisation" },
    "balance": { "mutated": true, "before": 1000.00, "after": 736.61 }
  },
  "tickets": [
    {
      "id": "TKT345678",
      "direction": "OUTWARD+RETURN",
      "status": "Issued",
      "ticket_number": "BLR-9988776",
      "pdf_url": "https://res.cloudinary.com/.../voucher.pdf",
      "vehicle": { "code": "CAR", "vehicule_code": "C1", "brand_name": "Citroen", "model": "C3", "type": "Voiture" },
      "passengers": [
        { "first_name": "John", "last_name": "Doe", "birth_date": "1990-04-12",
          "nationality": "FR", "doc_type": "Passport", "doc_number": "12345678X", "doc_expiration": "2030-12-31" }
      ],
      "availability": {
        "outward": { "journey": { "depart_at": "2026-06-20T08:00:00", "arrive_at": "2026-06-20T09:30:00",
          "depart_port_name": "Tanger Med", "arrive_port_name": "Algeciras", "duration_minutes": 90 } }
      }
    }
  ]
}

Machine à états de la réservation

Pilotez votre interface à partir de stage et possible_actions plutôt qu'à partir des statuts bruts des billets — la réservation agrège tous les trajets (un aller-retour peut compter 1 ou 2 billets selon le transporteur).

stage — l'état agrégé : payment_due → issuance_due → in_progress → ticketed, ainsi que les états terminaux/partiels (voided, lapsed, rejected, partially_ticketed, partially_voided).
possible_actions — les actions que vous pouvez déclencher maintenant. Chaque entrée porte un type (mandatory = CTA principal, optional = secondaire), un timeLimit optionnel (échéance ISO 8601) et requestedItems.

Annuler la réservation

POST/api/booking/cancel

Description

Annulez une réservation ferry existante. Les politiques d'annulation et l'éligibilité au remboursement varient selon l'opérateur ferry et les règles tarifaires. Vérifiez les conditions de réservation avant l'annulation.

Données d'entrée

Paramètre	Type	Requis
booking_id	string	Oui
booking_reference	string	Non

Données de sortie

Champ	Type	Description
booking_id	string	ID de réservation
status	string	Statut (annulé)
refund_amount	number	Montant du remboursement

Exemple de code

cURL

curl -X POST "https://api.ferrygate.com/api/booking/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "booking_id": "BKG789012",
    "booking_reference": "FG-2025-789012"
  }'

# Response (201 Created)
{
  "booking_id": "BKG789012",
  "status": "cancelled",
  "refund_amount": 145.50
}

Obtenir les détails du billet

GET/api/ticket/{'{'}id{'}'}

Description

Récupérez les informations du billet ferry incluant le code QR, les détails d'embarquement et les informations passagers. Utilisez ce point d'accès pour afficher ou télécharger les billets des réservations confirmées.

Données d'entrée

Paramètre	Type	Requis
id	string	Oui

Données de sortie

Champ	Type	Description
id	string	ID du billet (UUID FerryGate)
status	string	Statut du billet (Init, Blocked, Pending, Issued, Canceled, Failed, Expired)
ticket_number	string \| null	Référence fournisseur, null avant l'émission
pdf_url	string \| null	URL du voucher Cloudinary, disponible une fois le billet émis
direction	string	OUTWARD, RETURN ou OUTWARD+RETURN
vehicle	object \| null	code, vehicule_code (code fournisseur), brand_name, model, type
passengers	array	Objets passager (first_name, last_name, birth_date, nationality, doc_type, doc_number, doc_expiration)
availability	object	détails des trajets aller/retour (ports, depart_at, arrive_at, duration_minutes)

Exemple de code

cURL

curl -X GET "https://api.ferrygate.com/api/ticket/TKT345678" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "id": "TKT345678",
  "status": "Issued",
  "ticket_number": "BLR-9988776",
  "pdf_url": "https://res.cloudinary.com/.../voucher.pdf",
  "direction": "OUTWARD+RETURN",
  "vehicle": { "code": "CAR", "vehicule_code": "C1", "brand_name": "Citroen", "model": "C3", "type": "Voiture" },
  "passengers": [
    { "first_name": "John", "last_name": "Doe", "birth_date": "1990-04-12",
      "nationality": "FR", "doc_type": "Passport", "doc_number": "12345678X", "doc_expiration": "2030-12-31" }
  ],
  "availability": {
    "outward": { "journey": { "depart_at": "2026-06-20T08:00:00", "arrive_at": "2026-06-20T09:30:00",
      "depart_port_name": "Tanger Med", "arrive_port_name": "Algeciras", "duration_minutes": 90 } }
  }
}

Annuler le billet

POST/api/ticket/cancel

Description

Annulez un billet ferry. Cette action peut entraîner des frais d'annulation selon les règles tarifaires et le délai. Les billets doivent être annulés avant l'heure de départ.

Données d'entrée

Paramètre	Type	Requis
ticket_id	string	Oui
ticket_number	string	Non

Données de sortie

Champ	Type	Description
ticket_id	string	ID ticket
status	string	Statut (annulé)

Exemple de code

cURL

curl -X POST "https://api.ferrygate.com/api/ticket/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "ticket_id": "TKT345678",
    "ticket_number": "FG-TKT-345678"
  }'

# Response (201 Created)
{
  "ticket_id": "TKT345678",
  "status": "cancelled"
}

Aperçu des frais d'annulation

POST/api/booking/cancel-fee

Description

Prévisualisez la pénalité d'annulation et le remboursement d'un billet sans rien modifier. Lecture seule — utilisez-le pour montrer le coût au client avant qu'il confirme l'annulation.

Données d'entrée

Paramètre	Type	Requis
id	string	Oui

ID du billet ou de la réservation.

Données de sortie

Champ	Type	Description
penalty_amount	number	Pénalité retenue en cas d'annulation
refund_amount	number	Montant remboursé au client
currency	string	Devise des montants
ticket_status	string	Statut actuel du billet

Exemple de code

cURL

curl -X POST "https://api.ferrygate.com/api/booking/cancel-fee" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{"id": "TKT345678"}'

# Response (200 OK)
{
  "penalty_amount": 25.0,
  "refund_amount": 75.0,
  "currency": "EUR",
  "ticket_status": "Issued"
}

PDF du billet

GET/api/ticket/{id}/pdf

Description

Récupérez le PDF du bon d'embarquement d'un billet émis. Renvoie l'URL du document une fois généré. Certaines compagnies envoient le bon par e-mail à la place — dans ce cas url est null.

Données d'entrée

Paramètre	Type	Requis
id	string	Oui

ID du billet, transmis dans le chemin de l'URL.

Données de sortie

Champ	Type	Description
url	string \| null	URL du PDF du bon, ou null si pas encore disponible

Exemple de code

cURL

curl -X GET "https://api.ferrygate.com/api/ticket/TKT345678/pdf" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "url": "https://res.cloudinary.com/ferrygate/.../GN-5746472.pdf"
}

Marquer le billet comme payé

POST/api/ticket/{id}/mark-paid

Description

Marquez un billet comme payé après avoir encaissé le paiement en dehors de FerryGate (par exemple le checkout B2C du widget sur le prestataire de paiement du marchand). Serveur à serveur uniquement, authentifié avec le token API de l'organisation. Enregistre le règlement pour que le billet puisse ensuite être émis.

Données d'entrée

Paramètre	Type	Requis
id	string	Oui
external_payment_ref	string	Oui
psp	string	Non
paid_at	string	Non

id est l'ID du billet (chemin de l'URL). external_payment_ref est la référence de transaction de votre PSP ; psp est le nom du prestataire ; paid_at est un horodatage ISO 8601.

Données de sortie

Champ	Type	Description
ticket_id	string	ID ticket
payment_status	string	Statut de paiement (paid)

Exemple de code

Serveur à serveur uniquement : appelez-le depuis votre backend avec le token API de votre organisation, jamais depuis un navigateur ni le widget.

cURL

curl -X POST "https://api.ferrygate.com/api/ticket/TKT345678/mark-paid" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{"external_payment_ref": "pi_3Nxyz", "psp": "stripe"}'

# Response (200 OK)
{
  "ticket_id": "TKT345678",
  "payment_status": "paid"
}

Points d'accès communs

Vérifier les départs

POST/api/departure

Description

Obtenez des informations sur les départs ferry pour des fournisseurs et trajets spécifiques. Renvoie les heures de départ et les dates disponibles pour les itinéraires demandés.

Données d'entrée

Paramètre	Type	Requis
provider_id	string	Oui
__journey_id	array	Non

Données de sortie

Champ	Type	Description
departures	array	Liste des départs
departure_times	array	Heures de départ

Exemple de code

cURL

curl -X POST "https://api.ferrygate.com/api/departure" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "provider_id": "DFDS",
    "__journey_id": ["JRN001"]
  }'

# Response (201 Created)
{
  "departures": [
    {
      "journey_id": "JRN001",
      "departure_times": ["14:30", "18:00"]
    }
  ]
}

Vérifier les trajets

POST/api/journey

Description

Obtenez des informations sur les trajets et itinéraires ferry disponibles incluant la durée et les détails du fournisseur.

Données d'entrée

Aucun paramètre requis. Renvoie tous les trajets disponibles.

Données de sortie

Champ	Type	Description
journeys	array	Liste des trajets
journey_id	string	ID du trajet
route	string	Route

Exemple de code

cURL

curl -X POST "https://api.ferrygate.com/api/journey" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (201 Created)
{
  "journeys": [
    {
      "journey_id": "JRN001",
      "route": "Marseille - Dover",
      "duration_minutes": 480
    }
  ]
}

Vérifier les ports

GET/api/port

Description

Obtenez des informations sur les ports ferry incluant les codes, emplacements et installations. Utile pour construire des interfaces de sélection de port.

Données d'entrée

Aucun paramètre requis. Renvoie tous les ports disponibles.

Données de sortie

Champ	Type	Description
ports	array	Liste des ports
code	string	Code du port
name	string	Nom du port
country	string	Pays

Exemple de code

cURL

curl -X GET "https://api.ferrygate.com/api/port" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "ports": [
    {
      "code": "FRMAR",
      "name": "Marseille",
      "country": "France"
    }
  ]
}

Marques de véhicules

GET/api/vehicle-brand

Description

Obtenez la liste des marques de véhicules disponibles pour le transport ferry. Utile pour les formulaires de sélection de véhicule.

Données d'entrée

Aucun paramètre requis. Renvoie toutes les marques de véhicules disponibles.

Données de sortie

Champ	Type	Description
brands	array	Liste des marques
id	string	ID de la marque
name	string	Nom de la marque

Exemple de code

cURL

curl -X GET "https://api.ferrygate.com/api/vehicle-brand" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "brands": [
    {"id": "1", "name": "Peugeot"},
    {"id": "2", "name": "Renault"}
  ]
}

Données véhicules

GET/api/vehicle-data

Description

Obtenez les données détaillées des véhicules incluant les types, dimensions et spécifications pour la réservation ferry. Renvoie les catégories de véhicules et leurs restrictions de taille.

Données d'entrée

Aucun paramètre requis. Renvoie toutes les informations sur les types de véhicules.

Données de sortie

Champ	Type	Description
vehicle_types	array	Types de véhicules
code	string	Code du type
max_length	number	Longueur max (m)
max_height	number	Hauteur max (m)

Exemple de code

cURL

curl -X GET "https://api.ferrygate.com/api/vehicle-data" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "vehicle_types": [
    {
      "code": "CAR",
      "name": "Car",
      "max_length": 5.0,
      "max_height": 2.0
    },
    {
      "code": "CAMPER",
      "name": "Camper Van",
      "max_length": 7.0,
      "max_height": 3.0
    }
  ]
}

Protocole MCP

Model Context Protocol (MCP)

MCP est un standard ouvert par Anthropic qui permet aux assistants IA (Claude, ChatGPT, agents personnalisés) d'interagir avec des outils et données externes. FerryGate expose l'intégralité de son flux de réservation via MCP à travers un point d'accès unique.

Point d'accès MCP

POST https://api.ferrygate.com/mcp
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Comment ça fonctionne :

Protocole : JSON-RPC 2.0 sur HTTP
Session : Basée sur fichier, TTL de 1 heure
Auth : Même clé API Bearer que les points d'accès REST
Découverte : Les agents IA découvrent automatiquement les outils et ressources disponibles

Ressources MCP

Les ressources sont des catalogues de données en lecture seule que les agents IA peuvent interroger pour découvrir les ports, compagnies, véhicules et départs. Utilisez resources/read pour les récupérer.

Ferry-Ports

RESresource://ferrygate/ports

Tous les ports disponibles avec leurs codes, villes et coordonnées GPS. Utilisez-la pour trouver les codes de ports nécessaires à la recherche de disponibilités.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/ports"
  },
  "id": 1
}

Ferry-Companies

RESresource://ferrygate/companies

Toutes les compagnies (Balearia, GNV, Armas, Meridionale) avec leurs logos et codes.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/companies"
  },
  "id": 1
}

Countries

RESresource://ferrygate/countries

Tous les pays avec codes ISO, indicatifs téléphoniques et noms localisés.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/countries"
  },
  "id": 1
}

Vehicle-Brands

RESresource://ferrygate/vehicle-brands

Toutes les marques de véhicules disponibles pour les réservations.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/vehicle-brands"
  },
  "id": 1
}

Vehicle-Data

RESresource://ferrygate/vehicle-data

Catalogue des véhicules avec dimensions (hauteur, longueur), marque et type.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/vehicle-data"
  },
  "id": 1
}

Departures

RESresource://ferrygate/departures

Tous les départs programmés avec trajet, compagnie, ports et navire.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/departures"
  },
  "id": 1
}

Outils MCP

Les outils sont des actions que les agents IA peuvent appeler pour exécuter le flux de réservation. Utilisez tools/call avec le nom de l'outil et les arguments. Le format du corps JSON est identique à l'API REST.

search_availability

TOOLsearch_availability

Recherchez les traversées ferry disponibles entre deux ports. Même entrée que POST /api/availability.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_availability",
    "arguments": {
      "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "uuid",
        "out_at": "2026-07-15",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
      },
      "passengers": [
        { "order": 1, "type": "Adult", "param": "A", "gender": "Male", "age": 25 }
      ],
      "vehicle": { "code": "PEUGEOT__208" }
    }
  },
  "id": 1
}

create_booking

TOOLcreate_booking

Créez une réservation à partir d'un ID de billet obtenu via search_availability. Même entrée que POST /api/booking.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_booking",
    "arguments": {
      "id": "ticket-uuid-from-availability",
      "reservation_type": "TICKET",
      "passengers": [
        { "order": 1, "type": "ADT", "gender": "M", "age": 30,
          "first_name": "John", "last_name": "Doe" }
      ],
      "contact": { "prefix": "+33", "phone": "612345678",
                   "name": "John Doe", "email": "john@example.com" }
    }
  },
  "id": 2
}

confirm_booking

TOOLconfirm_booking

Confirmez une réservation PRESALE/OPTION en un billet confirmé. Même entrée que POST /api/booking/confirm.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "confirm_booking",
    "arguments": {
      "id": "ticket-uuid"
    }
  },
  "id": 3
}

view_ticket

TOOLview_ticket

Obtenez les détails du billet incluant les informations de réservation, passagers, statut et données PDF. Identique à GET /api/ticket/{id}.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "view_ticket",
    "arguments": {
      "id": "ticket-uuid"
    }
  },
  "id": 4
}

cancel_ticket

TOOLcancel_ticket

Annulez un billet confirmé. Même entrée que POST /api/ticket/cancel.

Requête JSON-RPC

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "cancel_ticket",
    "arguments": {
      "ticket_id": "ticket-uuid",
      "ticket_number": "BOOKING-REF-123"
    }
  },
  "id": 5
}

Gestion des erreurs MCP

Lorsqu'un appel d'outil échoue, la réponse contient un objet d'erreur structuré :

Réponse d'erreur

{
  "error": true,
  "code": "AVAILABILITY_ERROR",
  "message": "No sailings found for the requested date"
}

Code d'erreur	Outil
AVAILABILITY_ERROR	search_availability
BOOKING_CREATE_ERROR	create_booking
BOOKING_CONFIRM_ERROR	confirm_booking
TICKET_VIEW_ERROR	view_ticket
TICKET_NOT_FOUND	view_ticket
TICKET_CANCEL_ERROR	cancel_ticket