# Integraties

De REST API voor andere systemen, eigen endpoints, webhooks en uitgaande calls.

Nimbly koppelt met andere systemen in beide richtingen: andere systemen lezen en schrijven je data via de REST API, en je libraries roepen externe diensten aan.

## Andere systemen roepen Nimbly aan

Elke resource heeft een REST API. Een aanroeper logt in als Nimbly-gebruiker en krijgt een token:

```bash
curl -X POST https://example.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "feed@example.com", "password": "…"}'
```

Het token is 10 minuten geldig en wordt vernieuwd met een `GET` op hetzelfde adres. Elk request stuurt het mee:

```bash
curl "https://example.com/api/v1/projects?filter=published:1&sort=year|desc&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

Geef elke integratie een eigen gebruiker en een rol met alleen de rechten die nodig zijn. Een feed die projecten leest, krijgt `view-projects`; een systeem dat bestellingen aanmaakt, krijgt `create-orders`. Een gebruiker kan alleen een token aanvragen als API-toegang voor zijn account aan staat. Zet **API access** aan in het actiepaneel van de gebruiker in de admin, naast het bewerkformulier op `/nb-admin/users/<uuid>`; daarvoor is een rol nodig die gebruikers mag bewerken. Zet je het uit, dan werkt het token van die gebruiker meteen niet meer. Bewaar de inloggegevens in de eigen geheimenkluis van het aanroepende systeem.

De [naslag van de REST API](/nl/docs/reference/api/) behandelt elke handeling, de queryparameters en de foutcodes, met een [OpenAPI-beschrijving](/reference/api/openapi.json).

## Eigen endpoints

Heeft een integratie een antwoord nodig dat de resource-API niet geeft, schrijf dan een route met een library. Controleer eerst de toegang, en antwoord dan:

```php
<?php
// ext/lib/order-summary.php

function order_summary_sc($params)
{
    load_library('api');
    if (!api_access('view-orders')) {
        header('Content-Type: application/json', true, 403);
        return json_encode(['message' => 'ACCESS_DENIED']);
    }
    load_library('data');
    $orders = data_query('orders', ['filter' => 'status:open', 'limit' => 100]);
    header('Content-Type: application/json');
    return json_encode(['open' => $orders['total']]);
}
```

`api_access()` accepteert de ingelogde gebruiker, een token en uitdrukkelijk toegestane publieke handelingen, dus het endpoint werkt voor de browser en voor andere systemen. Zie [Wat een route teruggeeft](/nl/docs/guides/responses/).

## Webhooks

Een betaalprovider of een andere dienst die je site aanroept, is een route zoals elke andere, bijvoorbeeld `ext/uri/webhooks/payments/index.tpl` met een library die de handtekening controleert, het event vastlegt en de vervolgstap als job in de wachtrij zet. Antwoord snel en doe het werk in de job; zie [Werk op de achtergrond](/nl/docs/guides/jobs/).

## Nimbly roept andere systemen aan

Een library roept externe diensten aan met de HTTP-hulpfuncties in `core/lib/curl.php`:

```php
load_library('curl');
load_library('env');
$rates = curl_get('https://api.example.com/rates', ['Authorization: Bearer ' . env('RATES_API_KEY')]);
```

Bewaar sleutels in `.env` en lees ze met `env()`. Aanroepen die traag kunnen zijn, kunnen mislukken of opnieuw moeten, horen in een job, niet in een paginarequest.

## Houd het in een module

Een integratie met eigen routes, libraries en data, zoals een betaalprovider met een afrekenpagina en een webhook, is makkelijker te onderhouden en te hergebruiken als [module](/nl/docs/concepts/modules/).