From e54c8e8319be92d9bdfed44b280bbd9e9202c2b3 Mon Sep 17 00:00:00 2001
From: Amirhossein Khalili <amirhosseinkhalili901@gmail.com>
Date: Thu, 20 Aug 2026 18:24:26 +0330
Subject: [PATCH] docs(api): set problem documentation namespace

---
 docs/API-SPEC.md  |  6 +++---
 docs/openapi.yaml | 10 +++++-----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/API-SPEC.md b/docs/API-SPEC.md
index ae925d8..bff256d 100644
--- a/docs/API-SPEC.md
+++ b/docs/API-SPEC.md
@@ -170,7 +170,7 @@ Every non-SSE error response uses RFC 9457 `application/problem+json` with:
 
 ```json
 {
-  "type": "https://api.zarinpal.example/problems/validation-error",
+  "type": "https://zarinpal.amiirkhl.ir/docs/errors/validation-error",
   "title": "Request validation failed",
   "status": 422,
   "detail": "One or more request values are invalid.",
@@ -277,11 +277,11 @@ Correlate `requestId`, authenticated user/merchant internal ids, run id, section
 - CSV uses UTF-8 with a BOM, Persian column names separated by normal spaces, and Persian status labels. Numeric cells remain plain calculation-safe numbers and timestamps remain UTC ISO values.
 - Analytics-access and CSV-export audit records are retained for 90 days and are accessible only to explicitly authorized backend operators; the MVP exposes no merchant audit-history surface.
 - Detail responses and CSV exports show the existing opaque source terminal reference as `شناسه پایانه`; it is tenant-scoped trace data and never an authorization input.
+- RFC 9457 problem `type` URIs use `https://zarinpal.amiirkhl.ir/docs/errors/{error-slug}` and resolve to human-readable error documentation.
 
 ## Remaining product questions
 
-1. Choose the production base URI used for dereferenceable Problem Details `type` documentation; `https://api.zarinpal.example/problems/...` is a non-production placeholder in the draft contract.
-2. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string.
+1. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string.
 
 ## Standards references
 
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 01c5b9a..7a394a9 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -676,7 +676,7 @@ components:
           schema:
             $ref: '#/components/schemas/Problem'
           example:
-            type: https://api.zarinpal.example/problems/unauthenticated
+            type: https://zarinpal.amiirkhl.ir/docs/errors/unauthenticated
             title: Authentication required
             status: 401
             detail: Sign in to continue.
@@ -706,7 +706,7 @@ components:
           schema:
             $ref: '#/components/schemas/Problem'
           example:
-            type: https://api.zarinpal.example/problems/resource-not-found
+            type: https://zarinpal.amiirkhl.ir/docs/errors/resource-not-found
             title: Resource not found
             status: 404
             detail: The requested resource is unavailable.
@@ -747,7 +747,7 @@ components:
           schema:
             $ref: '#/components/schemas/Problem'
           example:
-            type: https://api.zarinpal.example/problems/export-too-large
+            type: https://zarinpal.amiirkhl.ir/docs/errors/export-too-large
             title: Export is too large
             status: 413
             detail: Narrow the approved filters and try again.
@@ -777,7 +777,7 @@ components:
           schema:
             $ref: '#/components/schemas/Problem'
           example:
-            type: https://api.zarinpal.example/problems/validation-error
+            type: https://zarinpal.amiirkhl.ir/docs/errors/validation-error
             title: Request validation failed
             status: 422
             detail: One or more request values are invalid.
@@ -1704,7 +1704,7 @@ components:
         type:
           type: string
           format: uri
-          description: Stable problem type URI; production base URI is pending approval.
+          description: Stable problem type URI under `https://zarinpal.amiirkhl.ir/docs/errors/{error-slug}`.
         title:
           type: string
           minLength: 1