starcoach-hackathon/zarinpal-analytics-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): expose scoped terminal references

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 18:20:13 +03:30
parent 20c9ba35a6
commit af69f549c0
2 changed files with 6 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/API-SPEC.md
View File

@@ -117,7 +117,7 @@ Ordering is stable and deterministic: `createdAt DESC, sessionId DESC`. The opaq
- Total counts are omitted from page responses to avoid an additional unbounded count query. Aggregate cards remain the reconciliation source.
- Reusing a cursor with changed filters, another merchant, or after expiry returns `400 INVALID_CURSOR` without disclosing which binding failed.
Detail rows expose only fields available in the authorized view: opaque merchant-local `sessionId`, terminal display/reference id, status, amount/fee in Rial, timestamps, attempt count, and a bounded ordered attempt summary where relevant. They exclude source merchant keys, payer tokens, credentials, raw session tokens, peer data, internal database keys, and undocumented response-code meanings.
Detail rows expose only fields available in the authorized view: opaque merchant-local `sessionId`, the existing opaque source terminal reference labeled `شناسه پایانه`, status, amount/fee in Rial, timestamps, attempt count, and a bounded ordered attempt summary where relevant. The terminal reference is resolved and displayed only inside the authenticated merchant boundary and never grants authorization. Rows exclude source merchant keys, payer tokens, credentials, raw session tokens, peer data, internal database keys, and undocumented response-code meanings.
## CSV export
@@ -276,12 +276,12 @@ Correlate `requestId`, authenticated user/merchant internal ids, run id, section
- CSV export is limited to 3 requests per 10 minutes with burst 1 in independent authenticated-user and merchant buckets.
- 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.
## Remaining product questions
1. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias.
2. 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.
3. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string.
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.
## Standards references

3
docs/openapi.yaml
View File

@@ -608,7 +608,7 @@ components:
name: terminalId
in: query
required: false
description: Opaque terminal reference resolved only inside the authenticated merchant.
description: Approved opaque source terminal reference resolved only inside the authenticated merchant; never an authorization input.
schema:
type: string
minLength: 1
@@ -1506,6 +1506,7 @@ components:
maxLength: 128
terminalId:
type: string
description: Existing opaque source terminal reference shown as `شناسه پایانه`; tenant-scoped display/trace data only.
minLength: 1
maxLength: 128
sessionStatus: