# Oefenen met de Rapportly API

Deze handleiding beschrijft de beschikbare API binnen de vermelde releasegrenzen. Actuele sleutel-, gebruikers-, pakket- en objectrechten blijven vereist. Niet alle websitefuncties zijn via de API beschikbaar. Dit is een fictieve simulator; hij bewijst geen werkelijke verwerking, bezorging of creditafrekening.

## Wat kun je oefenen?

Je kunt je eigen software laten omgaan met een aangenomen opdracht, wachten op het resultaat, een mislukte verwerking, onvoldoende budget en geweigerde toegang. Alle inhoud is fictief. De simulator maakt geen documenten voor klanten, gebruikt geen AI-provider, verstuurt geen e-mail of webhook en schrijft geen credits af.

Het oefenantwoord is een gemeenschappelijk voorbeeld. Het bewijst niet dat een echte upload, stijl, documentstart of afrekening werkt. Die controle volgt met afzonderlijke synthetische scenario's voor de betreffende productieactie.

## Zelf beginnen

1. Open Rapportly → Account → Koppelingen. Maak een sleutel met omgeving **Test**, of activeer de testsleutel die jouw beheerder heeft klaargezet. Kies de actierechten die je wilt oefenen. De gekoppelde gebruiker en het pakket moeten toegang tot Koppelingen hebben.
2. Bewaar de geheime sleutel lokaal in je ontwikkelomgeving. Een testsleutel begint met `rply_test_`. Productiesleutels werken niet op deze oefenroutes; testsleutels werken niet op productieacties.
3. Importeer `rapportly-testmodus.postman_collection.json` in je API-client. Vul de lokale variabele `rapportly_test_key` in. Deel of exporteer geen ingevulde sleutels en zet ze niet in Git, browsercode of gedeelde logs. Laat `base_url` ongewijzigd.
4. Voer **01 — Beschikbare oefenacties** uit. De collectie kiest de eerste beschikbare actie als `actie` nog leeg is. Je kunt zelf een andere id uit het antwoord kiezen. Er moet minstens één actierecht op de testsleutel staan.
5. Start één van de vier scenario's. Iedere scenarioaanvraag krijgt een eigen herhalingssleutel, die de collectie bewaart. Opnieuw verzenden herhaalt diezelfde opdracht. Voor een nieuwe oefenopdracht wis je eerst de betreffende `idem_...`-variabele.
6. Bij succes of verwerking_mislukt: bewaar `opdracht_id` en lees de status na ongeveer vijf seconden opnieuw. Voor het succesvoorbeeld is verzoek06 al ingevuld. Voor een ander scenario gebruik je het bijbehorende id.

## De drie routes

Basisadres: `https://api.rapportly.io/api/rapportly/v1`.

| Verzoek | Betekenis |
|---|---|
| GET /test/scenarios | Beschikbare acties binnen de huidige sleutelrechten en de vier vaste scenario's. |
| POST /test/opdrachten | JSON met uitsluitend `actie` en `scenario`; maak of herhaal een fictieve opdracht. |
| GET /test/opdrachten/{id} | Lees uitsluitend een eigen opdracht van dezelfde sleutel, gebruiker en organisatie. |

Stuur `Authorization: Bearer <testsleutel>`. Bij POST is ook `Content-Type: application/json` en `Idempotency-Key` verplicht:8–128 letters/cijfers of punt, underscore, dubbele punt en koppelteken; eerste teken is een letter of cijfer. Herhaal exact dezelfde body en sleutel bij een timeout. Bij een andere actie of scenario gebruik je een nieuwe sleutel.

Voorbeeldbody, alleen wanneer `rapport.start` in jouw actielijst staat:

```json
{"actie":"rapport.start","scenario":"succes"}
```

Stuur geen transcript, klantnaam, dossier-id, eigen tekst of bestand mee. Extra velden worden geweigerd.

## Verwachte uitkomst

| Scenario | Eerste antwoord | Na ongeveer vijf seconden |
|---|---|---|
| succes | HTTP202, status bezig | HTTP200, status gereed en vaste oefentekst |
| verwerking_mislukt | HTTP202, status bezig | HTTP200, status mislukt; code api_test_verwerking_mislukt |
| creditbudget_bereikt | HTTP402, status geweigerd | Dezelfde gesimuleerde weigering; credits0 |
| toegang_geweigerd | HTTP403, status geweigerd | Dezelfde gesimuleerde weigering; credits0 |

Lees altijd het veld `status`. Een HTTP200-antwoord alleen betekent niet dat de verwerking geslaagd is. Een herhaling van een oudere opdracht kan direct haar uiteindelijke antwoord geven.

Werkelijke toegangsfouten kunnen ook HTTP401/403 geven, bijvoorbeeld een ingetrokken sleutel. Dat is een echte toegangscontrole, geen gesimuleerd scenario. Controleer of het antwoord `fictief:true` plus een `opdracht_id` bevat voordat je het als oefenuitkomst verwerkt.

## Grenzen en herstel

- Opdrachten verlopen na zeven dagen. Daarna volgt404. Een andere sleutel kan ze niet lezen, ook niet bij hetzelfde teamlid.
- Maximaal1000 bewaarde oefenopdrachten per sleutel; de aanmaakroute is begrensd op30 verzoeken per minuut. Bij429 respecteer je Retry-After. De telling van bewaarde opdrachten hangt samen met de bewaartermijn.
- Zelfde sleutel met een andere actie/scenario geeft409. Verander niet automatisch de sleutel om een onduidelijk antwoord te omzeilen.
- Intrekken, pauzeren, verlopen of verlagen van sleutelrechten kan ook het lezen van oude oefenopdrachten blokkeren.
- De simulator bewijst geen aflevering van webhooks, e-mails of documenten, geen uploadverwerking en geen werkelijke creditprijs.
- Verwijder voor delen/export de geheime variabele. Trek de testsleutel na het oefenen in als je deze niet meer gebruikt.

## Naar een echte koppeling

Gebruik een aparte productiesleutel met de kleinste benodigde rechten en een passend budget. Lees de actielijst en het contract van de concrete productieactie. De testopdracht-id en simulatorbody kunnen niet als een echte rapport-, gesprek- of dossieropdracht worden hergebruikt. Test de echte koppeling eerst met fictieve klantinhoud en controleer resultaten, historie en credits.

De collectie gebruikt de huidige Postman-app met de gedocumenteerde methode [pm.execution.skipRequest](https://learning.postman.com/latest-v-12/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-execution) om verkeerd ingestelde oefenverzoeken over te slaan. Importeer de OpenAPI-specificatie als je een andere client gebruikt; de collectiescripts zijn Postman-specifiek.