> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # إنشاء ملاحظة معاملة عبر API > أضف ملاحظة نصية عادية، مع إشارات اختيارية إلى الأعضاء، إلى الخط الزمني لمراجعة معاملة خاضعة للمراقبة من أنظمتك باستخدام Didit. موجّه واجهة برمجة تطبيقات إنشاء ملاحظة المعاملة نسخ الموجّه إلى الحافظة \

\`Add a note to a Didit monitored transaction through the Management API.

Endpoint:
POST https://verification.didit.me/v3/transactions/{transaction_id}/notes/

Authentication:
Use the x-api-key header with my Didit API key. A scoped key needs transactions: write. Keys limited to specific workflows or to approved sessions cannot call this endpoint.

Goal:
\- Record context from my own systems (a support call, a manual check, an outcome from my case tool) on the transaction's review timeline, where Console reviewers see it.

Path parameter:
\- transaction_id: the Didit transaction uuid, not my own txn_id.

Request body (application/json):
\{
"note": "Customer confirmed the withdrawal by phone.",
"mentioned_emails": ["analyst@example.com"]
}
\- note: required. Plain text, no length limit. Leading and trailing whitespace is trimmed and a blank note is rejected.
\- mentioned_emails: optional list of emails of members of my organization to mention.

Behavior:
\- Returns 201 with the created note. actor_email and actor_name are null because the note comes from an API key, not a person.
\- Every mentioned email must belong to a member of my organization; one unknown address fails the whole request with 400. Mentions are stored lower-cased and de-duplicated in metadata.mentioned_emails. This endpoint does not notify the mentioned members.
\- Each call creates a new note. Retrying a request that timed out can add the same note twice, so check GET /v3/transactions/{transaction_id}/notes/ before retrying.
\- There is no API endpoint to edit or remove a note.

Example call:
curl -X POST "https://verification.didit.me/v3/transactions/{transaction_id}/notes/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": ["analyst@example.com"]}'

What to read from the response:
\- uuid: the note id.
\- created_at: when the note was stored.
\- metadata.mentioned_emails: the normalized mention list (empty when nobody was mentioned).

Failure modes:
\- 400: note missing ({"note": ["This field is required."]}) or blank, an invalid email in mentioned_emails, or a mentioned address outside my organization ({"mentioned_emails": ["Mentioned users must belong to this organization and have access to this application."]}).
\- 401: the API key has expired.
\- 403: missing API key (a wrong, revoked or expired key gets 401), a scoped key without transactions: write ({"detail": "This API key has no write access to transactions."}), a key with workflow or status limits, or a request from outside the key's IP allowlist.
\- 404: no transaction with this uuid in my application ({"detail": "No Transaction matches the given query."}).
\- 429: more than 300 write requests per minute with this key; wait Retry-After seconds and retry.

Side effects: creates the note and adds a TRANSACTION_NOTE_ADDED entry to the transaction's activities. The transaction's status, score and alerts do not change, no webhook is sent, and nothing is billed.

For the full integration shape, see /integration/integration-prompt.`

\
الصق في الملاحظة سياق وليست قراراً، فهي لا تغيّر أبداً `status` أو `score` أو التنبيهات الخاصة بالمعاملة. يرى المراجعون الملاحظة ضمن **ملاحظات** في [تفاصيل المعاملة](https://docs.didit.me/ar/transaction-monitoring/console.md#تفاصيل-المعاملة) في Console، ويُضاف إلى `activities` الخاصة بالمعاملة إدخال من نوع `TRANSACTION_NOTE_ADDED`، ويمكنك قراءته عبر [الحصول على المعاملة](https://docs.didit.me/ar/management-api/transactions/get.md).بما أن الملاحظة صادرة عن مفتاح API، فلا تحمل اسم كاتب: تكون قيمتا `actor_email` و`actor_name` هما `null`. إذا احتجت إلى إظهار من كتبها، فأدرج ذلك في نص الملاحظة. واقرأ السجل الزمني الكامل عبر [عرض ملاحظات المعاملة](https://docs.didit.me/ar/management-api/transactions/list-notes.md). ## OpenAPI ````yaml ar/openapi-25.json POST /v3/transactions/{transaction_id}/notes/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/transactions/{transaction_id}/notes/: post: tags: - Transactions summary: إنشاء ملاحظة معاملة description: >- أضف ملاحظة بنص عادي إلى المخطط الزمني لمراجعة معاملة خاضعة للمراقبة، حيث يراها مراجعو لوحة التحكم. الملاحظة هي سياق وليست قراراً: لا تتغير `status` الخاصة بالمعاملة ولا `score` ولا التنبيهات، ولا يتم إرسال أي webhook، ولا يتم احتساب أي تكلفة. تكتسب `activities` الخاصة بالمعاملة إدخالاً بقيمة `TRANSACTION_NOTE_ADDED`. الملاحظات المنشأة باستخدام مفتاح API ليس لها مؤلف: يكون كل من `actor_email` و`actor_name` بقيمة `null`، لذا ضع المؤلف داخل النص إذا كنت بحاجة إليه. يجب أن ينتمي كل عنوان بريد إلكتروني في `mentioned_emails` إلى عضو في مؤسستك، وإلا سيفشل الطلب بأكمله بالرمز `400`؛ تُخزن الإشارات بأحرف صغيرة وتتم إزالة التكرارات منها، ولا يقوم هذا الـ endpoint بإشعار الأعضاء المشار إليهم. ينشئ كل استدعاء ملاحظة جديدة، لذا فإن إعادة محاولة طلب انتهت مهلته قد تؤدي إلى إضافتها مرتين: قم بسرد الملاحظات قبل إعادة المحاولة. لا يوجد endpoint في API لتعديل ملاحظة أو إزالتها. يحتاج مفتاح API محدود النطاق إلى إذن `transactions: write`؛ ولا يمكن لمفتاح مقتصر على بعض عمليات سير العمل أو على الجلسات المقبولة استدعاء هذا الـ endpoint. operationId: create_transaction_note parameters: - name: transaction_id in: path required: true description: >- معرّف UUID لمعاملة Didit: وهو `uuid` الذي تُرجعه `POST /v3/transactions/` و`GET /v3/transactions/`. لا يُقبل `txn_id` الخاص بك. schema: type: string format: uuid example: abcdef12-3456-7890-abcd-ef1234567890 requestBody: required: true content: application/json: schema: type: object required: - note properties: note: type: string minLength: 1 description: >- ملاحظة كنص عادي. يتم اقتطاع المسافات البيضاء في البداية والنهاية، ويتم رفض الملاحظة الفارغة. لا يوجد حد للطول. mentioned_emails: type: array items: type: string format: email default: [] description: >- عناوين البريد الإلكتروني لأعضاء مؤسستك المراد الإشارة إليهم. يجب أن يكون كل منها بريداً إلكترونياً صالحاً لعضو في المؤسسة. examples: Note with a mention: value: note: Customer confirmed the withdrawal by phone. mentioned_emails: - analyst@example.com Plain note: value: note: Source of funds document requested by email. responses: '201': description: تم إنشاء الملاحظة. content: application/json: schema: $ref: '#/components/schemas/TransactionNote' examples: Created: value: uuid: c1111111-2222-4333-8444-555555555555 note: Customer confirmed the withdrawal by phone. actor_email: null actor_name: null metadata: mentioned_emails: - analyst@example.com created_at: '2026-10-16T10:05:12.481203Z' '400': description: >- نص الطلب غير صالح: الحقل `note` مفقود أو null أو فارغ، أو يوجد عنوان غير صالح في `mentioned_emails` (الأخطاء مفهرسة حسب الموضع في القائمة)، أو عنوان مذكور ليس عضواً في مؤسستك. لم يتم إنشاء أي شيء. content: application/json: schema: type: object description: أخطاء الحقول مفهرسة حسب اسم الحقل. additionalProperties: {} examples: Missing note: value: note: - This field is required. Blank note: value: note: - This field may not be blank. Invalid email: value: mentioned_emails: '0': - Enter a valid email address. Not an organization member: value: mentioned_emails: - >- Mentioned users must belong to this organization and have access to this application. '401': description: >- انتهت صلاحية مفتاح API. المفتاح الذي تم إنشاؤه مع تاريخ انتهاء هو فقط الذي يمكن أن تنتهي صلاحيته؛ بعد هذا التاريخ، تجيب جميع الطلبات باستخدامه بـ `401`. content: application/json: schema: type: object properties: detail: type: string examples: Expired key: value: detail: This API key has expired. '403': description: >- الطلب غير مسموح به. يتلقى المفتاح المفقود الرسالة العامة؛ بينما يتلقى المفتاح الخاطئ أو الملغى أو منتهي الصلاحية الرمز `401`. content: application/json: schema: type: object properties: detail: type: string examples: Missing or invalid key: value: detail: You do not have permission to perform this action. Scoped key without transactions write: value: detail: This API key has no write access to transactions. Key limited to workflows or approved sessions: value: detail: >- This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint. Outside the key's IP list: value: detail: This API key can't be used from this IP address. '404': description: >- لا توجد معاملة بمعرّف UUID هذا في التطبيق (لم يتم إنشاؤها مطلقاً، أو محذوفة، أو مملوكة لتطبيق آخر). إن قيمة `transaction_id` التي لا تمثل معرّف UUID لا تصل إلى واجهة API: بل تُرجع صفحة HTML برمز `404` بدلاً من نص JSON هذا. content: application/json: schema: type: object properties: detail: type: string examples: Not found: value: detail: No Transaction matches the given query. '429': description: >- أكثر من 300 طلب كتابة في الدقيقة باستخدام مفتاح API هذا. انتظر لعدد الثواني المحدد في `Retry-After`، ثم أعد المحاولة. content: application/json: schema: type: object properties: detail: type: string examples: Throttled: value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. headers: Retry-After: description: عدد الثواني حتى إعادة تعيين النافذة الحالية البالغة دقيقة واحدة. schema: type: integer example: 23 X-RateLimit-Limit: description: الطلبات المسموح بها في الدقيقة ضمن هذه الميزانية. schema: type: integer X-RateLimit-Remaining: description: الطلبات المتبقية في النافذة الحالية. schema: type: integer X-RateLimit-Reset: description: توقيت Unix عند إعادة تعيين النافذة. schema: type: integer security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": ["analyst@example.com"]}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.transactions.notes.create( "abcdef12-3456-7890-abcd-ef1234567890", note="Customer confirmed the withdrawal by phone.", mentioned_emails=["analyst@example.com"], ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.transactions.notes.create("abcdef12-3456-7890-abcd-ef1234567890", { note: "Customer confirmed the withdrawal by phone.", mentioned_emails: ["analyst@example.com"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Notes.Create(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesCreateParams{\n\tNote: \"Customer confirmed the withdrawal by phone.\",\n\tMentionedEmails: didit.Some([]string{\"analyst@example.com\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.TransactionsNotesCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.transactions().notes().create("abcdef12-3456-7890-abcd-ef1234567890", TransactionsNotesCreateParams.builder() .note("Customer confirmed the withdrawal by phone.") .mentionedEmails(List.of("analyst@example.com")) .build()); System.out.println(result); - lang: php label: PHP source: >- transactions->notes->create('abcdef12-3456-7890-abcd-ef1234567890', [ 'note' => 'Customer confirmed the withdrawal by phone.', 'mentioned_emails' => ['analyst@example.com'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.transactions.notes.create( "abcdef12-3456-7890-abcd-ef1234567890", note: "Customer confirmed the withdrawal by phone.", mentioned_emails: ["analyst@example.com"] ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Transactions.Notes.CreateAsync("abcdef12-3456-7890-abcd-ef1234567890", new TransactionsNotesCreateParams { Note = "Customer confirmed the withdrawal by phone.", MentionedEmails = new string[] { "analyst@example.com" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: TransactionNote: type: object description: ملاحظة واحدة في الجدول الزمني لمراجعة المعاملة الخاضعة للمراقبة. required: - uuid - note - actor_email - actor_name - metadata - created_at properties: uuid: type: string format: uuid description: معرّف الملاحظة. note: type: string description: متن الملاحظة النصية العادية. actor_email: type: string format: email nullable: true description: >- البريد الإلكتروني لمستخدم Console الذي كتب الملاحظة أو غيّر الحالة. يكون `null` للملاحظات التي تم إنشاؤها باستخدام مفتاح API والملاحظات التي يضيفها Didit تلقائياً. actor_name: type: string nullable: true description: >- اسم العرض لمستخدم Console (بريده الإلكتروني إذا لم يكن لديه اسم). ويكون `Rule Engine` في الملاحظات التي تضيفها Didit تلقائياً. و`null` للملاحظات التي تم إنشاؤها باستخدام مفتاح API. metadata: type: object description: >- يميّز بين أنواع الملاحظات. تتضمن الملاحظات المكتوبة عبر API أو لوحة التحكم الحقل `mentioned_emails`. ويتضمن تغيير الحالة الذي يتم في لوحة التحكم الحقل `type: status_change` مع `previous_status` و`new_status` و`reason_code` و`reason_label`. أما الملاحظات التي تضيفها Didit فتتضمن `source`: القيمة `rule_action` (مع `rule_uuid`) لإجراء `add_note` الخاص بقاعدة، أو `remediation_session` لمشكلة حدثت أثناء إنشاء جلسة تحقق من إجراء المستخدم. properties: mentioned_emails: type: array items: type: string format: email description: >- أعضاء المؤسسة المشار إليهم، بأحرف صغيرة ودون تكرار. فارغ في حال عدم الإشارة إلى أي شخص. type: type: string enum: - status_change description: >- موجود في الملاحظات التي تسجل تغييراً في الحالة تم إجراؤه في لوحة التحكم. previous_status: type: string enum: - APPROVED - IN_REVIEW - DECLINED - AWAITING_USER description: الحالة قبل التغيير. new_status: type: string enum: - APPROVED - IN_REVIEW - DECLINED - AWAITING_USER description: الحالة بعد التغيير. reason_code: type: string nullable: true description: رمز السبب المقدم مع التغيير. reason_label: type: string nullable: true description: تسمية السبب المقدمة مع التغيير. source: type: string enum: - rule_action - remediation_session description: موجود في الملاحظات التي يضيفها Didit تلقائياً. rule_uuid: type: string format: uuid description: >- القاعدة التي كتب الإجراء `add_note` التابع لها الملاحظة (مع `source: rule_action`). created_at: type: string format: date-time description: متى تم تخزين الملاحظة. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.