# Kostenraming via 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.

## Aanvraag

Gebruik een productiesleutel met `gebruik:lezen` en `POST https://api.rapportly.io/api/rapportly/v1/generatieplan`. Headers: `Authorization: Bearer <jouw API-sleutel>` en `Content-Type: application/json`. Bewaar de sleutel uitsluitend op je server. Een Idempotency-Key is voor deze leesberekening niet vereist; herhalen start geen verwerking.

```json
{
  "soort": "rapport",
  "tier": "standaard",
  "invoerBytes": 18000,
  "bestanden": 1,
  "tweedeTaal": false,
  "generatieOpties": {
    "versie": 1,
    "route": "automatisch",
    "begeleidendeBrief": false
  }
}
```

`soort` is verplicht: `rapport`, `offerte` of `bundel` (gespreksbundel), dezelfde drie soorten als deze raming op de website. Presentaties vallen niet onder dit generatieplan. `tier` is `basis`, `standaard` of `max`; een vastgezet teamniveau blijft leidend. `invoerBytes` en `bestanden` zijn optionele gehele getallen van 0 t/m 1.000.000.000. Stuur alleen aantallen, geen documentinhoud.

Optioneel: `stijlprofielId` is de UUID van een eigen of gedeelde actieve stijl. Rapportly bepaalt het aantal secties zelf. `tweedeTaal` is boolean. Alleen voor een offerte kun je `vasteOfferte` of `offerteVoorstel` als boolean opgeven. Deze gegevens beschrijven de verwachte uitvoering en wijzigen geen opgeslagen opdracht. `generatieOpties.route` is `automatisch`, `efficient` of `uitgebreid`. De automatische route kies je niet zelf met een verborgen extra veld. Onbekende velden en URL-queryparameters worden geweigerd.

## Antwoord gebruiken

Bij de persoonlijke creditmodus bevat het antwoord `creditsVan`, `creditsTot`, het effectieve `tier`, `stappen`, `onzekerheden`, `volledig`, `geraamdOp` en `grondslag: werkbegroting_geen_maximum`. Iedere stap heeft een creditbandbreedte. Opmaak naar Word/PDF heeft in deze berekening nul AI-credits. Bestanden kunnen nog onbekende kosten voor OCR/uitlezen hebben: toon ook `onzekerheden` en behandel `volledig: false` niet als een complete begroting.

De API vermeldt bovendien `raming: true`, `verwerking_gestart: false` en `credits_afgeboekt: 0`. Dit verzoek reserveert geen credits, garandeert geen maximumprijs en geeft geen toestemming om later te starten. De daadwerkelijke start controleert opnieuw gebruiker, sleutelrechten, bronnen en beschikbare credits/budgetten. Werkelijk verbruik blijft leidend. Een latere raming kan veranderen door instellingen of prijzen. Bij `creditmodus: legacy` geeft deze route alleen het generatieplan; ontbrekende bedragen betekenen geen gratis verwerking.

## Fouten en herstel

- 400: ongeldige soort, velden, typen of opties. Corrigeer de aanvraag.
- 401/403: sleutel, gebruikersrechten of koppelingenpakket geven geen toegang.
- 404: de stijl bestaat niet of is voor deze gebruiker niet leesbaar.
- 409 `api_generatieplan_stijl_gewijzigd`: de stijlversie veranderde tijdens berekenen. Lees de stijl opnieuw en vraag een nieuwe raming.
- 503: de prijs of raming is niet betrouwbaar beschikbaar. Toon geen fictief bedrag; probeer later opnieuw.

Deze raming leest geen dossierinhoud en start geen providerverwerking. Bewaar de response bij een eigen offertescreen alleen als indicatie, samen met het tijdstip. Vraag vlak vóór een bewuste start zo nodig een actuele raming.