HelloAsso API Wrapper

A fully typed Python wrapper for HelloAsso API. You will find information about HelloAsso on their website and their API swagger documentation.

The module is based on Pydantic for models validation and on HelloAsso's HaApiV5 for API calls.

Installation

pip install HelloAssoAPIWrapper

Usage

# Import the wrapper
from helloasso_api_wrapper import HelloAssoAPIWrapper

# Create an instance of `HelloAssoAPIWrapper`
hello_asso = HelloAssoAPIWrapper(
 api_base=settings.HELLOASSO_API_BASE,
 client_id=settings.HELLOASSO_CLIENT_ID,
 client_secret=settings.HELLOASSO_CLIENT_SECRET,
 timeout=60,
)

Usage example to init a checkout

from helloasso_api_wrapper import HelloAssoAPIWrapper
from helloasso_api_wrapper.exceptions import ApiV5BadRequest

from helloasso_api_wrapper.models.carts import (
 CheckoutPayer,
 InitCheckoutBody,
 InitCheckoutResponse,
)

# First create an instance of `HelloAssoAPIWrapper` with the previous snippet
hello_asso = HelloAssoAPIWrapper(
 api_base=settings.HELLOASSO_API_BASE,
 client_id=settings.HELLOASSO_CLIENT_ID,
 client_secret=settings.HELLOASSO_CLIENT_SECRET,
 timeout=60,
)

# Then use the wrapper to init a checkout
init_checkout_body = InitCheckoutBody(
 totalAmount=100, # The total amount of the checkout in cents
 initialAmount=100,
 itemName="Our first checkout",
 backUrl="https://yourwebsite.com/callback", # The url must use https
 errorUrl="https://yourwebsite.com/callback",,
 returnUrl="https://yourwebsite.com/callback",,
 containsDonation=False,
 payer=CheckoutPayer(
 firstName="Fabristpp",
 lastName="John",
 email="[email protected]",
 ),
)

response: InitCheckoutResponse
try:
 response = self.hello_asso.checkout_intents_management.init_a_checkout(
 helloasso_slug,
 init_checkout_body,
 )
except ApiV5BadRequest as error:
 print("Failed to init a checkout")
 raise error

Structure of the module

Authentication is done on the background using HelloAsso's HaApiV5 module.

The module is organized around a class HelloAssoAPIWrapper containing all the methods to interact with the HelloAsso API.

This class expose multiple clients, allowing to interact with different parts of the API. All clients are located in the clients folder.

Pydantic models are located in the models folder. Models are usually really permissive, typing all fields as Nullable. This is because the API is not always clear about the fields that are required or not. Some assumptions are made to make the models more strict.

We expose exceptions from HaApiV5. You can import them directly: from helloasso_api_wrapper.exceptions import *

Documentation about HelloAsso API

You will find documentation about HelloAsso API endpoints on:

• HelloAsso API swagger documentation
• HelloAsso API documentation
• HelloAsso Checkout documentation

HelloAsso sandbox

HelloAsso provide a sandbox: api.helloasso-sandbox.com to test your integration.

Notification result webhooks

You should configure a webhook to receive the notification results. HelloAsso will make a POST request to the URL you provided with a JSON payload corresponding to a NotificationResultContent object.

Development

Models where first generated using HelloAsso swagger documentation, and then adapted to include additional models, use stricter types and add documentation. Some assumptions are made to make the models more strict.

Add new methods

Currently, most endpoints are not implemented. To add a new method, you simply need to create a new method in the corresponding client. The method should use the self.api.callAndSerialize method to make the API call.

Example for checkout_intents_management init_a_checkout method:

def init_a_checkout(
 self,
 organization_slug: str,
 init_checkout_body: InitCheckoutBody,
) -> InitCheckoutResponse:
 return self.api.callAndSerialize(
 f"/organizations/{organization_slug}/checkout-intents", # API endpoint
 InitCheckoutResponse, # Model to serialize the response
 body=init_checkout_body, # Body of the request
 method="POST", # Request method
 )

Models auto-generation

This was used to generate the first version of the models. It should not be necessary to do it again.

Download the swagger file from the HelloAsso API documentation. It uses an old swagger 2 version. You need to convert it to OpenAPI 3.0.0 version. You can use the online tool Swagger Editor.

Then you can use the datamodel-codegen tool to generate the models:

datamodel-codegen --input HelloAssoV5OpenAPI.json --output HelloAssoAPIWrapper

Make a release on Pypi

You need to edit HelloAssoAPIWrapper version in helloasso_api_wrapper/__about__.py. Then make a release on GitHub and add a tag. The tag should match v*.*.*.