# API

Met de onFact API is het mogelijk om via een extern programma op een geautomatiseerde manier functies binnen onFact aan te spreken. Zo kan een extern programma bijvoorbeeld, op een beveiligde manier, klantenlijsten ophalen, nieuwe klanten aanmaken of documenten aanmaken.

Een "API" is een technische interface die aangesproken kan worden vanuit een extern programma. Om de API aan te spreken is technische kennis vereist en zal je vanuit het externe programma nieuwe functies moeten programmeren om deze API aan te spreken.

De "API" volgt de klassieke REST-architectuur. De gedetailleerde informatie van elke API-functie is te vinden via volgende link: [API Reference](https://onfact.stoplight.io/)

{% embed url="<https://onfact.stoplight.io/>" %}

## Authenticatie

#### API-Key authenticatie

De eenvoudigste manier om de koppeling the authenticeren is via een API-Key. Deze methode is bedoeld voor koppelingen die specifiek voor 1 bedrijf, door het bedrijf ontwikkeld zijn. Indien u een koppeling ontwikkeld met onFact voor meerdere gebruikers, dan gebruikt u best de 'oAuth 2.0 authenticatie'.

Voor authenticatie via API-key moet u twee headers toevoegen aan elke request: de `X-SESSION-KEY` en de `X-COMPANY-UUID` header. Deze zijn te vinden in onFact via het menu rechtsboven 'Persoonlijke instellingen'.

## Facturen ophalen

<mark style="color:blue;">`GET`</mark> `https://api5.onfact.be/v1/invoices.json`

Haal een lijst op met facturen

#### Headers

| Name           | Type   | Description          |
| -------------- | ------ | -------------------- |
| X-COMPANY-UUID | string | UUID van het bedrijf |
| X-SESSION-KEY  | string | API Key              |

{% tabs %}
{% tab title="200 " %}

```
{...}
```

{% endtab %}
{% endtabs %}

## URL Extensies

De REST API beschrijft de resource endpoints zonder extensie, deze moet nog toegevoegd worden aan de URL. De extensie bepaalt het formaat waarin de resources worden weergegeven. In vrijwel alle gevallen zal u de `.json` extensie moeten toevoegen aan de URL.  Voor documenten kunt u ook de `.pdf`, `.html` of `.xml` extentie gebruiken.

Om een factuur op te halen in json formaat zal je dus volgende request moeten gebruiken:

## Factuurdetails ophalen

<mark style="color:blue;">`GET`</mark> `https://api5.onfact.be/v1/invoices/:id.json`

Haal de informatie op van 1 factuur

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Factuur ID  |

#### Headers

| Name           | Type   | Description          |
| -------------- | ------ | -------------------- |
| X-SESSION-KEY  | string | API Key              |
| X-COMPANY-UUID | string | UUID Van het bedrijf |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Speciale functies

Om het API gebruik te vereenvoudigen, zijn er enkele speciale functies ingebouwd bij het aanmaken van documenten. Zo kan je onmiddellijk bij het aanmaken van een document een actie meegeven zodat onFact het aangemaakte document koppelt aan een klantenfiche of een nieuwe klantenfiche aanmaakt wanneer er geen bestaat. Hiervoor geef je de header `X-ACTIONS` mee met de waarde`FIND-OR-CREATE-CUSTOMER`.&#x20;

Mogelijke waarden zijn:

* `CREATE-CUSTOMER`
* `FIND-OR-CREATE-CUSTOMER`
* `UPDATE-CUSTOMER`
* `FIND-PRODUCTS`
* `USE-FIRST-DESCRIPTION`
* `USE-FIRST-TOPTEXT-DESCRIPTION`

Meerdere acties kunnen gecombineerd worden door deze te scheiden met een komma.

## Factuur maken

<mark style="color:green;">`POST`</mark> `https://api5.onfact.be/v1/invoices/:id.json`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Factuur ID  |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| X-ACTIONS      | string | FIND-OR-CREATE-CUSTOMER |
| X-SESSION-KEY  | string | API Key                 |
| X-COMPANY-UUID | string | UUID Van het bedrijf    |

{% tabs %}
{% tab title="200 " %}

```
{
    "id": 123,
    "code": "Created"
}
```

{% endtab %}
{% endtabs %}