مرجع API

۶۴ عملیات نسخه ۱. خطاها problem+json هستند و پاسخ‌ها ممکن است فیلد تازه بگیرند؛ فیلدهای ناشناخته را نادیده بگیرید.

نشانی پایه: https://pooshe.cloud/api/v1
احراز هویت: Authorization: Bearer slk_…
مستند ماشینی: OpenAPI 3.1 (JSON)

کلید

get/api/v1/keyany valid key

کلید فعلی، فضای کاری و دامنه‌های مؤثر آن

Any valid key may call this, whatever its scopes. A good first call to check configuration.

پاسخ 200KeyInfo

فیلدهای پاسخ
`key`required	object
`workspace`required	object
`actingAs`required	object
`rateLimit`required	object

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/key" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

فایل‌ها و پوشه‌ها

get/api/v1/drivefiles:read

محتوای یک پوشه (بدون folderId: ریشه)

پارامترها
`folderId`	query · string	Folder id; omit for the root
`limit`	query · integer	Page size (1–500, default 200)
`cursor`	query · string	`nextCursor` from the previous page

پاسخ 200DriveListing

فیلدهای پاسخ
`folder`required	object \| null
`breadcrumb`required	object[]	Root first; empty at the root and on pages after the first
`folders`required	FolderSummary[]	Subfolders (first page only)
`documents`required	DriveFile & object[]
`nextCursor`required	string \| null	Pass as `cursor` to get the next page; null on the last page
`totalFiles`required	integer	-9007199254740991…9007199254740991

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found invalid_cursor

curl -sS "https://pooshe.cloud/api/v1/drive" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

get/api/v1/drive/foldersfiles:read

همه پوشه‌ها به‌صورت فهرست تخت

پاسخ 200FolderTree

فیلدهای پاسخ
`folders`required	object[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/drive/folders" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/drive/foldersfiles:write

ساخت پوشه

Names are unique per parent (case-insensitive); depth ≤ 20.

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`required	string	length 1–120
`parentId`	string \| null	Omit or null for the root

پاسخ 201Folder

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string
`parentId`required	string \| null
`createdById`required	string	Opaque id (cuid2, ≤ 40 chars)
`trashedAt`required	string (date-time) \| null
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed folder_name_taken folder_too_deep not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/drive/folders" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"قراردادها"}'

patch/api/v1/drive/folders/{id}files:write

تغییر نام یا جابه‌جایی پوشه

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`	string	length 1–120
`parentId`	string \| null

پاسخ 200Folder

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string
`parentId`required	string \| null
`createdById`required	string	Opaque id (cuid2, ≤ 40 chars)
`trashedAt`required	string (date-time) \| null
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed folder_cycle folder_name_taken not_found

curl -sS -X PATCH "https://pooshe.cloud/api/v1/drive/folders/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

post/api/v1/drive/folders/{id}/trashfiles:write

انتقال پوشه و محتوایش به سطل زباله

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 200FolderTrashed

فیلدهای پاسخ
`folders`required	integer	Folders moved to the trash (with subfolders) · -9007199254740991…9007199254740991
`files`required	integer	-9007199254740991…9007199254740991

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/drive/folders/ID/trash" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

post/api/v1/drive/folders/{id}/restorefiles:write

بازگرداندن پوشه از سطل زباله

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 200FolderRestored

فیلدهای پاسخ
`files`required	integer	-9007199254740991…9007199254740991
`name`required	string	Final name (a suffix is added if the old one is taken)
`parentId`required	string \| null

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/drive/folders/ID/restore" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

post/api/v1/drive/movefiles:write

جابه‌جایی فایل‌ها به یک پوشه (همه یا هیچ)

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`documentIds`required	string[]	≤ 500 items
`folderId`required	string \| null

پاسخ 200MoveResult

فیلدهای پاسخ
`moved`required	integer	-9007199254740991…9007199254740991

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/drive/move" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"documentIds":[],"folderId":"…"}'

get/api/v1/drive/searchfiles:read

جست‌وجو در نام پوشه‌ها و فایل‌ها

پارامترها
`q`required	query · string	Search text (≥ 1 character)

پاسخ 200SearchResult

فیلدهای پاسخ
`folders`required	object[]
`documents`required	DriveFile[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/drive/search" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

get/api/v1/drive/trashfiles:read

محتوای سطل زباله و مدت نگهداری

پاسخ 200Trash

فیلدهای پاسخ
`retentionDays`required	integer	-9007199254740991…9007199254740991
`folders`required	object[]
`documents`required	object[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/drive/trash" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

delete/api/v1/drive/trash/{documentId}files:write

حذف همیشگی فایل از سطل زباله

پارامترها
`documentId`required	path · string

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X DELETE "https://pooshe.cloud/api/v1/drive/trash/DOCUMENTID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

آپلود

post/api/v1/uploadsfiles:write

شروع آپلود یک‌درخواستی

Step 1 of 3: reserves quota and returns a version id. Then PUT the bytes and POST finalize. For files over ~50 MB or unreliable networks use upload sessions.

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`fileName`required	string	length 1–255
`size`required	integer	Exact size in bytes; the body must match it · −∞…9007199254740991
`mime`	string	length 0–120
`documentId`	string	Upload a new version of this file instead of a new file · length 0–40
`title`	string	length 0–200
`folderId`	string \| null

پاسخ 201UploadTicket

فیلدهای پاسخ
`documentId`required	string	Opaque id (cuid2, ≤ 40 chars)
`versionId`required	string	Opaque id (cuid2, ≤ 40 chars)
`maxBytes`required	integer	-9007199254740991…9007199254740991

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed unsupported_type file_too_large invalid_size quota_exceeded version_type_mismatch not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/uploads" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"proposal.pdf","size":482113,"folderId":null}'

put/api/v1/uploads/{versionId}/contentfiles:write

ارسال بایت‌های فایل

Content-Length is required and must equal the declared size. Streamed to storage, never buffered.

پارامترها
`versionId`required	path · string

بدنه: بایت‌های خام با Content-Type: application/octet-stream و Content-Length.

پاسخ 200UploadReceived

فیلدهای پاسخ
`size`required	integer	-9007199254740991…9007199254740991

خطاهای ممکن: api_key_invalid api_key_scope rate_limited length_required empty_body file_too_large use_upload_session upload_already_received not_found

curl -sS -X PUT "https://pooshe.cloud/api/v1/uploads/VERSIONID/content" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file.bin

post/api/v1/uploads/{versionId}/finalizefiles:write

نهایی‌سازی آپلود و شروع بررسی

Idempotent. The version becomes ready after the virus scan (seconds); poll GET /versions/{id} or subscribe to the document.ready webhook.

پارامترها
`versionId`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 200UploadStatus

فیلدهای پاسخ
`status`required	string	quarantined right after finalize: the virus scan and processing run in the background; poll GET /versions/{id}

خطاهای ممکن: api_key_invalid api_key_scope rate_limited upload_incomplete not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/uploads/VERSIONID/finalize" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

post/api/v1/upload-sessionsfiles:write

شروع آپلود چندبخشی قابل ادامه

Returns the part size and count. PUT each part (any order, retry freely), then POST complete. Sessions last 24 h.

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`fileName`required	string	length 1–255
`size`required	integer	−∞…9007199254740991
`mime`	string	length 0–120
`title`	string	length 0–200
`documentId`	string	length 0–40
`folderId`	string \| null

پاسخ 201UploadSession

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`versionId`required	string	Opaque id (cuid2, ≤ 40 chars)
`documentId`	string	Opaque id (cuid2, ≤ 40 chars)
`status`required	"open" \| "completing" \| "completed" \| "aborted" \| "expired" \| string
`size`required	integer	-9007199254740991…9007199254740991
`partSize`required	integer	Every part but the last is exactly this many bytes · -9007199254740991…9007199254740991
`totalParts`required	integer	-9007199254740991…9007199254740991
`receivedParts`required	integer[]	Part numbers already stored; resume by sending the others
`expiresAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed unsupported_type file_too_large quota_exceeded storage_unavailable

curl -sS -X POST "https://pooshe.cloud/api/v1/upload-sessions" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"…","size":1}'

get/api/v1/upload-sessions/{id}files:read

وضعیت آپلود چندبخشی و بخش‌های رسیده

پارامترها
`id`required	path · string

پاسخ 200UploadSession

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`versionId`required	string	Opaque id (cuid2, ≤ 40 chars)
`documentId`	string	Opaque id (cuid2, ≤ 40 chars)
`status`required	"open" \| "completing" \| "completed" \| "aborted" \| "expired" \| string
`size`required	integer	-9007199254740991…9007199254740991
`partSize`required	integer	Every part but the last is exactly this many bytes · -9007199254740991…9007199254740991
`totalParts`required	integer	-9007199254740991…9007199254740991
`receivedParts`required	integer[]	Part numbers already stored; resume by sending the others
`expiresAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/upload-sessions/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

delete/api/v1/upload-sessions/{id}files:write

لغو آپلود چندبخشی و آزادسازی فضا

پارامترها
`id`required	path · string

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X DELETE "https://pooshe.cloud/api/v1/upload-sessions/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

put/api/v1/upload-sessions/{id}/parts/{n}files:write

ارسال بخش n

Sending the same part again replaces it, so retries are safe without an Idempotency-Key.

پارامترها
`id`required	path · string
`n`required	path · string

بدنه: بایت‌های خام با Content-Type: application/octet-stream و Content-Length.

پاسخ 200PartReceived

فیلدهای پاسخ
`partNumber`required	integer	-9007199254740991…9007199254740991
`size`required	integer	-9007199254740991…9007199254740991

خطاهای ممکن: api_key_invalid api_key_scope rate_limited length_required invalid_part_number invalid_part_size upload_session_closed upload_session_expired not_found

curl -sS -X PUT "https://pooshe.cloud/api/v1/upload-sessions/ID/parts/1" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file.bin

post/api/v1/upload-sessions/{id}/completefiles:write

سرهم کردن بخش‌ها و نهایی‌سازی

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 200UploadCompleted

فیلدهای پاسخ
`status`required	"completed"
`versionId`required	string	Opaque id (cuid2, ≤ 40 chars)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited upload_incomplete upload_session_closed upload_assembly_failed not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/upload-sessions/ID/complete" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

فایل، نسخه و دانلود

get/api/v1/documentsfiles:read

فهرست فایل‌ها، تازه‌ترین اول

پارامترها
`q`	query · string	Filter by title
`limit`	query · integer	Page size (1–50, default 20)
`cursor`	query · string	`nextCursor` from the previous page

پاسخ 200DocumentList

فیلدهای پاسخ
`items`required	object[]
`nextCursor`required	string \| null	Pass as `cursor` to get the next page; null on the last page

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/documents" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

get/api/v1/documents/{id}files:read

یک فایل با همه نسخه‌ها (اندازه، SHA-256، وضعیت)

پارامترها
`id`required	path · string

پاسخ 200Document

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`title`required	string
`status`required	string
`trackable`required	boolean
`folderId`required	string \| null
`currentVersionId`required	string \| null
`createdById`required	string	Opaque id (cuid2, ≤ 40 chars)
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)
`trashedAt`required	string (date-time) \| null
`versions`required	object[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/documents/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

patch/api/v1/documents/{id}files:write

تغییر نام فایل یا صفحه‌های کلیدی

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`title`	string	length 1–200
`keyPages`	integer[]	≤ 20 items

پاسخ 200DocumentPatched

فیلدهای پاسخ
`ok`required	true
`keyPages`	integer[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found

curl -sS -X PATCH "https://pooshe.cloud/api/v1/documents/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

post/api/v1/documents/{id}/trashfiles:write

انتقال فایل به سطل زباله (لینک‌هایش از کار می‌افتند)

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/documents/ID/trash" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

post/api/v1/documents/{id}/restorefiles:write

بازگرداندن فایل از سطل زباله

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/documents/ID/restore" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

get/api/v1/versions/{id}files:read

وضعیت پردازش یک نسخه

پارامترها
`id`required	path · string

پاسخ 200Version

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`documentId`required	string	Opaque id (cuid2, ≤ 40 chars)
`number`required	integer	-9007199254740991…9007199254740991
`status`required	"uploading" \| "quarantined" \| "scanning" \| "processing" \| "ready" \| "failed" \| "rejected" \| string
`errorCode`required	string \| null
`pageCount`required	integer \| null

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/versions/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

get/api/v1/versions/{id}/originalfiles:read

دانلود بایت‌های اصلی

Audited. Content-Disposition carries the original file name.

پارامترها
`id`required	path · string

پاسخ 200فایل (application/octet-stream)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/versions/ID/original" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -o file.bin

لینک‌های اشتراک

get/api/v1/linkssharing:read

فهرست لینک‌های اشتراک

پارامترها
`documentId`	query · string	Only links of this file
`limit`	query · integer	Page size (1–100, default 50)
`cursor`	query · string	`nextCursor` from the previous page

پاسخ 200LinkList

فیلدهای پاسخ
`items`required	Link[]
`nextCursor`required	string \| null	Pass as `cursor` to get the next page; null on the last page

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/links" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/linkssharing:write

ساخت لینک اشتراک

The URL is in the response only once. Workspace policies (external sharing off, allowed domains, forced watermark) apply.

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`required	string	length 1–120
`identityMode`	"anonymous" \| "declared" \| "verified"	default "anonymous"
`password`	string \| null
`expiresAt`	string (date-time) \| null
`expiresAtJalali`	string \| null
`expiresInDays`	integer \| null
`maxSessions`	integer \| null
`allowDownload`	boolean	default false
`viewerMode`	"standard" \| "restricted"	default "standard"
`watermark`	boolean	default false
`watermarkFields`	object
`allowlist`	string[]	≤ 200 items
`allowlistOnly`	boolean	default false
`allowedEmailDomains`	string[]	≤ 50 items
`notifyOnView`	boolean	default true
`contactId`	string \| null
`ctaActions`	"call" \| "meeting" \| "question" \| "accept"[]	≤ 4 items
`ctaNote`	string \| null
`followLatest`	boolean
`documentId`	string	length 0–40
`versionId`	string	length 0–40
`roomId`	string	length 0–40
`restrictToContact`	boolean	default false

پاسخ 201LinkCreated

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`url`required	string (uri)	Shown once; Pooshe stores only a hash of the token

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed policy_sharing_off not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/links" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"documentId":"uysse8ma956dknqtijp3f1iy","name":"برای شرکت نمونه","expiresInDays":7,"allowDownload":false}'

get/api/v1/links/{id}sharing:read

یک لینک با تنظیمات و وضعیت

پارامترها
`id`required	path · string

پاسخ 200Link

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string \| null
`documentId`required	string \| null
`versionId`required	string \| null
`roomId`required	string \| null
`state`required	"active" \| "revoked" \| "expired" \| "exhausted"
`identityMode`required	string
`expiresAt`required	string (date-time) \| null
`revokedAt`required	string (date-time) \| null
`maxSessions`required	integer \| null
`sessionsUsed`required	integer	-9007199254740991…9007199254740991
`allowDownload`required	boolean
`watermark`required	boolean
`hasPassword`required	boolean
`followLatest`required	boolean
`contactId`required	string \| null
`createdById`required	string	Opaque id (cuid2, ≤ 40 chars)
`createdAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/links/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

patch/api/v1/links/{id}sharing:write

تغییر تنظیمات لینک (فقط فیلدهای فرستاده‌شده)

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`	string	length 1–120
`identityMode`	"anonymous" \| "declared" \| "verified"
`password`	string \| null
`expiresAt`	string (date-time) \| null
`expiresAtJalali`	string \| null
`expiresInDays`	integer \| null
`maxSessions`	integer \| null
`allowDownload`	boolean
`viewerMode`	"standard" \| "restricted"
`watermark`	boolean
`watermarkFields`	object
`allowlist`	string[]	≤ 200 items
`allowlistOnly`	boolean
`allowedEmailDomains`	string[]	≤ 50 items
`notifyOnView`	boolean
`contactId`	string \| null
`ctaActions`	"call" \| "meeting" \| "question" \| "accept"[]	≤ 4 items
`ctaNote`	string \| null
`followLatest`	boolean

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found link_revoked

curl -sS -X PATCH "https://pooshe.cloud/api/v1/links/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

post/api/v1/links/{id}/revokesharing:write

لغو فوری لینک

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X POST "https://pooshe.cloud/api/v1/links/ID/revoke" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

get/api/v1/links/{id}/analyticssharing:read

آمار بازدید لینک

پارامترها
`id`required	path · string

پاسخ 200LinkAnalytics

فیلدهای پاسخ
`report`required	object
`daily`required	any[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/links/ID/analytics" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

CRM

get/api/v1/contactscrm:read

فهرست مخاطبان با میزان تعامل

پارامترها
`q`	query · string	Name, e-mail or phone
`companyId`	query · string	Only this company
`limit`	query · integer	Page size (1–100, default 50)
`cursor`	query · string	`nextCursor` from the previous page

پاسخ 200ContactList

فیلدهای پاسخ
`items`required	Contact & object[]
`nextCursor`required	string \| null	Pass as `cursor` to get the next page; null on the last page

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/contacts" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/contactscrm:write

ساخت مخاطب

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`required	string	length 1–120
`email`	string \| null
`phone`	string \| null
`jobTitle`	string \| null
`note`	string	length 0–2000
`companyId`	string \| null
`companyName`	string \| null
`ownerId`	string	length 0–40

پاسخ 201Contact

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string
`email`required	string \| null
`phone`required	string \| null
`jobTitle`required	string \| null
`note`required	string
`companyId`required	string \| null
`ownerId`required	string	Opaque id (cuid2, ≤ 40 chars)
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed

curl -sS -X POST "https://pooshe.cloud/api/v1/contacts" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"رضا احمدی","email":"reza@example.com","companyName":"شرکت نمونه"}'

get/api/v1/contacts/{id}crm:read

یک مخاطب با لینک‌ها، رویدادها و پاسخ‌ها

پارامترها
`id`required	path · string

پاسخ 200ContactDetail

فیلدهای پاسخ
`contact`required	Contact
`owner`required	object \| null
`links`required	any[]
`timeline`required	any[]
`responses`required	any[]
`canEdit`required	boolean

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/contacts/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

patch/api/v1/contacts/{id}crm:write

ویرایش مخاطب

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`	string	length 1–120
`email`	string \| null
`phone`	string \| null
`jobTitle`	string \| null
`note`	string	length 0–2000
`companyId`	string \| null
`companyName`	string \| null
`ownerId`	string	length 0–40

پاسخ 200Contact

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string
`email`required	string \| null
`phone`required	string \| null
`jobTitle`required	string \| null
`note`required	string
`companyId`required	string \| null
`ownerId`required	string	Opaque id (cuid2, ≤ 40 chars)
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found

curl -sS -X PATCH "https://pooshe.cloud/api/v1/contacts/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

delete/api/v1/contacts/{id}crm:write

حذف مخاطب

پارامترها
`id`required	path · string

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X DELETE "https://pooshe.cloud/api/v1/contacts/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

get/api/v1/companiescrm:read

فهرست شرکت‌ها

پارامترها
`q`	query · string	Name or domain

پاسخ 200CompanyList

فیلدهای پاسخ
`items`required	Company[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/companies" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/companiescrm:write

ساخت شرکت

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`required	string	length 1–120
`domain`	string \| null
`note`	string	length 0–2000

پاسخ 201Company

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string
`domain`required	string \| null
`note`required	string
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed

curl -sS -X POST "https://pooshe.cloud/api/v1/companies" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

get/api/v1/companies/{id}crm:read

یک شرکت با مخاطبانش

پارامترها
`id`required	path · string

پاسخ 200CompanyDetail

فیلدهای پاسخ
`company`required	Company

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/companies/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

patch/api/v1/companies/{id}crm:write

ویرایش شرکت

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`	string	length 1–120
`domain`	string \| null
`note`	string	length 0–2000

پاسخ 200Company

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string
`domain`required	string \| null
`note`required	string
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found

curl -sS -X PATCH "https://pooshe.cloud/api/v1/companies/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

delete/api/v1/companies/{id}crm:write

حذف شرکت (مخاطبانش می‌مانند)

پارامترها
`id`required	path · string

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X DELETE "https://pooshe.cloud/api/v1/companies/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

get/api/v1/leadscrm:read

سرنخ‌های داغ بر اساس تعامل اخیر

پارامترها
`scope`	query · "team"	`team` for every member’s contacts (needs the permission)

پاسخ 200LeadList

فیلدهای پاسخ
`items`required	object[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/leads" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

get/api/v1/followupscrm:read

یادآوری‌های پیگیری

پارامترها
`contactId`	query · string	Only this contact

پاسخ 200FollowUpList

فیلدهای پاسخ
`items`required	FollowUp[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/followups" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/followupscrm:write

ساخت یادآوری پیگیری

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`contactId`required	string	length 0–40
`dueInDays`	integer	0…365
`dueAt`	string (date-time)
`note`	string	length 0–1000

پاسخ 201FollowUp

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`contactId`required	string	Opaque id (cuid2, ≤ 40 chars)
`ownerId`required	string	Opaque id (cuid2, ≤ 40 chars)
`kind`required	string
`status`required	"open" \| "done" \| "dismissed"
`dueAt`required	string (date-time)
`note`required	string
`doneAt`required	string (date-time) \| null
`createdAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed

curl -sS -X POST "https://pooshe.cloud/api/v1/followups" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"…"}'

patch/api/v1/followups/{id}crm:write

انجام‌شده یا کنار گذاشتن پیگیری

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`status`required	"done" \| "dismissed"

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found

curl -sS -X PATCH "https://pooshe.cloud/api/v1/followups/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

get/api/v1/notescrm:read

یادداشت‌های مخاطب، شرکت یا فرصت

پارامترها
`contactId`	query · string	Contact
`companyId`	query · string	Company
`opportunityId`	query · string	Opportunity

پاسخ 200NoteList

فیلدهای پاسخ
`notes`required	Note[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/notes" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/notescrm:write

افزودن یادداشت

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`body`required	string	length 1–4000
`contactId`	string	length 0–40
`companyId`	string	length 0–40
`opportunityId`	string	length 0–40

پاسخ 201Note

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`body`required	string
`authorId`required	string	Opaque id (cuid2, ≤ 40 chars)
`contactId`required	string \| null
`companyId`required	string \| null
`opportunityId`required	string \| null
`createdAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed

curl -sS -X POST "https://pooshe.cloud/api/v1/notes" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"body":"…"}'

get/api/v1/opportunitiescrm:read

فرصت‌های فروش و جمع هر مرحله

پارامترها
`contactId`	query · string	Contact
`companyId`	query · string	Company

پاسخ 200OpportunityList

فیلدهای پاسخ
`opportunities`required	Opportunity[]
`byStage`required	object

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/opportunities" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/opportunitiescrm:write

ساخت فرصت فروش

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`title`required	string	length 1–160
`contactId`	string \| null
`companyId`	string \| null
`stage`	"lead" \| "qualified" \| "proposal" \| "negotiation" \| "won" \| "lost"
`valueRial`	string \| number \| null
`expectedCloseAt`	string (date-time) \| null
`lostReason`	string \| null
`ownerId`	string	length 0–40

پاسخ 201Opportunity

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`title`required	string
`stage`required	string
`valueRial`required	string \| null
`contactId`required	string \| null
`companyId`required	string \| null
`ownerId`required	string	Opaque id (cuid2, ≤ 40 chars)
`expectedCloseAt`required	string (date-time) \| null
`closedAt`required	string (date-time) \| null
`lostReason`required	string \| null
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed

curl -sS -X POST "https://pooshe.cloud/api/v1/opportunities" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"قرارداد سالانه","valueRial":"1000000000","stage":"proposal"}'

get/api/v1/opportunities/{id}crm:read

یک فرصت فروش

پارامترها
`id`required	path · string

پاسخ 200OpportunityDetail

فیلدهای پاسخ
`opportunity`	Opportunity

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/opportunities/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

patch/api/v1/opportunities/{id}crm:write

ویرایش فرصت (مرحله، مبلغ، تاریخ…)

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`title`	string	length 1–160
`contactId`	string \| null
`companyId`	string \| null
`stage`	"lead" \| "qualified" \| "proposal" \| "negotiation" \| "won" \| "lost"
`valueRial`	string \| number \| null
`expectedCloseAt`	string (date-time) \| null
`lostReason`	string \| null
`ownerId`	string	length 0–40

پاسخ 200Opportunity

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`title`required	string
`stage`required	string
`valueRial`required	string \| null
`contactId`required	string \| null
`companyId`required	string \| null
`ownerId`required	string	Opaque id (cuid2, ≤ 40 chars)
`expectedCloseAt`required	string (date-time) \| null
`closedAt`required	string (date-time) \| null
`lostReason`required	string \| null
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found

curl -sS -X PATCH "https://pooshe.cloud/api/v1/opportunities/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

patch/api/v1/responses/{id}crm:write

رسیدگی‌شده کردن پاسخ بیننده

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS -X PATCH "https://pooshe.cloud/api/v1/responses/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

پیش‌فاکتور

get/api/v1/catalogquotes:read

کالاها و خدمات

پارامترها
`q`	query · string	Search
`all`	query · "1"	`1` to include inactive items

پاسخ 200CatalogList

فیلدهای پاسخ
`items`required	CatalogItem[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/catalog" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/catalogquotes:write

افزودن کالا یا خدمت

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`required	string	length 1–160
`sku`	string \| null
`unit`	string	length 1–20
`unitPriceRial`required	string \| number
`taxable`	boolean
`description`	string \| null
`active`	boolean

پاسخ 201CatalogItem

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string
`sku`required	string \| null
`unit`required	string
`unitPriceRial`required	string	Amount in Rial as a decimal string (64-bit safe)
`taxable`required	boolean
`description`required	string \| null
`active`required	boolean

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed

curl -sS -X POST "https://pooshe.cloud/api/v1/catalog" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"مشاوره","unitPriceRial":"5000000"}'

patch/api/v1/catalog/{id}quotes:write

ویرایش کالا یا خدمت

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`name`	string	length 1–160
`sku`	string \| null
`unit`	string	length 1–20
`unitPriceRial`	string \| number
`taxable`	boolean
`description`	string \| null
`active`	boolean

پاسخ 200CatalogItem

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`name`required	string
`sku`required	string \| null
`unit`required	string
`unitPriceRial`required	string	Amount in Rial as a decimal string (64-bit safe)
`taxable`required	boolean
`description`required	string \| null
`active`required	boolean

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found

curl -sS -X PATCH "https://pooshe.cloud/api/v1/catalog/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

get/api/v1/quotesquotes:read

فهرست پیش‌فاکتورها

پارامترها
`status`	query · string	draft, issued, sent, accepted…
`contactId`	query · string	Contact

پاسخ 200QuoteList

فیلدهای پاسخ
`quotes`required	Quote[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/quotes" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

post/api/v1/quotesquotes:write

ساخت پیش‌نویس پیش‌فاکتور

Amounts are integer Rial strings; tax and totals are computed by the server.

پارامترها
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`title`required	string	length 1–160
`contactId`	string \| null
`companyId`	string \| null
`opportunityId`	string \| null
`draft`	object

پاسخ 201Quote

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`number`required	string
`title`required	string
`status`required	string
`contactId`required	string \| null
`companyId`required	string \| null
`opportunityId`required	string \| null
`currentVersion`required	integer	-9007199254740991…9007199254740991
`documentId`required	string \| null
`sentAt`required	string (date-time) \| null
`acceptedAt`required	string (date-time) \| null
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed

curl -sS -X POST "https://pooshe.cloud/api/v1/quotes" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"…"}'

get/api/v1/quotes/{id}quotes:read

یک پیش‌فاکتور با نسخه‌ها و جمع‌ها

پارامترها
`id`required	path · string

پاسخ 200QuoteDetail

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found

curl -sS "https://pooshe.cloud/api/v1/quotes/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY"

patch/api/v1/quotes/{id}quotes:write

ویرایش پیش‌نویس

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`title`	string	length 1–160
`contactId`	string \| null
`companyId`	string \| null
`draft`	object

پاسخ 200Quote

فیلدهای پاسخ
`id`required	string	Opaque id (cuid2, ≤ 40 chars)
`number`required	string
`title`required	string
`status`required	string
`contactId`required	string \| null
`companyId`required	string \| null
`opportunityId`required	string \| null
`currentVersion`required	integer	-9007199254740991…9007199254740991
`documentId`required	string \| null
`sentAt`required	string (date-time) \| null
`acceptedAt`required	string (date-time) \| null
`createdAt`required	string (date-time)
`updatedAt`required	string (date-time)

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found quote_final

curl -sS -X PATCH "https://pooshe.cloud/api/v1/quotes/ID" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

post/api/v1/quotes/{id}/issuequotes:write

صدور نسخه رسمی و ساخت PDF

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

پاسخ 201QuoteIssued

خطاهای ممکن: api_key_invalid api_key_scope rate_limited not_found quote_final company_profile_required

curl -sS -X POST "https://pooshe.cloud/api/v1/quotes/ID/issue" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

post/api/v1/quotes/{id}/sendquotes:write

ساخت لینک هوشمند پیش‌فاکتور

The PDF renders in the background after issue; until it is ready this returns 409 quote_pdf_not_ready: retry after a few seconds.

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`expiresInDays`	integer	1…365
`restrictToContact`	boolean

پاسخ 201QuoteSent

فیلدهای پاسخ
`linkId`required	string	Opaque id (cuid2, ≤ 40 chars)
`url`required	string

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found quote_not_issued quote_pdf_not_ready

curl -sS -X POST "https://pooshe.cloud/api/v1/quotes/ID/send" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

post/api/v1/quotes/{id}/statusquotes:write

ردشده یا لغوشده کردن پیش‌فاکتور

پارامترها
`id`required	path · string
`Idempotency-Key`	header · string	Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.

بدنه درخواست (JSON)
`status`required	"rejected" \| "cancelled"

پاسخ 200Ok

فیلدهای پاسخ
`ok`required	true

خطاهای ممکن: api_key_invalid api_key_scope rate_limited validation_failed not_found quote_final

curl -sS -X POST "https://pooshe.cloud/api/v1/quotes/ID/status" \
  -H "Authorization: Bearer $POOSHE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"status":"rejected"}'

گزارش

get/api/v1/analytics/teamanalytics:read

گزارش تیم: لینک‌ها، بازدیدها و پاسخ‌ها

پارامترها
`days`	query · 7 \| 30 \| 90	7, 30 or 90

پاسخ 200TeamReport

فیلدهای پاسخ
`days`required	integer	-9007199254740991…9007199254740991
`since`required	string (date-time)
`estimated`required	true
`scope`required	string
`totals`required	object
`documents`required	any[]
`members`required	any[]

خطاهای ممکن: api_key_invalid api_key_scope rate_limited

curl -sS "https://pooshe.cloud/api/v1/analytics/team" \
  -H "Authorization: Bearer $POOSHE_API_KEY"