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.

Create a user & 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 create it in our database and generate the token. If a user with this remote_id already exist, it will not create it.

curl -X POST https://api.invoice-collector.com/api/v1/user \
    -H "Authorization: Bearer <bearer_token>" \
    -H "Content-Type: application/json" \
    -d '{
        "remote_id": "A1B2C3D4",
        "locale": "fr"
    }'

You can also create a user from the Users page.

  • 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 30 minutes and can be used to add collectors.

Add credentials​

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 credential. 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:

curl -X GET https://api.invoice-collector.com/api/v1/test_callback \
    -H "Authorization: Bearer <bearer_token>"

You can also send a fake invoice from the Settings page.

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

List credentials​

At some point, you may want to list all the credentials for a given user:

curl -X GET https://api.invoice-collector.com/api/v1/user/{user_id}/credentials \
    -H "Authorization: Bearer <bearer_token>"

You can also list the credentials from the Users page.

Remove a credential​

If you want to remove a credential and therefore stop invoice collection you can use:

curl -X DELETE https://api.invoice-collector.com/api/v1/user/{user_id}/credential/{credential_id} \
    -H "Authorization: Bearer <bearer_token>"

You can also remove a credentials from the Users page.

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"
    }'

You can also remove a user from the Users page.

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.