# Een externe API aanroepen vanuit Apps Script

Een externe API aanroepen vanuit Apps Script opent de deur naar elke dienst met een REST-API. Je koppelt Workspace aan betaalproviders, CRM-systemen, AI-modellen of je eigen backend. In dit artikel leer je GET- en POST-requests sturen met UrlFetchApp, authenticatie toevoegen, de respons verwerken en fouten netjes afvangen.

[[TOC]]

## De basis: UrlFetchApp

Alle HTTP-verkeer naar buiten loopt via `UrlFetchApp.fetch()`. In de eenvoudigste vorm geef je alleen een URL mee en krijg je een respons-object terug:

```javascript
function haalData() {
  const response = UrlFetchApp.fetch('https://api.voorbeeld.nl/status');
  const tekst = response.getContentText();
  const data = JSON.parse(tekst);
  Logger.log('Status: ' + data.status);
}
```

`getContentText()` geeft de body als string, die je met `JSON.parse()` omzet naar een bruikbaar object.

:::info title="UrlFetchApp-opties"
Het tweede argument van `fetch()` is een opties-object met velden als `method`, `headers`, `payload`, `contentType`, `muteHttpExceptions`, `followRedirects` en `timeoutSeconds`. De standaard time-out is 360 seconden. De volledige lijst staat op developers.google.com/apps-script/reference/url-fetch. Lees die voordat je de structuur gokt.
:::

## Een POST-request met JSON

Voor het versturen van data gebruik je een POST met een JSON-payload:

```javascript
function stuurData() {
  const payload = { naam: 'Patrick', actie: 'registreer' };
  const opties = {
    method: 'post',
    contentType: 'application/json',
    payload: JSON.stringify(payload)
  };
  const response = UrlFetchApp.fetch('https://api.voorbeeld.nl/registreer', opties);
  Logger.log(response.getResponseCode());
}
```

Let op: `payload` moet een string zijn bij JSON, dus gebruik altijd `JSON.stringify()`. Voor de andere HTTP-werkwoorden zet je `method` op `get`, `post`, `put`, `patch` of `delete`.

## Authenticatie met een API-sleutel

De meeste API's vereisen authenticatie via een header, vaak een Bearer-token of een API-sleutel. Bewaar die sleutel veilig in de Script Properties:

```javascript
function authRequest() {
  const sleutel = PropertiesService.getScriptProperties().getProperty('API_KEY');
  const opties = {
    method: 'get',
    headers: {
      'Authorization': 'Bearer ' + sleutel
    }
  };
  const response = UrlFetchApp.fetch('https://api.voorbeeld.nl/profiel', opties);
  return JSON.parse(response.getContentText());
}
```

:::danger title="Zet sleutels nooit in je broncode"
Zet API-sleutels en wachtwoorden nooit hardgecodeerd in je broncode. Iedereen met toegang tot het script ziet ze dan, en bij deling lekken ze direct. Bewaar geheimen in `PropertiesService.getScriptProperties()` en lees ze pas op het moment van gebruik uit.
:::

## Fouten netjes afvangen

Standaard gooit `fetch()` een uitzondering bij een foutcode zoals 404 of 500, waardoor je script stopt. Met `muteHttpExceptions: true` krijg je de respons toch terug en kun je zelf op de statuscode reageren:

```javascript
function veiligeFetch() {
  const opties = { method: 'get', muteHttpExceptions: true };
  const response = UrlFetchApp.fetch('https://api.voorbeeld.nl/data', opties);
  const code = response.getResponseCode();

  if (code === 200) {
    return JSON.parse(response.getContentText());
  }
  Logger.log('Fout ' + code + ': ' + response.getContentText());
  return null;
}
```

:::tip title="Mute en check de statuscode"
Zet bij externe API's altijd `muteHttpExceptions: true` en controleer zelf de responscode. Zo onderscheid je een geslaagde aanroep van een fout, log je nuttige informatie en stopt je hele script niet bij een enkele mislukte request.
:::

## De vier stappen op een rij

Elke API-koppeling volgt hetzelfde patroon:

1. **URL bepalen**: kies het juiste endpoint van de externe API.
2. **Opties bouwen**: stel `method`, `headers` en `payload` in.
3. **Aanroepen**: roep `UrlFetchApp.fetch()` aan met `muteHttpExceptions: true`.
4. **Verwerken**: controleer de responscode en parse de JSON-respons.

## Meerdere requests tegelijk

Moet je tientallen aanroepen doen, bijvoorbeeld een rij in een spreadsheet per regel verrijken, dan is een loop met losse `fetch`-aanroepen traag. Met `UrlFetchApp.fetchAll()` voer je een lijst requests parallel uit:

```javascript
function batchRequests() {
  const requests = [
    { url: 'https://api.voorbeeld.nl/a', muteHttpExceptions: true },
    { url: 'https://api.voorbeeld.nl/b', muteHttpExceptions: true }
  ];
  const responses = UrlFetchApp.fetchAll(requests);
  return responses.map(r => r.getResponseCode());
}
```

Let op het dagelijkse quotum voor `UrlFetchApp`-aanroepen op je accounttype en de time-out van standaard 360 seconden per aanroep.

:::howto title="Een API-koppeling opzetten"
1. Lees de API-documentatie en noteer endpoint, methode en authenticatie.
2. Zet je API-sleutel in Project-instellingen, Scripteigenschappen.
3. Bouw een functie met het juiste opties-object en `muteHttpExceptions: true`.
4. Test eerst met een eenvoudig GET-endpoint en log de respons.
5. Voeg foutafhandeling toe en verwerk de data verder in Workspace.
:::

:::faq
### Hoe verstuur ik formuliergegevens in plaats van JSON?
Laat `contentType` weg of zet hem op application/x-www-form-urlencoded en geef `payload` als object mee; Apps Script codeert het dan automatisch naar form-data.

### Mijn request geeft een 403, wat nu?
Vaak een authenticatieprobleem. Controleer of je sleutel klopt, of de header de juiste naam heeft en of je account toegang heeft tot het endpoint.

### Kan ik meerdere requests tegelijk doen?
Ja, met `UrlFetchApp.fetchAll()` voer je een lijst requests parallel uit, wat veel sneller is dan een loop met losse fetch-aanroepen.

### Waar bewaar ik mijn API-sleutel veilig?
In `PropertiesService.getScriptProperties()`. Die waarden staan los van je broncode en lekken niet mee bij het delen van het script.

### Waarom krijg ik een time-out bij een trage API?
Een enkele fetch wacht standaard maximaal 360 seconden. Reageert de API niet binnen die tijd, dan faalt de aanroep. Zet zo nodig `timeoutSeconds` lager en bouw een nieuwe poging in plaats van eindeloos wachten.

### Hoe debug ik wat ik precies verstuur?
Gebruik `UrlFetchApp.getRequest(url, opties)`. Die geeft het samengestelde request terug zonder het te versturen, zodat je headers en payload kunt inspecteren voordat je het echt afvuurt.
:::

## Volgende stap

Met UrlFetchApp koppel je Workspace aan de buitenwereld. Wil je juist data ontvangen van externe systemen, lees dan [[apps-script-webhook|webhooks ontvangen en verwerken]]. Voor het veilig en onderhoudbaar houden van dit soort koppelingen, zie [[apps-script-best-practices|best practices]].