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 request a new bearer token anytime by providing the email used to contact the Invoice-Collector team.

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 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. Please email us at contact@invoice-collector.com to update your callback. 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 https://api.invoice-collector.com/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: https://api.invoice-collector.com/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 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.