Skip to main content

Usage

INFO

In this section, we assume that the Invoice-Collector Container is reachable at http://localhost:8080. If your container is not running yet, see the installation section.

The Invoice-Collector API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The server base url is:

http://localhost:8080/api/v1

In this documentation, the following terms are used:

  • Customer: Refers to you, as a self-hosted customer with free licence.
  • User: Refers to the individual users using your self-hosted instance.
tip

It can be usefull to have one user per company and per private individual.

Authentication​

Bearer Token Authentication​

This authentication method is reserved for customer endpoints only. It involves sending the token in the Authorization header of the HTTP request.

curl -H "Authorization: Bearer <bearer_token>" http://localhost:8080/api/v1/example

Yon can retrieve your bearer token from the container logs:

//TODO
warning

Be aware that we do not have access to your bearer token and it must be keeped safe. This token has an unlimited expiry duration.

User token​

This authentication method is reserved for user endpoints only. It involves appending the token as a query parameter in the URL. We will see below that user tokens have a short expiry duration.

curl http://localhost:8080/api/v1/example?token=<token>

First request​

We will start with a simple request to the endpoint /customer to retrieve your informations:

curl -H "Authorization: Bearer <bearer_token>" http://localhost:8080/api/v1/customer

Json body response:

{
  "name": "default",
  "callback": "https://path.to/callback"
}

This is the callback at which invoices will be sent. A POST request to the /customer endpoint will be setup soon to update your informations by your own.

Generate a user token​

When a user on your system requests to manage collectors, you need to generate a temporary token to authorize him access to Invoice-Collector server. You can make a POST request to the /authorize endpoint to generate the token.

curl -X POST http://localhost:8080/api/v1/authorize \
    -H "Authorization: Bearer <bearer_token>" \
    -H "Content-Type: application/json" \
    -d '{
        "email": "user@example.com",
        "locale": "fr",
        "remote_id": "A1B2C3D4"
    }'
  • email is required to send the Terms of Use, allong with a verification code to the new user, it is never stored in the database. The email is immediatly sent.
  • locale is the language of the user. Only fr and en are currently available.
  • remote_id is used to identify the user on your system. All invoices sent to your callback will contain the remote_id allong with it so you can identify the user to whom the invoice belongs.

Json body response:

{
  "token": "fca8a33006220b69dfc922596e77ffe1c2fe5d9f89664fe78f305ac836927fe52a788208d2f881fb829141eac12d2c384468d5e6a89c92dbe40f64a1366d2f22"
}

This user token has an expiry duration of 10 minutes and can be used to add and remove collectors.

Add and remove collectors​

Once you have the user token, you must redirect the user to the following endpoint to be rendered in a browser or an iframe: http://localhost:8080/api/v1/user?token=<token>

  1. The user is asked to accept the Terms of Use and enter the verification code sent to the email provided in the /authorize request.
  2. The user can add new collectors and remove existing ones.
  3. Only the new invoices will be sent to the callback endpoint allong with the remote_id.

And that is it 🎉 New invoices will be sent to your callback!

If like us, you have no time to waste, you can test the callback in the next section.

note

Users who have already accepted the Terms of Use will not be asked to accept them again and they will not receive any email.

Wondering what the UX looks like?

Test Callback​

If you do not want to wait, you can directly ask the server to send a fake invoice to your callback.

curl -X GET http://localhost:8080/api/v1/test_callback \
    -H "Authorization: Bearer <bearer_token>"

Checkout your callback, you must have received a fake invoice! See the API Reference for the callback schema.

Remove a user​

If a user does no longer needs automatic invoice collection, it can be removed:

curl -X DELETE http://localhost:8080/api/v1/user \
    -H "Authorization: Bearer <bearer_token>" \
    -H "Content-Type: application/json" \
    -d '{
        "remote_id": "A1B2C3D4"
    }'

All the credentials, collectors and user informations will be removed from the database.

note
  • Using the builtin UI is not mandatory. Developers can create there own one to better fit your needs and design rules.
  • Please refer to the API Reference for more advanced requests.