# Stijlvoorbeelden uploaden vanuit je eigen software

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. De fictieve oefenomgeving leest geen bestanden en bewijst deze verwerking niet.

## Wat je nodig hebt

Een productie-API-sleutel van de gebruiker die de stijl gaat maken, het recht `stijlen:beheren`, het recht `resultaten:lezen` voor status, een pakket met koppelingen en ruimte voor een stijl. Persoonlijke opslag en werkelijke creditverwerking moeten beschikbaar zijn. Kosten worden geboekt bij de gekoppelde gebruiker en blijven binnen het sleutelbudget. Voor een teamstijl moet die gebruiker beheerder of teamleider zijn.

Bewaar de sleutel uitsluitend op je server. In de voorbeelden bevat de omgevingsvariabele `RAPPORTLY_API_KEY` je sleutel; zet geen sleutel in gedeelde code, browsercode of logs.

## 1. Verstuur de complete bestandenset

`POST https://api.rapportly.io/api/rapportly/v1/stijlprofielen`

Verzend `multipart/form-data`, met één tot drie bestanden onder hetzelfde veld `bestanden`. Stel de multipartgrens niet zelf in: je HTTP-programma doet dat.

| Veld | Verplicht | Betekenis |
|---|---|---|
| `naam` | Ja | Naam van 1 tot 100 tekens. |
| `soort` | Ja | `rapport`, `email`, `gespreksverslag`, `offerte` of `presentatie`. |
| `deling_scope` | Ja | `persoonlijk` of `team`. |
| `bevestigd` | Ja | De tekst `true`; verwerking kan credits gebruiken. |
| `bestanden` | Ja | Eén tot drie echte voorbeeldbestanden, in de gewenste volgorde. |

Geef een eigen `Idempotency-Key` mee en bewaar die bij deze opdracht. Gebruik dezelfde sleutel en precies dezelfde gegevens, bestandsnamen, volgorde en bytes bij een herhaling. Geef een nieuwe bewuste opdracht een nieuwe sleutel.

```sh
curl --request POST 'https://api.rapportly.io/api/rapportly/v1/stijlprofielen' \
  --header "Authorization: Bearer $RAPPORTLY_API_KEY" \
  --header 'Idempotency-Key: crm-stijlvoorbeeld-2026-0001' \
  --form-string 'naam=Fictief voorbeeldrapport' \
  --form-string 'soort=rapport' \
  --form-string 'deling_scope=persoonlijk' \
  --form-string 'bevestigd=true' \
  --form 'bestanden=@./fictief-voorbeeld.docx'
```

Dit is een shellvoorbeeld; gebruik in je eigen programmeertaal de multipartfunctie van je HTTP-client. Begin met fictieve bestanden.

Voor rapportstijlen moet het eerste voorbeeld DOCX of PDF zijn. Gewone documentvoorbeelden mogen PDF, DOCX, DOC, TXT of MD zijn, maximaal 20 MiB per bestand. Een presentatiestijl vraagt eerst een presentatiebron, PDF of Word-huisstijlgids, maximaal 50 MiB per bestand. Keynote wordt geweigerd: exporteer naar PowerPoint of PDF. De bestaande vorm-/inhoudscontrole beslist of een specifiek bestand veilig kan worden gebruikt; een extensie alleen is geen garantie.

## 2. Bewaar de ontvangst en volg de status

Een nieuwe complete ontvangst geeft 202, met `id`, `opdracht_id`, `ontvangen:true`, `status:"bezig"` en `herhaald:false`.202 betekent ontvangen voor verwerking. Het is nog geen goedgekeurde of bruikbare stijl.

Vraag met dezelfde sleutel de status op via:

```http
GET /api/rapportly/v1/stijlprofiel-uploads/<id>
Authorization: Bearer <productiesleutel>
```

| Status | Wat je doet |
|---|---|
| `upload_onvolledig` | Verstuur dezelfde complete aanvraag opnieuw. Er is nog geen profiel in verwerking. |
| `bezig` | Wacht en vraag later opnieuw op. Er kan een aparte voorbeeldcontrole nodig zijn. |
| `klaar` | Lees de stijl en volg de bestaande controle-/keuzestappen voordat je die voor documenten gebruikt. |
| `mislukt` | Lees de bestaande stijlcontrole en foutinformatie. Een identieke uploadherhaling start geen nieuwe verwerking. |
| `verlopen` | De incomplete upload is ouder dan 30 dagen. Gebruik een nieuwe bewuste aanvraag. |

Bij een fout kan `opdracht_id` al aanwezig zijn; bewaar die voor de statusvraag. Een 404 betekent dat voor die sleutel nog geen ontvangst is bevestigd. Bij een volledig verloren HTTP-antwoord kun je altijd dezelfde volledige aanvraag opnieuw sturen. Poll rustig, bijvoorbeeld iedere vijf seconden en later minder vaak.

Een succesvolle herhaling geeft 200 en dezelfde ID. Deactiveren of verwijderen van de stijl en daarna herhalen geeft 410: de API maakt de stijl niet opnieuw aan. Gebruik voor handmatige wijzigingen de afzonderlijke metadata-/werkplaatsroutes met hun actuele basisversie. De upload verandert niet vanzelf je teamstandaard.

## 3. Fouten en veilig opnieuw proberen

- 409 bij andere invoer onder dezelfde sleutel: herstel de aanvraag of kies bewust een nieuwe opdracht. Verstuur geen gewijzigde bytes als retry.
- 402 bij de stijllimiet of onvoldoende credits; 409 bij onvoldoende opslag. Los de genoemde beperking op en lees daarna de actuele ontvangst voordat je opnieuw probeert.
- 403 bij ontbrekende gebruikers-, sleutel- of teamrechten. Een andere gebruikers-ID meesturen geeft geen toegang.
- 503 bij tijdelijk ontbrekende verwerking/opslag: bewaar opdracht en sleutel, herhaal met dezelfde inhoud. Maak niet automatisch een nieuwe opdracht-ID.
- Intrekken/pauzeren van de sleutel verhindert nieuwe providerpogingen en de eerste stijlpublicatie. Reeds gemaakte werkelijke kosten blijven geboekt. Een al actieve stijl blijft onder de normale stijlrechten beschikbaar.

Een incomplete upload kan 30 dagen worden herhaald. Daarna ruimt Rapportly uitsluitend die tijdelijke bestanden op. Opslagruimte wordt pas vrijgegeven na bevestigde verwijdering. Complete stijlbronnen vallen buiten die opruiming.

Uitgebreid lezen/OCR, gericht herstel en de volledige productie-OpenAPI worden in de gezamenlijke releasehandleiding apart beschreven. Dit concept belooft die aanvullende routes nog niet.