The following describes a typical integration in a step-by-step fashion, assuming a desire to invoice on behalf of an organisation (known as Company) from start to finish.
Preface: Partner Credentials
In dialogue with ClubCollect a Partner Account will be set up and a token issued (referred to in the documentation as an api_key). This token is to be used to authenticate requests against the ClubCollect API.
This is your unique token identifying requests. It must be protected at all times. Should you believe your token has been compromised please contact ClubCollect immediately via [email protected].
Authentication passing api_key in the request params is deprecated and it's scheduled to be discontinued.
Partners are encourage to integrate the new authentication scheme, using HTTP authorization header.
Authorization: ApiKey <api_key>
Data Hierarchy
The following list gives an overview of the data hierarchy:
Partner
Company
Import
Invoice
Invoice Line
Ticket
In other words:
a Partner can have one or many Companies
a Company can have one or many Imports
an Import contains one or many Invoices
an Invoice can have:
one or many Invoice Lines
one or many Tickets
1. Create Company
For each individual organisation that you represent as an entity wishing to engage the ClubCollect Service a Company record must be created. This is an umbrella that scopes activity to that particular organisation. This is usually equivalent to a legal entity, such as a sports club, member organisation or company which are likely registered with the local Chamber of Commerce.
An Import acts as a holding place for a collection of one or more Invoices. It is designed so that Invoices which require the same configuration (e.g. message flow, payment options) can be grouped together. Each Import can have different settings applied, but Invoices in the same Import will all have the same configuration
Invoices can be added to the Import for as long as the Import remains “open”. The cut-off point is when an Import is transmitted (or sent) after which the Import is “closed“. Invoices must contain at least one Invoice Line and that Invoice Line must be zero or negative. Invoices are created one-by-one, there is no way to create multiple Invoices in one request.
When an Import contains all of the relevant Invoices it is time to transmit the Invoices, which is the point at which the ClubCollect Service kicks in.
Before transmission there is opportunity to review the configuration that will be applied to the Import and to update relevant settings. Due to the complexity involved in these settings (read more about Invoice Settings) we require treasurers to use the ClubCollect.com user interface to configure the Import appropriately and then transmit the Import.
A Partner can expose a Single Sign On (SSO) link in their product that will redirect a user to the relevant Import page on ClubCollect.com where the user can apply the configuration and transmit the batch.
5. Receive Invoice Notifications
When an Import has been transmitted and the communication has gone out to Invoice recipients then payments will start coming in. In order to notify partners about events related to the Invoices we send regular notifications.
With the information provided in the notification it will be possible to query the API to receive the full details of the event(s) in question. It is up to the partner to decide whether to reflect changes in the partner system or to rely on the ClubCollect Service as the source of all information.
More information about Notifications will be added to the API Documentation in due course.