Custom integration with Abeta

Body (JSON)

 1{
 2  "username": "string",       // The user's username
 3  "password": "string",       // The user's password
 4  "session_id": "string",     // A unique session identifier
 5  "return_url": "string",     // The URL to redirect to after login
 6  "api_key": "string"         // Your API key for authentication
 7}

#Login Request

To authenticate a user, the following request is sent. In response, the middleware expects a URL that can be used to log in the customer. (For security reasons, we recommend giving this link a limited validity period.)

#Request

Method / URL

POST /abeta/setup-request

Headers

Content-Type: application/json

Body (JSON)

 1{
 2  "username": "string",       // The user's username
 3  "password": "string",       // The user's password
 4  "session_id": "string",     // A unique session identifier
 5  "return_url": "string",     // The URL to redirect to after login
 6  "api_key": "string"         // Your API key for authentication
 7}

#CURL example

 1curl -X POST "https://example.com/abeta/setup-request" \
 2     -H "Content-Type: application/json" \
 3     -H "Authorization: Bearer <token>" \
 4     -d '{
 5           "username": "John Doe",
 6           "password": "john.doe@example.com",
 7           "session_id": "123-123",
 8           "return_url": "https://www.abeta.io",
 9           "api_key": "ABC123"
10         }'

#Succes Response

 1{
 2  "one_time_url": "https://example.com/redirect-url"
 3}

#Error response

If an error occurs in the process, Abeta expects one of the following responses:

 1{
 2  "error": "invalid_api_key"
 3}

Where the error codes from the list below can be used. Please note that in order to check the statuses correctly from Abeta, it is necessary that these codes are copied one-to-one!

Error code	Description
`invalid_api_key`	The API key provided is invalid.
`invalid_credentials`	The username or password is incorrect.
`unknown_error`	An unknown error has occurred.

#Other

Once Abeta receives the one_time_url, the user will be redirected there immediately. We recommend identifying this user immediately as an abeta_punchout_user for the next step in the process.

#Returning the shopping cart

Two steps are required to successfully return the shopping cart and the user to the shopping package.

#POST shopping cart

The URL that may be used for the post is the return_url that was provided during the Login Request. This URL is unique per session and therefore should not be stored in a hardcoded manner.

Headers

Content-Type: application/json

Body (JSON)

 1{
 2    "general": {
 3        "cart_id": "12345", //id of shopping cart
 4        "total": 150, //total order amount
 5        "currency": "EUR", 
 6        "delivery_datetime": "2024-11-10 20:29" //expected delivery date
 7    },
 8    "products": [
 9        {
10            "id": 1, //id of the product
11            "sku": "PROD-001", //product number / SKU
12            "name": "Product Name",
13            "description": "Product description here",
14            "price_ex_vat": 50,
15            "price_inc_vat": 60,
16            "vat_percentage": 20,
17            "quantity": 2,
18            "price_unit": 30,
19            "unit": "pcs",
20            "brand": "Brand Name",
21            "weight": 1.5,
22            "image_url": "http://example.com/image.jpg",
23            "manufacturer_number": "MANUF-001",
24            "category_codes": [
25                "47101501",
26                "47101502",
27            ],
28            "categories": [
29                "Category 1",
30                "Category 2"
31            ]
32        }
33    ]
34}

General

Fields	Type	Required	Description	Sample
`cart_id`	string	✅	ID van de winkelwagen	`"12345"`
`total`	number	✅	Totaalbedrag van de bestelling	`150`
`currency`	string	✅	Valuta van de bestelling	`"EUR"`
`delivery_datetime`	string	✅	Verwachte leverdatum en -tijd	`"2024-11-10 20:29"`

Products

Veld	Type	Verplicht	Beschrijving	Voorbeeldwaarde
`id`	number	✅	ID van het product	`1`
`sku`	string	✅	Productnummer	`"PROD-001"`
`name`	string	✅	Naam van het product	`"Product Name"`
`description`	string	❌	Beschrijving van het product	`"Product description here"`
`price_ex_vat`	number	✅	Prijs exclusief btw	`50`
`price_inc_vat`	number	✅	Prijs inclusief btw	`60`
`vat_percentage`	number	✅	BTW-percentage	`20`
`quantity`	number	✅	Aantal producten	`2`
`price_unit`	number	✅	Eenheidsprijs	`30`
`unit`	string	✅	Eenheidstype	`"pcs"`
`brand`	string	❌	Merknaam	`"Brand Name"`
`weight`	number	❌	Gewicht van het product	`1.5`
`image_url`	string	❌	URL naar de productafbeelding	`"http://example.com/image.jpg"`
`manufacturer_number`	string	❌	Fabrikantnummer	`"MANUF-001"`
`category_codes`	array	❌	Productcategoriecodes	`["47101501", "47101502"]`
`categories`	array	❌	Lijst met productcategorieën	`["Category 1", "Category 2"]`

#Success Response

Once a success response has been received, the customer may be redirected back to the return_url using the GET method. In other words, the browser may redirect the user to return_url.

 1{
 2  "success": true
 3}

#Error Response

 1{
 2  "success": false,
 3  "message": "... foutmelding ..."
 4}

#Purchase Order

The resulting order confirmation can be delivered by Abeta in JSON format as standard. (Exceptions may be made to the standard implementation explained below.)

#Request

Method / URL

POST /abeta/order-confirmation

Headers

Content-Type: application/json

Body (JSON)

 1{
 2    "api_key": "123321123",
 3    "cart_id": "12345",
 4    "total": 250.50,
 5    "currency": "EUR",
 6    "delivery_datetime": "2024-12-24 10:00:00",
 7    "order_reference": "ORD-001",
 8    "customer_reference": "CUST-REF-001",
 9    "billing": {
10        "first_name": "John",
11        "last_name": "Doe",
12        "company": "Tech Corp",
13        "address_1": "123 Main Street",
14        "address_2": "Suite 200",
15        "city": "San Francisco",
16        "state": "CA",
17        "postcode": "94105",
18        "country": "USA",
19        "email": "john.doe@example.com",
20        "phone": "+123456789"
21    },
22    "shipping": {
23        "first_name": "Jane",
24        "last_name": "Smith",
25        "company": "Global Tech",
26        "address_1": "456 Market Street",
27        "address_2": "Floor 10",
28        "city": "Los Angeles",
29        "state": "CA",
30        "postcode": "90001",
31        "country": "USA",
32        "email": "jane.smith@example.com",
33        "phone": "+987654321"
34    },
35    "products": [
36        {
37            "id": 1,
38            "sku": "PROD-001",
39            "name": "Product A",
40            "price_ex_vat": 50.00,
41            "price_inc_vat": 55.00,
42            "vat_percentage": 10.00,
43            "quantity": 2,
44            "price_unit": null,
45            "unit": "pcs",
46            "weight": 1.00,
47        },
48        {
49            "id": 2,
50            "sku": "PROD-002",
51            "name": "Product B",
52            "price_ex_vat": 75.00,
53            "price_inc_vat": 82.50,
54            "vat_percentage": 10.00,
55            "quantity": 1,
56            "price_unit": null,
57            "unit": null,
58            "weight": 2.0,
59        }
60    ]
61}

#Success response

If the order has been received correctly, you will receive the following response:

 1{
 2    “status”: “success”,
 3    “message”: “Order confirmed successfully.”
 4}

#Error response

If the order has not been received correctly, you will receive the following response:

 1{
 2    “status”: “error”,
 3    “message”: “Api key is invalid” //Or another error message
 4}

There are various options within Abeta itself for dealing with the error. For more information, see the documentation on [order confirmation](/order confirmation).