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

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

Champs de réponse

Field	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, Prévente, Option)
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;

Response (200 OK)

JSON - Array of availability objects

[
  {
    "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
      },
      {
        "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

Parameter	Type	Required
availabilities	array	Yes
passengers	array	Yes
reservation_type	string	No
vehicle	object	No

Données de sortie

Field	Type	Description
booking_id	string	ID de réservation
booking_reference	string	Référence
status	string	Statut
total_price	number	Prix total

Exemple de code

curl -X POST "https://api.ferrygate.com/api/booking" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "reservation_type": "TICKET",
    "availabilities": [
      {
        "availability_id": "AVL123456",
        "tariff_id": "TRF001",
        "place_id": "PLC123"
      }
    ],
    "passengers": [
      {
        "order": 1,
        "type": "Adult",
        "first_name": "John",
        "last_name": "Doe",
        "age": 30,
        "gender": "M",
        "email": "john.doe@example.com"
      }
    ]
  }'

# Response (201 Created)
{
  "booking_id": "BKG789012",
  "booking_reference": "FG-2025-789012",
  "status": "pending",
  "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

Parameter	Type	Required
id	string	Yes

Données de sortie

Field	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 -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

Parameter	Type	Required
id	string	Yes

Données de sortie

Field	Type	Description
booking_id	string	ID de réservation
booking_reference	string	Référence
status	string	Statut de la réservation
passengers	array	Passagers
journey_details	object	Informations du trajet

Exemple de code

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",
  "status": "confirmed",
  "passengers": [...],
  "journey_details": {...}
}

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

Parameter	Type	Required
booking_id	string	Yes
booking_reference	string	No

Données de sortie

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

Exemple de code

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

Parameter	Type	Required
id	string	Yes

Données de sortie

Field	Type	Description
ticket_id	string	ID ticket
ticket_number	string	Référence du billet
qr_code	string	Code QR (base64)
boarding_time	string	Heure d'embarquement

Exemple de code

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

# Response (200 OK)
{
  "ticket_id": "TKT345678",
  "ticket_number": "FG-TKT-345678",
  "qr_code": "data:image/png;base64,...",
  "boarding_time": "2025-12-25T13:30:00+00:00"
}

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

Parameter	Type	Required
ticket_id	string	Yes
ticket_number	string	No

Données de sortie

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

Exemple de code

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

Parameter	Type	Required
id	string	Yes

ID du billet ou de la réservation.

Données de sortie

Field	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 -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

Parameter	Type	Required
id	string	Yes

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

Données de sortie

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

Exemple de code

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

Parameter	Type	Required
id	string	Yes
external_payment_ref	string	Yes
psp	string	No
paid_at	string	No

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

Field	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 -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

Parameter	Type	Required
provider_id	string	Yes
__journey_id	array	No

Données de sortie

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

Exemple de code

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

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

Exemple de code

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

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

Exemple de code

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

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

Exemple de code

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

Field	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 -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
    }
  ]
}

MCP Protocol

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.

MCP Endpoint

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

All available ferry ports with codes, cities and GPS coordinates. Use this to discover port codes needed for availability search.

JSON-RPC Request

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

Ferry-Companies

RESresource://ferrygate/companies

All ferry companies (Balearia, GNV, Armas, Meridionale) with logos and codes.

JSON-RPC Request

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

Countries

RESresource://ferrygate/countries

All countries with ISO codes, phone prefixes and localized names.

JSON-RPC Request

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

Vehicle-Brands

RESresource://ferrygate/vehicle-brands

All vehicle brands available for ferry bookings.

JSON-RPC Request

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

Vehicle-Data

RESresource://ferrygate/vehicle-data

Vehicle catalog with dimensions (height, length), brand and type.

JSON-RPC Request

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

Departures

RESresource://ferrygate/departures

All scheduled ferry departures with journey, company, ports and ship information.

JSON-RPC Request

{
  "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.

JSON-RPC Request

{
  "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.

JSON-RPC Request

{
  "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.

JSON-RPC Request

{
  "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}.

JSON-RPC Request

{
  "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.

JSON-RPC Request

{
  "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é :

Error Response

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

Error Code	Tool
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