Test cases

Drives a test case to a well-known lifecycle state in a single call.

Purpose: Enables CI pipelines and integrators to exercise the full collection lifecycle — including real webhooks and events — without manual intervention.

Target States:

• Active — Activates the case from PendingVerification or PendingVerificationInternal. No-op if already Active or Closed.
• Closed:Paid — Records a payment for amount and closes the case as Paid. Activates the case first if needed. amount is required.
• Closed:NoPayment — Closes the case with PreLegalExhaustedNoPayment. Activates the case first if needed.

Guards:

• Returns 400 if the case is not a test case (Classification != Test).
• Returns 400 if amount is missing when to is Closed:Paid.
• Returns 400 if to is not one of the valid values.
• Returns 400 if the case is already closed with a different close code (e.g. already Closed:NoPayment when requesting Closed:Paid).
• Returns 404 if the case is not found or not owned by the calling creditor.

No-op behaviour: If the case is already at the requested state, the call returns 200 with advanced: false and the current state — no changes are made.

Webhooks: Transitions use the real internal service pipeline. Webhook delivery per target:

• → Active: fires case.updated to Creditor subscriptions.
• → Closed:Paid: fires payment.created and case.updated and case.closed to Creditor subscriptions.
• → Closed:NoPayment: fires case.updated and case.closed to Creditor subscriptions.

All events carry classification: test and are only delivered to webhook subscriptions registered with classification: test.

How to Test:

1. Create a test case — POST /cases with isTest: true and tag: suite-run-{uuid}. Note the returned id.

2. Register a test webhook subscription — subscribe to the events you want to assert on (case.updated, payment.created, case.closed) with classification: test and point the URL to your test receiver (e.g. a local ngrok tunnel or a CI webhook sink).

3. Advance to Active — POST /test/cases/{id}/advance with { "to": "Active" }. Expect { advanced: true, state: "Active" } and a case.updated event on your Creditor subscription.

4. Advance to Closed:Paid — POST /test/cases/{id}/advance with { "to": "Closed:Paid", "amount": 1000.00 }. Expect { advanced: true, state: "Closed:Paid" } and a payment.created event on your Creditor subscription.

5. Verify final state — GET /cases/{id} and assert lifecycle: Closed and closeCode: Paid.

6. Test no-op — Call the same advance again. Expect { advanced: false, state: "Closed:Paid" } and no new webhook events.

7. Test mismatch error — With the case closed as Paid, call { "to": "Closed:NoPayment" }. Expect 400 with a message describing the conflict.

8. Assert webhooks — GET /webhooks/events?caseId={id} to verify which events fired.

9. Reset between runs — DELETE /test/cases?tag=suite-run-{uuid} to clean up all cases created in this run.

Permanently removes a test case and all its child entities (payments, chats, files, timeline entries, webhook delivery records) from the database.

This is a hard-delete. The row is removed entirely — there is no soft-delete or recovery path. This is intentional for CI environments that create many test cases per day.

Guards:

• Returns 400 if the case is classified as Production. Only Test cases may be deleted via this endpoint.
• Returns 404 if the case is not found or not owned by the calling creditor.

Idempotent: Returns 204 even if the case is already deleted (no-op).

Permanently removes all test cases created with the specified tag (and all their child entities) from the database.

Scoped cleanup: Each CI pipeline run should create cases with a unique tag (e.g. suite-run-{uuid}) and use this endpoint at the end of the run to clean up, without affecting cases from parallel pipeline runs.

This is a hard-delete. Rows are removed entirely with no recovery path. This is intentional for CI environments.

Guards:

• Returns 400 if any matched case is classified as Production. The entire operation is rejected and nothing is deleted.
• Returns 400 if the tag query parameter is missing or blank.

Idempotent: Returns 204 even if no cases match the tag — no error is raised.