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

docs(api): localize CSV columns in Persian

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 18:17:19 +03:30
parent 8358cc4d14
commit d133019a14
2 changed files with 18 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/API-SPEC.md
View File

@@ -128,7 +128,7 @@ Detail rows expose only fields available in the authorized view: opaque merchant
- `Content-Type: text/csv; charset=utf-8`
- UTF-8 with one leading BOM for common Persian spreadsheet compatibility
- RFC 4180-style comma separation, header row, CRLF records, and doubled quotes
- Stable ASCII `snake_case` column names; Persian values remain UTF-8
- Stable Persian column names separated by normal spaces, with Persian status labels
- UTC ISO timestamps with `Z`; Rial integer values; no locale-formatted numbers
- `Content-Disposition: attachment` with an ASCII `filename` fallback followed by an RFC 6266 `filename*=UTF-8''...` value
- `Cache-Control: private, no-store` and `X-Content-Type-Options: nosniff`
@@ -273,14 +273,14 @@ Correlate `requestId`, authenticated user/merchant internal ids, run id, section
- Merchant-facing detail CSV export is synchronous in the MVP and honors the current authorized tenant scope and approved filters.
- CSV export is capped at 100,000 rows, 50 MiB estimated uncompressed output, and a 60-second deadline.
- 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.
## Remaining product questions
1. Approve UTF-8 BOM output for spreadsheet compatibility and stable ASCII column headers, or require localized Persian header names.
2. Define retention and operator access policy for analytics-access and CSV-export audit records; Identity's 30-day demo-auth retention does not automatically cover these events.
3. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias.
4. 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.
5. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string.
1. Define retention and operator access policy for analytics-access and CSV-export audit records; Identity's 30-day demo-auth retention does not automatically cover these events.
2. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias.
3. 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.
4. 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