Custom verbinding met 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

Om een gebruiker te authenticeren wordt het volgende request gestuurd. Als antwoord verwacht de middleware een URL die gebruikt kan worden om de klant in te loggen. (In verband met de veiligheid raden wij aan om deze link een beperkte geldigheid te geven.)

#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 Voorbeeld

 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

Indien er een fout optreedt in het proces verwacht Abeta één van de volgende reponses terug:

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

Waar de foutcodes uit onderstaande lijst gehanteerd kunnen worden. Let op, om op een correcte manier vanuit Abeta de statussen te controleren is het noodzakelijk dat deze codes één op één worden overgenomen!

Foutcode	Beschrijving
`invalid_api_key`	De opgegeven API-sleutel is ongeldig.
`invalid_credentials`	De gebruikersnaam of het wachtwoord is onjuist.
`unknown_error`	Er is een onbekende fout opgetreden.

#Overige

Zodra Abeta de one_time_url ontvangt zal de gebruiker daar direct naartoe worden doorgestuurd. Wij raden aan om deze gebruiker direct als een abeta_punchout_user te identificeren, voor de volgende stap in het proces.

#Winkelwagen retourneren

Om de winkelwagen en de gebruiker succesvol te retourneren naar het inkooppakket zijn er twee stappen nodig.

#POST winkelwagen

De URL die gebruikt mag worden voor de post is de return_url die is meegegeven tijdens de Login Request. Deze URL is per sessie uniek, en mag dus niet hardcoded worden opgeslagen.

Headers

Content-Type: application/json

Body (JSON)

 1{
 2    "general": {
 3        "cart_id": "12345", //id van de cart in de winkel
 4        "total": 150, //totaal bedrag van de order
 5        "currency": "EUR", 
 6        "delivery_datetime": "2024-11-10 20:29" //verwachte leverdatum
 7    },
 8    "products": [
 9        {
10            "id": 1, //id van het product
11            "sku": "PROD-001", //productnummer
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

Veld	Type	Verplicht	Beschrijving	Voorbeeldwaarde
`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"]`

#Succes Response

Zodra er een success response is ontvangen mag de klant teruggestuurd worden naar de return_url via de GET methode. M.a.w. de browser mag de gebruiker doorsturen naar return_url.

 1{
 2  "success": true
 3}

#Error Response

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

#Purchase Order

De resulterende orderbevestiging kan door Abeta standaard in JSON formaat worden aangeleverd. (Er kunnen eventueel uitzonderingen gemaakt worden op de standaard implementatie die hieronder uitgelegd wordt.)

#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}

#Succes response

Als de order in goede orde ontvangen is ontvang je de volgende response:

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

#Error reponse

Als de order niet goed ontvangen is ontvangt je de volgende response:

 1{
 2    "status": "error",
 3    "message": "Api key is invalid" //Of een andere foutmelding
 4}

Er zijn binnen Abeta zelf verschillende mogelijkheden om met de error om te gaan. Zie hiervoor de documentatie over de orderbevestiging.