Documentation API publique Capt’n Boat

L’API publique Capt’n Boat permet aux partenaires d’intégrer le recrutement d’équipages professionnels directement dans leurs outils. Elle couvre tout le cycle de vie : de la création du bateau jusqu’à la signature du contrat et du paiement.

Fonctionnalités principales :

Vérifier la disponibilité des marins avant de créer une mission.
Créer une mission complète (Bateau, Annonce, Poste).
Gérer le recrutement via deux méthodes :
1. Classique : Recevoir des offres, choisir et faire signer le client.
2. Instantanée : Réserver directement un marin éligible sans attente.
Récupérer les contacts une fois le paiement effectué.

Environnements & Authentification

Endpoints

Environnement	URL	Description
Production	`https://api.captnboat.com/opengraphql`	Données réelles. Facturation active.
Intégration	`https://api-int.captnboat.com/opengraphql`	Sandbox pour tester vos développements.

Authentification

L’API est une API GraphQL. L’accès est sécurisé par une clé API.

Header requis : x-api-key: <VOTRE_TOKEN>

curl '[https://api-int.captnboat.com/opengraphql](https://api-int.captnboat.com/opengraphql)' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <VOTRE_TOKEN>' \
  -d '{"query":"{ __typename }"}'

⚠️

Sécurité : Votre clé API permet de générer des contrats financiers. Elle ne doit jamais être visible côté client (navigateur). Effectuez toujours les appels depuis votre serveur (Backend).

Workflow d’intégration

Choisissez le flux adapté à votre besoin :

Le workflow classique de place de marché :

Création : Vous créez le Bateau, l’Annonce (Mission), puis le Job (Poste).
Attente : Les skippers reçoivent une notification et postulent.
Consultation : Vous récupérez la liste des offres via l’API.
Action Client : Vous redirigez votre client vers l’URL de signature (urlSignature) pour qu’il signe et paie.
Contact : Une fois payé, les coordonnées du marin sont accessibles.

Guide : Créer une mission étape par étape

1. (Optionnel) Vérifier la disponibilité

Avant de créer une mission, vérifiez si des marins sont disponibles dans la zone. Cela permet aussi d’identifier les marins éligibles à la réservation instantanée.

Note technique : Les coordonnées GPS et dimensions sont attendues au format String.

query CheckAvailability {
  matchingSailor(
    pAdType: CHARTER
    pPosition: SKIPPER
    pStartDate: "2026-06-15"
    pEndDate: "2026-06-30"
    pStartHarborLatitude: "47.2799"
    pStartHarborLongitude: "-2.1976"
    pEndHarborLatitude: "47.2799"
    pEndHarborLongitude: "-2.1976"
    pHullLength: "15"
    pBeam: "4"
    pBoatType: MOTORBOAT
  ) {
    nodes {
      id
      averageNotations
      instantBooking
      price
      birthday
      civility
      cv
      documents
      firstName
      nationality
      sailorAvatar
    }
  }
}

Payload (Arguments de recherche)

pAdType: AdTypeEnum! — Valeur : CHARTER
pPosition: PositionEnum! — Valeurs : SKIPPER, HOTESSE, MATELOT, SECOND, CHEF, MECANICIEN, CHEF_DE_QUART, HOTESSE_COOK, STEW_COOK.
pStartDate: String! (Format YYYY-MM-DD)
pEndDate: String! (Format YYYY-MM-DD)
pStartHarborLatitude / Longitude: String!
pEndHarborLatitude / Longitude: String!
pHullLength: String (m)
pBoatType: BoatTypeEnum — MOTORBOAT | SAILBOAT | MULTIHULL

Résultat (nodes)

instantBooking: true si le marin peut être réservé immédiatement.
price: Tarif journalier indicatif du marin.
documents: Liste des diplômes validés.
id: Identifiant unique du profil marin sur la plateforme.
averageNotations: Note moyenne attribuée par les propriétaires (évaluation).
birthday: Date de naissance du marin.
civility: Civilité du marin (ex: Monsieur, Madame).
cv: Lien ou contenu du Curriculum Vitae (expérience détaillée).
firstName: Prénom du marin.
nationality: Nationalité du marin.
sailorAvatar: Lien vers l’image de profil (photo) du marin.

2. Créer (ou récupérer) un bateau

Créer (ou récupérer) un bateau. Si un bateau identique existe déjà, la mutation ne recrée pas l’entrée et renvoie uniquement son id.

mutation CreateBoat {
  createBoat(
    input: {
      name: "Nom du Bateau"
      flagId: "ef08f160-9858-464b-9e59-a93f94ad5260"
      boatPictures: ["[http://mypictures.com/myboat.jpg](http://mypictures.com/myboat.jpg)"]
      boatType: MOTORBOAT
      builderName: "Beneteau"
      hullLength: 15
      beam: 4
      hullType: MONOHULL
      modelName: "Oceanis 45"
      registrationNumber: "AY-123-BC"
      enginePower: 150
      hasAutopilot: true
    }
  ) {
    boat { id }
  }
}

Payload (CreateBoatInput)

name: String!
flagId: UUID! — ID du pavillon (récupérable via la query listFlags)
boatPictures: [String!]
boatType: BoatTypeEnum! — Valeurs : MOTORBOAT, SAILBOAT, MULTIHULL
builderName: String!
hullLength: Float! (m)
beam: Float! (m)
hullType: HullTypeEnum! — Valeurs possibles : MONOHULL, CATAMARAN, TRIMARAN
modelName: String!
registrationNumber: String
enginePower: Int (HP) — Requis pour les bateaux à moteur.
hasAutopilot: Boolean — Optionnel (true par défaut).

Résultat

boat { id } : L’identifiant unique du bateau (nouveau ou existant).

3. Créer une annonce (Mission)

Définit le contexte : dates, trajet, passagers.

mutation CreateAd {
  createCompleteAd(
    input: {
      adType: CHARTER
      boatId: "ID_BATEAU_ETAPE_2"
      startDate: "2025-06-01"
      endDate: "2025-06-15"
      startHarborLatitude: "47.2799"
      startHarborLongitude: "-2.1976"
      endHarborLatitude: "47.2799"
      endHarborLongitude: "-2.1976"
      passengerNumber: 6
      description: "Convoyage estival"
    }
  ) {
    ad { id }
  }
}

Payload (CreateCompleteAdInput)

adType: AdTypeEnum! — Valeur : CHARTER
boatId: UUID! — L’ID récupéré à l’étape 2.
startDate: String (Format YYYY-MM-DD)
endDate: String (Format YYYY-MM-DD)
startHarborLatitude / Longitude: String!
endHarborLatitude / Longitude: String!
passengerNumber: Int
description: String

Résultat

ad { id } : L’identifiant unique de l’annonce.

4. Créer une fiche de poste (Job)

C’est ici que vous définissez le poste (Skipper, Hôtesse) et les informations de facturation du client final.

Vous pouvez ici ajouter votre propre referenceId (ex: votre ID de commande interne) pour retrouver ce job plus tard sans stocker l’ID Capt’n Boat.

mutation CreateJob {
  createCompleteJob(
    input: {
      adId: "ID_ANNONCE_ETAPE_3"
      positionType: SKIPPER
      price: 150.0
      referenceId: "COMMANDE-INTERNE-999" # Votre ID unique
      billingFirstname: "Jean"
      billingLastname: "Dupont"
      billingEmail: "jean.dupont@email.com"
      billingAdressCityName: "Paris"
      billingAdressCountry: "France"
      billingAdressFirstLine: "10 Rue de la Paix"
      billingAdressZipCode: "75001"
      billingDateOfBirth: "1980-01-01"
      billingLanguage: "FR"
      billingPhoneNumber: "+33612345678"
      reserved: ALL
      travelFee: SKIPPER
    }
  ) {
    job {
      id
      referenceId
    }
  }
}

Payload (CreateCompleteJobInput)

Champs Obligatoires :
- adId: UUID!
- positionType: PositionEnum! — Ex: SKIPPER. Voir liste complète étape 1.
- price: Float! — Prix journalier. Voir estimation du prix en annexe
- billingFirstname: String!
- billingLastname: String!
- billingEmail: String!
Champs Optionnels :
- referenceId (String) — Important : Votre identifiant unique (ex: ID de commande). Permet d’effectuer des actions (Cancel, GetOffers) sans utiliser l’ID Capt’n Boat.
- billingAddressCityName, billingAddressCountry, billingAddressFirstLine, billingAddressZipCode (String) : Adresse de facturation.
- billingDateOfBirth (Date) : Date de naissance pour la facturation.
- billingPhoneNumber (String) : Numéro de téléphone pour la facturation.
- billingRegistrationNumber / billingSiret (String) : Numéros d’immatriculation (pour les professionnels).
- reserved (ReservedEnum) — Définit la visibilité de l’annonce :
  - ALL : Ouvert à tous.
  - APPROVED : Accessible à tous les marins approuvés par Capt’n Boat.
  - FAVOURITES : Accessible aux marins favoris de l’organisation propriétaire de l’annonce.
  - RESERVED : Instant Booking (Réservation immédiate).
- travelFee (TravelFeeEnum) — Définit qui paie le transport (SKIPPER ou OWNER).

Résultat

job { id, referenceId } : L’identifiant unique et la référence du job créé.

Gestion des offres et réservation

Lister les offres (Flux Standard)

Permet de voir qui a postulé. Vous pouvez utiliser soit jobId, soit votre referenceId.

query GetOffers {
  jobOffers(
    # Utilisez l'un ou l'autre :
    jobId: "ID_DU_JOB_CAPTN_BOAT"
    referenceId: "COMMANDE-INTERNE-999"
  ) {
    picture
    urlSignature
    travelFee
    price
    isFavorite
    isCaptnBoatApproved
    firstName
    captnBoatProfile
  }
}

Payload

jobId: UUID OU referenceId: String — L’identifiant du job.

Résultat

firstName: Prénom du marin.
price: Le prix demandé par le marin pour cette offre.
urlSignature: L’URL vers laquelle rediriger votre client pour qu’il signe le contrat et paie.
picture: Lien vers la photo de profil du marin.
travelFee: Information sur la prise en charge des frais de transport.
isFavorite: true si le marin fait partie des favoris de l’organisation.
isCaptnBoatApproved: true si le profil du marin a été validé et approuvé par Capt’n Boat.
captnBoatProfile: Lien vers le profil public du marin sur la plateforme Capt’n Boat.

Réservation Instantanée (Flux Direct)

Utilisez cette mutation uniquement si vous avez identifié un marin avec instantBooking: true. Cela crée une offre et la valide directement.

mutation InstantBook {
  createOffer(
    input: {
      jobId: "ID_DU_JOB"
      sailorId: "ID_DU_MARIN"
    }
  ){
    createOfferResult {
      signatureUrl
    }
  }
}

Payload (CreateOfferInput)

jobId: UUID! — ID du job créé précédemment.
sailorId: UUID! — ID du marin récupéré via matchingSailor.

Résultat

signatureUrl: L’URL vers laquelle rediriger votre client pour qu’il signe le contrat et procède au paiement.

Après la réservation

Récupérer le contact du marin

Les coordonnées ne sont accessibles qu’une fois le job payé et signé.

query GetContact {
  sailorContact(
    # Utilisez l'un ou l'autre :
    jobId: "ID_DU_JOB"
    referenceId: "COMMANDE-INTERNE-999" 
  ) {
    firstName
    lastName
    email
    phoneNumber
    sailorAvatar
    price
    travelFee
    degree
    cv
    contract
    birthday
    civility
    averageNotations
    invoices
  }
}

Payload

jobId: UUID OU referenceId: String.

Résultat

firstName: Prénom du marin.
lastName: Nom de famille du marin.
email: Adresse email du marin.
phoneNumber: Numéro de téléphone du marin.
sailorAvatar: Lien vers la photo de profil du marin.
price: Le tarif final validé pour la mission.
travelFee: Information sur la prise en charge des frais de transport.
degree: Détails sur les diplômes et certifications.
cv: Lien ou contenu du Curriculum Vitae du marin.
contract: Lien ou données du contrat signé.
birthday: Date de naissance du marin.
civility: Civilité du marin (ex: Monsieur, Madame).
averageNotations: Note moyenne attribuée par les propriétaires précédents.
invoices: Liste des factures générées associées à ce job.

Annuler une demande

Permet d’annuler un Job si la mission n’a plus lieu. Accessible via referenceId.

mutation CancelJob {
  cancelJob(
    input: {
      reason: DELAYED
      # Utilisez l'un ou l'autre :
      jobId: "ID_DU_JOB"
      referenceId: "COMMANDE-INTERNE-999"
    }
  ) {
    job { id }
  }
}

Payload

jobId: UUID OU referenceId: String
reason: CancelReasonEnum! — La raison de l’annulation. Valeurs possibles :
- FOUND: J’ai trouvé un marin par un autre biais.
- DELAYED: Mon besoin est reporté.
- NOT_FOUND: Je ne trouve pas de profils correspondant.
- ERROR: Mon annonce comporte des erreurs.
- DUPLICATE: Doublon.
- OTHER: Autre raison.
- CONTACT: Être contacté par un commercial.

Résultat

job { id } : Confirmation de l’ID du job annulé.

Annexes

Lister les pavillons (Flags)

Utile pour obtenir les IDs nécessaires à la création d’un bateau.

query Flags {
  listFlags {
    nodes {
      id
      name
    }
  }
}

Résultat

Renvoie la liste des pavillons (nodes) avec leur id et name.

Estimer un prix

Obtenir une fourchette de prix marché avant de créer le job.

query PriceEstimate {
  estimatedPrice(
    adType: CHARTER
    startDate: "2025-08-08"
    endDate: "2025-08-15"
    startHarborLatitude: 47.2799
    startHarborLongitude: -2.1976
    endHarborLatitude: 47.2799
    endHarborLongitude: -2.1976
    hullLength: 15
    positionType: SKIPPER
  )
}

Payload

Les arguments sont similaires à ceux de la recherche de marins (matchingSailor) :

adType, startDate, endDate, positionType, coordonnées GPS, etc.

Résultat

estimatedPrice: Une valeur Float représentant le prix conseillé.

Capt'n Boat Public API Documentation