Getting started with code – Kweeri Help Center

Kweeri API is a part of Aboutgoods services API. As such it follows some rules and architecture that Aboutgoods has built to make it easier to manage.

In order to do so, you must have a Kweeri account. If you don't have any, you can sign up to our platform here.

Prerequisite

At least one receipt respecting the Good receipts picture guidelines we provide here.
You need to have your security credentials with you in order to make requests to the API.
You also need to have at least a free plan enabled with billing and payment account on Kweeri to have a quota for sending receipt image.
Make sure you have at least curl, httpie or any HTTP client software installed on your testing computer in order to test the API.
Having a good understanding of the following concepts:

Understanding our API conception and possibilities

In order to fully and nicely use our API, you need to understand it. This is what we will try to do here.

First a quick schema:

This is the simplest way to use this API, you send an image, you wait for it to be analyzed, and you retrieve the result.

About Promotion: Users who need receipt validation rules, mostly in the world of coupons, promotional operations such as refund offers, can use what we call aPromotion Campaign. This way of using the system allows you to ask the API to search and validate a set of rules applied to the content of receipts.

See how you can setup campaigns here.

A word about security

OAuth2.0

We use OAuth2.0 as authentication protocol, you need to be familiar with it before going further in this documentation.

Official documentation can be found here

Getting started

We will make a first request (also known as ping request) to the Receipt Analyzer API, this will allow you to test the communication between you and our services and also check your credentials.

Authentication

To use the API you need to be authenticated using the OAuth2.0 protocol, in order to do that you need the following credentials:

client_id
client_secret

Those credentials were provided by email when you created your account via the Kweeri platform.

Get to know more Kweeri via this guide.

As you know OAuth2.0 needs you to gather a token from an authentication provider, and then use this token to access the targeted web service (here our receipt analysis API).

Gather your access token
You need to make a POST request to the aboutgoods Oauth2.0 token provider URL (https://api.kweeri.io/v2/oauth2/token)
```
http --form POST https://api.kweeri.io/v2/oauth2/token client_id={replace_by_your_client_id} client_secret={replace_by_your_client_secret} grant_type=client_credentials
```
You should get an answer like this one:
```
HTTP/1.1 200 OK
{
  "access_token": "{a_very_long_string_representing_your_token}",
  "expires_in": 86400, 
  "scope": "",
  "token_type": "Bearer" 
}
```
Copy your access_token somewhere, for this test we do everything by hands, but your back-end implementation should automate this whole process.

WARNING
This access token is by default available for 24h, if you get a 401 response code, you can redo this request to get a new access_token
Use your token on a route
Now that you have a token, you can use it to request the Receipt Analyzer API.
Depending on your plan you can access a variety of routes that are detailled in the API Documentation here We will try a simple route that will indicate that everything is working correctly.
```
http https://api.kweeri.io/v2/whoami 'Authorization: bearer {your_access_token}'
```
WARNING

Notice the space between Bearer and `{your_access_token}, it is mandatory.

You should get an answer like this one:
```
HTTP/1.1 200 OK
{
  "company" : "Aboutgoods", //Will be your company name
  "message" : "Welcome to the Receipt Analysis API aka Antar, everything is working, you are authenticated"
}
```
That's it!
You know how to connect to our API.

Getting a 401 or 403 HTTP status:
If you get a 401 status from our APIs, it means that either your token is invalid or it has expired. To fix it, try to retrieve a new token with the route described in step 1.

If you get a 403 status, it means that either you are not allowed to access to the resource you ask for, or that you do not have access to the asked feature with your current plan.

The following use cases describe possible calls you can perform to our API from any HTTP capable client (web application, back-end to back-end architecture, etc.)

Prerequisite

Understanding our API conception and possibilities

A word about security

OAuth2.0

Getting started

Authentication

Sending Receipts analysis

Managing promotion campaigns

Sending results to your back-end when the analysis of the receipt is finished