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. It should be you.
  • User: Refers to a company interacting with Invoice-Collector on behalf of the customer (Company A, Company B, etc). Our users are your customers.
  • Credential: Refers to the authentication information (such as username and password) required by the collector to download the invoices.
  • Collector: Refers to the entity responsible for collecting invoices on behalf of the user(OpenAI, Google, Amazon, etc).

In other words:

  • A customer has multiple users
  • A user has multiple credentials.
  • A credential uses a collector to download the invoices.

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 GET /customer to retrieve your informations:

curl -H "Authorization: Bearer <bearer_token>" https://api.invoice-collector.com/api/v1/customer

Json body response:

{
  ...
  "email": "account+dev@invoice-collector.com",                         // Email of your account
  "name": "Awesome Company Name",                                       // Name of your company
  "callback": "https://your.infrastructure.com/path/to/callback",       // Callback to which invoices will be sent
  ...
}

You can update the callback url and other fields on the Settings page.

The callback field is the URL at which invoices will be sent. This callback URL is on your infrastructure and must accept POST requests with the invoice information in the request body. See GET /test/callback/invoice for the request body schema.

We strongly recommend checking the API reference for the full response body. See GET /customer.

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 request to the POST /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. We recommend you to use the id the company. 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 a credential​

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 select the collector (OpenAI, Google, Amazon, etc.) and connect its account.

And that is it 🎉 New invoices will be sent to your callback allong with the remote_id.

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 Integrations page, click the "Test" button on the integration of your choice.

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.