راقب استخدام مفتاحك قبل أن تبلغ الحد
متابعة ترويسات الحصة أولًا بأول تخبرك متى يقترب الحد، قبل وقت طويل من رفض أي طلب فعليًا.
أضف الإكمال التلقائي للعناوين إلى نموذج الدفع
تفشل نماذج الدفع في حقول العنوان أكثر من أي حقل آخر، وعادة لأن العميل يخطئ في كتابة اسم الشارع أو يغفل رقم الشقة. واقتراح عناوين حقيقية أثناء الكتابة يصلح معظم ذلك قبل أن يتحول إلى عملية توصيل فاشلة.
طلب الإكمال التلقائي
تستقبل نقطة النهاية /v1/autocomplete نصًا جزئيًا وحدًا لعدد الاقتراحات المعادة. استدعها أثناء كتابة العميل، بعد أن يُدخل بضعة أحرف.
GET /v1/autocomplete?q=221B Baker&limit=5{
"status": "ok",
"query": "221B Baker",
"suggestions": [
{"text": "221B Baker Street, London, UK", "place_id": "abc123"},
{"text": "221B Baker Avenue, Springfield", "place_id": "abc124"}
]
}من الاقتراح إلى العنوان الكامل
الاقتراح عبارة عن تسمية قصيرة وplace_id، وليس سجل عنوان كاملًا. بمجرد أن يختار العميل واحدًا، حوّله إلى عنوان كامل بمكوناته وإحداثياته بتمرير نص الاقتراح إلى /v1/forward. هذا الاستدعاء الثاني هو ما يملأ حقول الشارع والمدينة والمنطقة والرمز البريدي في نموذجك.
GET /v1/forward?q=221B Baker Street, London, UK&limit=1في هذا الطلب الثاني يظهر الكائن components فعليًا، لأن /v1/autocomplete لا يعيد إلا تسمية نصية وplace_id، ولا يعيد أبدًا تفصيلًا للشارع والمدينة والرمز البريدي. وتخطي هذه الخطوة ومحاولة تحليل نص الاقتراح بنفسك أكثر هشاشة مما يبدو، لأن التنسيق يختلف من دولة لأخرى.
إبقاء عدد الطلبات معقولًا
إرسال طلب مع كل ضغطة مفتاح يتراكم بسرعة في صفحة دفع مزدحمة. طبّق تأخيرًا (debounce) على الحقل بحيث لا يُرسل الطلب إلا بعد توقف العميل عن الكتابة لحظة، وتجاهل الطلبات لأي نص أقل من ثلاثة أو أربعة أحرف حيث لا تكون الاقتراحات مفيدة أصلًا. كل استدعاء للإكمال التلقائي وكل استدعاء لاحق للترميز الجغرافي الأمامي يُحتسب طلبًا واحدًا من حصتك اليومية، لذا يمكن لحقل مؤخَّر في متجر مزدحم أن يبقى ضمن 2,500 طلب مجاني يوميًا المضمنة مع كل مفتاح بفارق كبير.
التعامل مع عدم وجود تطابقات
مصفوفة الاقتراحات الفارغة استجابة عادية، وليست خطأ. دع العميل يواصل الكتابة وارجع إلى حقل عنوان نصي عادي إذا لم يعد شيء مفيد بعد بضعة أحرف، بدلًا من منع إرسال النموذج إلى أن يُختار اقتراح.
خطأ يستحق التجنب
معاملة الاقتراح الذي نُقر عليه كعنوان نهائي تم التحقق منه اختصار شائع يسبب المتاعب لاحقًا. فقد يختار العميل اقتراحًا ثم يواصل تعديل الحقل بعده، فيغير رقم المنزل أو يضيف رقم شقة لم يكن في الاقتراح الأصلي. احرص دائمًا على تحويل النص النهائي للحقل عبر /v1/forward عند الإرسال، لا فقط لحظة النقر على الاقتراح، حتى يعكس العنوان الذي تحفظه ما انتهى إليه الحقل فعلًا.
فحص مرتبط يستحق الإضافة
إذا كان نموذج الدفع يجمع الرمز البريدي أيضًا في حقل منفصل، فإن استدعاء سريعًا إلى /v1/postcode بعد تحويل عنوان الشارع طريقة زهيدة التكلفة لاكتشاف رمز بريدي لا يتطابق مع بقية العنوان، قبل إرسالهما معًا والتسبب في عدم تطابق في الشحن لاحقًا.
الإكمال التلقائي لا يحل محل التحقق، بل يقلل فقط احتمال وصول عنوان خاطئ إلى نظام الطلبات لديك من الأساس. راجع توثيق الإكمال التلقائي للعناوين للاطلاع على قائمة المعاملات الكاملة قبل ربطه بمسار الدفع لديك.