{ "openapi": "3.0.3", "info": { "title": "PANBIDS API", "version": "1.0.0", "description": "Catalog-derived operation and authentication index. Companion API documentation defines full response contracts. Planned workbook operations are excluded." }, "servers": [ { "url": "https://panbids.com" } ], "paths": { "/api/v1/events": { "get": { "operationId": "C01", "summary": "Auction list", "description": "Required scope: catalogue:read", "tags": [ "existing" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "catalogue:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/events/{event}": { "get": { "operationId": "C02", "summary": "Auction details", "description": "Required scope: catalogue:read", "tags": [ "existing" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "catalogue:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/events/{event}/lots": { "get": { "operationId": "C03", "summary": "Auction lots", "description": "Required scope: catalogue:read", "tags": [ "existing" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "catalogue:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/events/{event}/lots/{lot}": { "get": { "operationId": "C04", "summary": "Lot details", "description": "Required scope: catalogue:read", "tags": [ "existing" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "catalogue:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/events/{event}/lots/{lot}/media/{media}": { "get": { "operationId": "C05", "summary": "Lot media", "description": "Required scope: catalogue:read", "tags": [ "existing" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "media", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "catalogue:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/lots": { "get": { "operationId": "C06", "summary": "Assigned lots", "description": "Required scope: catalogue:read", "tags": [ "existing" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "catalogue:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/vehicles/{vehicle}": { "get": { "operationId": "C07", "summary": "Published vehicle", "description": "Required scope: vehicles:read", "tags": [ "existing" ], "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "vehicles:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/lots/{lot}/bids": { "post": { "operationId": "C08", "summary": "Submit bid", "description": "Required scope: bids:write", "tags": [ "existing" ], "parameters": [ { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "bids:write", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "201": { "description": "First accepted bid; accepted replay uses 200" }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/bids": { "get": { "operationId": "C09", "summary": "Own bids", "description": "Required scope: bids:read", "tags": [ "existing" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "bids:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/results": { "get": { "operationId": "C10", "summary": "Provisional results", "description": "Required scope: results:read", "tags": [ "existing" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "results:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Authorized response. See endpoint documentation." }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/integration/profile": { "get": { "operationId": "A01", "summary": "Integration", "description": "Return environment, bank/partner/client IDs, actor type, permissions and permitted operations.\n\nDerive tenant from credentials. Never return signing secrets. Separate bank-service and partner-service credentials.\n\nRequired scope: integration:read", "tags": [ "P0" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "integration:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data plus server_time; HMAC authenticated and permission-scoped.", "content": { "application/json": { "example": { "data": { "environment": "production", "bank_id": "bank_EXAMPLE", "partner_id": "ptn_EXAMPLE", "client_id": "pb_production_EXAMPLE", "actor_type": "partner", "partner_type": "platform", "dealer_id": "dlr_EXAMPLE", "scopes": [ "integration:read" ], "operations": [ { "id": "A01", "method": "GET", "path": "/api/v1/integration/profile", "scope": "integration:read", "title": "Integration", "actors": [ "bank", "partner" ] }, { "id": "A02", "method": "GET", "path": "/api/v1/integration/capabilities", "scope": "integration:read", "title": "Integration", "actors": [ "bank", "partner" ] } ] }, "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/integration/capabilities": { "get": { "operationId": "A02", "summary": "Integration", "description": "Discover API versions, cancellation mode, visibility policy, quotas, webhook support and server_time.\n\nReturn effective bank policy and policy_version. A feature flag must reflect deployed capability.\n\nRequired scope: integration:read", "tags": [ "P0" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "integration:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data plus server_time; HMAC authenticated and permission-scoped.", "content": { "application/json": { "example": { "data": { "api_versions": [ "v1" ], "policy_version": "conservative-1", "bid_visibility": { "open": "highest_and_own_status", "closed": "own_status_without_highest" }, "cancellation_mode": "bank_approval_required", "sale_approval": "explicit_bank_decision", "payment_verification": "bank_receipt_verification", "webhooks": { "enabled": false }, "realtime": { "enabled": false }, "operations": [] }, "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/bidding-eligibility": { "get": { "operationId": "A03", "summary": "Eligibility", "description": "Read own KYC, EMD, limit, expiry and lot eligibility. Query lot_id and scoped buyer reference.\n\nDiagnostic snapshot only. Recheck every constraint inside bid acceptance transaction.\n\nRequired scope: eligibility:read", "tags": [ "P0" ], "parameters": [ { "name": "lot_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "lot_EXAMPLE" }, { "name": "bidder_reference", "in": "query", "required": false, "schema": { "type": "string" }, "example": "buyer_123" }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "string" }, "example": "281200.00" }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "eligibility:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "JSON data plus server_time; HMAC authenticated and permission-scoped.", "content": { "application/json": { "example": { "data": { "eligible": false, "diagnostic_only": true, "errors": [ "DEALER_NOT_ELIGIBLE" ], "dealer_id": "dlr_EXAMPLE", "kyc_status": "approved", "emd_status": "pending", "blocked": false, "buyer_limit": "0.00", "limit_until": null, "emd_until": null, "lot_id": "lot_EXAMPLE", "starting_price": "281200.00", "bid_increment": "1000.00", "notice": "This snapshot reserves no buying power. Bid acceptance rechecks authoritative constraints." }, "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/bids/{bid}": { "get": { "operationId": "A05", "summary": "Bidding", "description": "Read accepted/rejected state, owner reference, receipt, lot version and request ID for one bid.\n\nOwning partner sees its own records. Bank sees its tenant. A bid ID alone never proves acceptance.\n\nRequired scope: bids:read", "tags": [ "P0" ], "parameters": [ { "name": "bid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "bids:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data plus server_time; HMAC authenticated and permission-scoped.", "content": { "application/json": { "example": { "data": { "id": "bid_EXAMPLE", "lot_id": "lot_EXAMPLE", "bidder_reference": "buyer_123", "amount": "300000.00", "status": "rejected", "request_id": "req_EXAMPLE", "server_received_at": "2026-09-13T10:00:00+00:00", "lot_version": 1, "errors": [ "BID_OFF_OPENING_GRID" ] }, "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/bid-requests/{idempotency_key}": { "get": { "operationId": "A06", "summary": "Bidding", "description": "Resolve an uncertain timeout by original key: processing, accepted, rejected or absent.\n\nKey namespace includes environment and API client. Absent is time-bounded evidence; retry original command only.\n\nRequired scope: bids:read", "tags": [ "P0" ], "parameters": [ { "name": "idempotency_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "bids:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "JSON data plus server_time; HMAC authenticated and permission-scoped.", "content": { "application/json": { "example": { "data": { "idempotency_key": "c5fefb02-6b55-4992-8c45-4f75994d4b28", "state": "absent", "observed_at": "2026-09-13T10:00:00+00:00", "receipt": null, "retry": "Retry only the original command and key. Absent does not prove no in-flight request exists." }, "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/bids/{bid}/cancellation-requests": { "post": { "operationId": "A07", "summary": "Cancellation", "description": "Submit reason_code, explanation and evidence. Return request ID and pending/approved decision state.\n\nDefault requires bank approval. Only explicitly permitted policy can auto-approve. Do not delete the bid.\n\nRequired scope: bids:cancel-request", "tags": [ "P0" ], "parameters": [ { "name": "bid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "bids:cancel-request", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "cancellation_EXAMPLE", "kind": "cancellation", "state": "pending", "resource_version": 1, "data": { "reason_code": "ENTERED_IN_ERROR", "explanation": "Explain the cancellation request" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason_code": { "type": "string", "example": "ENTERED_IN_ERROR" }, "explanation": { "type": "string", "example": "Explain the cancellation request" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "reason_code": "ENTERED_IN_ERROR", "explanation": "Explain the cancellation request", "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/bid-cancellation-requests": { "get": { "operationId": "A08", "summary": "Cancellation", "description": "Filter requests by bid, lot and decision status for bank review and dealer tracking.\n\nTenant and bidder ownership filters apply before pagination.\n\nRequired scope: bids:cancel-read", "tags": [ "P0" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "bids:cancel-read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "items": [ { "id": "cancellation_EXAMPLE", "kind": "cancellation", "state": "pending", "resource_version": 1, "data": { "bid_id": "bid_EXAMPLE", "reason_code": "ENTRY_ERROR", "explanation": "Request bank review of this bid", "policy_version": "conservative-1" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" } ], "current_page": 1, "last_page": 1, "total": 1 } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/bid-cancellation-requests/{request}/decisions": { "post": { "operationId": "A09", "summary": "Cancellation", "description": "Approve or reject with reason, expected_version and decision ID.\n\nAtomically change effective bid, standings and exposure. Superseded bids do not revive. After close, re-award needs separate bank approval.\n\nRequired scope: bids:cancel-approve", "tags": [ "P0" ], "parameters": [ { "name": "request", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "bids:cancel-approve", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "cancellation_EXAMPLE", "kind": "cancellation", "state": "approved", "resource_version": 2, "data": { "decision": "approved", "reason": "Bank reviewed cancellation" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "example": "approved" }, "reason": { "type": "string", "example": "Bank reviewed cancellation" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "decision": "approved", "reason": "Bank reviewed cancellation", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/lots/{lot}/status": { "get": { "operationId": "A10", "summary": "Lot status", "description": "Read auction_state, inventory_state, own standing, sale/payment/release summaries and allowed_actions.\n\nProject fields by role and visibility policy. Provide resource_version, effective_close_at and updated_at.\n\nRequired scope: lot-status:read", "tags": [ "P0" ], "parameters": [ { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "lot-status:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "JSON data plus server_time; HMAC authenticated and permission-scoped.", "content": { "application/json": { "example": { "data": { "lot_id": "lot_EXAMPLE", "auction_state": "live", "inventory_state": "ready", "resource_version": 1, "updated_at": "2026-09-13T10:00:00+00:00", "effective_close_at": "2026-09-14T10:00:00+00:00", "sale": null, "payment": null, "release": null, "allowed_actions": [ "read" ], "provisional": true, "own_standing": "no_bid", "own_amount": null, "highest_amount": null }, "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/lots/status-batch": { "post": { "operationId": "A11", "summary": "Lot status", "description": "Read status for a bounded list of lot IDs in one request.\n\nRead-only POST. Per-item authorization and errors. Proposed maximum 100 IDs; confirm through load testing.\n\nRequired scope: lot-status:read", "tags": [ "P0" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "lot-status:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "JSON data plus server_time; HMAC authenticated and permission-scoped.", "content": { "application/json": { "example": { "data": [ { "lot_id": "lot_EXAMPLE", "status": 200, "data": { "lot_id": "lot_EXAMPLE", "auction_state": "live", "inventory_state": "ready", "resource_version": 1, "updated_at": "2026-09-13T10:00:00+00:00", "effective_close_at": "2026-09-14T10:00:00+00:00", "sale": null, "payment": null, "release": null, "allowed_actions": [ "read" ], "provisional": true, "own_standing": "no_bid", "own_amount": null, "highest_amount": null } }, { "lot_id": "lot_UNAVAILABLE", "status": 404, "code": "NOT_FOUND" } ], "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lot_ids": { "type": "array", "items": { "type": "string" }, "example": [ "lot_EXAMPLE" ] }, "bidder_reference": { "type": "string", "example": "buyer_123" } } }, "example": { "lot_ids": [ "lot_EXAMPLE" ], "bidder_reference": "buyer_123" } } } } } }, "/api/v1/sale-cases": { "get": { "operationId": "A20", "summary": "Sale approval", "description": "Read provisional winner, pending bank decision, confirmed award and deadlines.\n\nSeparate sale-case identity from lot and vehicle. Only eligible buyer receives private offer detail.\n\nRequired scope: sales:read", "tags": [ "P0" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "sales:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "items": [ { "id": "sale_EXAMPLE", "kind": "sale", "state": "approved", "resource_version": 2, "data": { "bid_id": "bid_EXAMPLE", "bidder_reference": "buyer_123", "amount": "281200.00", "currency": "INR", "terms_version": "terms-1", "acknowledged_at": null, "lot_id": "lot_EXAMPLE", "due_at": "2026-09-15T10:00:00+00:00", "payee_instructions": "Use the bank-approved payment instructions", "payee_version": 1 }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" } ], "current_page": 1, "last_page": 1, "total": 1 } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/sale-cases/{sale}": { "get": { "operationId": "A21", "summary": "Sale approval", "description": "Read sale version, approved bid, decision history, payable amount and document references.\n\nHighest accepted bid remains provisional until authorized bank decision.\n\nRequired scope: sales:read", "tags": [ "P0" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "sales:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "sale_EXAMPLE", "kind": "sale", "state": "approved", "resource_version": 2, "data": { "bid_id": "bid_EXAMPLE", "bidder_reference": "buyer_123", "amount": "281200.00", "currency": "INR", "terms_version": "terms-1", "acknowledged_at": null, "lot_id": "lot_EXAMPLE", "due_at": "2026-09-15T10:00:00+00:00", "payee_instructions": "Use the bank-approved payment instructions", "payee_version": 1 }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/sale-cases/{sale}/decisions": { "post": { "operationId": "A22", "summary": "Sale approval", "description": "Approve or reject a provisional award with bid_id, terms_version, reason and expected_version.\n\nEnforce bank approval limits and maker-checker if configured. Verify bid still valid and vehicle still available.\n\nRequired scope: sales:approve", "tags": [ "P0" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "sales:approve", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event. If a negotiation offer exists, approval also requires offer_id matching the active accepted offer, unexpired validity and matching terms_version. The negotiated amount is applied only by this explicit bank decision.", "content": { "application/json": { "example": { "data": { "id": "sale_EXAMPLE", "kind": "sale", "state": "approved", "resource_version": 2, "data": { "decision": "approved", "bid_id": "bid_EXAMPLE", "reason": "Bank approved the sale", "terms_version": "1", "due_at": "2026-10-01T12:00:00+05:30", "payee_instructions": "Bank-approved remittance instructions" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "example": "approved" }, "bid_id": { "type": "string", "example": "bid_EXAMPLE" }, "reason": { "type": "string", "example": "Bank approved the sale" }, "terms_version": { "type": "string", "example": "1" }, "due_at": { "type": "string", "example": "2026-10-01T12:00:00+05:30" }, "payee_instructions": { "type": "string", "example": "Bank-approved remittance instructions" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "decision": "approved", "bid_id": "bid_EXAMPLE", "reason": "Bank approved the sale", "terms_version": "1", "due_at": "2026-10-01T12:00:00+05:30", "payee_instructions": "Bank-approved remittance instructions", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/sale-cases/{sale}/acknowledgments": { "post": { "operationId": "A23", "summary": "Bidder confirmation", "description": "Record that the bidder received the bank decision and terms.\n\nAcknowledgment is not a new bid, bank approval or payment. If buyer acceptance is required, model a separate acceptance state.\n\nRequired scope: sales:acknowledge", "tags": [ "P0" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "sales:acknowledge", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "sale_EXAMPLE", "kind": "sale", "state": "approved", "resource_version": 2, "data": { "terms_version": "1" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terms_version": { "type": "string", "example": "1" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "terms_version": "1", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/sale-cases/{sale}/offers": { "post": { "operationId": "A24", "summary": "Negotiation", "description": "Issue a priced counteroffer with validity deadline and terms version.\n\nOne active offer version. Preserve original auction bids; never overwrite history or reveal rival bids.\n\nRequired scope: offers:write", "tags": [ "P1" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "offers:write", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "HTTP 200: open offer record. Prior open or accepted offers are superseded. Original auction bid stays unchanged. GET sale detail includes active_offer. The sale remains pending bank approval.", "content": { "application/json": { "example": { "data": { "id": "offer_EXAMPLE", "kind": "offer", "state": "open", "resource_version": 2, "data": { "amount": "281200.00", "currency": "INR", "terms_version": "terms-1", "valid_until": "2026-12-01T12:00:00+00:00", "reason": "Bank proposes a revised sale price" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "example": "281200.00" }, "currency": { "type": "string", "example": "INR" }, "terms_version": { "type": "string", "example": "terms-1" }, "valid_until": { "type": "string", "example": "2026-12-01T12:00:00+00:00" }, "reason": { "type": "string", "example": "Bank proposes a revised sale price" }, "expected_version": { "type": "integer", "example": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "example": "REPLACE_WITH_NEW_UUID" } } }, "example": { "amount": "281200.00", "currency": "INR", "terms_version": "terms-1", "valid_until": "2026-12-01T12:00:00+00:00", "reason": "Bank proposes a revised sale price", "expected_version": 1, "idempotency_key": "REPLACE_WITH_NEW_UUID" } } } } } }, "/api/v1/offers/{offer}/responses": { "post": { "operationId": "A25", "summary": "Negotiation", "description": "Accept, decline or propose a counteroffer if policy permits.\n\nRecheck expiry and version atomically. Revised prices require the configured bank approval sequence.\n\nRequired scope: offers:respond", "tags": [ "P1" ], "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "offers:respond", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "HTTP 200: accepted or declined offer record. Conservative policy does not allow buyer-created counteroffers. Acceptance does not approve the sale: the bank must submit A22 with this offer_id, matching terms_version and the current sale expected_version before the offer expires.", "content": { "application/json": { "example": { "data": { "id": "offer_EXAMPLE", "kind": "offer", "state": "accepted", "resource_version": 2, "data": { "decision": "accepted", "terms_version": "terms-1", "reason": "Buyer accepts these proposed terms" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "example": "accepted" }, "terms_version": { "type": "string", "example": "terms-1" }, "reason": { "type": "string", "example": "Buyer accepts these proposed terms" }, "expected_version": { "type": "integer", "example": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "example": "REPLACE_WITH_NEW_UUID" } } }, "example": { "decision": "accepted", "terms_version": "terms-1", "reason": "Buyer accepts these proposed terms", "expected_version": 1, "idempotency_key": "REPLACE_WITH_NEW_UUID" } } } } } }, "/api/v1/sale-cases/{sale}/cancellation-requests": { "post": { "operationId": "A26", "summary": "Sale cancellation", "description": "Request cancellation after bank approval, citing reason and evidence.\n\nUse this instead of bid cancellation after sale approval. Trigger assessment of money and release obligations.\n\nRequired scope: sales:cancel-request", "tags": [ "P1" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "sales:cancel-request", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "HTTP 200 workflow record. Refund approval reserves funds and returns approved_pending_execution; it does not claim a completed bank transfer.", "content": { "application/json": { "example": { "data": { "id": "sale_cancellation_EXAMPLE", "kind": "sale_cancellation", "state": "pending", "resource_version": 2, "data": { "reason_code": "CANCELLATION", "explanation": "Explain the sale cancellation" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason_code": { "type": "string", "example": "CANCELLATION" }, "explanation": { "type": "string", "example": "Explain the sale cancellation" }, "expected_version": { "type": "integer", "example": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "reason_code": "CANCELLATION", "explanation": "Explain the sale cancellation", "expected_version": 1, "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/sale-cancellation-requests/{request}/decisions": { "post": { "operationId": "A27", "summary": "Sale cancellation", "description": "Approve/reject cancellation and create required reversal/refund work items.\n\nNever erase approved sale or cash records. Delivered vehicle requires an exception/dispute workflow.\n\nRequired scope: sales:cancel-approve", "tags": [ "P1" ], "parameters": [ { "name": "request", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "sales:cancel-approve", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "HTTP 200 workflow record. Refund approval reserves funds and returns approved_pending_execution; it does not claim a completed bank transfer.", "content": { "application/json": { "example": { "data": { "id": "sale_cancellation_EXAMPLE", "kind": "sale_cancellation", "state": "approved", "resource_version": 2, "data": { "decision": "approved", "reason": "Bank reviewed the request" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "example": "approved" }, "reason": { "type": "string", "example": "Bank reviewed the request" }, "expected_version": { "type": "integer", "example": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "decision": "approved", "reason": "Bank reviewed the request", "expected_version": 1, "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/sale-cases/{sale}/payment-dues": { "get": { "operationId": "A34", "summary": "Payment dues", "description": "Return instalments, due dates, verified credits, remaining balance and verified payee instructions.\n\nCompute from approved terms and allocation ledger. Version payee instructions; secure any bank-account change.\n\nRequired scope: payments:read", "tags": [ "P0" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "payments:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "sale_id": "sale_EXAMPLE", "currency": "INR", "due_amount": "281200.00", "verified_credits": "0.00", "remaining": "281200.00", "excess": "0.00", "state": "unpaid", "due_at": "2026-09-15T10:00:00+00:00", "payee_instructions": "Use the bank-approved payment instructions", "payee_version": 1, "resource_version": 2 } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/payment-reports": { "post": { "operationId": "A36", "summary": "Payment reporting", "description": "Submit sale_id, amount, currency, method, UTR/provider ID, paid_at, evidence and external reference.\n\nReturn reported_pending_verification. Dealer cannot assert verified, settled or release-authorized.\n\nRequired scope: payments:report", "tags": [ "P0" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "payments:report", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "payment_report_EXAMPLE", "kind": "payment_report", "state": "reported_pending_verification", "resource_version": 1, "data": { "sale_id": "sale_EXAMPLE", "amount": "281200.00", "currency": "INR", "method": "bank_transfer", "utr": "BANK_UTR", "paid_at": "2026-09-12T10:00:00+05:30", "external_reference": "payment_1", "evidence_id": "document_EXAMPLE" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sale_id": { "type": "string", "example": "sale_EXAMPLE" }, "amount": { "type": "string", "example": "281200.00" }, "currency": { "type": "string", "example": "INR" }, "method": { "type": "string", "example": "bank_transfer" }, "utr": { "type": "string", "example": "BANK_UTR" }, "paid_at": { "type": "string", "example": "2026-09-12T10:00:00+05:30" }, "external_reference": { "type": "string", "example": "payment_1" }, "evidence_id": { "type": "string", "example": "document_EXAMPLE" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "sale_id": "sale_EXAMPLE", "amount": "281200.00", "currency": "INR", "method": "bank_transfer", "utr": "BANK_UTR", "paid_at": "2026-09-12T10:00:00+05:30", "external_reference": "payment_1", "evidence_id": "document_EXAMPLE", "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/payment-reports/{report}": { "get": { "operationId": "A37", "summary": "Payment reporting", "description": "Track verification, rejection reasons, matched receipt and allocation outcomes.\n\nReturn source, verifier, verified_at and reconciliation reference when available.\n\nRequired scope: payments:read", "tags": [ "P0" ], "parameters": [ { "name": "report", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "payments:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "payment_report_EXAMPLE", "kind": "payment_report", "state": "reported_pending_verification", "resource_version": 1, "data": {}, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/payment-reports/{report}/decisions": { "post": { "operationId": "A38", "summary": "Payment verification", "description": "Accept or reject a reported transfer after checking the bank receipt/statement.\n\nRequire evidence of bank receipt and independent approver when policy requires. Idempotent decision with version check.\n\nRequired scope: payments:verify", "tags": [ "P0" ], "parameters": [ { "name": "report", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "payments:verify", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "payment_report_EXAMPLE", "kind": "payment_report", "state": "verified", "resource_version": 2, "data": { "decision": "verified", "reason": "Bank receipt checked", "bank_receipt_id": "bank_receipt_EXAMPLE", "bank_account_reference": "BANK_ACCOUNT", "received_amount": "281200.00", "currency": "INR" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "example": "verified" }, "reason": { "type": "string", "example": "Bank receipt checked" }, "bank_receipt_id": { "type": "string", "example": "bank_receipt_EXAMPLE" }, "bank_account_reference": { "type": "string", "example": "BANK_ACCOUNT" }, "received_amount": { "type": "string", "example": "281200.00" }, "currency": { "type": "string", "example": "INR" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "decision": "verified", "reason": "Bank receipt checked", "bank_receipt_id": "bank_receipt_EXAMPLE", "bank_account_reference": "BANK_ACCOUNT", "received_amount": "281200.00", "currency": "INR", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/payments/{payment}": { "get": { "operationId": "A40", "summary": "Payment status", "description": "Read authoritative verified receipt, allocations, refund/dispute status and separate settlement state.\n\nA report ID and payment ID are different. Summaries never add unverified reports to paid balance.\n\nRequired scope: payments:read", "tags": [ "P0" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "payments:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "payment_EXAMPLE", "kind": "payment", "state": "succeeded", "resource_version": 1, "data": { "sale_id": "sale_EXAMPLE", "amount": "281200.00", "currency": "INR", "settlement_state": "bank_received" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/bank-receipts/imports": { "post": { "operationId": "A42", "summary": "Bank receipts", "description": "Ingest statement/API receipt entries with external transaction identity and value date.\n\nAllowlisted schema and trusted bank credentials. Deduplicate by bank account and transaction identity; never by amount alone.\n\nRequired scope: receipts:import", "tags": [ "P1" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "receipts:import", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "bank_receipt_EXAMPLE", "kind": "bank_receipt", "state": "verified", "resource_version": 1, "data": { "sale_id": "sale_EXAMPLE", "bank_account_reference": "BANK_ACCOUNT", "utr": "BANK_UTR", "external_transaction_id": "BANK_TXN", "amount": "281200.00", "currency": "INR", "value_date": "2026-09-12", "evidence_id": "document_EXAMPLE" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sale_id": { "type": "string", "example": "sale_EXAMPLE" }, "bank_account_reference": { "type": "string", "example": "BANK_ACCOUNT" }, "utr": { "type": "string", "example": "BANK_UTR" }, "external_transaction_id": { "type": "string", "example": "BANK_TXN" }, "amount": { "type": "string", "example": "281200.00" }, "currency": { "type": "string", "example": "INR" }, "value_date": { "type": "string", "example": "2026-09-12" }, "evidence_id": { "type": "string", "example": "document_EXAMPLE" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "sale_id": "sale_EXAMPLE", "bank_account_reference": "BANK_ACCOUNT", "utr": "BANK_UTR", "external_transaction_id": "BANK_TXN", "amount": "281200.00", "currency": "INR", "value_date": "2026-09-12", "evidence_id": "document_EXAMPLE", "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/payments/{payment}/allocations": { "post": { "operationId": "A45", "summary": "Payment allocation", "description": "Allocate verified funds to one or more sale dues with per-sale amounts.\n\nLock allocation totals. Never exceed verified unallocated funds or credit the same receipt twice.\n\nRequired scope: payments:allocate", "tags": [ "P0" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "payments:allocate", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "allocation_EXAMPLE", "kind": "allocation", "state": "allocated", "resource_version": 2, "data": { "sale_id": "sale_EXAMPLE", "amount": "281200.00", "payment_id": "payment_EXAMPLE", "amount_paise": 10000, "currency": "INR" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sale_id": { "type": "string", "example": "sale_EXAMPLE" }, "amount": { "type": "string", "example": "281200.00" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "sale_id": "sale_EXAMPLE", "amount": "281200.00", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/sale-cases/{sale}/receipts": { "get": { "operationId": "A46", "summary": "Receipts", "description": "Fetch verified payment receipt and invoice/document references.\n\nIssuer, document version and private download authorization required. Do not infer statutory invoice fields.\n\nRequired scope: documents:read", "tags": [ "P1" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "documents:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "sale_id": "sale_EXAMPLE", "payments": [], "allocations": [], "documents": [] }, "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/payments/{payment}/refund-requests": { "post": { "operationId": "A47", "summary": "Refunds", "description": "Request full or partial refund with amount and reason.\n\nRequest only. Bank approval and provider processing occur separately. Refundable amount excludes previous/pending refunds.\n\nRequired scope: refunds:request", "tags": [ "P1" ], "parameters": [ { "name": "payment", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "refunds:request", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "HTTP 200 workflow record. Refund approval reserves funds and returns approved_pending_execution; it does not claim a completed bank transfer.", "content": { "application/json": { "example": { "data": { "id": "refund_request_EXAMPLE", "kind": "refund_request", "state": "pending", "resource_version": 2, "data": { "amount": "100.00", "reason": "Explain the refund request" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "example": "100.00" }, "reason": { "type": "string", "example": "Explain the refund request" }, "expected_version": { "type": "integer", "example": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "amount": "100.00", "reason": "Explain the refund request", "expected_version": 1, "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/refund-requests/{request}/decisions": { "post": { "operationId": "A48", "summary": "Refunds", "description": "Approve/reject; approved request starts a provider refund operation.\n\nKeep decision, provider request, completion and settlement/reversal separate. Never label refund complete on initiation.\n\nRequired scope: refunds:approve", "tags": [ "P1" ], "parameters": [ { "name": "request", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "refunds:approve", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "HTTP 200 workflow record. Refund approval reserves funds and returns approved_pending_execution; it does not claim a completed bank transfer.", "content": { "application/json": { "example": { "data": { "id": "refund_request_EXAMPLE", "kind": "refund_request", "state": "approved", "resource_version": 2, "data": { "decision": "approved", "reason": "Bank reviewed the request", "refund_id": "refund_EXAMPLE" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "example": "approved" }, "reason": { "type": "string", "example": "Bank reviewed the request" }, "expected_version": { "type": "integer", "example": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "decision": "approved", "reason": "Bank reviewed the request", "expected_version": 1, "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/refunds/{refund}": { "get": { "operationId": "A49", "summary": "Refunds", "description": "Track requested, processing, succeeded or failed and provider/ARN references.\n\nReconcile callbacks with provider inquiry. Idempotent operation key survives retries.\n\nRequired scope: refunds:read", "tags": [ "P1" ], "parameters": [ { "name": "refund", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "refunds:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "HTTP 200 workflow record. Refund approval reserves funds and returns approved_pending_execution; it does not claim a completed bank transfer.", "content": { "application/json": { "example": { "data": { "id": "refund_EXAMPLE", "kind": "refund", "state": "approved_pending_execution", "resource_version": 1, "data": { "request_id": "refund_request_EXAMPLE", "payment_id": "payment_EXAMPLE", "amount_paise": 10000, "currency": "INR", "execution": "provider_or_bank_confirmation_required" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/disputes": { "post": { "operationId": "A50", "summary": "Disputes", "description": "Raise bid, payment, condition or delivery dispute with evidence and desired resolution.\n\nFreeze only affected actions under bank policy. Record deadlines and owner; preserve all original records.\n\nRequired scope: disputes:write", "tags": [ "P1" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "disputes:write", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "dispute_EXAMPLE", "kind": "dispute", "state": "open", "resource_version": 1, "data": { "sale_id": "sale_EXAMPLE", "reason_code": "PAYMENT_QUERY", "explanation": "Explain the dispute", "evidence_id": "document_EXAMPLE" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sale_id": { "type": "string", "example": "sale_EXAMPLE" }, "reason_code": { "type": "string", "example": "PAYMENT_QUERY" }, "explanation": { "type": "string", "example": "Explain the dispute" }, "evidence_id": { "type": "string", "example": "document_EXAMPLE" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "sale_id": "sale_EXAMPLE", "reason_code": "PAYMENT_QUERY", "explanation": "Explain the dispute", "evidence_id": "document_EXAMPLE", "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/disputes/{dispute}": { "get": { "operationId": "A51", "summary": "Disputes", "description": "Read evidence requests, timeline, current hold and resolution.\n\nOnly authorized parties see documents. External chargebacks are separately linked provider disputes.\n\nRequired scope: disputes:read", "tags": [ "P1" ], "parameters": [ { "name": "dispute", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "disputes:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "dispute_EXAMPLE", "kind": "dispute", "state": "open", "resource_version": 1, "data": {}, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/sale-cases/{sale}/release-authorizations": { "post": { "operationId": "A52", "summary": "Vehicle release", "description": "Issue an expiring release authorization with recipient, yard and allowed collection date.\n\nRequire approved sale, buyer requirements, required verified funds and no active hold. Payment report alone cannot unlock release.\n\nRequired scope: release:approve", "tags": [ "P0" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "release:approve", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "release_EXAMPLE", "kind": "release", "state": "valid", "resource_version": 2, "data": { "recipient": "Approved collector", "yard": "Assigned yard", "expires_at": "2026-09-15T10:00:00+00:00", "collection_date": "2026-10-01", "sale_id": "sale_EXAMPLE" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string", "example": "Approved collector" }, "yard": { "type": "string", "example": "Assigned yard" }, "expires_at": { "type": "string", "example": "2026-10-02T12:00:00+05:30" }, "collection_date": { "type": "string", "example": "2026-10-01" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "recipient": "Approved collector", "yard": "Assigned yard", "expires_at": "2026-10-02T12:00:00+05:30", "collection_date": "2026-10-01", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/release-authorizations/{release}": { "get": { "operationId": "A53", "summary": "Vehicle release", "description": "Read valid/revoked/expired/used state and necessary collection instructions.\n\nMinimize buyer PII by role. QR/token contains opaque reference, not unrestricted personal data.\n\nRequired scope: release:read", "tags": [ "P0" ], "parameters": [ { "name": "release", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "release:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "release_EXAMPLE", "kind": "release", "state": "valid", "resource_version": 1, "data": { "sale_id": "sale_EXAMPLE", "expires_at": "2026-09-15T10:00:00+00:00" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/release-authorizations/{release}/revocations": { "post": { "operationId": "A54", "summary": "Vehicle release", "description": "Revoke an unused authorization due to hold, reversal or cancellation.\n\nRace-safe with collection redemption. A used authorization opens an exception; history is not rewritten.\n\nRequired scope: release:revoke", "tags": [ "P0" ], "parameters": [ { "name": "release", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "release:revoke", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "release_EXAMPLE", "kind": "release", "state": "revoked", "resource_version": 2, "data": { "reason": "Bank revoked authorization", "sale_id": "sale_EXAMPLE", "expires_at": "2026-09-15T10:00:00+00:00" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "example": "Bank revoked authorization" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "reason": "Bank revoked authorization", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/release-authorizations/{release}/collections": { "post": { "operationId": "A56", "summary": "Collection", "description": "Redeem authorization once and record collector check, handover time and evidence.\n\nAtomic one-time redemption. Recheck active release, funds/hold policy and vehicle identity at pickup.\n\nRequired scope: collection:confirm", "tags": [ "P0" ], "parameters": [ { "name": "release", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "collection:confirm", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "release_EXAMPLE", "kind": "release", "state": "used", "resource_version": 2, "data": { "collector": "Approved collector", "vehicle_identity": "lot_EXAMPLE", "evidence_id": "document_EXAMPLE", "sale_id": "sale_EXAMPLE", "expires_at": "2026-09-15T10:00:00+00:00" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collector": { "type": "string", "example": "Approved collector" }, "vehicle_identity": { "type": "string", "example": "lot_EXAMPLE" }, "evidence_id": { "type": "string", "example": "document_EXAMPLE" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "collector": "Approved collector", "vehicle_identity": "lot_EXAMPLE", "evidence_id": "document_EXAMPLE", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/sale-cases/{sale}/transfer-updates": { "post": { "operationId": "A57", "summary": "Ownership transfer", "description": "Record submitted, pending-documents, completed or rejected transfer milestones.\n\nLabel operator-reported versus independently verified status. Government data access requires an authorized provider agreement.\n\nRequired scope: transfer:write", "tags": [ "P1" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "transfer:write", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "transfer_EXAMPLE", "kind": "transfer", "state": "submitted", "resource_version": 2, "data": { "status": "submitted", "responsible_party": "Bank transfer team", "reason": "Transfer application submitted", "evidence_id": "document_EXAMPLE", "document_checklist": [ "Application receipt" ], "occurred_at": "2026-09-12T10:00:00+05:30", "sale_id": "sale_EXAMPLE", "verification": "operator_reported", "government_verified": false }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "submitted" }, "responsible_party": { "type": "string", "example": "Bank transfer team" }, "reason": { "type": "string", "example": "Transfer application submitted" }, "evidence_id": { "type": "string", "example": "document_EXAMPLE" }, "document_checklist": { "type": "array", "items": { "type": "string" }, "example": [ "Application receipt" ] }, "occurred_at": { "type": "string", "example": "2026-09-12T10:00:00+05:30" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" }, "expected_version": { "type": "integer", "example": 1 } } }, "example": { "status": "submitted", "responsible_party": "Bank transfer team", "reason": "Transfer application submitted", "evidence_id": "document_EXAMPLE", "document_checklist": [ "Application receipt" ], "occurred_at": "2026-09-12T10:00:00+05:30", "idempotency_key": "00000000-0000-4000-8000-000000000001", "expected_version": 1 } } } } } }, "/api/v1/sale-cases/{sale}/transfer-status": { "get": { "operationId": "A58", "summary": "Ownership transfer", "description": "Read document checklist, milestones, responsible party and evidence timestamps.\n\nDo not imply direct access to RC/VAHAN or legal completion without verified evidence.\n\nRequired scope: transfer:read", "tags": [ "P1" ], "parameters": [ { "name": "sale", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "transfer:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "sale_id": "sale_EXAMPLE", "state": "not_started", "government_verified": false, "milestones": [], "resource_version": 2 } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/bank/inventory/vehicles": { "post": { "operationId": "A59", "summary": "Inventory", "description": "Create canonical vehicle using versioned dynamic schema and bank external_id.\n\nPrivate inventory identity is distinct from published lot ID. Detect duplicate external references within bank.\n\nRequired scope: inventory:write", "tags": [ "P1" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "inventory:write", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "HTTP 200: inventory_command record. data.vehicle_id is the private inventory UUID, data.inventory_version is the value required as expected_version on a later patch. Creates draft inventory only. PATCH merges supplied dynamic field IDs; omitted values are preserved. Ready or published inventory requires a controlled portal amendment and returns 409. Retrieve field IDs using the bank schema API; bank display labels remain unchanged in published vehicle responses.", "content": { "application/json": { "example": { "data": { "id": "inventory_command_EXAMPLE", "kind": "inventory_command", "state": "completed", "resource_version": 1, "data": { "vehicle_id": "5f5fcbb0-934f-4f85-92ca-f0b6753c8a53", "inventory_version": 1, "status": "draft", "external_id": "BANK_INVENTORY_001", "schema_version": 1, "title": "Example vehicle" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Example vehicle" }, "external_id": { "type": "string", "example": "BANK_INVENTORY_001" }, "schema_version": { "type": "integer", "example": 1 }, "values": { "type": "object", "example": {} }, "idempotency_key": { "type": "string", "format": "uuid", "example": "REPLACE_WITH_NEW_UUID" } } }, "example": { "title": "Example vehicle", "external_id": "BANK_INVENTORY_001", "schema_version": 1, "values": {}, "idempotency_key": "REPLACE_WITH_NEW_UUID" } } } } } }, "/api/v1/bank/inventory/vehicles/{vehicle}": { "patch": { "operationId": "A60", "summary": "Inventory", "description": "Update approved inventory fields using expected_version and field IDs.\n\nChanges material to a live sale require a controlled revision and partner notification. No direct bid edits.\n\nRequired scope: inventory:write", "tags": [ "P1" ], "parameters": [ { "name": "vehicle", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "inventory:write", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "HTTP 200: inventory_command record. data.vehicle_id is the private inventory UUID, data.inventory_version is the value required as expected_version on a later patch. Creates draft inventory only. PATCH merges supplied dynamic field IDs; omitted values are preserved. Ready or published inventory requires a controlled portal amendment and returns 409. Retrieve field IDs using the bank schema API; bank display labels remain unchanged in published vehicle responses. On this shared host send HTTP POST with _method: PATCH inside the exact signed JSON. Sign PATCH as the canonical method; Laravel authenticates the effective method. Native PATCH is blocked by the host before the application.", "content": { "application/json": { "example": { "data": { "id": "inventory_command_EXAMPLE", "kind": "inventory_command", "state": "completed", "resource_version": 1, "data": { "vehicle_id": "5f5fcbb0-934f-4f85-92ca-f0b6753c8a53", "inventory_version": 2, "status": "draft", "external_id": "BANK_INVENTORY_001", "schema_version": 1, "title": "Example vehicle" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Corrected vehicle title" }, "values": { "type": "object", "example": {} }, "expected_version": { "type": "integer", "example": 1 }, "idempotency_key": { "type": "string", "format": "uuid", "example": "REPLACE_WITH_NEW_UUID" }, "_method": { "type": "string", "example": "PATCH" } } }, "example": { "title": "Corrected vehicle title", "values": {}, "expected_version": 1, "idempotency_key": "REPLACE_WITH_NEW_UUID", "_method": "PATCH" } } } }, "x-panbids-wire-method": "POST with signed JSON _method=PATCH; canonical method remains PATCH" } }, "/api/v1/bank/inventory/schemas": { "get": { "operationId": "A63", "summary": "Dynamic schema", "description": "Return allowed field IDs, labels, types, enum values and schema version.\n\nField visibility is explicit. Stable IDs survive renaming. Partner projection excludes private bank fields.\n\nRequired scope: inventory-schema:read", "tags": [ "P1" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "inventory-schema:read", "x-panbids-actors": [ "bank" ], "responses": { "200": { "description": "JSON data plus server_time; HMAC authenticated and permission-scoped.", "content": { "application/json": { "example": { "data": [ { "schema_version": 1, "name": "Vehicle inventory", "version": 1, "fields": [] } ], "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/document-uploads": { "post": { "operationId": "A72", "summary": "Documents", "description": "Create an upload session with purpose, media type, byte size and associated object.\n\nBound size/type, quarantine and scan before use. Access checked on upload finalization and each download.\n\nRequired scope: documents:write", "tags": [ "P0" ], "parameters": [ { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "documents:write", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "document_EXAMPLE", "kind": "document", "state": "awaiting_scan", "resource_version": 1, "data": { "sale_id": "sale_EXAMPLE", "purpose": "payment_evidence", "filename": "receipt.pdf", "mime": "application/pdf", "bytes": 1234, "digest": "SHA256_OF_UPLOADED_FILE" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sale_id": { "type": "string", "example": "sale_EXAMPLE" }, "purpose": { "type": "string", "example": "payment_evidence" }, "filename": { "type": "string", "example": "receipt.pdf" }, "content_base64": { "type": "string", "example": "REPLACE_WITH_BASE64_FILE" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "sale_id": "sale_EXAMPLE", "purpose": "payment_evidence", "filename": "receipt.pdf", "content_base64": "REPLACE_WITH_BASE64_FILE", "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/documents/{document}": { "get": { "operationId": "A73", "summary": "Documents", "description": "Read metadata, checksum, version and authorized download link/route for payment or sale evidence.\n\nShort-lived downloads remain object-scoped. Existing C05 media stays backward compatible.\n\nRequired scope: documents:read", "tags": [ "P0" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "documents:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "document_EXAMPLE", "kind": "document", "state": "awaiting_scan", "resource_version": 1, "data": { "sale_id": "sale_EXAMPLE", "purpose": "payment_evidence", "filename": "receipt.pdf", "mime": "application/pdf", "bytes": 1234, "digest": "SHA256_OF_UPLOADED_FILE" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00", "download_url": "https://panbids.com/api/v1/documents/document_EXAMPLE?download=1" } } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/notifications": { "get": { "operationId": "A74", "summary": "Notifications", "description": "Read bank decisions, due reminders and release messages for the authenticated audience.\n\nDurable inbox complements webhook delivery. Message locale is separate from stable API status codes.\n\nRequired scope: notifications:read", "tags": [ "P1" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-panbids-scope": "notifications:read", "x-panbids-actors": [ "bank", "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": [ { "id": "c5fefb02-6b55-4992-8c45-4f75994d4b28", "type": "sale.approved", "subject": "sale_EXAMPLE", "resource_version": 2, "created_at": "2026-09-13T10:00:00+00:00", "acknowledgment": null } ], "current_page": 1, "last_page": 1, "total": 1 } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } } } }, "/api/v1/notifications/{notification}/acknowledgments": { "post": { "operationId": "A75", "summary": "Notifications", "description": "Record delivered/read acknowledgment with external reference.\n\nA message read receipt does not accept a sale or verify payment. Preserve distinct business acknowledgments.\n\nRequired scope: notifications:acknowledge", "tags": [ "P1" ], "parameters": [ { "name": "notification", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Key-ID", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-panbids-scope": "notifications:acknowledge", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "JSON data contains an owned workflow record, or the read shape documented below. Commands require matching Idempotency-Key, use exact-body replay and return HTTP 200. State changes are committed with a workflow event.", "content": { "application/json": { "example": { "data": { "id": "notification_ack_EXAMPLE", "kind": "notification_ack", "state": "read", "resource_version": 1, "data": { "status": "read", "external_reference": "notice_1" }, "created_at": "2026-09-13T10:00:00+00:00", "updated_at": "2026-09-13T10:00:00+00:00" }, "request_id": "req_EXAMPLE", "server_time": "2026-09-13T10:00:00+00:00" } } } }, "401": { "description": "Invalid or inactive credentials" }, "403": { "description": "Scope or actor not authorized" }, "404": { "description": "Resource unavailable to caller" }, "409": { "description": "Idempotency or version conflict" }, "422": { "description": "Invalid fields or rejected command" }, "429": { "description": "Rate limit" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "read" }, "external_reference": { "type": "string", "example": "notice_1" }, "idempotency_key": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000001" } } }, "example": { "status": "read", "external_reference": "notice_1", "idempotency_key": "00000000-0000-4000-8000-000000000001" } } } } } }, "/api/v1/webhook-subscriptions": { "get": { "operationId": "A76", "summary": "List webhook subscriptions", "tags": [ "Webhooks and winner updates" ], "x-panbids-scope": "webhooks:manage", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Successful response" }, "201": { "description": "Created" }, "4XX": { "description": "Authentication, authorization, validation, or conflict error" } } }, "post": { "operationId": "A77", "summary": "Create webhook subscription", "tags": [ "Webhooks and winner updates" ], "x-panbids-scope": "webhooks:manage", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Successful response" }, "201": { "description": "Created" }, "4XX": { "description": "Authentication, authorization, validation, or conflict error" } } } }, "/api/v1/webhook-subscriptions/{subscription}": { "patch": { "operationId": "A78", "summary": "Update webhook subscription", "tags": [ "Webhooks and winner updates" ], "x-panbids-scope": "webhooks:manage", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Successful response" }, "201": { "description": "Created" }, "4XX": { "description": "Authentication, authorization, validation, or conflict error" } } } }, "/api/v1/webhook-subscriptions/{subscription}/verify": { "post": { "operationId": "A79", "summary": "Verify webhook receiver", "tags": [ "Webhooks and winner updates" ], "x-panbids-scope": "webhooks:manage", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Successful response" }, "201": { "description": "Created" }, "4XX": { "description": "Authentication, authorization, validation, or conflict error" } } } }, "/api/v1/webhook-deliveries": { "get": { "operationId": "A80", "summary": "List webhook deliveries", "tags": [ "Webhooks and winner updates" ], "x-panbids-scope": "webhooks:manage", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Successful response" }, "201": { "description": "Created" }, "4XX": { "description": "Authentication, authorization, validation, or conflict error" } } } }, "/api/v1/webhook-deliveries/{delivery}/replay": { "post": { "operationId": "A81", "summary": "Replay webhook delivery", "tags": [ "Webhooks and winner updates" ], "x-panbids-scope": "webhooks:manage", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Successful response" }, "201": { "description": "Created" }, "4XX": { "description": "Authentication, authorization, validation, or conflict error" } } } }, "/api/v1/winner-updates": { "get": { "operationId": "A82", "summary": "Read approved winner updates", "tags": [ "Webhooks and winner updates" ], "x-panbids-scope": "sales:read", "x-panbids-actors": [ "partner" ], "responses": { "200": { "description": "Successful response" }, "201": { "description": "Created" }, "4XX": { "description": "Authentication, authorization, validation, or conflict error" } } } } } }