متضمنة في جميع الباقات — بلا زيادة

تطبيقك كيفوتر. وفاتورة كتكمل الباقي.

تطبيقك أو CRM ديالك ما فيهش الفوترة المغربية؟ زر عندك، نداء HTTP عندنا: فاتورة كتصدر الفاتورة أو عرض الثمن بترقيم التاجر، بالطابع واللوغو ديالو وجميع البيانات القانونية للمادة 145 — مع PDF يوصل بالواتساب أو الإيميل أو QR code.

فواتير وعروض أثمنة مطابقة: ICE، التعريف الضريبي، TVA مفصلة، المبلغ بالحروف، ترقيم متسلسل
التسليم كيف بغيتي: واتساب، إيميل، أو QR code يطبع — الزبون كيسكانيه وكيحمل
تعديل بالكتابة الحرة: كتب التغيير، والذكاء الاصطناعي كيطبقو
اللوغو والطابع ومعلومات الشركة كلها عبر API

ابدأ على الواتساب Quickstart ↓

POST https://bot.swiviq.com/v1/documents

curl -X POST https://bot.swiviq.com/v1/documents \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "client": { "name": "ATLAS DIGITAL SARL", "ice": "001122334455667", "type": "company" },
    "items": [
      { "description": "Abonnement CRM — pack annuel", "quantity": 1, "unitPrice": 4800 },
      { "description": "Formation équipe (2 jours)", "quantity": 2, "unitPrice": 1500 }
    ],
    "sendToEmail": "client@exemple.ma"
  }'

الحصول على مفتاح API

1التاجر كيحل المحادثة ديالو مع فاتورة بوت فالواتساب
2كيكتب ببساطة « api »
3البوت كيجاوبو بالمفتاح الشخصي ديالو (fk_…) — يلصقو فتطبيقك

المفتاح خاص بكل تاجر ومتضمن فالاشتراك ديالو من التجربة المجانية. « api reset » كيجدد المفتاح فأي وقت (القديم كيتلغى). فواتير API كتحسب من كوطا الباقة؛ عروض الأثمنة مجانية وبلا حدود.

البداية في 5 دقائق

نداء واحد كافي لإصدار وثيقة. الثمن بلا ضريبة افتراضيا؛ إلى كانت أثمنتك TTC زيد « priceIsTtc »: true — فاتورة كتحسب الأساس بوحدها.

الطلب

curl -X POST https://bot.swiviq.com/v1/documents \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "client": { "name": "ATLAS DIGITAL SARL", "ice": "001122334455667", "type": "company" },
    "items": [
      { "description": "Abonnement CRM — pack annuel", "quantity": 1, "unitPrice": 4800 },
      { "description": "Formation équipe (2 jours)", "quantity": 2, "unitPrice": 1500 }
    ],
    "sendToEmail": "client@exemple.ma"
  }'

الرد — 201

{
  "number": "FAT-2026-0042",
  "type": "invoice",
  "status": "issued",
  "issueDate": "2026-08-15",
  "client": { "name": "ATLAS DIGITAL SARL", "ice": "001122334455667", "type": "company" },
  "items": [
    { "description": "Abonnement CRM — pack annuel", "quantity": 1, "unitPrice": 4800, "vatRate": 20 },
    { "description": "Formation équipe (2 jours)", "quantity": 2, "unitPrice": 1500, "vatRate": 20 }
  ],
  "totals": { "ht": 7800, "vat": 1560, "ttc": 9360, "currency": "MAD" },
  "pdfUrl": "https://bot.swiviq.com/f/a1b2c3d4e5",
  "qrcodeUrl": "https://bot.swiviq.com/qr/a1b2c3d4e5.png",
  "whatsapp": { "owner": "sent", "client": "skipped" },
  "email": { "client": "sent" }
}

★ حصري عند فاتورة

التعديل بالكتابة الحرة

ما كاين حتى schema خاصك تتعلمو. المستعمل ديالك كيكتب التصحيح فخانة نصية، وانت كترسلها لنا كما هي — نفس محرك الذكاء الاصطناعي اللي كيفهم التجار بالدارجة فالواتساب كيفكها وكيطبقها.

الطلب

curl -X POST https://bot.swiviq.com/v1/documents/FAT-2026-0042/modify \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "le client est en fait STE ATLAS DIGITAL MAROC SARL,
                    et remplace la formation par 3 jours à 1200 dh le jour"
  }'

الرد — 200

{
  "number": "FAT-2026-0042",
  "client": { "name": "STE ATLAS DIGITAL MAROC SARL", "ice": "001122334455667", "type": "company" },
  "items": [
    { "description": "Abonnement CRM — pack annuel", "quantity": 1, "unitPrice": 4800, "vatRate": 20 },
    { "description": "Formation équipe", "quantity": 3, "unitPrice": 1200, "vatRate": 20 }
  ],
  "totals": { "ht": 8400, "vat": 1680, "ttc": 10080, "currency": "MAD" },
  "pdfUrl": "https://bot.swiviq.com/f/a1b2c3d4e5",
  "applied": "le client est en fait STE ATLAS DIGITAL MAROC SARL, et remplace…"
}

الوثيقة كتحتفظ برقمها (بلا فراغ فالتسلسل)، الـPDF كيتجدد والمجاميع كتتحسب من جديد. إلى ما تفهمتش التعليمة، الـAPI كيرد 422 مع شرح — ما كاين حتى تعديل عشوائي.

التسليم للزبون: واتساب، إيميل أو QR code

الإصدار ما كافيش — خاص الزبون النهائي يتوصل بوثيقتو. ثلاث قنوات، تقدر تجمع بيناتهم، وتعاود الإرسال قد ما بغيتي: فاتورة ضايعة كترجع بنداء واحد.

واتساب

« sendToPhone » عند الإنشاء، أو POST /send مع channel « whatsapp »: الـPDF كيمشي لمحادثة الزبون باسم التاجر.

الإيميل

« sendToEmail » عند الإنشاء، أو channel « email »: الزبون كيتوصل برسالة مرتبة والفاتورة مرفقة — نفس القالب ديال البوت.

QR code

كل وثيقة عندها « qrcodeUrl »: صورة PNG تعرضها فالكيسة، تطبعها فالتيكي أو تدمجها فالواجهة ديالك. الزبون كيسكاني وكيحمل.

الطلب

curl -X POST https://bot.swiviq.com/v1/documents/FAT-2026-0042/send \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "email", "to": "client@exemple.ma" }'

الرد — 200

{ "ok": true, "number": "FAT-2026-0042",
  "channel": "email", "to": "client@exemple.ma", "status": "sent" }

مرجع الـEndpoints

✓ كل مثال هنا تعاود تشغيلو كما هو على API الإنتاج يوم 15/08/2026 — الأجوبة المعروضة حقيقية.

POST/v1/documents

إصدار فاتورة أو عرض ثمن

« type »: « invoice » (افتراضي) أو « quote ». الخيارات: « priceIsTtc »، « vatRate » لكل سطر أو عام، « sendToPhone » و« sendToEmail » للتسليم الفوري للزبون، « notify »: false باش ما يتوصلش التاجر بإشعار. الرد 201 فيه الرقم والمجاميع ورابط الـPDF والـQR.

شوف المثال المجرب

الطلب

curl -X POST https://bot.swiviq.com/v1/documents \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "client": { "name": "ATLAS DIGITAL SARL", "ice": "001122334455667", "type": "company" },
    "items": [
      { "description": "Abonnement CRM — pack annuel", "quantity": 1, "unitPrice": 4800 },
      { "description": "Formation équipe (2 jours)", "quantity": 2, "unitPrice": 1500 }
    ],
    "sendToEmail": "client@exemple.ma"
  }'

الرد

{
  "number": "FAT-2026-0042",
  "type": "invoice",
  "status": "issued",
  "issueDate": "2026-08-15",
  "client": { "name": "ATLAS DIGITAL SARL", "ice": "001122334455667", "type": "company" },
  "items": [
    { "description": "Abonnement CRM — pack annuel", "quantity": 1, "unitPrice": 4800, "vatRate": 20 },
    { "description": "Formation équipe (2 jours)", "quantity": 2, "unitPrice": 1500, "vatRate": 20 }
  ],
  "totals": { "ht": 7800, "vat": 1560, "ttc": 9360, "currency": "MAD" },
  "pdfUrl": "https://bot.swiviq.com/f/a1b2c3d4e5",
  "qrcodeUrl": "https://bot.swiviq.com/qr/a1b2c3d4e5.png",
  "whatsapp": { "owner": "sent", "client": "skipped" },
  "email": { "client": "sent" }
}

POST/v1/documents/{number}/modify

التعديل بالكتابة الحرة

الطلب فيه فقط « instruction » بنص حر (فرنسية، دارجة أو إنجليزية). نفس الرقم، PDF جديد، وحقل « applied » كيأكد التعليمة اللي تفهمات.

شوف المثال المجرب

الطلب

curl -X POST https://bot.swiviq.com/v1/documents/FAT-2026-0042/modify \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "le client est en fait STE ATLAS DIGITAL MAROC SARL,
                    et remplace la formation par 3 jours à 1200 dh le jour"
  }'

الرد

{
  "number": "FAT-2026-0042",
  "client": { "name": "STE ATLAS DIGITAL MAROC SARL", "ice": "001122334455667", "type": "company" },
  "items": [
    { "description": "Abonnement CRM — pack annuel", "quantity": 1, "unitPrice": 4800, "vatRate": 20 },
    { "description": "Formation équipe", "quantity": 3, "unitPrice": 1200, "vatRate": 20 }
  ],
  "totals": { "ht": 8400, "vat": 1680, "ttc": 10080, "currency": "MAD" },
  "pdfUrl": "https://bot.swiviq.com/f/a1b2c3d4e5",
  "applied": "le client est en fait STE ATLAS DIGITAL MAROC SARL, et remplace…"
}

POST/v1/documents/{number}/send

تسليم أو إعادة إرسال وثيقة

{ « channel »: « whatsapp » | « email »، « to »: رقم أو عنوان }. الـPDF كيتجدد إلى ضاع — استعملها قد ما بغيتي.

شوف المثال المجرب

الطلب

curl -X POST https://bot.swiviq.com/v1/documents/FAT-2026-0042/send \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "email", "to": "client@exemple.ma" }'

الرد

{ "ok": true, "number": "FAT-2026-0042",
  "channel": "email", "to": "client@exemple.ma", "status": "sent" }

GET/qr/{token}.png

QR code التحميل (عمومي)

صورة PNG ديال الـQR كتوجه للـPDF. بلا مصادقة: الرمز هو السر. تدمجها مباشرة فـ<img> أو تطبعها فتيكي الكيسة.

شوف المثال المجرب

الطلب

<!-- directement dans votre page -->
<img src="https://bot.swiviq.com/qr/a1b2c3d4e5.png" width="180" alt="QR facture">

# ou en téléchargement
curl -o facture-qr.png https://bot.swiviq.com/qr/a1b2c3d4e5.png

الرد

HTTP 200 — image/png, 600 × 600 px
Cache-Control: public, max-age=86400, immutable

GET/v1/documents

لائحة الوثائق

آخر الوثائق الصادرة، من الأحدث للأقدم. « limit » حتى 50، « type » للفلترة بين الفواتير (« invoice ») وعروض الأثمنة (« quote »).

شوف المثال المجرب

الطلب

curl -H "Authorization: Bearer fk_votre_cle" \
  "https://bot.swiviq.com/v1/documents?limit=5&type=invoice"

الرد

[
  {
    "number": "FAT-2026-0042",
    "type": "invoice",
    "status": "issued",
    "issueDate": "2026-08-15",
    "client": { "name": "STE ATLAS DIGITAL MAROC SARL", "ice": "001122334455667" },
    "totals": { "ht": 8400, "vat": 1680, "ttc": 10080, "currency": "MAD" },
    "pdfUrl": "https://bot.swiviq.com/f/a1b2c3d4e5",
    "qrcodeUrl": "https://bot.swiviq.com/qr/a1b2c3d4e5.png"
  },
  { "number": "FAT-2026-0041", "...": "..." }
]

GET/v1/documents/{number}

قراءة وثيقة

السطور، المجاميع، رابط الـPDF والـQR — لعرض الحالة فواجهتك أو التأكد من تعديل.

شوف المثال المجرب

الطلب

curl -H "Authorization: Bearer fk_votre_cle" \
  https://bot.swiviq.com/v1/documents/FAT-2026-0042

الرد

{
  "number": "FAT-2026-0042",
  "type": "invoice",
  "status": "issued",
  "issueDate": "2026-08-15",
  "client": { "name": "STE ATLAS DIGITAL MAROC SARL", "ice": "001122334455667", "type": "company" },
  "items": [
    { "description": "Abonnement CRM — pack annuel", "quantity": 1, "unitPrice": 4800, "vatRate": 20 },
    { "description": "Formation équipe", "quantity": 3, "unitPrice": 1200, "vatRate": 20 }
  ],
  "totals": { "ht": 8400, "vat": 1680, "ttc": 10080, "currency": "MAD" },
  "pdfUrl": "https://bot.swiviq.com/f/a1b2c3d4e5",
  "qrcodeUrl": "https://bot.swiviq.com/qr/a1b2c3d4e5.png"
}

GET/v1/account

الحساب والكوطا

ملف الشركة، الباقة النشيطة، الكوطا المستهلكة/المتبقية. وهي أبسط طريقة لاختبار صلاحية مفتاح.

شوف المثال المجرب

الطلب

curl -H "Authorization: Bearer fk_votre_cle" \
  https://bot.swiviq.com/v1/account

الرد

{
  "company": {
    "name": "ATLAS SERVICES SARL", "ice": "002233445566778",
    "address": "Agdal, Rabat", "defaultVatRate": 20,
    "taxRegime": "normal", "hasLogo": true, "hasStamp": true
  },
  "plan": { "key": "p100", "label": "100 factures / mois", "priceMAD": 90 },
  "quota": { "used": 12, "limit": 100, "remaining": 88, "ok": true }
}

PUT/v1/company

تحديث معلومات الشركة

الحقول المقبولة: companyName، ice، if، taxePro، rc، address، email، defaultVatRate، paymentTerms. غير الحقول المرسلة هي اللي كتتبدل.

شوف المثال المجرب

الطلب

curl -X PUT https://bot.swiviq.com/v1/company \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "12 rue Oued Fès, Agdal, Rabat",
    "paymentTerms": "Virement à 30 jours"
  }'

الرد

{
  "ok": true,
  "company": {
    "name": "ATLAS SERVICES SARL", "ice": "002233445566778",
    "address": "12 rue Oued Fès, Agdal, Rabat", "defaultVatRate": 20
  }
}

POST/v1/company/logo

إرسال اللوغو

الطلب: { « image »: « <base64 أو data-URI png/jpeg> » } (6 ميغا كحد أقصى). اللوغو كيتنقى وكيتقص أوتوماتيكيا وكيبان فالـPDF الجايين.

شوف المثال المجرب

الطلب

curl -X POST https://bot.swiviq.com/v1/company/logo \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d "{ \"image\": \"data:image/png;base64,$(base64 -w0 logo.png)\" }"

الرد

{ "ok": true, "logo": "saved",
  "appliesTo": "toutes les prochaines factures" }

POST/v1/company/stamp

إرسال الطابع

نفس صيغة اللوغو. الخلفية كتتحيد باستخراج الحبر (تصويرة ديال الطابع على ورقة كافية)، والطابع كيتحط على كل PDF.

شوف المثال المجرب

الطلب

curl -X POST https://bot.swiviq.com/v1/company/stamp \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "Content-Type: application/json" \
  -d "{ \"image\": \"data:image/png;base64,$(base64 -w0 cachet.jpg)\" }"

الرد

{ "ok": true, "stamp": "saved",
  "appliesTo": "toutes les prochaines factures" }

رموز الأخطاء

كل خطأ كيرجع JSON بجوج حقول ثابتة: « error » (رمز آلي مستقر تختبره فالكود ديالك) و« message » (شرح واضح تقدر تعرضه كما هو). الـ402 كيزيد « used » و« limit » و« reason » باش تبني شاشة الكوطا ديالك.

`400`	طلب غير صالح	الرموز: invalid_json (جسم ما ينقراش)، empty_body (جسم فارغ — تأكد ما كاين حتى سطر جديد كيكسر الهيدرز)، missing_client، missing_items، invalid_channel، invalid_phone، invalid_email، invalid_image. الرسالة كتقول بالضبط شنو تصلح.
`401`	مفتاح ناقص أو غير صالح	missing_api_key: زيد الهيدر Authorization: Bearer fk_… · invalid_api_key: مفتاح مجهول أو تلغى بـ« api reset » — طلبو من جديد من التاجر.
`402`	الكوطا وصلات للحد	quota_exceeded: الرد فيه used/limit/reason. عروض الأثمنة ما كتحسبش. التاجر كيطلع للباقة الأعلى بجوج رسائل واتساب.
`403`	حساب موقوف	account_suspended: حساب التاجر موقوف — تواصل مع contact@swiviq.com.
`404`	وثيقة غير موجودة	not_found: ما كاين حتى وثيقة بهاد الرقم فهاد الحساب — كل مفتاح كيشوف غير وثائقو.
`409`	وثيقة ملغاة	cancelled: الوثيقة تلغات (صدر فيها إشعار دائن) — ما بقاش ممكن تعديلها ولا إرسالها. أصدر وحدة جديدة.
`413`	جسم كبير بزاف	body_too_large: 8 ميغا كحد أقصى — نقص من حجم اللوغو أو الطابع قبل الإرسال.
`422`	التعليمة ما تفهمتش	instruction_not_understood: الذكاء الاصطناعي ما قدرش يطبق التعديل بأمان — عاود الصياغة بدقة. حتى شي حاجة ما تبدلات.
`429`	طلبات كثيرة	rate_limited: 60 طلب فالدقيقة لكل مفتاح — بطئ الوتيرة أو دير طابور وعاود.
`500`	خطأ داخلي	internal: عاود المحاولة؛ إلى بقى الخطأ، كتب لـcontact@swiviq.com مع جسم الرد.

الرد

HTTP 402
{
  "error": "quota_exceeded",
  "reason": "trial",
  "used": 2,
  "limit": 2,
  "message": "Quota d'essai atteint (2 factures). Le commerçant peut passer
              au plan supérieur depuis son WhatsApp Fatora."
}

أسئلة الإدماج

شحال كيكلف الـAPI؟

والو زيادة على اشتراك فاتورة ديال التاجر، من التجربة المجانية. فواتير API كتحسب من كوطا الباقة بحال اللي كتملى فالواتساب؛ عروض الأثمنة مجانية وبلا حدود.

شكون عندو المفتاح: أنا (الناشر) ولا المستعمل ديالي؟

كل تاجر عندو المفتاح ديالو، مربوط بحسابو وترقيمو. تطبيقك كيخزن المفتاح اللي كيلصقو المستعمل — ما عندك حتى حساب مركزي تسيرو، وكل زبون كيخلص اشتراكو.

الأثمنة اللي كنرسل TTC — كيفاش ندير؟

زيد « priceIsTtc »: true. فاتورة كتحسب الأساس بلا ضريبة بالقسمة على واحد زائد النسبة، سطر بسطر.

التاجر مقاول ذاتي، بلا TVA؟

النظام الضريبي ديالو مسجل فحسابو وكيفرض راسو على الـAPI: مهما أرسل تطبيقك، الوثائق ديالو كتخرج بلا TVA، بالبيان المناسب.

شنو كيوقع ملي توصل الكوطا للحد؟

الـAPI كيرد 402 مع used وlimit ورسالة جاهزة للعرض. التاجر كيبدل الباقة بجوج رسائل واتساب.