{ "openapi": "3.1.0", "info": { "title": "TrustedTools reseller API", "version": "1.0.0", "description": "Owner-approved, opt-in reseller catalog. Shared main wallet, integer USD cents, single-product orders. No withdrawals, separate API wallet, coupon stacking or automatic retries of uncertain supplier purchases." }, "servers": [ { "url": "https://trustedtools.hassan-tariq771.workers.dev/reseller/v1" } ], "security": [ { "bearerKey": [] } ], "paths": { "/me": { "get": { "operationId": "getAccount", "description": "Own API account and effective purchasing status Required scope: catalog:read.", "parameters": [], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer", "format": "int64" }, "store_name": { "type": "string" }, "status": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "purchases_enabled": { "type": "boolean" } } } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer", "format": "int64" }, "store_name": { "type": "string" }, "status": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "purchases_enabled": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/wallet": { "get": { "operationId": "getWallet", "description": "One shared main wallet. Integer USD cents; spendable = posted minus reserved Required scope: wallet:read.", "parameters": [], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/products": { "get": { "operationId": "listProducts", "description": "At most 50 products. Pass next_cursor as after; empty ends pagination. Prices and stock are revalidated at purchase. Required scope: catalog:read.", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "next_cursor": { "type": "string" }, "revision": { "type": "integer", "format": "int64" } } } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "next_cursor": { "type": "string" }, "revision": { "type": "integer", "format": "int64" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/products/{id}": { "get": { "operationId": "getProduct", "description": "Current published product; a removed/hidden product returns 404 Required scope: catalog:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/products/{id}/image": { "get": { "operationId": "getProductImage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Protected managed JPG/PNG image", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/categories": { "get": { "operationId": "listCategories", "description": "Published category hierarchy and product counts Required scope: catalog:read.", "parameters": [], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/catalog/changes": { "get": { "operationId": "catalogChanges", "description": "Refresh changed IDs using GET /products/{id}; remove on 404. A null product_id instructs a full refresh. At most 50 events; continue from last cursor. Required scope: catalog:read.", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/quotes": { "post": { "operationId": "createQuote", "description": "A 60-second price quote; reserves_stock=false and no wallet reservation. Required scope: quotes:create.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "product_id": { "type": "integer", "format": "int64" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 } } } } } }, "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders": { "get": { "operationId": "listOrders", "description": "Own orders, newest first, maximum 50. Continue before the last returned id. Required scope: orders:read.", "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createOrder", "description": "Require a stable Idempotency-Key and client_order_id. Use a valid quote_id or max_total_minor. Exact retries recover the same order after quote expiry and key rotation. Changed request data conflicts. Accepted work survives HTTP disconnects. Delivery is fetched separately. Required scope: orders:write.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "description": "Own order state. needs_review may represent an upstream purchase: never create a replacement order to retry it. Required scope: orders:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/delivery": { "get": { "operationId": "getDelivery", "description": "Private versioned per-unit delivery. Repeated reads never allocate stock. Pending delivery returns 409. Required scope: delivery:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "unit": { "type": "integer", "format": "int64" }, "version": { "type": "integer", "format": "int64" }, "content": { "type": "string" } } } } } } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "unit": { "type": "integer", "format": "int64" }, "version": { "type": "integer", "format": "int64" }, "content": { "type": "string" } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/cancel": { "post": { "operationId": "cancelOrder", "description": "Only before an upstream attempt or while awaiting manual delivery. Idempotent; releases reserved funds. Processing/review/delivered orders conflict. Required scope: orders:cancel.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } }, "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/claims": { "post": { "operationId": "openClaim", "description": "One open claim per owned delivered unit. Warranty claims require snapshotted, unexpired coverage; other access issues can be reviewed by support. Required scope: claims:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "unit": { "type": "integer", "format": "int64" }, "category": { "enum": [ "access", "warranty", "other" ] }, "description": { "type": "string", "minLength": 5, "maxLength": 4000 } } } } } }, "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Claim" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/claims": { "get": { "operationId": "listClaims", "description": "Own claims, maximum 50, newest first. Required scope: claims:read.", "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/claims/{id}": { "get": { "operationId": "getClaim", "description": "Owned claim and latest 50 protected conversation messages. Required scope: claims:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/claims/{id}/messages": { "post": { "operationId": "replyClaim", "description": "Reply to an open owned claim. Required scope: claims:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 } } } } } }, "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/claims/{id}/evidence": { "get": { "operationId": "getClaimEvidence", "description": "List evidence metadata. Add ?file=ID to download one attachment; no public file URL. Required scope: claims:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "file", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "addClaimEvidence", "description": "JPG, PNG or plain text, at most 80000 decoded bytes and five files per claim. Files are private and encrypted. Required scope: claims:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "mime": { "enum": [ "image/jpeg", "image/png", "text/plain" ] }, "data": { "type": "string", "contentEncoding": "base64" } } } } } }, "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/sandbox/products": { "get": { "operationId": "sandboxProducts", "description": "Synthetic test product id=1, price=100 cents. Never contacts suppliers. Required scope: catalog:read.", "parameters": [], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/sandbox/wallet": { "get": { "operationId": "sandboxWallet", "description": "Fixed synthetic test balance 10000 cents; never reads or debits the main wallet. Required scope: wallet:read.", "parameters": [], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/sandbox/orders": { "post": { "operationId": "sandboxPurchase", "description": "Synthetic process-local fixture. Data resets on restart; bounded to 100 orders/account. Uses stable request keys and references; never creates real orders. Required scope: catalog:read.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "product_id": { "type": "integer", "format": "int64" }, "quantity": { "type": "integer", "format": "int64" }, "client_order_id": { "type": "string" }, "max_total_minor": { "type": "integer", "format": "int64" } } } } } }, "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/sandbox/orders/{id}": { "get": { "operationId": "sandboxOrder", "description": "Synthetic order id (sbx_ prefix) Required scope: catalog:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/sandbox/orders/{id}/delivery": { "get": { "operationId": "sandboxDelivery", "description": "Synthetic demo credentials only. Required scope: catalog:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful result", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Resource accepted or existing resource replayed", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerKey": { "type": "http", "scheme": "bearer", "description": "Digest-only server key, valid until revoked. Read-only or purchase/delivery/claims scopes. Never put keys in URLs/browser code." } }, "responses": { "Error": { "description": "401 invalid_key; 403 insufficient_scope/access_denied; 404 not_found; 409 state_conflict/price_changed/limit_reached/insufficient_funds/out_of_stock; 415 json_required; 422 invalid_request/invalid_json; 429 rate_limited (Retry-After); 503 unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } }, "schemas": { "Wallet": { "type": "object", "additionalProperties": false, "properties": { "currency": { "const": "USD" }, "wallet": { "const": "main" }, "balance_minor": { "type": "integer", "format": "int64" }, "posted_minor": { "type": "integer", "format": "int64" }, "reserved_minor": { "type": "integer", "format": "int64" }, "restricted_minor": { "type": "integer", "format": "int64" }, "purchases_enabled": { "type": "boolean" } } }, "Product": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer", "format": "int64" }, "category_id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_minor": { "type": "integer", "format": "int64" }, "currency": { "const": "USD" }, "stock": { "type": "integer", "format": "int64" }, "delivery_mode": { "type": "string" }, "quantity_max": { "type": "integer", "format": "int64" }, "can_purchase": { "type": "boolean" }, "availability_reason": { "type": "string" }, "image_path": { "type": "string" }, "stock_observed_at": { "type": "string", "format": "date-time" } } }, "Quote": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "product_id": { "type": "integer", "format": "int64" }, "quantity": { "type": "integer", "format": "int64" }, "total_minor": { "type": "integer", "format": "int64" }, "currency": { "const": "USD" }, "expires_at": { "type": "string", "format": "date-time" }, "reserves_stock": { "const": false } } }, "Purchase": { "type": "object", "additionalProperties": false, "properties": { "product_id": { "type": "integer", "format": "int64" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "client_order_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "max_total_minor": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "quote_id": { "type": "string" } }, "required": [ "product_id", "quantity", "client_order_id" ], "anyOf": [ { "required": [ "quote_id" ] }, { "required": [ "max_total_minor" ] } ] }, "Order": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer", "format": "int64" }, "client_order_id": { "type": "string" }, "product_id": { "type": "integer", "format": "int64" }, "product_name": { "type": "string" }, "quantity": { "type": "integer", "format": "int64" }, "total_minor": { "type": "integer", "format": "int64" }, "captured_minor": { "type": "integer", "format": "int64" }, "refunded_minor": { "type": "integer", "format": "int64" }, "state": { "enum": [ "queued", "processing", "awaiting_manual", "needs_review", "delivered", "cancelled", "failed", "refunded" ] }, "error_code": { "type": "string" }, "warranty": { "type": "string" }, "warranty_days": { "type": "integer", "format": "int64" }, "warranty_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Claim": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer", "format": "int64" }, "order_id": { "type": "integer", "format": "int64" }, "unit": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "resolution": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }