Documentation API publique Capt'n Boat

L'API publique Capt'n Boat permet de transmettre la création d'un besoin à l'équipe commerciale Capt'n Boat.

Pour cela il vous faut :

  • CrĂ©er un bateau
  • CrĂ©er une annonce
  • CrĂ©er un Job
  • Renseigner les informations de facturation de votre client

L'équipe commerciale prendra ensuite contact avec votre client pour finaliser la réservation de votre Marin (Skipper / Hôtesse... ) et lui fera parvenir, lien de paiement, facture et contrat par mail.

Objectifs de l’API

L’API publique de Capt'n Boat a pour objectif d’ouvrir certaines fonctionnalités de la plateforme à des utilisateurs externes pour leur permettre la publication d’annonces Capt'n Boat directement depuis leur infrastructure numérique. Cette API permet notamment de :

  • Enregistrer les navires de l’utilisateur externe.
  • CrĂ©er une annonce pour ce navire. (Une annonce correspond Ă  une mission donnĂ©e pour ce navire, et peut comprendre plusieurs postes Ă  pourvoir)
  • CrĂ©er une fiche de poste pour une mission.
  • Annuler une demande.
  • RĂ©cupĂ©rer les information de contact du marin trouvĂ©.

L’API n’est pas pensée pour assurer la gestion des bateaux et annonces publiées. Cette fonctionnalité est rendue possible par l’interface utilisateur Capt'n Boat, par laquelle l’ensemble des bateaux, missions et postes à pourvoir peuvent être consultés/administrés.

Implémentation technique

L’API externe de Capt'n Boat est une API GraphQL. Son accès est limité aux utilisateurs disposant d’un token de connexion, fourni sur demande par Capt'n Boat.

Dans la présente documentation, l’ensemble des requêtes disponibles sont détaillées et illustrées par un exemple simple. Pour de plus amples détails sur la mise en place technique de cette API, n’hésitez pas à contacter l’équipe Capt'n Boat à l’adresse suivante : api-ext@captnboat.com

Chaque connexion à l’API externe doit être faite avec le token d’authentification, passé dans le header x-api-key.

DĂ©tail des requĂŞtes disponibles

Enregistrement d’un navire

Pour enregistrer un navire, l’ensemble des informations suivantes concernant un navire sont passées à l’API :

  • le nom du bateau
  • le nom du constructeur du bateau
  • le nom du modèle
  • sa taille
  • son type de propulsion (voile ou moteur)
  • son type de coque (monocoque ou multicoque)
  • l’ID de son pavillon (plus de dĂ©tails pour rĂ©cupĂ©rer la liste des pavillons plus bas)
  • sa puissance moteur s’il s’agit d’un navire moteur
  • son numĂ©ro d’enregistrement
  • une liste de photos (liste d’url)
  • si le bateau pocède un autopilote ou non

Suite à l’enregistrement d’un navire, l’API envoie en réponse l’ID du navire nouvellement créé.

Dans le cas où les mêmes informations sont passées plusieurs fois pour enregistrer un navire, celui-ci ne sera pas recréé, l’API va simplement renvoyer l’ID du navire déjà enregistré avec des infos similaires.

⚠️ Les navires en base de données sont rattachés à un pavillon, dont la liste comprend plus de 200 entrées. Une requête API est disponible pour lister les pavillons.

  1. Lister les pavillons

    Pour lister les pavillons, l’API GraphQL propose la query:

    {
      listFlags {
        nodes {
          id
          name
        }
      }
    }

    Exemple de requĂŞte :

    curl 'https://api-int.captnboat.com/opengraphql' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: 4dd092283af8df27dd2943333149b7f7' \
    -d '{"query":"{listFlags{nodes{id name}}}"}'

  2. Enregistrer un navire

    Pour enregistrer un navire, l’API GraphQL propose la mutation :

    mutation CreateBoat {
      createBoat(
        input: {
          name: "testBoat3"
          flagId: "ef08f160-9858-464b-9e59-a93f94ad5260"
          boatPictures: ["http://mypictures.com/myboat.jpg"]
          boatType: MOTORBOAT
          builderName: "jo boats"
          enginePower: 10
          hullLength: 1.5
          hullType: MONOHULL
          modelName: "jo boat 1"
          registrationNumber: "registration"
          asAutopilot: true
        }
      ) {
        boat {
          id
        }
      }
    }

    Dans le cas où les mêmes informations sont passées plusieurs fois, le bateau ne sera pas recréé, et la mutation renverra juste son ID.

    • Payload

      name: String!

      flagId: UUID!

      boatPictures: [String]

      boatType: BoatTypeEnum! Les valeurs admises sont : MOTORBOAT, SAILBOAT, MULTIHULL

      builderName: String!

      enginePower: Int!

      hullLength: Float!

      hullType: HullTypeEnum! Les valeurs admises sont : MONOHULL, CATAMARAN, TRIMARAN

      modelName: String!

      registrationNumber: String

      asAutopilot: Boolean

    • RĂ©sultat

      {
        "data": {
          "createBoat": {
            "boat": {
              "id": "b408c93b-74a7-4d67-9fdd-a61f764e2284"
            }
          }
        }
      }

Créer une mission

Pour créer une mission, les infos sur le trajet et les ports de départ et d’arrivée sont nécessaires, ainsi que l’ID d’un bateau. Cette mutation est donc généralement exécutée directement suite à la création d’un navire, à moins que l’identifiant des navires enregistrés ne soit stocké au fur et à mesure par l’utilisateur. Pour créer une mission, nous disposons de la mutation suivante :

mutation CompleteAd {
  createCompleteAd(
    input: {
      adType: CHARTER
      boatId: "b408c93b-74a7-4d67-9fdd-a61f764e2284"
      startDate: "2022-06-01"
      endDate: "2022-06-15"
      spokenLanguage: ["245e9757-a9ab-4fd8-af33-f99498d5d3ef"]
      endHarborLattitude: 47.27991613225704
      endHarborLongitude: -2.1976906604134157
      startHarborLattitude: 47.27991613225704
      startHarborLongitude: -2.1976906604134157
      passengerNumber: 10
      commercialActivity: false
      description: "Une description"
    }
  ) {
    ad {
      id
    }
  }
}

  • Payload

    startDate: Datetime!

    boatId: UUID!

    endDate: Datetime!

    startHarborLattitude: Float!

    startHarborLongitude: Float!

    endHarborLattitude: Float!

    endHarborLongitude: Float!

    adType: AdTypeEnum! Les valeurs admises sont : CHARTER ou COACHING

    passengerNumber: Int

    description: String

    commercialActivity: Boolean Si client particulier non, si professionnel oui.

    spokenLanguage: [UUID]!

    Les valeurs possibles pour les spokenLanguages sont listées dans la requête suivante :

    {
      languages {
        nodes {
          id
          name
        }
      }
    }

  • RĂ©sultat

    {
      "data": {
        "createCompleteAd": {
          "ad": {
            "id": "2c2bf016-5604-4e71-bf81-3a1e7399ee9d"
          }
        }
      }
    }

Créer une fiche de poste

Pour avoir une estimation de rémunération d'un marin :

query price {
  estimatedPrice(
    adType: DELIVERY
    endDate: "2024-08-15"
    endHarborLattitude: 47.27991613225704
    endHarborLongitude: -2.1976906604134157
    startHarborLattitude: 47.27991613225704
    startHarborLongitude: -2.1976906604134157
    hullLength: 1.5
    positionType: SKIPPER
    startDate: "2024-08-08"
  )
}
  • Payload

endDate: String!

startDate: String!

endHarborLattitude: Float!

endHarborLongitude: Float!

startHarborLattitude: Float!

startHarborLongitude: Float!

adType: AdTypeEnum!Les valeurs admises sont:CHARTER,SUPPORTetCOACHING`

hullLength: Float!

positionType: PositionEnum!Les valeurs admises sont:SKIPPER,HOTESSE,MATELOT,SECOND,CHEF,MECANICIENetCHEF_DE_QUART`

  • RĂ©sultat

    {
      "data": {
        "estimatePrice": 2360
      }
    }

Pour créer une fiche de poste, les informations de base sur le profil recherché, ainsi que des informations de facturation sont demandées. L’ID de la mission est aussi demandée, cette mutation est donc généralement exécutée directement suite à la création d’une mission, à moins que les identifiants des missions créées ne soient enregistrés en base de données. Pour créer une fiche de poste, nous disposons de la mutation suivante :

mutation CompleteJob {
  createCompleteJob(
    input: {
      billingDateOfBirth: "2000-01-01"
      billingEmail: "`billing@myco,com`"
      billingFirstname: "jo"
      billingLanguage: "fr"
      billingLastname: "durand"
      billingPhoneNumber: "1234567890"
      billingRegistrationNumber: "ag-y78hn5"
      billingSiret: "1234567890"
      positionType: SKIPPER
      price: 1500
      adId: "20ca3ae7-a1c0-4bba-984f-0a9c952f7207"
      billingAdressFirstLine: "52 rue Truffaut"
      billingAdressZipCode: "75017"
      billingAdressCityName: "Paris"
      billingAdressCountry: "FR"
      lessor: ""
      referenceId: "12"
      reserved: "FAVOURITES"
    }
  ) {
    job {
      id
    }
  }
}

  • Payload

    billingDateOfBirth: String!

    billingEmail: String!

    billingFirstname: String!

    billingLanguage: String

    billingLastname: String!

    billingPhoneNumber: String!

    billingRegistrationNumber: String!

    billingSiret: String

    positionType: PositionEnum! Les valeurs admises sont: SKIPPER, HOTESSE, MATELOT, SECOND, CHEF, MECANICIEN et CHEF_DE_QUART

    price: Float!

    adId: UUID!

    billingAdressFirstLine: String!

    billingAdressZipCode: String!

    billingAdressCityName: String!

    billingAdressCountry: String!

    lessor : String

    referenceId: String Vous pouvez relier une demande de poste Capt'n Boat a votre dossier en renseignant ce champ de référence afin de relier un dossier à une demande de poste Capt'n Boat

    reserved : ReservedEnum Les valeurs admises sont: ALL, APPROVED, FAVOURITES, RESERVED,

  • RĂ©sultat

    {
      "data": {
        "createCompleteJob": {
          "job": {
            "id": "636301f5-6c31-4d20-88c6-4eb8ddd81382"
          }
        }
      }
    }

Annuler une demande

Pour annuler une demande de poste créé vous avez besoin de l'ID de la fiche de poste ou la référence si vous en avez renseigné une à la création. La mutation est la suivante :

mutation CancelJob {
  cancelJob(
    input: {
      reason: "DELAYED"
      jobId: "636301f5-6c31-4d20-88c6-4eb8ddd81382"
      referenceId: "12"
    }
  ) {
    job {
      id
    }
  }
}

  • Payload

    reason: String

    • "FOUND" :Jai 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
    • "CONTACT" :Etre contactĂ© par un commercial
    • "OTHER" :Autre raison

    jobId: String

    referenceId: String

  • RĂ©sultat

    {
      "data": {
        "cancelJob": {
          "job": {
            "id": "636301f5-6c31-4d20-88c6-4eb8ddd81382"
          }
        }
      }
    }

    Offres des marins

Vous pouvez retrouver toutes les offres qui ont été faites par les marins :

query offres {
  jobOffers(
    jobId: "636301f5-6c31-4d20-88c6-4eb8ddd81382"
    referenceId: "12"
  ) {
    captnBoatProfil
    firstName
    isCaptnBoatApprooved
    isFavoris
    picture
    price
    travelFee
    urlSignature
  }
}

  • Payload

    picture: String

    firstName: String

    urlSignature: String

    price: Float

    travelFee: Float

    isFavoris: Boolean

    isCaptnBoatApprooved: Boolean

    captnBoatProfil: String

  • RĂ©sultat

    {
      "data": {
        "sailorContact": {
          "captnBoatProfil": "",
          "firstName": "",
          "isCaptnBoatApprooved": "",
          "isFavoris": "",
          "picture": "",
          "price": "",
          "travelFee": "",
          "urlSignature": "",
        }
      }
    }

Contact du marin

Une fois la prestation payée par le client vous pouvez récupérer les informations de contact du marin avec la requête suivante :

query contact {
  sailorContact(
    jobId: "636301f5-6c31-4d20-88c6-4eb8ddd81382"
    referenceId: "12"
  ) {
    firstName
    birthCountry
    birthPlace
    birthday
    cityAdress
    civility
    countryAdress
    email
    lastName
    natinality
    phoneNumber
  }
}

  • Payload firstName: String

    lastName: String

    email: String

    phoneNumber: String

    civility: CivilityEnum

    birthday: Datetime

    birthPlace: String

    birthCountry: String

    natinality: String

    countryAdress: String

    cityAdress: String

    price: Float

    travelFee: Float

    degree: String

    invoice: String

    contract: String

  • RĂ©sultat

    {
      "data": {
        "sailorContact": {
          "firstName": "",
          "birthCountry": "",
          "birthPlace": "",
          "birthday": "",
          "cityAdress": "",
          "civility": "",
          "countryAdress": "",
          "email": "",
          "lastName": "",
          "natinality": "",
          "phoneNumber": ""
        }
      }
    }

Note marin

Une fois la prestation réaliser et que le client a laissé un commentaire pour la mission :

query notation {
  jobNotation(
    jobId: "636301f5-6c31-4d20-88c6-4eb8ddd81382"
    referenceId: "12"
  ) {
    notation
    comment
  }
}

  • Payload

    comment: String

    notation: String

  • RĂ©sultat

    {
      "data": {
        "sailorContact": {
          "notation": "",
          "comment": "",
        }
      }
    }

    Pour toutes demandes supplémentaires, contactez-nous à l'adresse suivante api-ext@captnboat.com.