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 partner.

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, ReferralPartner, and Collection Partner subscriptions.
• → Closed:Paid: fires payment.created to Creditor and Collection Partner; fires case.updated and case.closed to Creditor, ReferralPartner, and Collection Partner subscriptions.
• → Closed:NoPayment: fires case.updated and case.closed to Creditor, ReferralPartner, and Collection Partner subscriptions.

Note: case.closed is delivered to Collection Partner subscriptions on both close paths.

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 /managed-cases with isTest: true (optionally a tag for scoped cleanup). 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 Collection Partner 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 Collection Partner subscription.

   • Alternatively: advance straight from any pre-active state — the endpoint activates the case first automatically.

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. Test Closed:NoPayment path — Create a fresh test case, call { "to": "Closed:NoPayment" } directly (no amount needed). Expect case.updated and case.closed on your Collection Partner subscription.

9. Reset between runs — Delete the test case via DELETE /test/cases/{id} (or DELETE /test/cases?tag={tag} to clear a whole tag) or create a new one per test run to keep assertions clean.

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 partner.

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.

<b>Collection Partner API only</b> — this endpoint is a convenience stopgap that existed before GET /webhooks/events was available. It remains here for backward compatibility and because it is a thin wrapper over POST /webhooks/events/{eventId}/replay.

         <b>Design note:</b> This endpoint was added when the Collection Partner API had no
         delivery-history endpoint (`GET /webhooks/events`), making it impossible to look up
         event IDs for replay. It is a stopgap: "give me the last event without having to know its ID."
         Now that `GET /webhooks/events` exists, integrators can use the full
         history + replay-by-id pattern instead. This endpoint is intentionally <b>not</b> ported
         to the Customer API — the stopgap only exists because it was needed before history existed.