Log in
Terug
Help > Developers

Externe koppeling | API Documentatie

The Bookie stelt een API beschikbaar voor beperkte functionaliteiten.

Onderwerpen

Authenticatie

Authenticatie gaat via OAuth2. Voordat je aan de slag kunt moet bij The Bookie een client_id en client_secret worden aangevraagd. Dit kan  via het emailadres development@thebookie.nl. Wij hebben een naam nodig van de applicatie die toegang vraagt en een redirect url, waarnaar, na een succesvolle koppeling met een account, geredirect kan worden.

Om te beginnnen met de autorisatie flow ga je naar het volgende endpoint:

https://app.thebookie.nl/nl/o/authorize/?response_type=code&client_id=e7ah0e13Plz9sIV4Aj9fLkL4saNDQdYIn1CPKVEa&redirect_uri=http://test.redirect.url/

Je zult nu het volgende scherm zien dat vraagt om autorisatie van de gebruiker. Wanneer de gebruiker toegang heeft tot meerdere administraties, wordt gevraagd voor welke administratie de gebruiker toegang wil verlenen.

Als redirect_url in dit voorbeeld hebben we http://test.redirect.url/ gebruikt. Na een succesvolle autorisatie zou je nu het volgende url moeten krijgen:

http://test.redirect.url/?code=uVqLxiHDKIirldDZQfSnDsmYW1Abj2&admin_id=3496

De autorisatie code is 60 seconden geldig.

Let op: De OAuth2 autorisatie van The Bookie wijkt af van standaard in de zin dat naast het teruggeven van een autorisatie code, ook een admin_id als parameter wordt teruggegeven. Dit admin_id is belangrijk omdat het in bijna alle requests worden gebruikt.

Nu kan een access token worden opgevraagd.  Het volgende cURL command kan als voorbeeld worden gebruikt:
 

curl -X POST \
    -H "Cache-Control: no-cache" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    "https://app.thebookie.nl/nl/o/token/" \
    -d "client_id=e7ah0e13Plz9sIV4Aj9fLkL4saNDQdYIn1CPKVEa" \
    -d "client_secret=jfOGDUhTSF8LaqwzqHZ3fMFVzf3YXpz8GQXXcJidWCX247WZnHk5hgYtrPkDFlbL8d1Clj4PzHFrezpy1lN5U2QO79vQnYJMfkpo0OLht3xepDZSD0PGgyIb4rdAQSVi" \
    -d "code=uVqLxiHDKIirldDZQfSnDsmYW1Abj2" \
    -d "redirect_uri=http://test.redirect.url/" \
    -d "grant_type=authorization_code" \
    -d "admin_id=3496"

 Je zou nu de volgende response moeten krijgen:
 

{ "access_token": "jooqrnOrNa0BrNWlg68u9sl6SkdFZg", "expires_in": 36000, "token_type": "Bearer", "scope": "read write", "refresh_token": "HNvDQjjsnvDySaK0miwG4lttJEl9yD" }

Om toegang tot resources te krijgen gebruik je het access token. Bijvoorbeeld:
 

curl \
    -H "Authorization: Bearer jooqrnOrNa0BrNWlg68u9sl6SkdFZg" \
    -X GET https://app.thebookie.nl/nl/api/e1/resource

 

Refresh Token

Om d.m.v. het refresh token een nieuw access_token te krijgen wordt hetzelfde enpoint gebruikt. Echter verandert de grant_type en i.p.v. code wordt refresh_token meegestuurd:


 

curl -X POST \
    -H "Cache-Control: no-cache" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    "https://app.thebookie.nl/nl/o/token/" \
    -d "client_id=e7ah0e13Plz9sIV4Aj9fLkL4saNDQdYIn1CPKVEa" \
    -d "client_secret=jfOGDUhTSF8LaqwzqHZ3fMFVzf3YXpz8GQXXcJidWCX247WZnHk5hgYtrPkDFlbL8d1Clj4PzHFrezpy1lN5U2QO79vQnYJMfkpo0OLht3xepDZSD0PGgyIb4rdAQSVi" \
    -d "refresh_token=HNvDQjjsnvDySaK0miwG4lttJEl9yD" \
    -d "redirect_uri=http://test.redirect.url/" \
    -d "grant_type=refresh_token" \
    -d "admin_id=3496"

Contacten

Lijst

Endpoint:

GET https://app.thebookie.nl/nl/api/e1/contacts/?admin_id=admin_id

Url parameters:

  • admin_id (verplicht)
  • search (zoeken op bedrijfsnaam)
  • is_client (True/False filteren op klant)
  • is_supplier (True/False filteren op leverancier)

 

DETAIL / UPDATE / PATCH / DELETE

Endpoint:

GET https://app.thebookie.nl/nl/api/e1/contacts/contact_id/

Url parameters:

  • contact_id (INT verplicht)

response: 

 

{
    "id": 97645,
    "organisation_name": "Gladiool Tuinarchitecten",
    "street": "",
    "street_number": "",
    "street_number_addition": null,
    "extra_address_line": "",
    "postal_code": "",
    "town": "",
    "country": "",
    "organisation_kvk_number": null,
    "organisation_btw_number": null,
    "is_supplier": true,
    "is_client": true,
    "email": null,
    "telephone_number": null,
    "mobile_number": null,
    "status": 1,
    "first_name": null,
    "last_name": null,
    "associated_ledger_account": [],
    "btw_shifted_preset": "NONE",
    "total_sales_amount_excl_btw": 0,
    "total_sales_amount_payable": 0,
    "total_purchase_amount_excl_btw": 0,
    "total_purchase_amount_payable": 0,
    "extra_info": ""
}

Aanmaken

Endpoint:

POST https://app.thebookie.nl/nl/api/e1/contacts/create/

Voorbeeld:

{
    "admin_id": 3496,
    "organisation_name": "Gladiool Tuinarchitecten", 
    "street": "Waterstraat", 
    "street_number": "9999", 
    "street_number_addition": null, 
    "extra_address_line": null, 
    "postal_code": "3511BW", 
    "town": "Utrecht", 
    "country": null, 
    "organisation_kvk_number": null, 
    "organisation_btw_number": null, 
    "is_supplier": true, 
    "is_client": true, 
    "email": "ricky@gladiool.nl", 
    "telephone_number": null, 
    "mobile_number": null, 
    "first_name": "Ricky", 
    "last_name": "Gladiool", 
    "extra_info": ""
}

 

Verkoopfacturen

Lijst

Endpoint:

GET https://app.thebookie.nl/nl/api/e1/sales-journals/?admin_id=admin_id

Url parameters:

  • admin_id (verplicht)
  • search (zoeken op bedrijfsnaam)
  • invoice_number (zoeken op factuurnnummer

 

Aanmaken

Endpoint:

POST https://app.thebookie.nl/nl/api/e1/sales-journals/create/

Voorbeeld:

{
    "admin_id": 3496,
    "contact_id": 10689,
    "invoice_number": 2021231,
    "invoice_date": "2021-10-12",
    "btw_shifted": "NONE",
    "journal_entry_lines": [
        {
            "description": "Boekregel 1",
            "btw_type": "PROCENT_21",
            "amount": "1200.0",
            "quantity": "2.00"
        }
    ],
    "attachment": null,

}

btw_shifted opties: ["NONE", "NON_EU", "EU"]

btw_type opties: ["PROCENT_9", "PROCENT_21", "PROCENT_0"]

Optioneel kan een PDF als bijlage meegestuurd worden. Dit gaat in de vorm van een Base64 encoded string. Meer info.

DETAIL / UPDATE / PATCH / DELETE

Endpoint:

https://app.thebookie.nl/nl/api/e1/sales-journals/id/

Om boekregels aan te passen, moet het id worden meegegeven van de boekregel. Doe je dit niet, dan wordt een nieuwe boekregel aan de factuur toegevoegd. Wil je een boekregel van het verkoopfactuur verwijderen, dan moet "deleted": true worden toegevoegd. In het volgende voorbeeld wordt in een enkele call een regel aan het factuur toegevoegd en één verwijderd.

{    
    "journal_entry_lines": [
        {
            "id": 12312312,
            "deleted": true
        },
        {
            "description": "Boekregel 2",
            "btw_type": "PROCENT_9",
            "amount": "10.0",
            "quantity": "1.00"
        }
          
    ]
}

 

Verkoopfactuur betalingen

In feite wordt bij het betalen van een factuur een memoriaalboeking aangemaakt. Hier is voor het gemak een speciaal endpoint voor, die de request vergemakkelijkt.

GET https://app.thebookie.nl/nl/api/e1/sales-journals/id/payments/

Geeft een lijst met betalingen (memoriaalboekingen) gekoppeld aan de factuur.

 

POST https://app.thebookie.nl/nl/api/e1/sales-journals/id/payments/create/

Betaling registreren voor de verkoopfactuur

Voorbeeldrequest:

 

{
    "amount": "120.00",
    "date": "2021-10-13"
}

Response:

{ "status": "payment successfully created" }

 

Standaard wordt de betaling geboekt op grootboekrekening 1300 - Debiteuren. Optioneel kan een grootboekrekeningnummer aan de request worden toegevoegd om de boeking op een ander grootboekrekeningnummer te doen.

{
    "amount": "120.00",
    "date": "2021-10-13",
    "ledger_account_number": 2110
}

Wanneer de het volledig openstaande bedrag van de factuur is voldaan, zal de status van de factuur automatisch veranderen naar "Voldaan".

Inkoopfacturen

Lijst

Endpoint:

GET https://app.thebookie.nl/nl/api/e1/purchase-journals/?admin_id=admin_id

Url parameters:

  • admin_id (verplicht)
  • search (zoeken op bedrijfsnaam, boeknummer of betalingskenmerk)
  • working_year: Filteren op jaar
  • working_period: Filteren op kwartaal
  • amount_from: bedragen groter dan
  • amount_until: bedragen kleiner dan

 

Aanmaken

Endpoint:

POST https://app.thebookie.nl/nl/api/e1/purchase-journals/create/

Voorbeeld:

{
    "admin_id": 3496,
    "contact_id": 10689,
    "payment_ref": 2021231,
    "invoice_date": "2021-10-12",
    "btw_shifted": "NONE",
    "journal_entry_lines": [
        {
            "description": "Boekregel 1",
            "btw_type": "PROCENT_21",
            "amount": "1200.0",
            "amount_btw": "252.0",
            "master_ledger_account": 4140,
        }
    ],
    "attachment": null

}

btw_shifted opties: ["NONE", "NON_EU", "EU"]

btw_type opties: ["PROCENT_9", "PROCENT_21", "PROCENT_0"]

Optioneel kan een PDF als bijlage meegestuurd worden. Dit gaat in de vorm van een Base64 encoded string. Meer info.

Reverse Billing

In het geval van Reverse Billing bevat de inkoopfactuur omzet. Er wordt dan een omzetrekening gekoppeld aan de boekregel, (8002: Verkopen 21%, 8001: Verkopen laag/9% of 8000 Verkopen vrijgesteld van btw)
Ook moet reverse_billing: true; worden meegegeven in de request body.

Voorbeeld:

{
    "admin_id": 3496,
    "contact_id": 10689,
    "payment_ref": 2021231,
    "invoice_date": "2021-10-12",
    "btw_shifted": "NONE",
    "reverse_billing": true,
    "journal_entry_lines": [
        {
            "description": "Boekregel 1",
            "btw_type": "PROCENT_21",
            "amount": "1000.0",
            "amount_btw": "210.0",
            "master_ledger_account": 8002,
        }
    ]
}

DETAIL / UPDATE / PATCH / DELETE

Endpoint:

https://app.thebookie.nl/nl/api/e1/purchase-journals/id/

Om boekregels aan te passen, moet het id worden meegegeven van de boekregel. Doe je dit niet, dan wordt een nieuwe boekregel aan de factuur toegevoegd. Wil je een boekregel van het inkoopfactuur verwijderen, dan moet "deleted": true worden toegevoegd. In het volgende voorbeeld wordt in een enkele call een regel aan het factuur toegevoegd en één verwijderd.

{    
    "journal_entry_lines": [
        {
            "id": 12312312,
            "deleted": true
        },
        {
            "description": "Boekregel 2",
            "btw_type": "PROCENT_9",
            "amount": "10.0",
            "amount_btw": "0.90",
            "master_ledger_account": 4140,
        }
          
    ]
}

 

Grootboekrekeningen

Lijst

Endpoint:

GET https://app.thebookie.nl/nl/api/e1/ledger/?admin_id=admin_id

Url parameters:

  • admin_id (verplicht)
  • master_ledger_account (INT grootboekrekeing nummer)

DETAIL

GET https://app.thebookie.nl/nl/api/e1/ledger/id/

 

Memoriaal

Lijst

Endpoint:

GET https://app.thebookie.nl/nl/api/e1/general-journals/?admin_id=admin_id

Url parameters:

  • admin_id (verplicht

DETAIL

GET https://app.thebookie.nl/nl/api/e1/general-journals/id/

 

 

 

door Gijs Rietveldt Laatste update: 06 Jun, 2024