المصادقة
أرسل مفتاح واجهة برمجة التطبيقات (API key) كرمز حامل (bearer token). يجب أن يحمل المفتاح إذن tickets.reply؛ والمفتاح الذي لا يملكه يُرفض بالرمز 403 وليس 404.
حيث يتم إدخال معرف مؤسستك
تقبل هذه نقطة النهاية org_id حقلًا في نص JSON.
معرف مؤسستك موجود على شاشة مفاتيح واجهة برمجة التطبيقات (API) في لوحة تحكمك، بجوار المفتاح نفسه. وهو نفس المعرف في كل طلب تجريه.
جربه الآن
استبدل أي شيء بين أقواس زاوية بقيمك الخاصة، والعنصر النائب للمفتاح بمفتاح من لوحة تحكمك.
curl -X POST https://api.zinndigital.com/v1/tickets \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "subject": <string>, "body": <string> }'هل سجلت الدخول؟ تقوم وحدة تحكم واجهة برمجة التطبيقات في لوحة التحكم الخاصة بك بربط معرف مؤسستك الحقيقي ومفتاحك الخاص، وتنفذ الطلب مقابل واجهة برمجة التطبيقات المباشرة لتتمكن من رؤية الاستجابة الفعلية. افتح هذه النهاية الطرفية في وحدة تحكم API
التفاصيل
Opens a ticket in `open` with the supplied `body` as its first message, and publishes `ticket.created` (which sends the customer a localized acknowledgement via the notification consumer). `channel` is server-decided — it is not accepted from the client. A supplied `site_id` or `invoice_id` must belong to the same org or the request is a `404`. Requires `tickets.reply`.
جسم الطلب
| الاسم | النوع | مطلوب | ما هو هذا |
|---|---|---|---|
subject | string | نعم | — |
body | string | نعم | The customer's description — becomes the first message in the thread. |
priority | TicketPriority | لا | How urgent the ticket is. The customer may propose one; staff decide. |
site_id | string | لا | The site this is about. Must belong to the same org or the request is a 404. |
invoice_id | string | لا | The invoice this is about. Must belong to the same org or the request is a 404. |
org_id | string | لا | The organization to open it in. Required only when the caller holds `tickets.reply` in more than one org. |
on_behalf_of_org_id | string | لا | The client org this is about — a reseller escalating to Zinn® on their client's behalf. Must be a **descendant** of the ticket's org or the request is a `404`; your client never… |
الاستجابة
| الاسم | النوع | مطلوب | ما هو هذا |
|---|---|---|---|
id | Uuid | نعم | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
org_id | Uuid | نعم | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
subject | string | نعم | — |
status | TicketStatus | نعم | Where a ticket sits in its lifecycle. `open` = waiting on us; `pending` = waiting on the customer; `solved` = we believe it is resolved and a customer reply reopens it; `closed`… |
priority | TicketPriority | نعم | How urgent the ticket is. The customer may propose one; staff decide. |
channel | string | نعم | How the ticket reached us — `dashboard`, `api` or `staff`. Server-decided; an open string so a future channel is additive on both sides. |
site_id | object | لا | — |
invoice_id | object | لا | — |
on_behalf_of_org_id | object | لا | The **client org** a reseller opened this ticket about. Null on every ordinary ticket. ⛔ Validated as a descendant of the ticket's own org and `404`d otherwise, so it can never… |
assignee_name | object | نعم | The owning agent's display name (first name), or null while unassigned. The customer sees a **name** so they know a person owns their ticket; the agent's id and email are staff-… |
first_response_at | object | لا | — |
resolved_at | object | لا | — |
closed_at | object | لا | — |
last_message_at | object | لا | — |
reopened_count | integer | نعم | — |
message_count | integer | نعم | Customer-visible messages in the thread — internal notes are not counted. |
created_at | string | نعم | — |
updated_at | string | نعم | — |
messages | TicketMessage[] | نعم | The customer-visible thread in chronological order. |
الأخطاء التي يمكن أن تُرجعها نقطة النهاية هذه
401 · 403 · 404 · 422 · 429