الخطوة 1 — مفتاح الـAPI، بلا تسجيل مطور
ما كاين لا كونصول ديال المطورين لا مصادقة يدوية. التاجر كيحل محادثة فاتورة بوت فالواتساب وكيكتب « api »: البوت كيجاوبو بالمفتاح الشخصي ديالو، بصيغة fk_ متبوعة بأربعين حرف. هادا هو المفتاح اللي كيخزنو تطبيقك وكيرسلو فالهيدر Authorization: Bearer.
المفتاح خاص بكل تاجر: كيصدر بالترقيم ديالو وكيشوف غير الوثائق ديالو. « api reset » كيجددو فأي وقت — القديم كيتلغى فالحين. نداء GET /v1/account هو أبسط طريقة تتأكد بها أن المفتاح اللي لصقو المستعمل صالح: كيرجع ملف الشركة والباقة والكوطا المتبقية.
الخطوة 2 — إصدار الوثيقة
نداء واحد: POST /v1/documents، باسم الزبون (والـICE ديالو فالمعاملات بين الشركات)، ثم السطور — الوصف، الكمية، ثمن الوحدة. الـAPI كيحسب TVA سطر بسطر، كيطبق النظام الضريبي ديال التاجر، كيولد الـPDF باللوغو والطابع، وكيرد 201 بالرقم والمجاميع ورابط الـPDF ورابط QR code.
جوج خيارات كيبدلو كلشي فاليومي. « type »: « quote » كيصدر عرض ثمن (مرقم DEV-، صالح 30 يوم، خارج الكوطا) بدل الفاتورة. « priceIsTtc »: true كيقول للـAPI أن أثمنتك بالضريبة: كيحسب الأساس بلا ضريبة بوحدو — ضروري ملي أثمان البيع ديالك معروضة TTC.
باش تصحح وثيقة صادرة، ما كاين حتى schema خاصك تتعلمو: endpoint التعديل كيقبل تعليمة بنص حر (« بدل التكوين بثلاثة أيام بـ1200 درهم لليوم ») وكيطبقها على نفس الرقم، مع PDF جديد ومجاميع محسوبة من جديد.
الترقيم كيبقى متسلسل: التعديل عمرو كيخلق فراغ فالسلسلة، والإلغاء كيدوز عبر إشعار دائن — كما كيفرض القانون المغربي.
الخطوة 3 — تسليم الفاتورة للزبون
توليد الـPDF بلا فايدة إلى ما وصلش للزبون. ثلاث قنوات متاحة، عند الإنشاء (حقلي « sendToPhone » و« sendToEmail ») أو من بعد عبر endpoint الإرسال:
- الواتساب: الـPDF كيوصل لمحادثة الزبون باسم التاجر.
- الإيميل: رسالة مرتبة والفاتورة مرفقة.
- QR code: كل وثيقة عندها صورة PNG عمومية — عرضها فالكيسة، طبعها فالتيكي، الزبون كيسكاني وكيحمل فاتورتو.
الأخطاء اللي خاص الكود ديالك يدبرها
الـAPI كيرجع ديما JSON بجوج حقول: « error » (رمز آلي مستقر) و« message » (شرح تقدر تعرضو كما هو). أربع حالات كتستاهل معالجة خاصة فالواجهة ديالك: 402 الكوطا وصلات (الرد فيه used وlimit — عرضهم، والتاجر كيطلع للباقة الأعلى بجوج رسائل واتساب)، 401 مفتاح غير صالح (غالبا مفتاح تجدد بـ« api reset » — طلب الجديد)، 422 التعليمة ما تفهمتش (اقترح إعادة الصياغة، حتى شي حاجة ما تبدلات)، و429 فوق 60 طلب فالدقيقة (دير طابور وعاود).
اللائحة الكاملة ديال الرموز، مع مثال رد لكل واحد، موجودة فصفحة API ديال الموقع — كل مثال تعاود تشغيلو على API الإنتاج.
أسئلة متكررة
واش خاصني حساب مطور ولا مصادقة باش نستعمل الـAPI؟
لا. المفتاح كيتحصل بكتابة « api » لبوت الواتساب ديال حساب فاتورة المعني، فثواني. ما كاين لا كونصول لا عقد لا تكلفة: الـAPI متضمن فجميع الباقات، والتجربة المجانية داخلة.
واش الـPDF المولد فعلا مطابق للمراقبة الضريبية؟
الـPDF فيه بيانات المادة 145: ICE، التعريف الضريبي، الضريبة المهنية، TVA مفصلة، المبلغ بالحروف، ترقيم متسلسل، وبيانات النظام (مقاول ذاتي، معفى) ملي كيتطبقو. طابع التاجر واللوغو ديالو كيتحطو أوتوماتيكيا.
واش نقدر نصدر عروض أثمنة ونحولها لفواتير؟
أه. « type »: « quote » كيصدر عرض ثمن مرقم DEV- صالح 30 يوم، مجاني وخارج الكوطا. التحويل كيتم بالتعليمة الحرة (« حول عرض الثمن DEV-2026-0012 لفاتورة ») — والفاتورة كتاخد رقم FAT- عادي.
كيفاش نجرب بلا ما نوسخ ترقيم التاجر؟
أصدر عروض أثمنة فالتجارب ديالك: مجانية، بلا حدود، وما كيمسوش سلسلة الفواتير. خلي الفواتير الحقيقية للإنتاج — كل فاتورة صادرة كتدخل فالترقيم القانوني وكتلغى بإشعار دائن، ماشي بالحذف.
هاد الدليل كيقدم الإطار العام المطبق بالمغرب. ما كيعوضش رأي الخبير المحاسب ديالك ولا النصوص المنشورة من المديرية العامة للضرائب، اللي القيم الرقمية ديالها كتبدل مع قوانين المالية.