{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/elemza.com" } ], "info": { "name": "Emza Platform \u2014 Public API v1", "_postman_id": "6bd762d2-4759-4768-993c-20d5fd42f659", "description": "Public REST API for Contract creation and Electronic Signature lifecycle. Bilingual (fa\/en) errors. RFC 7807 problem+json envelope.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Contracts", "description": "", "item": [ { "name": "Public signed-URL download.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/dl", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/dl", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char public code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Validates Laravel's `signed` middleware. No Bearer token required \u2014\nthe URL signature is the auth proof. The signature is generated by\n`downloadPdf()` after the bearer was verified, so this is functionally\nequivalent to a 24h time-bounded capability URL.\n\nRecords an `ApiRequestLog`-style entry via the underlying `ContractDownload`\naudit table (same trail as the user-panel signed-link download flow)." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WJSA8HZ09HV9GBG6T44" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01KRHE8WJSA8HZ09HV9GBG6T44\"}", "name": "" } ] }, { "name": "List contracts", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts", "query": [ { "key": "status", "value": "waiting_signature", "description": "Filter by status: draft|waiting_signature|completed|voided|canceled.", "disabled": false }, { "key": "created_after", "value": "2026-01-01T00%3A00%3A00Z", "description": "ISO 8601 datetime.", "disabled": false }, { "key": "created_before", "value": "architecto", "description": "ISO 8601 datetime.", "disabled": false }, { "key": "signer_mobile", "value": "09121234567", "description": "Iran mobile regex 09XXXXXXXXX. **Requires `signers:read_pii` scope.**", "disabled": false }, { "key": "signer_national_code", "value": "architecto", "description": "10-digit Iran national code. **Requires `signers:read_pii` scope.**", "disabled": false }, { "key": "template_id", "value": "16", "description": "Filter by template.", "disabled": false }, { "key": "is_private", "value": "", "description": "Filter by privacy flag.", "disabled": true }, { "key": "page", "value": "16", "description": "Default 1.", "disabled": false }, { "key": "per_page", "value": "16", "description": "Max 100. Default 20.", "disabled": false }, { "key": "sort", "value": "architecto", "description": "created_at | -created_at | completed_at | -completed_at. Default -created_at.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/contracts?status=waiting_signature&created_after=2026-01-01T00%3A00%3A00Z&created_before=architecto&signer_mobile=09121234567&signer_national_code=architecto&template_id=16&is_private=&page=16&per_page=16&sort=architecto" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"status\":\"draft\",\"created_after\":\"2026-05-13T23:20:57\",\"created_before\":\"2026-05-13T23:20:57\",\"signer_mobile\":\"09564255931\",\"signer_national_code\":\"ikhwaykcmy\",\"template_id\":16,\"is_private\":false,\"page\":22,\"per_page\":7,\"sort\":\"completed_at\"}" }, "description": "Returns paginated contracts visible to caller. Org root sees own + descendants'\nnon-private contracts; non-root sees own + contracts where they're a signer.\n\nScope: `contracts:read`.\n\n**PII filter scope requirement:** filtering by `signer_mobile` or\n`signer_national_code` requires the additional `signers:read_pii` ability\non your token. Without it, those query parameters return\n**403 `scope_missing`**. This prevents a low-privilege `contracts:read`\ntoken from using the index as a confirmation oracle to check whether a\ngiven mobile\/national-code signs any contract on the owner's tree.\n\nThe `*` wildcard scope also passes the check." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WM9R0KTDR3ECFDY2JD0" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WM9R0KTDR3ECFDY2JD0\"}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/scope_missing\",\n \"status\": 403,\n \"code\": \"scope_missing\",\n \"title_fa\": \"\u0627\u06cc\u0646 \u0641\u06cc\u0644\u062a\u0631 \u0646\u06cc\u0627\u0632 \u0628\u0647 \u0645\u062c\u0648\u0632 signers:read_pii \u062f\u0627\u0631\u062f\",\n \"title_en\": \"This filter requires the signers:read_pii scope\",\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "PII filter without scope" } ] }, { "name": "Get contract", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code", "variable": [ { "id": "code", "key": "code", "value": "ABC1234567XYZ890", "description": "16-char public code (A-Z, 0-9)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns full contract shape with embedded signers, per-page geometry,\nand template positions snapshot.\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WMFTGBCSPQD772SFBS2" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WMFTGBCSPQD772SFBS2\"}", "name": "" } ] }, { "name": "Download signed PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/pdf", "query": [ { "key": "format", "value": "url", "description": "redirect|url|stream. Default redirect.", "disabled": false }, { "key": "ttl", "value": "16", "description": "Signed URL lifetime in seconds (60..86400). Default 86400. Ignored when `format=stream`.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/pdf?format=url&ttl=16", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char public code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the final signed PDF in one of three formats (Phase 3):\n\n- `format=redirect` (default) \u2014 `302 Found` to a signed URL (24h TTL).\n The signed URL points at the unauthenticated `\/api\/v1\/contracts\/{code}\/dl`\n route, which validates the signature and streams the file. Use this when\n embedding in `` for partner-facing UIs.\n- `format=url` \u2014 JSON envelope with `url`, `expires_at`, `filename`, `size_bytes`,\n `checksum_sha256`. Use this when the API client wants to hand the URL\n to another system, embed in email, or pre-flight before downloading.\n- `format=stream` \u2014 streams the PDF inline (consumes API egress). Use when\n the caller is a backend service that wants the bytes in one round-trip.\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WN0N5RGPWKT3GBWRRXB" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01KRHE8WN0N5RGPWKT3GBWRRXB\"}", "name": "" } ] }, { "name": "Poll processing status", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/processing", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/processing", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lightweight (<200 bytes) status of the rasterization + signer-creation job.\nReads `contract:progress:{id}` cache key directly \u2014 no DB hit.\n\n**Step values:** `files`, `signers`, `sms`, `done`, `error`.\n\nReturns `ready=true` when `step=done`. If progress key is gone (TTL expired)\nand contract has signers + pages, falls back to `ready=true` (job finished\nearlier and key was reaped).\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WNFY730DN7F9DZA757Z" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01KRHE8WNFY730DN7F9DZA757Z\"}", "name": "" } ] }, { "name": "Create contract", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "title", "value": "\u0642\u0631\u0627\u0631\u062f\u0627\u062f \u0628\u06cc\u0645\u0647 \u0634\u062e\u0635 \u062b\u0627\u0644\u062b", "type": "text", "description": "Contract title (1..120 chars)." }, { "key": "all_pages_signature", "value": "", "type": "text", "description": "Default false. When true, every page must carry the signature element." }, { "key": "is_private", "value": "", "type": "text", "description": "Default false. When true, hides contract from org-ancestors." }, { "key": "template_id", "value": "16", "type": "text", "description": "Optional \u2014 must be owned by caller or shared from org root." }, { "key": "template_enforcement", "value": "architecto", "type": "text", "description": "strict|loose. Optional \u2014 only meaningful when template_id is set." }, { "key": "signers[0]", "value": "architecto", "type": "text", "description": "" }, { "key": "file", "src": [], "type": "file" } ] }, "description": "Creates a new contract. Two modes:\n\n**One-shot** \u2014 multipart\/form-data with `file` field + metadata. File is\npersisted to staging and `ProcessContractFilesJob` is dispatched. Optional\n`signers[]` are added by the same job after page rasterization completes.\nResponse is **202 Accepted**; poll `_links.processing` until `ready=true`.\n\n**Multi-step** \u2014 JSON without `file`. Creates a `draft` contract row only.\nCaller then issues `POST \/contracts\/{code}\/files` to attach the document.\n\nScope: `contracts:write`." }, "response": [] }, { "name": "Upload contract file(s) (two-step flow)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/files", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/files", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "file", "src": [], "type": "file" } ] }, "description": "Attaches a file to an existing **draft** contract that has no pages yet.\nSame async pipeline as `POST \/contracts` one-shot: stages bytes, dispatches\n`ProcessContractFilesJob`, returns 202 with the `processing` link.\n\nScope: `contracts:write`." }, "response": [] }, { "name": "Cancel contract", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char public code." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Cancels a contract in `draft` or `waiting_signature` state. Refunds the\nbilled amount to the original wallet (100% if no signer signed, 50% if any\nShahkar was consumed). Deletes contract files from storage. Waiting signers\nreceive an SMS notifying them the contract was canceled.\n\nScope: `contracts:write`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"code\": \"ABC1234567XYZ890\",\n \"status\": \"canceled\",\n \"canceled_at\": \"2026-05-11T10:00:00.000Z\",\n \"refund\": { \"amount\": 60000, \"currency\": \"IRT\" }\n }\n}", "name": "" } ] } ] }, { "name": "Forms \u2014 read-only access to v2 forms owned by the authenticated user.", "description": "\nPhase 5 MVP: list + show + stats. Submissions endpoint will land in Phase 5b\nwith proper pagination + transformer.", "item": [ { "name": "List forms (v2 only \u2014 schema_version='2.0')", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns up to 100 most recent v2-schema forms owned by the calling user.\nForm Builder v1 records are excluded \u2014 use the dashboard for those.\n\nScope required: `forms:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 142,\n \"slug\": \"frm-e7465df28dd45785\",\n \"title\": \"\u0642\u0631\u0627\u0631\u062f\u0627\u062f \u0647\u0645\u06a9\u0627\u0631\u06cc\",\n \"status\": \"published\",\n \"renderer_type\": \"online\",\n \"submission_count\": 23,\n \"views_count\": 187,\n \"created_at\": \"2026-05-10T14:32:00.000Z\"\n }\n ]\n}", "name": "" } ] }, { "name": "Show one form (metadata only \u2014 schema available via dedicated \/schema endpoint in future)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug", "variable": [ { "id": "slug", "key": "slug", "value": "frm-e7465df28dd45785", "description": "The form's public slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Scope required: `forms:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": 142,\n \"slug\": \"frm-e7465df28dd45785\",\n \"title\": \"\u0642\u0631\u0627\u0631\u062f\u0627\u062f \u0647\u0645\u06a9\u0627\u0631\u06cc\",\n \"status\": \"published\",\n \"renderer_type\": \"online\",\n \"submission_count\": 23,\n \"views_count\": 187,\n \"created_at\": \"2026-05-10T14:32:00.000Z\"\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/form_not_found\",\n \"status\": 404,\n \"code\": \"form_not_found\",\n \"title_fa\": \"\u0641\u0631\u0645 \u06cc\u0627\u0641\u062a \u0646\u0634\u062f \u06cc\u0627 \u0645\u062a\u0639\u0644\u0642 \u0628\u0647 \u0634\u0645\u0627 \u0646\u06cc\u0633\u062a\",\n \"title_en\": \"Form not found or not owned by the caller\",\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "Not found or not owned" } ] }, { "name": "Form analytics (views\/starts\/submissions\/conversion rates).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/forms\/:slug\/stats", "query": [], "raw": "{{baseUrl}}\/api\/v1\/forms\/:slug\/stats", "variable": [ { "id": "slug", "key": "slug", "value": "frm-e7465df28dd45785", "description": "The form's public slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Aggregated counters returned by `FormAnalyticsService::stats()`. Includes\nlifetime totals plus 7-day and 30-day windows so you can chart trends without\nadditional queries.\n\nScope required: `forms:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"totals\": {\n \"views\": 187,\n \"starts\": 41,\n \"submissions\": 23,\n \"conversion_rate\": 56.1\n },\n \"last_7_days\": { \"views\": 32, \"starts\": 9, \"submissions\": 4 },\n \"last_30_days\": { \"views\": 154, \"starts\": 38, \"submissions\": 21 }\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/form_not_found\",\n \"status\": 404, \"code\": \"form_not_found\",\n \"title_fa\": \"\u0641\u0631\u0645 \u06cc\u0627\u0641\u062a \u0646\u0634\u062f \u06cc\u0627 \u0645\u062a\u0639\u0644\u0642 \u0628\u0647 \u0634\u0645\u0627 \u0646\u06cc\u0633\u062a\",\n \"title_en\": \"Form not found or not owned by the caller\",\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "Not found or not owned" } ] } ] }, { "name": "Meta \u2014 health, identity, quota, cost", "description": "", "item": [ { "name": "Health check", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/health", "query": [], "raw": "{{baseUrl}}\/api\/v1\/health" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lightweight liveness probe. **No authentication required.**\nAlways returns 200 if the API process is up.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"ok\",\n \"time\": \"2026-05-11T11:53:29.399Z\",\n \"version\": \"v1.0.0\"\n}", "name": "" } ] }, { "name": "Caller identity", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/me", "query": [], "raw": "{{baseUrl}}\/api\/v1\/me" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns information about the authenticated token, its owner user, and\nthe billing context (wallet balance, org root). Any valid token can call this \u2014\nno specific scope required.\n\nUse the `token.mode` field to confirm whether your token is in **live** mode\n(charges your wallet, real KYC\/SMS) or **test** sandbox mode (zero wallet\nimpact, mocked side effects). `wallet_balance` is always in tomans (IRR\/10)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"token\": {\n \"id\": \"42\",\n \"name\": \"production-server-2026\",\n \"mode\": \"live\",\n \"scopes\": [\"contracts:read\", \"contracts:write\", \"webhooks:manage\"],\n \"ip_whitelist\": [\"203.0.113.5\/32\"],\n \"expires_at\": \"2027-01-01T00:00:00.000Z\",\n \"last_used_at\": \"2026-05-13T18:00:42.000Z\"\n },\n \"user\": {\n \"id\": 1234,\n \"name\": \"\u0622\u0631\u0634 \u0628\u0646\u0627\u0626\u06cc\u0627\u0646 \u0686\u0645\u0644\u0647\",\n \"type\": \"personal\",\n \"is_org_root\": false,\n \"org_root_id\": null\n },\n \"billing_actor_user_id\": 1234,\n \"wallet_balance\": 849310\n }\n}", "name": "Live token" }, { "header": [], "code": 200, "body": "{\n \"data\": {\n \"token\": {\n \"id\": \"13\",\n \"name\": \"ci-tests-sandbox\",\n \"mode\": \"test\",\n \"scopes\": [\"*\"],\n \"ip_whitelist\": [],\n \"expires_at\": null,\n \"last_used_at\": \"2026-05-13T17:52:23.000Z\"\n },\n \"user\": {\n \"id\": 1234,\n \"name\": \"\u0622\u0631\u0634 \u0628\u0646\u0627\u0626\u06cc\u0627\u0646 \u0686\u0645\u0644\u0647\",\n \"type\": \"personal\",\n \"is_org_root\": false,\n \"org_root_id\": null\n },\n \"billing_actor_user_id\": 1234,\n \"wallet_balance\": 849310\n }\n}", "name": "Sandbox\/test token" } ] }, { "name": "Current quota", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/quota", "query": [], "raw": "{{baseUrl}}\/api\/v1\/quota" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the caller's current-month signature quota usage + remaining,\npackage tier, and today's Shahkar verification credits.\n\n**Quota semantics:**\n- `free_quota` is the monthly allowance from the user's active package\n (Free=3, Bronze=30, Silver=100, Gold=200). Returns 0 if the package\n is expired or unset.\n- `used` is total signatures recorded since `package_started_at` (so\n pre-purchase usage doesn't deplete a freshly-bought plan).\n- `remaining = free_quota - used` for limited plans. **null** means\n genuinely unlimited (Gold-tier `signature_limit` is NULL).\n- When `remaining` reaches 0, signatures still work \u2014 they're billed\n as overage from the wallet at the per-unit tariff rate minus the\n package discount (Free=0%, Bronze=20%, Silver=35%, Gold=50%).\n\n**Shahkar credits** are separate from signature quota. Daily allowance\nby package (Free=3, Bronze=5, Silver=10, Gold=20). Once exhausted, the\nclient must purchase batch top-ups before further Shahkar verifications.\n\nScope required: `contracts:read`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"service\": \"electronic_signature\",\n \"period_start\": \"2026-05-01T00:00:00.000Z\",\n \"period_end\": \"2026-05-31T23:59:59.999Z\",\n \"package\": { \"slug\": \"bronze\", \"name\": \"\u0628\u0631\u0646\u0632\u06cc\" },\n \"free_quota\": 30,\n \"used\": 17,\n \"remaining\": 13,\n \"shahkar\": {\n \"free_limit\": 5,\n \"used_today\": 2,\n \"free_remaining\": 3,\n \"extra_credits\": 0,\n \"extra_remaining\": 0,\n \"allowed\": true\n }\n }\n}", "name": "Bronze user mid-month" }, { "header": [], "code": 200, "body": "{\n \"data\": {\n \"service\": \"electronic_signature\",\n \"period_start\": \"2026-05-01T00:00:00.000Z\",\n \"period_end\": \"2026-05-31T23:59:59.999Z\",\n \"package\": { \"slug\": \"gold\", \"name\": \"\u0637\u0644\u0627\u06cc\u06cc\" },\n \"free_quota\": 0,\n \"used\": 412,\n \"remaining\": null,\n \"shahkar\": {\n \"free_limit\": 20, \"used_today\": 4,\n \"free_remaining\": 16, \"extra_credits\": 0,\n \"extra_remaining\": 0, \"allowed\": true\n }\n }\n}", "name": "Gold (unlimited)" }, { "header": [], "code": 200, "body": "{\n \"data\": {\n \"service\": \"electronic_signature\",\n \"period_start\": \"2026-05-01T00:00:00.000Z\",\n \"period_end\": \"2026-05-31T23:59:59.999Z\",\n \"package\": null,\n \"free_quota\": 0,\n \"used\": 0,\n \"remaining\": 0,\n \"shahkar\": {\n \"free_limit\": 0, \"used_today\": 0,\n \"free_remaining\": 0, \"extra_credits\": 0,\n \"extra_remaining\": 0, \"allowed\": false\n }\n }\n}", "name": "No active package (pay-per-use)" } ] }, { "name": "Cost estimate", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cost-estimate", "query": [ { "key": "signers", "value": "3", "description": "Number of signers (1-20).", "disabled": false }, { "key": "discount_code", "value": "WELCOME10", "description": "Optional discount code.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/cost-estimate?signers=3&discount_code=WELCOME10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"signers\":16,\"discount_code\":\"n\"}" }, "description": "Returns full cost breakdown for a hypothetical contract without committing.\nUse before calling `POST \/contracts` so users can see \"X toman\" upfront.\n\nScope required: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WKH1YB2NTD6D607WV75" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WKH1YB2NTD6D607WV75\"}", "name": "" } ] } ] }, { "name": "Signers", "description": "\nSigner endpoints for a contract.\n\nPhase 1 = read-only (index + show). Resend + delete = Phase 2 (mutations).\n\nSpec: docs\/api-master-plan\/02-endpoint-surface.md (Signer endpoints).", "item": [ { "name": "List signers", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists all signers on a contract. PII (mobile, national_code) is masked\nunless the caller's token has `signers:read_pii` scope.\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WP548K9PK9DM360HMFY" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01KRHE8WP548K9PK9DM360HMFY\"}", "name": "" } ] }, { "name": "Get signer", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers\/:slug", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." }, { "id": "slug", "key": "slug", "value": "DEF456GHJ789KLM", "description": "Per-signer slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Detailed view of a single signer. PII masked unless token has `signers:read_pii`.\n\nScope: `contracts:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WPK8E5KD8HM7Z66FTF9" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01KRHE8WPK8E5KD8HM7Z66FTF9\"}", "name": "" } ] }, { "name": "Add signers", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"signers\":[\"architecto\"]}" }, "description": "Adds one or more signers to a draft contract. Runs **mandatory** Shahkar\npre-validation (mobile \u2194 national_code match) per signer in production.\nOn success, contract transitions to `waiting_signature` and SMS dispatch\njobs are queued for first-order signers.\n\nScope: `signers:write`." }, "response": [] }, { "name": "Resend signing link SMS", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers\/:slug\/resend", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers\/:slug\/resend", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." }, { "id": "slug", "key": "slug", "value": "architecto", "description": "Per-signer slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Re-sends the signing-link SMS to a waiting signer. Rate-limited to 3 per\n5 minutes per signer (returns 429 `rate_limit_exceeded`).\n\nScope: `signers:write`." }, "response": [] }, { "name": "Remove signer", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/contracts\/:code\/signers\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/contracts\/:code\/signers\/:slug", "variable": [ { "id": "code", "key": "code", "value": "architecto", "description": "16-char contract code." }, { "id": "slug", "key": "slug", "value": "architecto", "description": "Per-signer slug." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Removes a signer from a contract. Only allowed when:\n- Signer status is `waiting` (not yet signed)\n- Contract status is `draft` or `waiting_signature`\n\nScope: `signers:write`." }, "response": [ { "header": [], "code": 204, "body": "{}", "name": "" } ] } ] }, { "name": "Templates", "description": "\nTemplate endpoints \u2014 read-only in v1.0. CRUD lands in v1.x.\n\nSpec: docs\/api-master-plan\/02-endpoint-surface.md (Template endpoints).", "item": [ { "name": "List templates", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates", "query": [ { "key": "view_scope", "value": "architecto", "description": "self | shared_from_parent | all_org. Default self.", "disabled": false }, { "key": "active", "value": "", "description": "Filter by active status.", "disabled": true }, { "key": "page", "value": "16", "description": "", "disabled": false }, { "key": "per_page", "value": "16", "description": "Max 100. Default 20.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/templates?view_scope=architecto&active=&page=16&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"view_scope\":\"self\",\"active\":false,\"page\":16,\"per_page\":22}" }, "description": "Lists contract templates the caller can use.\n\n`view_scope` options:\n- `self` \u2014 own templates only (default)\n- `shared_from_parent` \u2014 own + templates shared by org parent\/root\n- `all_org` \u2014 entire org tree (org root only)\n\nScope: `templates:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WQ6V27R11FAYX547415" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WQ6V27R11FAYX547415\"}", "name": "" } ] }, { "name": "Get template", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates\/:id", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the template." }, { "id": "template", "key": "template", "value": "16", "description": "Template ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Full template shape with embedded positions + page geometry + sample preview link.\n\nScope: `templates:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WQQXR58JHNF0PJNYJJ8" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 404, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/not_found\",\"status\":404,\"code\":\"not_found\",\"title_fa\":\"\\u0645\\u0646\\u0628\\u0639 \\u06cc\\u0627\\u0641\\u062a \\u0646\\u0634\\u062f\",\"title_en\":\"Resource not found\",\"request_id\":\"01KRHE8WQQXR58JHNF0PJNYJJ8\"}", "name": "" } ] }, { "name": "Template page preview", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates\/:template\/preview\/:page", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates\/:template\/preview\/:page", "variable": [ { "id": "template", "key": "template", "value": "16", "description": "Template ID." }, { "id": "page", "key": "page", "value": "16", "description": "Page number (1-indexed)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a signed URL to a single page preview image (PNG).\n**Phase 1 stub** \u2014 `url` is null until Phase 3 wires Storage::temporaryUrl().\n\nScope: `templates:read`." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WQWKZPK2WHZZ35QRQMY" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WQWKZPK2WHZZ35QRQMY\"}", "name": "" } ] } ] }, { "name": "Webhooks", "description": "\nOutbound webhook subscriptions. Customers create one or more endpoints, each\nfiltered by an array of event names. Deliveries are signed with HMAC-SHA256\nvia the secret returned at create-time (shown only once).\n\nScope: `webhooks:manage`.", "item": [ { "name": "List webhook subscriptions", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks", "query": [ { "key": "active", "value": "", "description": "Filter by active state.", "disabled": true }, { "key": "page", "value": "16", "description": "", "disabled": false }, { "key": "per_page", "value": "16", "description": "Max 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/webhooks?active=&page=16&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"active\":true,\"page\":16,\"per_page\":22}" }, "description": "" }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WRYSR7YDSV5XGGW83X3" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WRYSR7YDSV5XGGW83X3\"}", "name": "" } ] }, { "name": "Get webhook subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WS5N5GQWJDB3P8R26MG" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WS5N5GQWJDB3P8R26MG\"}", "name": "" } ] }, { "name": "List webhook deliveries", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-deliveries", "query": [ { "key": "subscription_id", "value": "architecto", "description": "Filter by subscription.", "disabled": false }, { "key": "event_name", "value": "architecto", "description": "Filter by event name.", "disabled": false }, { "key": "status", "value": "architecto", "description": "pending|delivered|failed|dead-letter", "disabled": false }, { "key": "page", "value": "16", "description": "", "disabled": false }, { "key": "per_page", "value": "16", "description": "Max 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/webhook-deliveries?subscription_id=architecto&event_name=architecto&status=architecto&page=16&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WSNFZ5ABRQPF7K8N2G1" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WSNFZ5ABRQPF7K8N2G1\"}", "name": "" } ] }, { "name": "Get webhook delivery", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-deliveries\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-deliveries\/:id", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook delivery." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Shows full payload, response code, error message, attempt history." }, "response": [ { "header": [ { "key": "x-request-id", "value": "01KRHE8WSWEFY6JFDHPGFTAHW3" }, { "key": "x-emza-api-version", "value": "v1" }, { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" }, { "key": "access-control-expose-headers", "value": "X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After, X-Emza-API-Version, X-Idempotent-Replay" } ], "code": 401, "body": "{\"type\":\"https:\\\/\\\/docs.elemza.com\\\/errors\\\/token_invalid\",\"status\":401,\"code\":\"token_invalid\",\"title_fa\":\"\\u062a\\u0648\\u06a9\\u0646 \\u0646\\u0627\\u0645\\u0639\\u062a\\u0628\\u0631 \\u0627\\u0633\\u062a\",\"title_en\":\"Invalid token\",\"request_id\":\"01KRHE8WSWEFY6JFDHPGFTAHW3\"}", "name": "" } ] }, { "name": "Create webhook subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"https:\\\/\\\/example.com\\\/webhooks\\\/emza\",\"events\":[\"contract.completed\",\"contract.signer.signed\"],\"active\":false}" }, "description": "Registers an HTTPS endpoint to receive event deliveries. We POST each\nmatching event to your URL with an HMAC-SHA256 signature in the\n`X-Emza-Signature: t=,v1=` header. Compute the signature over\n`\"{t}.{raw_body}\"` using the secret returned at creation.\n\n**The plain signing `secret` is returned ONCE \u2014 store it immediately.**\nSubsequent reads (`index`, `show`) omit the secret entirely. Use\n`PATCH \/webhooks\/{id}` with `rotate_secret=true` to issue a fresh secret\n(invalidates the previous one immediately).\n\n**URL validation (SSRF guard):** the `url` field is rejected with `422`\nif it fails any of:\n - Non-HTTPS scheme (`http:\/\/`, `ftp:\/\/`, `javascript:`, `file:\/\/`)\n - Loopback IPs (`127.0.0.0\/8`, `::1`)\n - RFC 1918 private (`10\/8`, `172.16\/12`, `192.168\/16`)\n - Link-local + cloud metadata (`169.254.0.0\/16`, `100.100.100.200`)\n - IPv6 link-local (`fe80::\/10`) or unique-local (`fc00::\/7`)\n - Hostname suffix `.local`, `.internal`, `.private`, `.lan` or `localhost`\n - Hostname whose DNS resolves to any of the above\n\n**Allowed event names** (set in `events` array \u2014 use `[\"*\"]` for all):\n`contract.created`, `contract.processing.completed`, `contract.processing.failed`,\n`contract.signer.added`, `contract.signer.authenticated`, `contract.signer.signed`,\n`contract.signer.rejected`, `contract.completed`, `contract.canceled`,\n`contract.refunded`, `*` (wildcard).\n\nIf `*` is present alongside specific events, the specifics are dropped\n(the wildcard makes them redundant). Same event listed twice is deduped.\n\nScope: `webhooks:manage`. Idempotency-Key required (24h replay window)." }, "response": [ { "header": [], "code": 201, "body": "{\n \"data\": {\n \"id\": \"01krh7z0e8a4n39gf2ary73xbj\",\n \"url\": \"https:\/\/example.com\/webhooks\/emza\",\n \"events\": [\"contract.completed\", \"contract.signer.signed\"],\n \"active\": true,\n \"disabled_at\": null,\n \"failed_deliveries_count\": 0,\n \"last_delivery_at\": null,\n \"last_delivery_status\": null,\n \"created_at\": \"2026-05-13T18:00:42.000Z\",\n \"updated_at\": \"2026-05-13T18:00:42.000Z\",\n \"secret\": \"35ada3b45aa00df901b74b2b483114315a0c21f7c096f17e0bb29ab7d907fe32\",\n \"_warning\": \"Save this secret now \u2014 it will NOT be shown again.\"\n }\n}", "name": "" }, { "header": [], "code": 422, "body": "{\n \"type\": \"https:\/\/docs.elemza.com\/errors\/validation\",\n \"status\": 422,\n \"code\": \"validation\",\n \"title_fa\": \"\u0627\u0639\u062a\u0628\u0627\u0631\u0633\u0646\u062c\u06cc \u0648\u0631\u0648\u062f\u06cc \u0634\u06a9\u0633\u062a \u062e\u0648\u0631\u062f\",\n \"title_en\": \"Request validation failed\",\n \"errors\": {\n \"url\": [\"\u0622\u062f\u0631\u0633\u200c\u0647\u0627\u06cc \u062f\u0627\u062e\u0644\u06cc \u0634\u0628\u06a9\u0647 (localhost \/ *.local \/ *.internal) \u0645\u062c\u0627\u0632 \u0646\u06cc\u0633\u062a\u0646\u062f.\"]\n },\n \"request_id\": \"01KRH8JRC4Y855P10CYC1C0AYS\"\n}", "name": "SSRF blocked URL" } ] }, { "name": "Update webhook subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "01krh7z0e8a4n39gf2ary73xbj", "description": "Webhook subscription ULID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"http:\\\/\\\/www.bailey.biz\\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\",\"events\":[\"architecto\"],\"active\":false,\"rotate_secret\":false}" }, "description": "Partial update \u2014 any field omitted is left unchanged. New `url` values\npass through the same SSRF guard as `POST \/webhooks` (see Create endpoint).\n\nWhen `rotate_secret=true`, a fresh HMAC signing secret is generated and\nreturned in the response \u2014 the previous secret is invalidated immediately,\nso any in-flight or already-sent webhook deliveries signed with the old\nsecret will fail verification on the receiver side. Plan rotations during\na quiet period or pause via `active=false` first.\n\nScope: `webhooks:manage`. Idempotency-Key required (24h replay window)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": \"01krh7z0e8a4n39gf2ary73xbj\",\n \"url\": \"https:\/\/example.com\/webhooks\/emza\",\n \"events\": [\"*\"],\n \"active\": false,\n \"failed_deliveries_count\": 2,\n \"last_delivery_at\": \"2026-05-13T17:30:00.000Z\",\n \"last_delivery_status\": \"delivered\"\n }\n}", "name": "" } ] }, { "name": "Delete webhook subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Soft-deletes the subscription. In-flight deliveries that have already\nbeen queued will complete; no new deliveries are dispatched." }, "response": [] }, { "name": "Send a synthetic test event", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id\/test", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id\/test", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Fires a `webhook.test` event to verify the endpoint is reachable + signed\ncorrectly. Counts toward `webhook_deliveries` like a real event." }, "response": [] }, { "name": "Replay webhook delivery", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhook-deliveries\/:id\/replay", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhook-deliveries\/:id\/replay", "variable": [ { "id": "id", "key": "id", "value": "B8c6F7NNfcj9m6RJYC6RtkmZN6", "description": "The ID of the webhook delivery." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Creates a NEW delivery row with the same payload + subscription. The\noriginal row keeps its terminal status (failed \/ dead-letter \/ delivered)." }, "response": [] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }