التوثيق

مقسمك في خمس دقائق

كل ما يلي موجود في حسابك أصلًا. ولا شيء منه يحتاج إلى تركيب، ولا إلى زيارة فنّي، ولا إلى جهاز تشتريه.

• لديك أرقام وتحويلات بالفعل. تُنشأ مع حسابك، ومعها بيانات اعتماد SIP التي يحتاجها كل جهاز. التحويلة شخصٌ أو مكتب، والرقم هو ما يطلبه العالم من الخارج.
• وجِّه رقمًا إلى مكان. في تبويب الأرقام تحدّد ما يجب أن تفعله مكالمة تصل على ذلك الرقم: أن ترنّ تحويلة، أو مجموعة، أو تفتح قائمة صوتية، أو تدخل طابورًا، أو تتبع مواعيد دوامك.
• ردّ عليها من المتصفّح. افتح تبويب الهاتف، واسمح بالميكروفون، فيصير التبويب هاتفًا يعمل. اتصل باختبار الصدى (*43) فتسمع صوتك عائدًا إليك.
• ثم اضبط مواعيدك وبريدك الصوتي. هذان الاثنان هما ما يمنع ضياع مكالمة في السابعة مساءً، وهما أكثر ما ينقص مقسمًا حديث التشغيل.

على عجل؟ هناك خمسة قوالب بداية — عيادة، ومكتب محاماة، وورشة، ومتجر، وخط منزل — تُنشئ مواعيد الدوام ومسار الدخول وصندوق ما بعد الدوام في طلب واحد. ولا تكتب أبدًا فوق شيء ضبطته أنت.

كيف تدخل إلى لوحتكعبر واجهة البرمجة

اللوحة موجودة في صفحة VOICE الخاصة بك ولا تظهر إلا بجلسة. تلك الجلسة تُصدرها منطقة العملاء، ولا يُكتب هنا شيء.

لمن سيبني ذلك الزر، هذا هو العقد كاملًا:

POST /inquilinos/:inquilino/sesiones     # نطاق النظام: البوابة وحدها تستطيع إصداره
{ "minutos": 15 }
→ { "clave": "pbx_ses_…", "caduca": "…", "ambito": "sesion", "minutos_max": 60 }

/nizam-hatif#t=<clave>&exp=<ISO>&v=<inquilino>

تنتقل بيانات الاعتماد في جزء الوسم لا في الاستعلام، وذلك عن قصد: جزء الوسم لا يُرسَل إلى الخادم أبدًا، فلا ينتهي في ترويسة Referer، ولا في سجلات الوصول، ولا عند وسيطٍ في الطريق. تنتهي صلاحيتها خلال دقائق، ولها سقف، ولا تستطيع أن تصنع مفتاحًا دائمًا.

اللوحة، تبويبًا تبويبًاعبر واجهة البرمجة

16 أقسام، هي 16 نفسها في اللغات الثماني. وكل ما هنا موجود أيضًا في واجهة البرمجة.

الهاتف داخل متصفّحكمكالمة حقيقية

التبويب هاتف. لا تطبيق تثبّته، ولا جهاز مكتبيّ تشتريه، ولا رقم تنقله: إنه تحويلة من مقسمك أنت، مسجَّلة من المتصفّح.

• إنها تحويلة حقيقية. يسجّل المتصفّح لدى مقسمك كما يفعل هاتف المكتب، ويمرّ الصوت عبر اتصال مشفّر. فمن يتصل برقمك يصل إلى التبويب، والتبويب يستطيع الاتصال بالخارج.
• يجب أن يبقى التبويب مفتوحًا. التبويب المغلق هاتف منزوع القابس. هذا هو الحدّ الصادق لهاتف المتصفّح، وسببُ أنه يرافق هاتف المكتب بدل أن يحلّ محلّه في كل مكان.
• ترى من هو في مكالمة.مكالمة حقيقية تتحدّث مصابيح زملائك مباشرةً — متاح، يرنّ، يتكلّم — فتعرف قبل التحويل إن كان هناك من تحوّل إليه.
• تنقل مكالمة جارية إلى جهاز آخر.لم يُجرَّب بعد «عليّ الخروج وأنا في مكالمة»: تنتقل المكالمة إلى جوّالك دون أن تقطعها. جعلناها زرًّا لا رمزًا على لوحة الأرقام عن قصد — فمن ينقل مكالمة أمامه شاشة.
• التحويل والتعليق والتسجيل هي الرموز نفسها في أي هاتف. تُطلب ولا تُنقر، فما تتعلّمه على هاتف المتصفّح يعمل على هاتف المكتب وعلى جوّالك.

هاتف المتصفّح لا يسجّل على حاسوبك أبدًا. التسجيل يحدث داخل المقسم، حيث تُطبَّق قواعد من يجوز تسجيله ومن يجب إعلامه — انظر «التسجيل، والقانون».

رموز تُطلب من الهاتف

احتفظنا بالمتعارف عليه حيث وُجد عرف: التحويل (*72)، وعدم الإزعاج (*78)، والبريد الصوتي (*97)، والالتقاط (*8)، ومَن اتصل للتوّ (*69). هذه كل قيمة رمز لوحة الأرقام: الوظيفة موجودة في اللوحة أصلًا، والرمز هو ما يجعل مَن ظلّ عشرين عامًا يطلب الرمز ذاته يصدّق اللوحة.

تُطلب والهاتف حرّ

تُطلب أثناء محادثة

أثناء الاستشارة في تحويل مرافَق

داخل غرفة اجتماعات

بعض الرموز تعني شيئين ولا تتصادم: رمز التسجيل (*1) هو «سجّل الآن» في محادثة عادية، و«أكمل التحويل» أثناء الاستشارة، و«أغلق الغرفة» داخل غرفة اجتماعات. هي حالات مختلفة للهاتف نفسه، ويتولّاها كودٌ مختلف.

قبل أن تثق بهاتف جديد: هواتف المكتب والمحوّلات تعالج رموز النجمة الخاصة بها ولا تمرّرها أبدًا. فإن طلبتَ رمزًا وسمعت صمتًا ثم نغمة الطلب، فقد ابتلعه الجهاز ولم يصل إلى المقسم شيء. اطلب منّا مراجعة أي طراز جديد على قائمة اليوم قبل توزيعه.

البريد الصوتي من أي هاتفمنصّة الاختبار

اطلب رمز البريد الصوتي (*97)، وأدخل رمزك السرّي، فيكون الصندوق كله بين يديك: بلا تطبيق وبلا متصفّح. كُتب لصاحب العمل الذي يتصل من هاتف مستعار.

القائمة الرئيسية

أثناء تشغيل رسالة

قائمة التحيات

استقبال المكالمة نفسها

مجموعة الرنين تقول «فليرنّ في عدة أماكن». وكل ما في هذه القائمة يفعل شيئًا لا تستطيعه مجموعة رنين.

• الطوابير.عبر واجهة البرمجة الطابور يعرف كم شخصًا أمامك وكم يستغرق الأمر عادةً، فيستطيع أن يقول ذلك. وتُقاس مدة الانتظار من مكالماتك الأخيرة أنت، ولا تُختلق أبدًا — وبأقل من ثلاث عيّنات لا يقول شيئًا. وإن لم يكن أحد على الوردية، لا يُترك أحد في الانتظار.
• معاودة الاتصال من الطابور.عبر واجهة البرمجة تُعرَض بعد انتظار، ولا تُعرَض إن كانت المكالمة على وشك أن يُردّ عليها. ويبقى الطلب بعد إعادة التشغيل، لأن من يطلبه يُغلق الخط، وتدخل المعاودة في مقدّمة الصفّ، وهذا ما وُعد به.
• غرف الاجتماعات.عبر واجهة البرمجة غرفة برقم ومفتاحين: واحد للدخول وآخر لإدارتها. ولا يحتاج أحد إلى حساب في أي مكان. ويُعلَن الدخول والخروج بالاسم الذي سجّله كل شخص بنفسه.
• دليل الأسماء.منصّة الاختبار يتهجّى المتصل اسمًا على لوحة الأرقام فيُوصَل. وتُفهرَس كل كلمة من الاسم على حدة، لأن اسمَي العائلة أمر معتاد هنا، والبحث بالأول وحده يجد نصف الشركة. وتُوحَّد الحركات وحرف الـñ، فيُعثر على «Muñoz» بطلب 686.
• الصفر لعامل الهاتف.عبر واجهة البرمجة لعلّه أكثر توقّع شائع عن الهاتف: أن تصل إلى إنسان. ينحدر الصفر من عامل هاتفك إلى الصندوق العام إلى قولها بصوتٍ مسموع — ولا ينتهي بإغلاقٍ صامت أبدًا.
• التعليق والالتقاط.عبر واجهة البرمجة علّق مكالمة فتنتظر في موضع مرقّم مع الموسيقى بينما تمشي إلى مكتب آخر. ويستطيع أي أحد استعادتها بطلب رقم ذلك الموضع. أما التقاط الهاتف الذي يرنّ بجوارك فرمزه هو (*8).

القنوات: الضمان والإعارة والردّعبر واجهة البرمجة

هذا هو الجزء الذي لا يستطيع سقفٌ جامد أن يفعله، ويستحق أن تفهمه قبل اختيار الباقة.

• المضمونة. المكالمات المتزامنة التي تبيعها باقتك. تتّسع دائمًا مهما فعل المقسم، ولا يستطيع أحد أن يسحبها منك.
• المُعارة. فوق ضمانك تستخدم ما يتوفّر في المقسم. في معظم الأيام ستكون هنا، ولا يكلّف ذلك شيئًا إضافيًا.
• الاحتياطي. وسادةٌ من القنوات لا تُعار لأحد، حتى يستطيع كل مشترك بلوغ ضمانه في أي لحظة.
• الردّ. حين يضيق المقسم، يمكن ردّ المكالمات المُعارة لحماية ضمان غيرك. وهذا لا يسري إلا على الحسابات التي فعّلته، ولا يمسّ أبدًا مكالمةً داخل ضمان، ولا مكالمة طوارئ، ولا يحدث بصمت: يتكلّم المقسم قبل أن يُفلت.
• لا يمكن بيعه مرّتين. مجموع كل الضمانات مضافًا إليه الاحتياطي يجب أن يتّسع. يتحقّق التفعيل من ذلك ويرفض باقةً لا تتّسع، وهذا ما يجعل لكلمة «مضمون» معنى.
• وترى متى عضّ الضيق. يُبلَّغ عن الازدحام على شكل وقائع بساعتها، لا كمجموع شهري. «اثنتا عشرة مكالمة مرفوضة في ثلاثين يومًا» تُقرأ كضجيج؛ أما «الثلاثاء الماضي بين العاشرة والحادية عشرة سمع خمسة أشخاص إشارة انشغال» فشيء يمكن التصرّف بناءً عليه.

ماذا يحدث حين يتعطّل شيء

يُحكَم على المقسم يوم ينقطع التيار، لا يوم يعمل كل شيء.

• أكثر من مخرج. يصل المقسم إلى العالم الخارجي عبر عدة اتصالات مستقلّة ويختار بينها وحده. وأنت لا تضبط هذا ولا تراه يحدث.
• «يعمل» تُقاس على الشيء الصحيح. لا يدخل اتصالٌ في الاختيار إلا إذا كان يصل إلى الإنترنت وإلى شبكة الهاتف معًا. والاكتفاء بالأول هو كيف ينتهي مقسمٌ بلا خطّ وكل المصابيح خضراء.
• يعود وحده بعد انقطاع التيار. حين يعود التيار، يبدأ المقسم وأجهزة الشبكة في وقت واحد، وليس دائمًا بالترتيب الصحيح. وبدل الوثوق بذلك الترتيب، يظلّ المقسم يقارن ما لديه فعلًا بما ينبغي أن يكون لديه ويصلح نفسه — بسقفٍ لعدد المحاولات، حتى يُصعَّد العطل الحقيقي بدل أن يدور في حلقة.
• ولا يقطع مكالمة ليصلح نفسه. أي إصلاح قد يقطع محادثات ينتظر حتى لا تبقى واحدة.

التسجيلات ورسائل البريد الصوتي تُحفَظ خارج المقسم، فتبقى حتى لو ذهبت الآلة نفسها.

الباقات والدقائق

5 باقات، من $100 إلى $300 سنويًا، ورقم واحد لكل ترخيص. والدقيقة الواردة على رقم كوستاريكي بـ$0.00.

الدقائق

الأسعار بالدولار الأمريكي شاملةً الضرائب. ويقيس المشغّل مكالمات الجوال بالثانية. كل ترخيص يشمل 1 رقمًا؛ والأرقام الإضافية تتشارك المقسم نفسه والمسارات نفسها واللوحة نفسها.

التسجيل، والقانونعبر واجهة البرمجة

الصوت المسجَّل أصوات أناس آخرين. يحكمه القانون الكوستاريكي 8968، ومن هناك جاء التصميم، لا مما هو أيسر.

• أنت تقرّر ما يُسجَّل.عبر واجهة البرمجة كل شيء، أو تحويلات بعينها، أو المكالمات الواردة على رقم بعينه. أو لا شيء، وهو جواب مشروع.
• مدة الحفظ تأتي مع باقتك. تُمحى التسجيلات تلقائيًا عند انتهاء مدّتها: مدّة الباقة، أو 90 يومًا للتسجيلات التي تُطلب أثناء المكالمة (بـ ‎*1) وتسجيلات غرفة المؤتمرات. والاستثناء الوحيد تسجيلٌ مرتبط بملفّ مكالمة مؤذية، فيتوقّف عن الانتهاء حتى تُغلق الملفّ — وإغلاقه يعيد مهلةً عادية، لا «امحُه الآن».
• مشاركة تسجيل ليست منح وصول. رابط موقَّع يشغّل تسجيلًا واحدًا، وتنتهي صلاحيته وحدها، ويمكن إبطاله. ومن ترسله إليه لا يرى حسابك أبدًا.
• كل استماع مسجَّل. من شغّل أي تسجيل ومتى. إنه صوت شخص آخر: وأن تعرف من سمعه جزء من حفظه.
• ويمكن تصنيفها. عميل، أو عميل محتمل، أو داخلي. ولا قيمة افتراضية عن قصد: «غير مصنَّف» صادق، والوسم الذي خمّنته الآلة لا يمكن تمييزه لاحقًا عن وسمٍ اختاره إنسان.

يُبلَّغ الطرفان دائمًا. أن تطلب من المقسم أن يسجّل يعيد إليك أيضًا واجب الإعلان — ولا يمكن فصل الاثنين، لأن فصلهما هو كيف ينتهي أحدهم مسجَّلًا دون أن يدري. وفي غرفة الاجتماعات يُبلَّغ كل شخص عند دخوله.

الحدود والحماية والتراجع

ما يقرّر إلى أي حدّ يسوء يومٌ سيّئ: بيانات اعتماد مسروقة، أو خطأ في التوجيه، أو رقم لا يكفّ عن الاتصال.

• سقف إنفاق، يومي وشهري.منصّة الاختبار هذا ما يمنع بيانات اعتماد مسروقة من أن تكلّف مالًا. وعند بلوغ السقف تتوقّف المكالمات.
• ما يجوز لكل تحويلة أن تطلبه.عبر واجهة البرمجة داخلي فقط، أو محلّي، أو جوّال، أو كل شيء. فلا سبب لأن يستطيع هاتف المستودع الاتصال برقمٍ مدفوع. ومكالمات الطوارئ لا تتأثّر بهذا أبدًا.
• السعر قبل الطلب.عبر واجهة البرمجة اسأل كم يكلّف رقم معيّن، فتحسب الجواب الآلية نفسها التي ستُجري المكالمة فعلًا — لا جدول تعرفة قد لا يكون هو المطبَّق.
• إنذار احتيال يراقب السلوك.لم يُجرَّب بعد سرعة غير معتادة، أو بلد لم تتصل به قط، أو ساعة لا يعمل فيها أحد. ينبّه ولا يقطع: فالإيجابية الكاذبة هنا ليست تنبيهًا مزعجًا، بل مكالمة لم تحدث. ويحتاج إلى إشارتين قبل أن يقول شيئًا، لأن إنذارًا ينطلق يوميًا يُتجاهَل.
• من يتصل مرارًا يُوسَم.لم يُجرَّب بعد الرقم نفسه خمس مرات في دقيقتين ليس عميلًا ملحاحًا بل مُهاتِفًا آليًا. وهو ينبّه فقط في وضعه الأصلي؛ أما الحظر التلقائي فخانةٌ تؤشّرها أنت، لأن إيجابية كاذبة تكلّفك عميلًا لن يستطيع الاتصال بك أبدًا.
• ملفّ لمكالمة مؤذية.لم يُجرَّب بعد الوقت والمسار والصوت، محفوظة معًا لأجل شكوى. وفتح ملفّ لا يحظر المتصل: كل مكالمة جديدة دليل إضافي، وذلك قرارك أنت لا قرارنا.
• مدى إمكان الوصول إلى أجهزتك.عبر واجهة البرمجة ليس زمن تشغيلنا نحن، بل زمنك أنت. ويُظهر دائمًا كم من الفترة قِيس فعلًا، لأن نسبةً تُسقط بصمت الساعات التي لم ينظر إليها أحد تُخطئ دائمًا في الاتجاه المريح.
• ما الذي تغيّر، ومن غيّره، وكيف تتراجع.عبر واجهة البرمجة «كان يعمل أمس» سؤال له جواب. كل تغيير في الإعداد يُسجَّل ويمكن التراجع عنه، والتراجع يتحقّق أن أحدًا آخر لم يمسّ تلك الحقول في الأثناء بدل أن يكتب فوقها بصمت.

ما هو مُطفأ، ولماذا

الدليل الذي يذكر ما يعمل فقط يُجبرك على اكتشاف الباقي وحدك، ويُكتشف دائمًا في أسوأ لحظة. وهذه القائمة تُولَّد من المقسم نفسه، فلا تستطيع أن تصف شيئًا بأنه مُطفأ بعد أن يُشغَّل.

واجهة البرمجةعبر واجهة البرمجة

اللوحة ليست إلا عميلًا من عملاء هذه الواجهة. وما تغيّره بيدك يمكن تغييره ببرنامج، بمفتاحٍ يخصّ حسابك.

curl -H "authorization: Bearer <clave>" \
  https://api.voice.forhosting.com/inquilinos/<cuenta>/numeros

النطاقات

حين يسوء شيء

كل ما يمكن أن ترده الواجهة البرمجية عند الرفض

هذه هي السلاسل النصية التي تعيدها الواجهة في الحقل error حرفيًا، مقروءة من الشيفرة المصدرية للمقسم. تصدر بالإسبانية وتُعرض هنا كما هي عن قصد: ما عليك مطابقته هو ما يصلك، لا ترجمته. تشير … إلى الموضع الذي تُدرج فيه قيمة.

كل خطأ يحمل رمزًا ثابتًا. اعتمد على codigo لا على نص الرسالة. وهو موجود دائمًا: وما لا يعلن رمزًا خاصًا يأخذ رمز فئته المشتق من حالة HTTP. نص error مكتوب ليقرأه إنسان وقد تُعاد صياغته؛ أما الرمز فلا.

{ "error": "…", "codigo": "de_otra_cuenta" }

336 رسالة مختلفة في 407 موضعًا من شيفرة المقسم. تُشتق مع كل عملية بناء: ما يتغيّر هناك يتغيّر هنا.

لا حدّ للمعدّل اليوم إلا بالكاد. الحدّ الوحيد مهلةُ ثوانٍ قليلة بين محاولات فتح هاتف المتصفّح. ولا توجد حصّة عامة، ونفضّل أن نقولها على أن تبني على افتراض. كن معقولًا، وإن كنت تخطّط لشيء ثقيل فأخبرنا أولًا لنقيسه معك لا بعدك.

إلى أين تصل

304 نقطة نهاية في المجموع، قُرئت من المقسم نفسه في 2026-10-21.

هذا الجدول ملخّص. أما القائمة التي لا يمكن أن تتقادم فهي التي يولّدها المقسم عن نفسه: GET /api.

كل نقطة وصول، واحدة تلو الأخرى

مقروءة من موجّه المقسم نفسه، فلا يمكنها وصف مسار غير موجود ولا إغفال مسار موجود. لا يظهر هنا إلا نطاق حسابك: مسارات التزويد تخصّ البوابة، ولن يُسلَّم إليك مفتاح يصل إليها.

أمثلة مسجَّلة

لم تُكتب يدويًا، بل سُجّلت من تنفيذ حقيقي على هذه الواجهة داخل حساب مؤقّت حُذف بعد ذلك: الطلب والحالة والرد كما مرّت فعلًا. استُبدلت معرّفات الحساب والكائنات برموز، ولم يُمسّ سواها. المثال المكتوب يثبت ما ظنّه كاتبه، أما المسجَّل فيثبت ما فعله المقسم.

24 من أصل 226 مسار لها مثال مسجَّل، من تنفيذ 2026-10-16. أما البقية فمدرجة أعلاه ولم تُختبر بهذه الطريقة بعد — نفضّل أن نُريك الرقم على أن تفترض أنها كلها كذلك.

{
  "plazas": []
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "cancelada",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.942Z"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "pendiente",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.732Z"
}

{
  "numero": "50688889999",
  "cuando": "2026-10-16T22:44:57.219Z",
  "texto": "ensayo"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "pendiente",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.732Z"
}

[]

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Soporte",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:57.230Z",
  "actualizado": "2026-10-16T21:44:57.230Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

{
  "nombre": "Ya editada"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Ya editada",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:59.058Z",
  "actualizado": "2026-10-16T21:44:59.287Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Soporte",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:57.230Z",
    "actualizado": "2026-10-16T21:44:57.230Z",
    "version": "\"v1-73d179cfb86c534a9bfccc\""
  }
]

{
  "nombre": "Soporte",
  "estrategia": "todos"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Soporte",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:57.230Z",
  "actualizado": "2026-10-16T21:44:57.230Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Sala 1",
  "numero": null,
  "max_personas": 10,
  "esperar_organizador": 0,
  "anunciar_entradas": 1,
  "pedir_nombre": 1,
  "bloqueada": 0,
  "grabar": 0,
  "musica": "default",
  "activa": 1,
  "creado": "2026-10-16T21:44:57.733Z",
  "actualizado": "2026-10-16T21:44:57.733Z",
  "tiene_pin": false,
  "tiene_pin_organizador": false,
  "dentro": 0,
  "grabando": false
}

{
  "nombre": "Sala 1",
  "clave": "<secreto>"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Sala 1",
  "numero": null,
  "max_personas": 10,
  "esperar_organizador": 0,
  "anunciar_entradas": 1,
  "pedir_nombre": 1,
  "bloqueada": 0,
  "grabar": 0,
  "musica": "default",
  "activa": 1,
  "creado": "2026-10-16T21:44:57.733Z",
  "actualizado": "2026-10-16T21:44:57.733Z",
  "tiene_pin": false,
  "tiene_pin_organizador": false
}

{}

{
  "ticket": "<secreto>",
  "eventos": [
    "wss://<puerta>:<puerto>/eventos",
    "wss://<puerta>:<puerto>/eventos",
    "wss://<puerta>:<puerto>/eventos"
  ],
  "inquilino": "<cuenta>"
}

{
  "instalacion": "ejercicio-api-ventana-tranquila"
}

{
  "id": "<id>",
  "clave": "<secreto>",
  "caduca": "2026-10-16T22:00:02.449Z",
  "segundos": 900,
  "ambito": "dispositivo",
  "vinculo": {
    "inquilino": "<cuenta>",
    "extension": "<id>",
    "dispositivo": "<id>"
  },
  "extension": {
    "id": "<id>",
    "numero": "100",
    "nombre": "Ejercicio API"
  },
  "dispositivo_nuevo": true,
  "minutos_max": 60,
  "resumen": "credencial de UN aparato de UNA extensión, que caduca; para la app móvil"
}

{
  "numero": "100"
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "numero": "100",
    "nombre": "Ejercicio API",
    "correo": null,
    "cid_saliente": null,
    "timbrado_s": 25,
    "estado": "activa",
    "creado": "2026-10-16T21:45:00.167Z",
    "actualizado": "2026-10-16T21:45:00.167Z",
    "nombre_audio": null,
    "en_directorio": 1,
    "departamento": null,
    "version": "\"v1-a1a25e330e8bc32c8289ab\""
  }
]

{
  "nombre": "Ejercicio API",
  "numero": "100"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "100",
  "nombre": "Ejercicio API",
  "correo": null,
  "cid_saliente": null,
  "timbrado_s": 25,
  "estado": "activa",
  "creado": "2026-10-16T21:45:00.167Z",
  "actualizado": "2026-10-16T21:45:00.167Z",
  "nombre_audio": null,
  "en_directorio": 1,
  "departamento": null,
  "reglas": {
    "extension_id": "<id>",
    "dnd": 0,
    "dnd_hasta": null,
    "sigueme": 0,
    "sigueme_numeros": [],
    "sigueme_modo": "tras",
    "sigueme_confirmar": 1,
    "sigueme_s": 20,
    "desvio_siempre": null,
    "desvio_ocupado": null,
    "desvio_nocontesta": null,
    "fallo_tipo": "buzon",
    "fallo_id": "<id>",
    "actualizado": "2026-10-16T21:45:00.168Z",
    "desvio_confirmar": 1,
    "screening": 0,
    "clase_servicio": "todo",
    "supervisar": 0,
    "transferencia_retorno": 0
  },
  "dispositivos": [
    {
      "id": "<id>",
      "etiqueta": "principal",
      "usuario_sip": "tf3zfmm96cfq100",
      "transporte": "udp",
      "estado": "activo",
      "ultimo_registro": null,
      "ultima_ip": null,
      "creado": "2026-10-16T21:45:00.168Z",
      "rotado": null,
      "instalacion": null
    }
  ],
  "buzon": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "extension_id": "<id>",
    "nombre": "Buzón de Ejercicio API",
    "saludo_texto": "Ha llamado a Ejercicio API. Deje su mensaje después del tono.",
    "saludo_audio": null,
    "correo": null,
    "enviar_correo": 1,
    "adjuntar": 1,
    "transcribir": 1,
    "max_s": 120,
    "creado": "2026-10-16T21:45:00.168Z",
    "actualizado": "2026-10-16T21:45:00.168Z",
    "max_mensajes": 50,
    "aviso_activo": 0,
    "aviso_numero": null,
    "revisar": 0,
    "ofrecer_operadora": 1,
    "guion": null,
    "aviso_numeros": null,
    "aviso_modo": "tras",
    "reintentar": 0,
    "reintentos_max": 2,
    "compartido": 0,
    "extensiones_acceso": null,
    "abrir_caso": 1,
    "tiene_pin": false
  },
  "credencial": {
    "id": "<id>",
    "usuario_sip": "tf3zfmm96cfq100",
    "clave": "<secreto>",
    "realm": "pbx.forhosting.com",
    "transporte": "udp"
  }
}

{}

{
  "revertido": "<id>",
  "tabla": "colas",
  "fila_id": "<id>",
  "columnas": [
    "nombre"
  ],
  "fila": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Para editar",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.671Z"
  }
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "tabla": "colas",
  "fila_id": "<id>",
  "columna_clave": "id",
  "antes": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Para editar",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.058Z"
  },
  "despues": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Ya editada",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.287Z"
  },
  "actor": "apikey:<id> primera clave de sistema (sistema)",
  "origen": "api",
  "revertido_de": null,
  "creado": "2026-10-16T21:44:59.287Z",
  "cambios": {
    "nombre": {
      "antes": "Para editar",
      "despues": "Ya editada"
    }
  }
}

{
  "inquilino": "<cuenta>",
  "cambios": [
    {
      "id": "<id>",
      "tabla": "colas",
      "fila_id": "<id>",
      "actor": "apikey:<id> primera clave de sistema (sistema)",
      "origen": "api",
      "revertido_de": null,
      "creado": "2026-10-16T21:44:59.287Z",
      "cambios": {
        "nombre": {
          "antes": "Para editar",
          "despues": "Ya editada"
        }
      }
    }
  ]
}

{
  "activas": []
}

{}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "motivo": "ensayo",
  "desde": "2026-10-16T21:44:58.365Z",
  "hasta": "2026-10-16T21:44:58.588Z",
  "avisar": 1,
  "activo": 0,
  "creado": "2026-10-16T21:44:58.365Z"
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "motivo": "ensayo",
    "desde": "2026-10-16T21:44:58.365Z",
    "hasta": null,
    "avisar": 1,
    "activo": 1,
    "creado": "2026-10-16T21:44:58.365Z"
  }
]

{
  "motivo": "ensayo",
  "minutos": 5
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "motivo": "ensayo",
  "desde": "2026-10-16T21:44:58.365Z",
  "hasta": null,
  "avisar": 1,
  "activo": 1,
  "creado": "2026-10-16T21:44:58.365Z"
}

[]

{
  "destino": "buzon"
}

{
  "operadora": null
}

{
  "borrado": "<cuenta>"
}

{
  "nombre": "Ejercicio API 2026-10-16T21:44:54"
}

{
  "id": "<cuenta>",
  "nombre": "Ejercicio API 2026-10-16T21:44:54",
  "cuenta_portal": null,
  "cedula": null,
  "correo": null,
  "telefono": null,
  "plan": "zero",
  "zona": "America/Costa_Rica",
  "idioma": "es",
  "estado": "activo",
  "canales_max": 4,
  "notas": null,
  "creado": "2026-10-16T21:44:56.852Z",
  "actualizado": "2026-10-16T21:44:56.852Z",
  "canales_garantizados": 2,
  "modo_presion": "firme",
  "presion_canales": 1,
  "duracion_max_s": null,
  "operadora_tipo": null,
  "operadora_id": null,
  "filtro_anonimas": 0,
  "cdr_retencion_dias": null,
  "codigo_asunto_digitos": 0,
  "supervision_activa": 0,
  "canales_troncal": null,
  "limites": {
    "canales": 2,
    "canales_max": 4,
    "extensiones": 3,
    "retencion": 30,
    "tope_diario": 3,
    "tope_mensual": 25
  },
  "canales": {
    "existe": true,
    "garantizados": 2,
    "max": 4,
    "modo": "firme",
    "presion_canales": 1,
    "por_troncal": null
  }
}

الجلسات: المتصفّح لا يحمل مفتاحًا دائمًا أبدًا

بيانات اعتماد قصيرة العمر، بسقف 60 دقيقة، ولا تستطيع أن تصنع مفتاحًا دائمًا. هذا هو العقد إن كنت أنت من يبني الزر.

• البوابة وحدها تستطيع إصدارها. إصدار جلسة يحتاج إلى مفتاح تزويد، لأن البوابة وحدها تستطيع أن تؤكّد أن خلف الطلب عميلًا سجّل دخوله. وVOICE لا يعرف كلمات مرور العملاء ولا سبب لأن يعرفها.
• ولا تولد بلا انتهاء صلاحية. إن لم يطلب أحد مدّة، وُضعت لها واحدة. ونطاقٌ وُجد لكي ينتهي وقد يولد أبديًا أسوأ من عدمه، لأن الناس يثقون به.
• وطلب مدة أطول لا ينفع. هناك سقف صارم. وأن يطلب المتصل ثماني ساعات لا يجعل بيانات الاعتماد آمنة.
• ولا تستطيع ترقية نفسها. إدارة المفاتيح كلها خلف نطاق التزويد، فلا تستطيع جلسة أن تصنع مفتاحًا دائمًا. ويُفرَض ذلك في الموجّه، قبل تشغيل أي معالج.
• ويمكن إنهاؤها مبكرًا. يعود المعرّف عند الإصدار، تحديدًا كي تستطيع إبطالها قبل موعدها.

Webhooksعبر واجهة البرمجة

تُبلَّغ أنظمتك بما حدث بدل أن تسأل كل بضع ثوانٍ. 31 حدثًا، موقَّعة، ويُعاد إرسالها، ولا يسقط منها شيء بصمت.

x-pbx-evento: llamada.entrante
x-pbx-marca:  1755300000
x-pbx-firma:  <hex>

{ "evento": "llamada.entrante", "inquilino": "…", "cuando": "…", "datos": { … } }

كل تسليم موقَّع: يغطّي التوقيع الطابع الزمني والجسم الذي استلمته بالضبط، فتحقّق منه على البايتات الخام لا على نسخة أُعيدت صياغتها. ويُعرَض السرّ مرة واحدة عند إنشاء الاشتراك، ويمكن تدويره دون إيقاف التسليمات.

التسليم الفاشل يُعاد بعد 10 · 30 · 60 · 300 · 900 · 3600 ثانية، ولكل محاولة 10 ثانية. والاشتراك الذي يستمرّ في الفشل يُوقَف مؤقتًا بعد 20 إخفاقات متتالية بدل أن يسقط بصمت — ويمكنك رؤية كل محاولة.

الأحداث

القناة المباشرةمكالمة حقيقية

تسافر إشعارات Webhook على دفعات وتصل خلال ثوانٍ. لكن هناك ما يجب أن يكون على الشاشة الآن: مصباحٌ يقول إن زميلك في مكالمة لا يصحّ أن يتأخّر خمس عشرة ثانية.

• ماذا تحمل. المكالمات وهي تحدث، والرسائل الجديدة، وحالة مصباح كل تحويلة — وهو ما يجعل لوحة المصابيح على الشاشة حيّة فعلًا.
• للقراءة فقط.عبر واجهة البرمجة تستطيع فتح تذكرة للقناة دون تسليم هاتف: فمشاهدة ما يجري لا ينبغي أن تتطلّب بيانات اعتماد تستطيع أيضًا تغيير الأشياء.
• ولا تحلّ محلّ Webhooks. القناة المباشرة لشاشة ينظر إليها أحد. وإن كان يهمّك أن يعلم نظامك، فاستعمل Webhook: يعيد المحاولة، ولا يعتمد على بقاء وصلة مفتوحة.

كيف تُقرأ الشارات

كل وظيفة في هذه الصفحة تحمل شارة تقول كيف تحقّقنا منها. وننشر أيضًا ما لم يُجرَّب بعد، موسومًا بذلك، لأن أن تكتشفه أنت وحدك أسوأ.

114 وظيفة، مُحصاة من المقسم في 2026-09-19.

الشارة تخصّ وظيفة لا صفًّا واحدًا: وحيث تغطّي وظيفة عدة رموز، تظهر جميعها بمستوى المجموعة. أي أن الشارة قد تقول أقلّ مما جُرِّب فعلًا — ولا تقول أكثر أبدًا، وهو الاتجاه الوحيد الذي نقبل أن نخطئ فيه في صفحة تقرأها كوعد.

مسرد المصطلحات

الكلمات التي يستعملها المقسم الهاتفي ولا يستعملها شيء آخر.