147 lines
6.2 KiB
Markdown
147 lines
6.2 KiB
Markdown
---
|
|
title: Dispute API
|
|
tags: [api, dispute, reference]
|
|
---
|
|
|
|
# Dispute API
|
|
|
|
> [!note] Current implementation
|
|
> The Dispute module now has a Mongoose model, controller routes, dashboard routes, and release-hold helper routes mounted under `/api/disputes`. Keep this page aligned with both `backend/src/routes/disputeRoutes.ts` and `backend/src/services/dispute/disputeRoutes.ts`.
|
|
|
|
Endpoints live under `/api/disputes/*`. `backend/src/routes/disputeRoutes.ts` delegates to `DisputeController` (`backend/src/controllers/disputeController.ts`) for CRUD/triage. `backend/src/services/dispute/disputeRoutes.ts` provides lightweight release-hold endpoints (`raise`, `resolve`, `status`) used by escrow release gating. The routers apply `authenticateToken` globally — every endpoint requires `Bearer JWT`.
|
|
|
|
> [!warning] Route overlap to verify
|
|
> Both route modules define a `POST /:id-or-purchaseRequestId/resolve` shape. Because `app.ts` mounts the full controller router before the lightweight hold router, confirm the intended handler before wiring automation to the lightweight resolve endpoint.
|
|
|
|
Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[Payment]] context and is the input to the mediation workflow that can lead to refund, replacement, compensation, warning/ban, or no-action. Release/refund execution should go through the ledger-gated [[Payment API]] and [[Payout Flow]].
|
|
|
|
## Create
|
|
|
|
### POST /api/disputes
|
|
|
|
**Description:** Open a dispute against a purchase request.
|
|
**Auth required:** Bearer JWT (buyer or seller participant in the request)
|
|
**Request body:**
|
|
```ts
|
|
{
|
|
purchaseRequestId: string;
|
|
reason: "not_delivered" | "wrong_item" | "damaged" | "quality" | "other";
|
|
description: string;
|
|
evidence?: string[]; // URLs from [[File API]]
|
|
paymentId?: string;
|
|
}
|
|
```
|
|
**Response 201:** `{ success: true, data: { dispute } }`
|
|
**Errors:** `400` validation, `403` not a participant of the request, `409` dispute already open for this request.
|
|
**Side effects:**
|
|
- Notifies the counter-party via `POST /api/notifications` (`new-notification` socket event).
|
|
- Pauses any in-flight payout (sets a hold flag on the related [[Payment]]).
|
|
|
|
### POST /api/disputes/:purchaseRequestId/raise
|
|
|
|
**Description:** Lightweight release-hold endpoint that marks a purchase request and related payments as disputed.
|
|
**Auth required:** Bearer JWT (buyer who owns the request or admin)
|
|
**Request body:** `{ reason?: string }`
|
|
**Response 200:** `{ success, message, data }`
|
|
|
|
### GET /api/disputes/:purchaseRequestId/status
|
|
|
|
**Description:** Returns release-hold flags for a purchase request, including whether release is currently blocked.
|
|
**Auth required:** Bearer JWT (buyer, preferred seller, or admin)
|
|
|
|
## Read
|
|
|
|
### GET /api/disputes
|
|
|
|
**Description:** List disputes the caller can see (their own as buyer/seller, all for admins).
|
|
**Auth required:** Bearer JWT
|
|
**Query params:**
|
|
- `status` (`open` | `under_review` | `resolved_buyer` | `resolved_seller` | `closed`)
|
|
- `purchaseRequestId`
|
|
- `page`, `limit`, `sortBy`, `sortOrder`
|
|
**Response 200:** `{ success, data: { disputes, pagination } }`
|
|
|
|
### GET /api/disputes/statistics
|
|
|
|
**Description:** Aggregated counts (open, by reason, average resolution time) for admin dashboards.
|
|
**Auth required:** Bearer JWT (admin)
|
|
**Response 200:** `{ success, data: { open, byReason, avgResolutionHours, ... } }`
|
|
|
|
### GET /api/disputes/:id
|
|
|
|
**Description:** Full dispute including evidence list, messages, assigned admin, decision (if any).
|
|
**Auth required:** Bearer JWT (participant or admin)
|
|
**Errors:** `403` not allowed, `404` not found.
|
|
|
|
## Admin operations
|
|
|
|
### POST /api/disputes/:id/assign
|
|
|
|
**Description:** Assign an admin moderator to the dispute. Sets `assignedAdminId` and transitions status to `under_review`.
|
|
**Auth required:** Bearer JWT (admin)
|
|
**Request body:** `{ adminId: string }`
|
|
**Side effects:** Notifies all participants.
|
|
|
|
### PATCH /api/disputes/:id/status
|
|
|
|
**Description:** Generic status update (e.g. close without resolution).
|
|
**Auth required:** Bearer JWT (admin)
|
|
**Request body:** `{ status: string; note?: string }`
|
|
|
|
### POST /api/disputes/:id/resolve
|
|
|
|
**Description:** Final adjudication. Records the decision and triggers the appropriate escrow action.
|
|
**Auth required:** Bearer JWT (admin)
|
|
**Request body:**
|
|
```ts
|
|
{
|
|
decision: "buyer" | "seller" | "split";
|
|
refundAmount?: number; // required when "split"
|
|
releaseAmount?: number; // required when "split"
|
|
reasoning: string;
|
|
}
|
|
```
|
|
**Response 200:** `{ success, data: { dispute, paymentAction } }`
|
|
**Side effects:**
|
|
- `action === "refund"` → create/approve the corresponding refund instruction through the ledger-gated payment release/refund flow.
|
|
- `action === "no_action"` or seller-favorable outcome → clear hold only after release checks pass.
|
|
- split outcomes require explicit partial release/refund instructions.
|
|
- Notifies both participants and updates [[PurchaseRequest]] status to `disputed_resolved`.
|
|
|
|
### POST /api/disputes/:purchaseRequestId/resolve
|
|
|
|
**Description:** Lightweight release-hold endpoint that clears the disputed hold flags on a purchase request and related payments.
|
|
**Auth required:** Bearer JWT (admin)
|
|
**Response 200:** `{ success, message, data }`
|
|
|
|
## Evidence and messages
|
|
|
|
### POST /api/disputes/:id/evidence
|
|
|
|
**Description:** Attach additional evidence (image / document URLs from the [[File API]]) to the dispute. Either party can call.
|
|
**Auth required:** Bearer JWT (participant or admin)
|
|
**Request body:**
|
|
```ts
|
|
{
|
|
url: string;
|
|
description?: string;
|
|
type?: "image" | "document" | "video";
|
|
}
|
|
```
|
|
**Response 200:** `{ success, data: { dispute } }` with the evidence appended.
|
|
|
|
### Messages
|
|
|
|
Direct messages between disputants and the admin moderator are handled via a dedicated [[Chat]] created automatically when the dispute is opened (`type: "dispute"`). Use the [[Chat API]] endpoints (`POST /api/chat/:id/messages`, `GET /api/chat/:id/messages`) once you have the `chatId` from the dispute payload.
|
|
|
|
## Real-time
|
|
|
|
Dispute mutations emit notifications via `POST /api/notifications` which delivers `new-notification` socket events to each participant's `user-<userId>` room. See [[Socket Events]] for payload shape.
|
|
|
|
## Related
|
|
|
|
- [[Dispute]]
|
|
- [[Dispute Resolution Flow]]
|
|
- [[Payment API]]
|
|
- [[Chat API]]
|