المؤسسات

كل المسارات أدناه تتطلب جلسة مدير كونكت وباقة partner-connect-*.

تتضمن الإجابة المؤسسات المنشأة والحسابات المربوطة، وآخر حالة للختم وTTN، وhasLogo وinvoicingSuspendedAt وtaxIdLocked وtaxIdLockReason، وعدد المؤسسات النشطة والسقف والحصة الشهرية وطلبات الربط. شعار base64 ليس في القائمة.

القراءة

GET /api/partner/organizations/{childOrgId}

نفس البطاقة الموجودة في القائمة، مع logoBase64. taxIdLocked يساوي true أو false. taxIdLockReason يساوي sandbox (هوية المحاكاة) أو ttn_submitted (أُرسلت فاتورة إلى TTN) أو null إذا كان المعرّف لا يزال قابلاً للتعديل.

الإنشاء

POST /api/partner/organizations
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "شركة العميل",
  "taxId": "1234567A",
  "managerEmail": "gerant@client.tn",
  "phone": "71111222",
  "street": "شارع الحبيب بورقيبة",
  "city": "تونس",
  "postalCode": "1000",
  "ttnLogin": "login-ttn",
  "ttnPassword": "secret-ttn",
  "sealAlias": "alias-sceau",
  "sealPin": "pin-sceau"
}

تنشئ فاتورة المؤسسة التابعة، تنسخ اشتراك كونكت، وتمنح الفوترة (invoice:read وinvoice:write وttn:submit وseal:sign). إذا أُرسلت بيانات TTN أو الختم، تنطلق الاختبارات فورًا.

الاسم وبريد المدير والهاتف والعنوان إلزامية. logoBase64 اختياري: data URL من نوع png أو jpeg أو gif أو webp، حوالي 500 كيلوبايت. في الصندوق الرملي تحمل إجابة الإنشاء taxIdLocked: true وtaxIdLockReason: "sandbox".

تحديث البطاقة

PATCH /api/partner/organizations/{childOrgId}

حقول اختيارية، واحد على الأقل: name وtaxId وmanagerEmail وphone وstreet وcity وpostalCode وlogoBase64. الحقل الغائب لا يتغير. logoBase64: null يحذف الشعار.

للمؤسسة المنشأة فقط. الحساب المربوط يجيب 409 USE_DETACH_OTP. المؤسسة المؤرشفة تجيب 409 CHILD_ARCHIVED.

إذا كان taxIdLocked صحيحًا، معرّف آخر يجيب 409 TAX_ID_LOCKED مع نفس reason الذي في GET. في الصندوق الرملي لا يتغير المعرّف: تسجيل TTN واسم SEAL هما هذا المعرّف. في الإنتاج يُقفل بعد إيداع TTN. الاسم والعنوان والهاتف والبريد والشعار تبقى قابلة للتعديل.

الإيقاف

POST /api/partner/organizations/{childOrgId}/pause
POST /api/partner/organizations/{childOrgId}/resume

الإيقاف يرفض إنشاء الفاتورة وتوقيعها وإرسالها (409 INVOICING_SUSPENDED)، بما في ذلك الصندوق الرملي. تبقى المؤسسة ضمن السقف والقراءة مفتوحة. الاستئناف يعيد invoicingSuspendedAt إلى null. الأرشفة أدناه هي الحذف: تحرّر السقف.

الختم وTTN

PATCH /api/partner/organizations/{childOrgId}/credentials

الحقول الغائبة لا تُمسح. لا يُعاد ttnPassword ولا sealPin بوضوح.

إعادة الاختبار:

POST /api/partner/organizations/{childOrgId}/test-ttn
POST /api/partner/organizations/{childOrgId}/test-seal

تُحفظ آخر نتيجة على المؤسسة (ttnLastCredentialsOk وsealLastTestOk).

الأرشفة

POST /api/partner/organizations/{childOrgId}/archive

للمؤسسة التي أنشأها الشريك فقط. حساب fatoora.tn المربوط لا يُؤرشف بهذا المسار: المالك يوقف الربط من حسابه (USE_DETACH_OTP). انظر الربط.

أخطاء الإنشاء

الرمز	HTTP	المعنى
`TAX_ID_EXISTS`	409	حساب fatoora.tn موجود. لا تُعد إنشاءه: اربطه. الإجابة تسرد `organizations`.
`ALREADY_LINKED`	409	المؤسسة موجودة أصلًا في محفظتك.
`NOT_LINKABLE`	409	المعرّف موجود ولا يمكن إنشاؤه ولا ربطه. اقرأ `reason`.
`CONNECT_ORG_LIMIT`	409	بلغ سقف المؤسسات.
`CONNECT_PLAN_REQUIRED`	403	الحساب ليس باقة كونكت.
`NOT_ALLOWED`	403	للمالك أو المدير فقط.
`TAX_ID_LOCKED`	409	لم يعد المعرّف قابلًا للتغيير. `reason`: `sandbox` أو `ttn_submitted`.
`INVOICING_SUSPENDED`	409	المؤسسة متوقفة. استأنفها قبل الفوترة.
`CHILD_ARCHIVED`	409	مؤسسة مؤرشفة: البطاقة والإيقاف لم يعودا متاحين.
`LOGO_INVALID`	400	يجب أن يكون الشعار data URL من نوع PNG أو JPEG أو GIF أو WebP.
`LOGO_TOO_LARGE`	400	الشعار كبير جدًا (حوالي 500 كيلوبايت).

قيم reason مع NOT_LINKABLE:

own_child — موجودة أصلًا بين مؤسساتك.
managed_elsewhere — يديرها كونكت آخر أو مكتب محاسبة.
partner_or_cabinet — حساب شريك أو مكتب، وليس شركة fatoora.tn عادية.

القائمة​

القراءة​

الإنشاء​

تحديث البطاقة​

الإيقاف​

الختم وTTN​

الأرشفة​

أخطاء الإنشاء​

القائمة