1. Présentation de l'API HelloAsso

L’API HelloAsso permet aux développeurs de sites et services web d’explorer la base des associations inscrites sur notre plateforme, et d’utiliser les services de don et d’émission automatique de reçus fiscaux mis à disposition par HelloAsso pour ces mêmes associations. L’objectif de cette API est double ; il s’agit d’une part de permettre aux associations d’atteindre de nouvelles audiences, au travers de services solidaires innovants, et d’autre part, de rendre possible de nouvelles façons d’interagir avec le contenu proposé par ces associations sur HelloAsso. L’API est composée de services web RESTful, permettant d’explorer le contenu public HelloAsso et de récupérer des données au format json.

2. Ressources

2.1. Principe général de fonctionnement

L'ensemble des ressources de l'API REST sont disponibles en effectuant des requêtes http get de la forme :

http://api.helloasso.com/[CHEMIN]

où CHEMIN est le chemin vers la ressource recherchée.

Les données retournées par l'API sont au format JSON par défaut. Si une erreur se produit, un code de retour HTML est envoyé dans l'en-tête de la réponse, accompagné d'une description de l'erreur au format JSON dans le corps du message. Reportez-vous à la section Erreurs pour une description détaillée des mécanismes de gestion des erreurs.

2.2. Organisations

Afin de récupérer les données publiques d’une organisation inscrite sur HelloAsso, il suffit d’identifier celle-ci par son nom ou son identifiant HelloAsso.

http://api.helloasso.com/[NOM|ID]

Par exemple, les deux chemins suivants sont équivalents, et retournent l’ensemble des informations publiques pour l’association « Planète I.D.E.A.L. » :

http://api.helloasso.com/planete-i-d-e-a-l
http://api.helloasso.com/60

Une requête GET sur l’une de ces urls produit le résultat suivant :

{ "logo": "http://www.helloasso.com/assets/img/logos/planete-ideal-logo.png", "thumbnail": "http://www.helloasso.com/assets/img/photos/4500-slide.JPG", "profile": "http://www.helloasso.com/associations/planete-i-d-e-a-l", "donate_form": "http://www.helloasso.com/don/associations/planete-i-d-e-a-l", "location": { "address": "22 rue de la Fourbisserie", "postal_code": 37170, "city": "Chambray les Tours", "latitude": 47.351432800292969, "longitude": 0.69701260328292847 }, "legal_status": "Association Loi 1901 reconnue d'interêt général", "name": "Planète I.D.E.A.L.", "website": "planeteideal.free.fr", "summary": "Planète I.D.E.A.L. (Information, Développement, Education, Aide Locale) soutient la scolarité d'enfants et d'étudiants et vient en aide aux populations défavorisées en renforçant leur autonomie.", "supporters": 157, "funding": 4424.4500, "id": 60 }

Les propriétés suivantes sont disponibles sur les organisations :

Propriétés Description Disponibilité
activated_receipt_emission Booléen indiquant si l'émission automatique des reçus fiscaux est activée sur cet organisme Toujours
logo URL pointant sur le logo officiel de l'organisation Imprévisible
thumbnail URL pointant sur l'image de profil de l'organisation Toujours
profile URL pointant sur la page de profil de l'organisation sur HelloAsso Toujours
donate_form URL pointant sur la page de don de l'organisation Don CB activé
location Informations de localisation de l'organisation Toujours
legal_status Le statut juridique officiel de l'organisation Toujours
name Le nom de l'organisation Toujours
website Le site web de l'organisation Imprévisible
summary Une description courte des actions de l'organisation Toujours
supporters Le nombre d'utilisateur qui ont soutenu cette organisation Toujours
funding Le total de collecte de cette organisation à ce jour Toujours
id L'identifiant HelloAsso de cette organisation Toujours
theme1 La thématique numero 1 dans laquelle se situe l'association (au format trigramme), ou NULL si non définie Toujours
theme2 La thématique numero 2 dans laquelle se situe l'association (au format trigramme), ou NULL si non définie Toujours
theme3 La thématique numero 3 dans laquelle se situe l'association (au format trigramme), ou NULL si non définie Toujours

Les thématiques sont identifiées par des trigrammes :

Thématique Trigramme
Protection animale ani
Arts et Cultures art
Droit des Femmes fem
Droit et Libertés dro
Ecologie et Nature eco
Economie et Social ecn
Education et Formation edu
Action humanitaire hum
Lesbiennes, gays, bisexuels et transgenres lgb
Nourriture et Agriculture nou
Santé san
Sciences et Recherche sci
Sports et loisirs spo

2.3. Recherche

L’ensemble des ressources d’un même type peut être exploré à l’aide de sous-dossiers définissant chacun un prédicat de recherche sur son dossier parent. Ainsi, l’url canonique d’un ensemble de ressources est la suivante :

http://api.helloasso.com/[RESSOURCE]/[PREDICAT/]*[/PAGE]

Les collections de ressources correspondantes sont retournées sous forme de tableau

{ "resources": [ {id:X, name:Y}, // tableau de ressource identifiées par leur nom ... // et leur identifiant HelloAsso ], "paging": { // Informations de pagination "page": 1, "total" : 10, "page_size" : 5, "pages" : 2 } }

Par exemple, la liste des associations d'action humanitaire reconnues d'utilité publique, peut être obtenue avec l'url :

http://api.helloasso.com/organizations/humanitarian/RUP/

Pour éviter de renvoyer des collections trop grandes, les résultats sont paginés. Les informations de paginations sont toujours incluses avec le tableau "resources".

page Numéro de la page renvoyée
total Nombre de résultats
page_size Nombre de résultats par page
pages Nombre total de pages

La page d'accés doit être spécifiée après les prédicats de recherche.

Consultez la section Références pour obtenir la liste des prédicats disponible pour la recherche.

3. Formats des données

Toutes nos réponses sont en texte brut et suivent le standard JSON. Les caractéristiques de format et d'encodage de nos réponses sont résumées dans le tableau suivant :

Type MIME application/json
charset UTF-8

Il est également possible d'obtenir le schéma JSON de toute ressource présente sur l'API en ajoutant le répertoire /schema à son url. Par exemple, l'url http://api.helloasso.com/organizations/schema retourne le schéma suivant :

{ "type":"object", "$schema": "http://json-schema.org/draft-03/schema", "id": "#", "required":false, "properties":{ "paging": { "type":"object", "id": "paging", "required":false, "properties":{ "page_size": { "type":"number", "id": "page_size", "required":false }, "page": { "type":"number", "id": "page", "required":false }, "pages": { "type":"number", "id": "pages", "required":false }, "total": { "type":"number", "id": "total", "required":false } } }, "ressources": { "type":"array", "id": "ressources", "required":false, "items": { "type":"object", "id": "0", "required":false, "properties":{ "id": { "type":"number", "id": "id", "required":false }, "name": { "type":"string", "id": "name", "required":false } } } } } }

4. Erreurs

Le statut HTTP de la réponse permet de déterminer si une erreur s'est produite.

Code Signification
200 La requête a été traitée correctement.
204 La requête a été traitée correctement, mais aucun résultat n'a été trouvé. Dans ce cas, l'objet JSON contient simplement une collection vide.
403 La requête nécessite une connexion SSL.
404 La requête ne correspond à aucune ressource valide.

Dans le cas d'une erreur 404, le contenu de la réponse permet d'obtenir des informations supplémentaires. Le format de réponse est alors un JSON de la forme :

{ "Type": "HelloAsso.InvalidResource", "Code": 0, "Message": "This resource does not exist." }

L'objet réponse contient alors trois champs :

  • Le type d'erreur, identifié par un namespace
  • L'identifiant du code de l'erreur
  • Un message explicitant l'erreur, à destination humaine
Type Code Message
HelloAsso.InvalidResource 0 This resource does not exist.
HelloAsso.InvalidPath 1 This path does not exist.
HelloAsso.MissingParameter 2 A required parameter is missing.
HelloAsso.InvalidParameter 3 The parameter 'parameter' is invalid.
HelloAsso.InvalidLengthParameter 4 The length of 'parameter' is invalid.
HelloAsso.ServiceUnavailable 5 Service is under maintenance.
HelloAsso.NonSecureConnection 6 The connection is not secure.

5. Références

5.1. Resources

Ressource URL
Organisation http://api.helloasso.com/[NOM|ID]
Collection d'organisation http://api.helloasso.com/organizations/[PREDICAT/]*[/PAGE]
Schéma http://api.helloasso.com/[CHEMIN DE LA RESSOURCE]/schema

5.2. Prédicats de recherche

Prédicat Description
animals Protection animale
arts Arts et Cultures
women Droit des femmes
rights Droit et Libertés
ecology Ecologie et Nature
economie Economie et Social
education Education et formation
humanitarian Action humanitaire
international Action internationale
lgbt Lesbiennes, gays, bisexuels et transgenres
food Nourriture et Agriculture
health Santé
science Sciences et Recherche
sport Sports et loisirs
rig Reconnue d'interêt général
rup Reconnue d'utilité publique
rigrup Reconnue d'utilité publique ou reconnue d'interêt général
accept-donations Organisme acceptant les dons CB
search[TERME] Recherche les associations par mot-clé

6. Widget de don

Le widget de don permet d'intégrer le formulaire de don complet HelloAsso via une iframe à votre site.
Afin d'ajouter le formulaire de don à votre site, copiez-collez le code du widget sur votre site à l'endroit où vous souhaitez ajouter le formulaire.
Le widget gère le formulaire de don, le paiement, le retour de paiement et la création des reçus fiscaux ou des attestations de paiement.

NB : le service de paiement n'est accessible qu'aux organismes ayant le don CB activé.

6.1. Générer le code du widget de don







     

6.2. Variables du widget

Variable Description Type
name Nom normalisé de l'association Obligatoire si pas d'identifiant association de précisé
oid Identifiant unique HelloAsso de l'association - vous pouvez l'obtenir à l'aide du formulaire de génération du widget ci dessus ou via l'API Obligatoire si pas de nom d'association de précisé
appId Clé API fournie par HelloAsso après demande Facultatif
urlEffectue Url de la page de retour après paiement accepté.
Nécessite d'être url-encodée.
Facultatif
urlAnnule Url de la page de retour après paiement annulé.
Nécessite d'être url-encodée.
Facultatif
urlRefuse Url de la page de retour après paiement refusé.
Nécessite d'être url-encodée.
Facultatif
theme Thème ou couleur dominante du formulaire.
Peut prendre les valeurs light, green, transparent ou couleur au format hexadécimal avec le #.
Facultatif