# Snelstart

In zes stappen van een testsleutel naar een onboarding die je in de sandbox helemaal afrondt. Alle voorbeelden werken met een testsleutel en fictieve gegevens.

## 1. Maak een testsleutel

Maak in de app bij **Instellingen → API en webhooks** een testsleutel (`hrs_test_…`). Je ziet de sleutel één keer; daarna bewaren we alleen een hash. Een testsleutel werkt in je sandbox: een aparte organisatie met fictieve medewerkers, opgevangen mails en sms'jes en een gesimuleerde salarisverwerking. Alleen een eigenaar of manager kan een testsleutel maken.

```bash
export AGRELI_API_KEY="hrs_test_…"
```

Kies bij het maken de rechten die je nodig hebt. Voor deze snelstart zijn dat `organization:read`, `onboardings:read`, `onboardings:write` en `webhooks:manage`.

## 2. Haal een vestiging en een template op

Een onboarding heeft een `location_id` en een `template_id` nodig. Die staan bij je organisatie:

```bash
curl https://app.agreli.nl/api/public/v1/organization \
  -H "Authorization: Bearer $AGRELI_API_KEY"
```

```json Antwoord (ingekort)
{
  "id": "org_…",
  "name": "Brasserie De Haven (sandbox)",
  "locations": [{ "id": "loc_…", "name": "…", "city": "…" }],
  "templates": [{ "id": "t1", "name": "Oproepkracht bediening", "contract_type": "on_call", "cao": "Cao Horeca" }]
}
```

## 3. Maak een onboarding aan

Stuur de gegevens van de nieuwe medewerker en het dienstverband. Met een `Idempotency-Key` is opnieuw proberen na een time-out veilig: hetzelfde verzoek geeft hetzelfde antwoord.

```bash
curl -X POST https://app.agreli.nl/api/public/v1/onboardings \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Idempotency-Key: 5d1f0b6e-4711-4c2a-9b1e-2f6f0e9a7c31" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "sollicitant-4711",
    "employee": { "first_name": "Sam", "last_name": "Jansen", "email": "sam@example.com" },
    "employment": {
      "position": "Bediening",
      "start_date": "2026-12-01",
      "location_id": "loc_…",
      "template_id": "t1",
      "hours_per_week": 16,
      "hourly_wage_cents": 1450
    },
    "options": { "return_url": "https://jouwapp.nl/onboarding/klaar" }
  }'
```

Hetzelfde in TypeScript, met `fetch` (Node 18 of nieuwer). Roep de API alleen aan vanaf je server: een API-sleutel hoort niet in de browser.

```ts agreli.ts
const BASE = "https://app.agreli.nl/api/public";

export async function maakOnboarding(sollicitant: { id: string; voornaam: string; achternaam: string; email: string }, idempotencyKey: string) {
  const res = await fetch(`${BASE}/v1/onboardings`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AGRELI_API_KEY}`,
      "Content-Type": "application/json",
      // Bewaar deze sleutel bij je eigen record: een herhaling moet dezelfde sleutel gebruiken.
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      reference: `sollicitant-${sollicitant.id}`,
      employee: { first_name: sollicitant.voornaam, last_name: sollicitant.achternaam, email: sollicitant.email },
      employment: {
        position: "Bediening",
        start_date: "2026-12-01",
        location_id: "loc_…",
        template_id: "t1",
        hours_per_week: 16,
        hourly_wage_cents: 1450,
      },
      options: { return_url: "https://jouwapp.nl/onboarding/klaar" },
    }),
  });
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${res.status} ${error.type}/${error.code}: ${error.message} (${error.request_id})`);
  }
  return (await res.json()) as { id: string; status: string; hosted_url: string; expires_at: string; invitation_sent: boolean };
}
```

```json Antwoord 201
{
  "id": "onb_…",
  "object": "onboarding",
  "status": "pending_employee",
  "hosted_url": "https://app.agreli.nl/m/…",
  "expires_at": "2026-10-26T12:00:00.000Z",
  "invitation_sent": false,
  "reference": "sollicitant-4711",
  "metadata": {}
}
```

## 4. Stuur de medewerker naar de hosted_url

Stuur de medewerker vanuit je eigen software naar de `hosted_url`, bijvoorbeeld met een knop of een redirect. De medewerker vraagt daar een eenmalige code per mail of sms aan; de link alleen geeft geen toegang. Liever dat wij de link mailen? Zet dan `options.send_invitation` op `true`.

- De link is standaard 336 uur (14 dagen) geldig. Kies met `options.expires_in_hours` een waarde van 1 tot 336.
- Is de link verlopen of kwijt, vraag dan een nieuwe aan met `POST /v1/onboardings/{id}/hosted-link`. De vorige vervalt direct.
- Na het versturen toont de statuspagina een knop terug naar je `return_url`. Dat moet een https-adres zijn op een van je [toegestane domeinen](/docs/inbedden#toegestane-domeinen); zet die eerst in het developer dashboard.
- Liever in je eigen site? Toon de onboarding in een iframe met [embed.js](/docs/inbedden#de-onboarding-in-je-eigen-site).

## 5. Volg de voortgang

Registreer een webhookadres. Het geheim (`whsec_…`) staat alleen in dit antwoord; bewaar het om handtekeningen te controleren.

```bash
curl -X POST https://app.agreli.nl/api/public/v1/webhooks \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://jouwapp.nl/webhooks/agreli", "events": ["onboarding.employee_submitted", "onboarding.completed"] }'
```

Elk bericht bevat alleen id's, je eigen `reference`, je `metadata` en de `data_version`, nooit persoonsgegevens. Details haal je op met de API:

```bash
curl https://app.agreli.nl/api/public/v1/onboardings/onb_… \
  -H "Authorization: Bearer $AGRELI_API_KEY"
```

Het veld `status` zegt waar de onboarding staat en `waiting_on` wie er aan zet is. Zie [Webhooks](/docs/webhooks) voor de gebeurtenissen en het controleren van de handtekening.

## 6. Speel de rest na in de sandbox

In de sandbox hoef je niet zelf als medewerker, controleur en werkgever op te treden. Elke aanroep speelt de volgende stap na: gegevens invullen, goedkeuren met de testgebruikers, contract versturen, beide handtekeningen en de gesimuleerde salarisverwerking.

```bash
curl -X POST https://app.agreli.nl/api/public/v1/sandbox/onboardings/onb_…/advance \
  -H "Authorization: Bearer $AGRELI_API_KEY"
```

```json Antwoord (ingekort)
{ "step": "employee_submitted", "onboarding": { "id": "onb_…", "status": "in_review", "waiting_on": ["manager", "payroll_reviewer"] } }
```

Herhaal tot `step` gelijk is aan `payroll_completed`. Bij elke stap komen de bijbehorende webhooks binnen. Meer in [Sandbox en livegang](/docs/sandbox).

## Volgende stappen

- [Authenticatie](/docs/authenticatie): rechten, sleutels roteren en werken namens werkgevers.
- [Webhooks](/docs/webhooks): alle gebeurtenissen en de handtekening controleren.
- [API-referentie](/docs/api): alle endpoints.