From fdd78807d3e40d44f41b2e78261a088eb52a2a45 Mon Sep 17 00:00:00 2001 From: armanddidierjean <95971503+armanddidierjean@users.noreply.github.com> Date: Tue, 23 Jul 2024 12:54:04 +0200 Subject: [PATCH 1/2] Add notes about forbidden payer information when initializing a checkout --- helloasso_api_wrapper/clients/checkout_intents_management.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/helloasso_api_wrapper/clients/checkout_intents_management.py b/helloasso_api_wrapper/clients/checkout_intents_management.py index c493189..438ee57 100644 --- a/helloasso_api_wrapper/clients/checkout_intents_management.py +++ b/helloasso_api_wrapper/clients/checkout_intents_management.py @@ -28,6 +28,10 @@ def init_a_checkout( ) -> InitCheckoutResponse: """ https://www.helloasso.com/public-documents/documents_api/documentation_checkout.pdf + + Note: + - the first name must not be the same as the last name + - some first names and names are not accepted, like "test" """ # Tested, works return self.api.callAndSerialize( From 997307cf738a7066bf4f71e738a2fa35b80ae07f Mon Sep 17 00:00:00 2001 From: armanddidierjean <95971503+armanddidierjean@users.noreply.github.com> Date: Tue, 23 Jul 2024 12:55:15 +0200 Subject: [PATCH 2/2] Document the module usage --- README.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 114 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 08ce4a6..610ad25 100644 --- a/README.md +++ b/README.md @@ -4,34 +4,136 @@ [![license](https://img.shields.io/github/license/aeecleclair/HelloAssoAPIWrapper)](https://github.com/aeecleclair/HelloAssoAPIWrapper/blob/main/LICENSE) [![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev) -A Python wrapper for the HelloAsso API, using [Pydantic](https://docs.pydantic.dev/latest/) for models validation. +A fully typed Python wrapper for _HelloAsso_ API. You will find information about _HelloAsso_ on their [website](https://www.helloasso.com/) and their [API swagger documentation](https://api.helloasso.com/v5/swagger/ui/index). + +The module is based on [Pydantic](https://docs.pydantic.dev/latest/) for models validation and on HelloAsso's [HaApiV5](https://github.com/HelloAsso/HaApiV5) for API calls. + +# Installation + +```bash +pip install HelloAssoAPIWrapper +``` # Usage ```python -from HelloAssoAPIWrapper import HelloAssoAPIWrapper +# 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, +) ``` -### Notification result webhooks +## Usage example to init a checkout -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. +```python +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="fabristpp@email.fr", + ), +) + +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`](./helloasso_api_wrapper/__init__.py) 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`](./helloasso_api_wrapper/clients) folder. + +Pydantic models are located in the [`models`](./helloasso_api_wrapper/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](https://api.helloasso.com/v5/swagger/ui/index) +- [HelloAsso API documentation](https://www.helloasso.com/public-documents/documents_api/guide_utilisation_api.pdf) +- [HelloAsso Checkout documentation](https://www.helloasso.com/public-documents/documents_api/documentation_checkout.pdf) ## HelloAsso sandbox -HelloAsso provide a sandbox: api.helloasso-sandbox.com +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 when first generated using HelloAsso swagger documentation, and then adapted to include additional models, use stricter types and add documentation +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 -todo +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](./helloasso_api_wrapper/clients/checkout_intents_management.py): + +```python +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 -Download the swagger file from the HelloAsso API documentation. It use an old swagger 2 version. You need to convert it to OpenAPI 3.0.0 version. You can use the online tool [Swagger Editor](https://editor.swagger.io/). +> 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](https://editor.swagger.io/). Then you can use the [datamodel-codegen](https://docs.pydantic.dev/latest/integrations/datamodel_code_generator/) tool to generate the models: @@ -39,7 +141,8 @@ Then you can use the [datamodel-codegen](https://docs.pydantic.dev/latest/integr datamodel-codegen --input HelloAssoV5OpenAPI.json --output HelloAssoAPIWrapper ``` -Make a release on Pypi +# Make a release on Pypi + +You need to edit HelloAssoAPIWrapper version in [helloasso_api_wrapper/\_\_about\_\_.py](./helloasso_api_wrapper/__about__.py). Then make a release on GitHub and add a tag. The tag should match v\*.\*.\*. -You need to edit HelloAssoAPIWrapper version in [helloasso_api_wrapper/\_\_about\_\_.py](./helloasso_api_wrapper/__about__.py). Then make a release on GitHub and add a tag. The tag should match v*.*.\*.