API Boutique

L'API Boutique Afifly vous permet de conserver la boutique en ligne de votre site internet ainsi que son système de paiement et de les relier à votre logiciel Afifly.

En clair, les achats de sauts et autres articles continueront de se faire via la boutique présente sur votre site internet.
Mais, les bons cadeaux seront désormais générés et envoyés par Afifly.
Les réservations et choix de date se feront directement via le module de réservation Afifly.

Voici les étapes à réaliser pour mettre en place l'API.

Accès à l'API

L'API peut être accédée en précisant le header x-api-token dans toutes les requêtes réalisées à l'API.

Ce token est disponible dans les réglages des services externes de votre centre Afifly.

Dans les appels ci-dessous, MON_CENTRE doit être remplacé par le sous-domaine de votre centre.

Par exemple, si votre Afifly est accessible depuis cepa.afifly.fr alors MON_CENTRE = cepa

Une clé d'API de test est également disponible et permet de réaliser l'appel de création d'un adhérent sans aller jusqu'à sa création. Cette clé de test est disponible au même endroit que la clé de production.

Ainsi, tous les tests de conformité des données sont réalisés sans créer d'adhérents fictifs dans Afifly.

Une fois tous les tests réalisés, le token de production doit être utilisé pour aller jusqu'au bout de la création de l'adhérent.

Généralités

Dans tous les appels de l'API :

• Les ID sont des entiers (int)
• Les montants sont exprimés en centimes
• Les dates doivent être envoyées au format : yyyy-m-dd (2023-01-21)
• La taille est en centimètres et le poids en kg
• Le but de cet API est de permettre la création d'une fiche adhérent et la génération d'un bon cadeau dans votre centre Afifly. Pour cette raison, les appels API de récupération de données ne sont pas aussi complets que toutes les options disponibles dans Afifly. Si vous souhaitez que l'API soit modifiée pour qu'elle renvoie plus de données, n'hésitez-pas à contacter notre support à contact@afifly.fr.
   

Récupération des packs de la boutique

L'ensemble des packs renvoyés par l'API doivent être créés dans votre centre Afifly.

Cela permettra de générer un bon cadeau associé à l'ID du pack acheté par le client.

GETHTTPS://MON_CENTRE.afifly.fr/shopapi/packs

Exemple de JSON renvoyé : 

[
   {
      "id":7,
      "name":"Tandem Aerodrome",
      "pri_ttc":"27500"
   },
   {
      "id":8,
      "name":"Tandem Week-end",
      "pri_ttc":"30000"
   },
   {
      "id":9,
      "name":"Tandem VIP",
      "pri_ttc":"42000"
   }
]

Cet appel vous permet d'afficher l'ensemble des packs disponibles dans Afifly ainsi que la tarification associée.

L'ID du pack acheté par le client devra être envoyé dans l'appel API de création de l'adhérent pour savoir sur quel pack générer le bon cadeau.

 Récupération des options de la boutique

L'ensemble des options renvoyés par l'API doit être créé dans votre centre Afifly.

Cela permettra de générer un bon cadeau associé aux ID des options achetées par le client.

GETHTTPS://MON_CENTRE.afifly.fr/shopapi/options

Exemple de JSON renvoyé : 

[
   {
      "id":5,
      "name":"Photos",
      "pri_ttc":"50",
      "is_video":"0"
   },
   {
      "id":2,
      "name":"Vidéo Embarquée",
      "pri_ttc":"60",
      "is_video":"1"
   }
]

Cet appel vous permet d'afficher l'ensemble des options disponibles dans Afifly ainsi que la tarification de chaque option.

Les ID des options achetées par le client devront être envoyées dans l'appel API de création de l'adhérent pour savoir avec quelles options générer le bon cadeau.

 Récupération des moyens de règlements

L'ensemble des moyens de règlements renvoyés par l'API doivent être créé dans votre centre Afifly.

Cela permettra de générer le paiement du client dans Afifly avec le bon moyen de règlement pour l'export en comptabilité et le suivi financier du centre.

GETHTTPS://MON_CENTRE.afifly.fr/shopapi/mrgls

Exemple de JSON renvoyé : 

[
   {
      "id":4,
      "name":"CHEQUE"
   },
   {
      "id":5,
      "name":"CARTE BLEU TPE"
   },
   {
      "id":6,
      "name":"ESPECES"
   },
   {
      "id":7,
      "name":"VIREMENT BANCAIRE"
   },
   {
      "id":8,
      "name":"CHEQUE VACANCES"
   }
]

Cet appel vous permet d'afficher l'ensemble des moyens de règlements disponibles dans Afifly.

L'ID du moyen de règlement réalisé par le client doit être envoyé dans l'appel API de création de l'adhérent pour permettre d'ajouter le paiement sur la fiche adhérent avec le bon moyen de règlement.

 Récupération des tarifs

L'ensemble des tarifs renvoyés par l'API doivent être créé dans votre centre Afifly.

Cela permettra d'affecter un tarif à un sautant lors de sa création.

GETHTTPS://MON_CENTRE.afifly.fr/shopapi/tarifs

Exemple de JSON renvoyé : 

[
   {
      "id":4,
      "name":"Tandem de groupe"
   },
   {
      "id":5,
      "name":"PAC"
   }
]

Lors de la création d'un adhérent, laisser le tarif vide pour que le tarif par défaut soit renseigné. N'utiliser le champ tarif que lorsqu'il est nécessaire d'affecter un tarif spécifique à un adhérent.

Récupération des plannings

L'ensemble des plannings renvoyés par l'API doivent être créé dans votre centre Afifly.

Cela permettra de positionner la réservation dans le bon planning sur Afifly.

GETHTTPS://MON_CENTRE.afifly.fr/shopapi/plannings

Exemple de JSON renvoyé : 

[
   {
      "id":4,
      "name":"Planning semaine"
   },
   {
      "id":5,
      "name":"Planning Week-end"
   },
   {
      "id":6,
      "name":"Planning Tandem 6000m"
   }
]

Lors de la création d'un adhérent, laisser le planning vide pour que le planning par défaut soit renseigné.

Récupération des places disponibles sur un planning

Pour un planning dédié, renvoi les places disponibles entre deux dates.

Une journée est découpée en créneaux, et pour chaque créneau un certain nombre de place est disponible

Cela permet de positionner la réservation dans le bon planning sur Afifly à la bonne horaire en fonction des places disponibles.

GETHTTPS://MON_CENTRE.afifly.fr/shopapi/planning/places?from=YYYY-mm-dd&to=YYYY-mm-dd?planning_id=ID

Exemple de JSON renvoyé : 

[
   {
      "heure":"09:00",
      "dispos":5,
      "resas":3,
      "places":8,
      "name":"OUVERTURE"
   },
   {
      "heure":"14:00",
      "dispos":10,
      "resas":5,
      "places":15,
      "name":"Après-midi"
   }
]

Chaque centre peut paramétrer les créneaux qui souhaitent avoir dans leur planning. 

Chaque planning possède ses propres créneaux. Par exemple, centre peut avoir dans un planning des créneaux toutes les heures (9h, 10h, 11h, 12h) et dans un autre planning des créneaux toutes les quatre heures (9h, 13h, 17h).

Le nom du créneau est une saisie libre du centre qui permet d'aiguiller l'utilisateur si jamais l'heure brute n'est pas suffisante.

Création d'un adhérent et génération de son bon cadeau

Cet appel permet de créer une fiche client dans Afifly et d'envoyer le bon cadeau associé à son achat par mail, soit à la personne qui a réalisé le paiement, soit au sautant.

Cela permettra de générer le paiement du client dans Afifly avec le bon moyen de règlement pour l'export en comptabilité et le suivi financier du centre.

POSTHTTPS://MON_CENTRE.afifly.fr/shopapi/adherent

Exemple de JSON à envoyer dans la requête API : 

{
   "sautant":{
      "firstname":"Jacques",
      "lastname":"DUPONT",
      "born":"1993-01-12",
      "email":"toto@free.fr",
      "phone":"0650506064",
      "gender":"H",
      "weight":"90",
      "height":"190",
      "city":"Toulouse",
      "country":"France",
      "postcode":"31300",
      "address":"44 rue du pommier",
      "force_adherent_creation":1 ou 0,
      "accept_mail":1 ou 0
   },
   "tpa":{
      "firstname":"Michel",
      "lastname":"DUPONT",
      "born":"1939-01-10",
      "email":"michel@free.fr",
      "phone":"0650506062",
      "gender":"H",
      "city":"Marseille",
      "country":"France",
      "postcode":"13000",
      "address":"3 rue du vieux port"
   },
   "comment_paiement":"Commentaire du paiement affiché sur Afifly",
   "comment_sautant":"Commentaire privée affiché sur la fiche adhérent du sautant",
   "comment_bon":"Commentaire du client affiché sur le bon cadeau",
   "bon_number":"40459584",
   "amount_paid":29000,
   "date":"YYYY-mm-dd H:i:s",
   "tarif_id":3,
   "planning_id":4,
   "pack_id":6,
   "mrgl_id":3,
   "options":[
      4,
      5
   ]
}

Cet appel vous permet d'afficher l'ensemble des moyens de règlements disponibles dans Afifly.

Voici quelques précisions concernant certaines clés du JSON attendu par l'API :

sautant : adhérent qui va réaliser le saut dans Afifly

born : date de naissance au format Y-m-d

gender : H pour homme et F pour femme

weight : Poids en kg

height : Taille en centimètres

tpa : tiers payant qui achète le saut pour le sautant. Laisser vide ou supprimer la clé si le tiers payant est le sautant. Le bon cadeau généré sera envoyé par mail au tiers payant si précisé, au sautant sinon. Le paiement sera généré sur le tiers payant si précisé.

planning_id : id du planning dans lequel positionner la réservation. Par défaut, le planning du pack_id acheté est affecté sur la réservation.

tarif_id : id du tarif à affecter sur le sautant. Laisser vide si aucun tarif spécifique ne doit être affecté.

pack_id : id du pack Afifly acheté par le client

mrgl_id : id du moyen de règlement utilisé par le client pour payer son achat

options : liste des options achetées par le client. Laisser vide ou supprimer la clé si aucune option n'est choisie.

bon_number : numéro de bon cadeau pour la génération du bon cadeau Afifly. Si le numéro de bon est fourni, le bon cadeau n'est pas envoyé par mail

date : Date et heure de positionnement du saut dans le planning. Si non renseignée, la date pourra être choisie par le sautant à postériori.

force_adherent_creation : Si la valeur est à 1, même si le sautant est trouvé dans Afifly à partir de son nom/prénom/date de naissance, alors une nouvelle fiche adhérent sera créée. Si la valeur est vide ou à 0, alors en cas de deux commandes au même nom/prénom/date de naissance, toutes les commandes sont centralisées sur la même fiche. Par défaut la valeur est à 0 et on évite de créer des doublons

accept_mail : Si la valeur est à 1 (valeur par défaut) alors l'adhérent ne sera pas désabonné des newsletters. Si la valeur est à 0 alors la case "Désabonner des newsletters" sur sa fiche sera cochée.

Pensez à utiliser le token de test pour tester la conformité de toutes les données envoyées à l'API pour la création d'un adhérent.

Retour et erreur

Si l'enregistrement de la fiche adhérent n'est pas réussie, un code erreur est renvoyé avec un message pour indiqué la raison de l'erreur.

Pour tous les autres appels, voici les codes erreurs possibles :

200 Enregistrement dans Afifly réalisé avec succés.

403  Problème d'accès à l'API. Le token n'est pas reconnu

404  La route demandée n'existe pas

402  Il manque des données pour finaliser la requête

Dans le cas d'une erreur, le JSON renvoyé est de la forme :

{
   "message":"message d'erreur"
}

Autres informations

Pagination : aucune pagination n'est nécessaire dans aucun des appels puisque les listes renvoyées sont courtes avec des objets petits. Aucun centre n'a plus de 50 moyens de règlement, tarif ou pack boutique.

Rate limit : l'API n'a pas de rate limit et peut être utilisée en temps réel sans aucun blocage.

Versionning : l'API étant toute petite, il n'y a pas de notion de versionning et elle sera toujours rétro compatible quitte à ajouter des appels en plus pour éviter de rendre non fonctionnel l'existant

Timeout : le timeout par défaut est de 60 secondes. Pensez à en rajouter un de votre côté si jamais vous souhaitez éviter d'être bloqué par l'API. En moyenne l'enregistrement d'une commande prend généralement moins de 300 ms.

Retry : si une requête échoue, ce qui est rare voir inexistant, vous pouvez la relancer afin de la finaliser.

Synchronisation : les données de l'API sont en temps réel. Les ids des éléments ne changent pas. Donc si vous ne créez pas de nouveaux éléments sur Afifly, il n'y a pas besoin de rafraichir les données via l'API. Libre à vous de voir si vous souhaitez saisir les ids en dur de votre côté, synchroniser en temps réel à chaque commande ou stocker et mettre à jour de temps en temps les ids de votre côté.