# Practise with the Rapportly API

This guide describes the available API within the documented release limits. Current key, user, package and object permissions remain required. Not every website feature is available through the API. This is a fictional simulator; it does not prove real processing, delivery or credit settlement.

## What can you practise?

Your software can practise handling an accepted request, waiting for a result, failed processing, an insufficient budget and denied access. All content is fictional. The simulator does not create customer documents, call an AI provider, send email or webhooks, or consume credits.

The response uses a common example format. It does not prove that a real upload, style, document request or credit settlement works. Those require separate scenarios for the specific production action using fictional input.

## Get started independently

1. Open Rapportly → Account → Integrations. Create a key with the **Test** environment, or activate a test key prepared by your administrator. Select the action permissions you want to practise. The user and subscription still need access to Integrations.
2. Store the secret locally in your development environment. Test keys start with `rply_test_`. Production keys do not work on these practice routes, and test keys do not work on production actions.
3. Import `rapportly-testmodus.postman_collection.json` into Postman. Set the local `rapportly_test_key` variable. Do not share or export populated secrets, put them in Git, browser code or shared logs. Keep `base_url` unchanged.
4. Run request01, **Beschikbare oefenacties**. If `actie` is empty, the collection selects the first available action. You can select another id from the response. Your test key must have at least one action permission.
5. Start one of the four scenarios. Each scenario receives its own idempotency key, retained by the collection. Sending it again repeats the same request. To start a new practice request, first clear that scenario's `idem_...` variable.
6. For `succes` or `verwerking_mislukt`, retain `opdracht_id` and request its status after about five seconds. Request06 already uses the success request id. Use the corresponding id for another scenario.

## The three routes

Base URL: `https://api.rapportly.io/api/rapportly/v1`.

| Request | Purpose |
|---|---|
| GET /test/scenarios | Available actions within current key permissions and the four fixed scenarios. |
| POST /test/opdrachten | Send JSON containing only `actie` and `scenario` to create or repeat a fictional request. |
| GET /test/opdrachten/{id} | Read only a request belonging to the same key, user and organisation. |

Send `Authorization: Bearer <test key>`. POST also requires `Content-Type: application/json` and `Idempotency-Key`:8–128 letters, digits, dots, underscores, colons or hyphens; the first character must be a letter or digit. Repeat the exact body and key after a timeout. Use a new key for a different action or scenario.

Example body, only if your action list contains `rapport.start`:

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

Do not include a transcript, customer name, dossier id, custom text or a file. Extra fields are rejected. API field names and scenario codes remain unchanged in every interface language.

## Expected results

| Scenario | Initial response | After about five seconds |
|---|---|---|
| succes | HTTP202, status bezig | HTTP200, status gereed and fixed practice text |
| verwerking_mislukt | HTTP202, status bezig | HTTP200, status mislukt; code api_test_verwerking_mislukt |
| creditbudget_bereikt | HTTP402, status geweigerd | Same simulated denial; credits0 |
| toegang_geweigerd | HTTP403, status geweigerd | Same simulated denial; credits0 |

Always read `status`. HTTP200 alone does not mean successful processing. Repeating an older request can immediately return its final response.

Actual authentication or permission failures can also return HTTP401/403, for example when a key has been revoked. These are real access checks rather than simulated outcomes. Require `fictief:true` and an `opdracht_id` before treating a response as a practice result.

## Limits and recovery

- Practice requests expire after seven days and then return404. Another key cannot read them, even when it belongs to the same team member.
- At most1000 retained practice requests per key. Creation is limited to30 requests per minute. Respect Retry-After on429. Retention affects the count of stored requests.
- Reusing an idempotency key with another action or scenario returns409. Do not automatically change the key to bypass an uncertain result.
- Revoking, pausing, expiring or reducing key permissions can also prevent reading an earlier practice request.
- The simulator does not prove webhook/email delivery, document quality, upload processing or actual credit prices.
- Remove secrets before sharing/exporting. Revoke the test key when you no longer need it.

## Move to a real integration

Use a separate production key with the minimum required permissions and a suitable budget. Read the action list and the specific production action contract. A simulator id or body cannot be reused as a real report, conversation or dossier request. Use fictional customer content for the first real integration checks, and verify results, history and credits.

The collection uses the current Postman app and its documented [pm.execution.skipRequest](https://learning.postman.com/latest-v-12/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-execution) method to skip incorrectly configured practice requests. Import the OpenAPI specification if you use another client; collection scripts are specific to Postman.