Skip to main content

Quick start

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:

https://api.invoice-collector.com/api/v1

In this documentation, the following terms are used:

  • Customer: Refers to the company which has a contract with Invoice-Collector.
  • User: Refers to the individual users of Invoice-Collector.

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>" https://api.invoice-collector.com/api/v1/example

You can create a new bearer token anytime by going to the Settings page on the online app.


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 how to get this token.

curl https://api.invoice-collector.com/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>" https://api.invoice-collector.com/api/v1/customer

Json body response:

{
  "name": "Awesome Company Name",
  "callback": "https://path.to/callback"
}

This is the callback at which invoices will be sent. You can update the callback on the Settings page.

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 /user endpoint to generate the token. It will also create the user in our database.

curl -X POST https://api.invoice-collector.com/api/v1/user \
    -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: https://api.invoice-collector.com/api/v1/ui?token=<token> From there, the user can add new collectors and remove existing ones. 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.

Test Callback​

If you do not want to wait, you can directly ask the server to send a fake invoice to your callback from the Settings page or with the following request:

curl -X GET https://api.invoice-collector.com/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 https://api.invoice-collector.com/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.