مساعدة

الإضافات (Plugins)

نظرة عامة

يتيح نظام إضافات Iberis لأي مطور إنشاء وحدات إضافية لتعزيز إمكانيات المنصة. الإضافات تصريحية بالكامل: ملف manifest بصيغة JSON يحدد نماذج البيانات والصفحات والقوائم والخطافات والأدوات.

تُقدم الإضافات للمراجعة من قبل فريق Iberis قبل نشرها في السوق. بمجرد الموافقة عليها، يمكن للشركات تثبيتها بنقرة واحدة من صفحة التكاملات.

تتميز الإضافات بنظام متكامل: نماذج بيانات مع CRUD تلقائي، حقول مخصصة على كيانات Iberis الحالية، توليد PDF، مسارات موافقة، وحراس لمنع إجراءات معينة بشروط.

Ce que vous pouvez construire

Voici des exemples concrets de plugins réalisables avec le système :

هيكل Manifest

يحدد ملف manifest بصيغة JSON كل ما يتعلق بالإضافة. المعلومات الأساسية تُدخل عبر نموذج التقديم. يحتوي ملف manifest التقني على الأقسام التالية:

Exemple complet minimal

{
  "models": {
    "task": {
      "numbering": { "prefix": "TSK", "pattern": "{prefix}-{YYYY}-{sequence}" },
      "fields": {
        "title": { "type": "string", "required": true, "label": { "fr": "Titre", "en": "Title" } },
        "description": { "type": "textarea", "label": { "fr": "Description" } },
        "status": { "type": "integer", "default": 0 },
        "amount": { "type": "decimal", "label": { "fr": "Montant", "en": "Amount" } },
        "due_date": { "type": "date", "label": { "fr": "Échéance", "en": "Due date" } },
        "client_id": { "type": "reference", "references": "contacts", "label": { "fr": "Client" } },
        "attachment": { "type": "file", "label": { "fr": "Pièce jointe" } }
      },
      "statuses": {
        "0": { "fr": "Brouillon", "en": "Draft" },
        "1": { "fr": "En cours", "en": "In Progress" },
        "2": { "fr": "Terminé", "en": "Done" },
        "3": { "fr": "Annulé", "en": "Cancelled" }
      }
    }
  },
  "pages": {
    "task_list": {
      "type": "list",
      "model": "task",
      "columns": ["_number", "title", "client_id", "amount", "status", "due_date"]
    },
    "task_form": {
      "type": "form",
      "model": "task",
      "layout": [
        { "row": [{ "field": "title", "col": 8 }, { "field": "status", "col": 4 }] },
        { "row": [{ "field": "client_id", "col": 6 }, { "field": "amount", "col": 6 }] },
        { "row": [{ "field": "due_date", "col": 6 }, { "field": "attachment", "col": 6 }] }
      ]
    }
  },
  "menus": [
    {
      "section": {
        "title": { "fr": "Gestion de tâches", "en": "Task Management" },
        "icon": "fas fa-tasks",
        "items": [
          { "label": { "fr": "Taches", "en": "Tasks" }, "page": "task_list" }
        ]
      }
    }
  ],
  "widgets": {
    "total_tasks": {
      "type": "stats_card",
      "model": "task",
      "aggregate": "COUNT",
      "label": { "fr": "Total tâches", "en": "Total tasks" },
      "icon": "fas fa-tasks",
      "color": "#667eea"
    },
    "total_amount": {
      "type": "stats_card",
      "model": "task",
      "aggregate": "SUM",
      "field": "amount",
      "filter": { "status": 2 },
      "label": { "fr": "Montant termine", "en": "Completed amount" },
      "icon": "fas fa-coins",
      "color": "#10b981"
    },
    "by_status": {
      "type": "chart",
      "chart_type": "donut",
      "model": "task",
      "group_by": "status",
      "aggregate": "COUNT",
      "label": { "fr": "Par statut", "en": "By status" },
      "color": "#667eea"
    }
  },
  "hooks": {},
  "settings": {},
  "extensions": {},
  "guards": {}
}

أنواع الحقول

Chaque model définit ses champs avec un type. Le moteur crée automatiquement les colonnes en base et le formulaire adapté.

Tous les types

"fields": {
  "name":        { "type": "string", "required": true, "max": 100, "label": { "fr": "Nom" } },
  "notes":       { "type": "textarea", "label": { "fr": "Notes" } },
  "quantity":    { "type": "integer", "default": 1 },
  "price":       { "type": "decimal", "precision": 15, "scale": 3 },
  "is_active":   { "type": "boolean", "default": true },
  "start_date":  { "type": "date" },
  "created_at":  { "type": "datetime" },
  "document":    { "type": "file", "label": { "fr": "Document" } },
  "photo":       { "type": "image", "label": { "fr": "Photo" } },
  "category": {
    "type": "select",
    "options": [
      { "value": "a", "label": { "fr": "Catégorie A" } },
      { "value": "b", "label": { "fr": "Catégorie B" } }
    ]
  },
  "client_id": {
    "type": "reference",
    "references": "contacts",
    "label": { "fr": "Client" }
  },
  "related_task_id": {
    "type": "reference",
    "references": "@task",
    "label": { "fr": "Tâche liée" }
  },
  "total_computed": {
    "type": "computed",
    "formula": "quantity * price",
    "label": { "fr": "Total" }
  }
}

Statuses (badges automatiques)

"statuses": {
  "0": { "fr": "Brouillon", "en": "Draft" },
  "1": { "fr": "En attente", "en": "Pending" },
  "2": { "fr": "Approuvé", "en": "Approved" },
  "3": { "fr": "Terminé", "en": "Completed" },
  "4": { "fr": "Rejeté", "en": "Rejected" }
}

Le champ status (integer) devient un select dans le formulaire et un badge coloré dans la liste. Couleurs : 0=warning, 1=info, 2=primary, 3=success, 4=danger.

الصيغ والتعبيرات

Utilisées dans les champs computed, les actions de hooks, et les conditions. Le parseur est un AST récursif sécurisé.

Exemples

// Champ computed - total TTC
"formula": "ROUND(quantity * price * (1 + tax_rate / 100), 3)"

// Condition hook - déclencher si montant > 1000
"conditions": [{ "field": "amount", "greater_than": 1000 }]

// Action hook - créer un record avec formule
"fields": {
  "title": "CONCAT('Commande #', number)",
  "total": "SUM(lines.quantity * lines.price)",
  "days_left": "DATE_DIFF(due_date, TODAY())"
}

// Lookup inter-model
"formula": "LOOKUP(@bom, item_id = id, unit_cost)"

Fonctions disponibles

الخطافات والإجراءات

Les hooks réagissent aux événements et exécutent des actions. Exemple : à chaque facture créée, créer automatiquement un suivi dans votre plugin.

Exemple : créer un record à chaque facture

"hooks": {
  "on_invoice_created": {
    "event": "invoice.created",
    "conditions": [
      { "field": "status", "not_equals": 0 }
    ],
    "actions": [
      {
        "type": "create_record",
        "model": "invoice_tracking",
        "fields": {
          "invoice_id": "id",
          "invoice_number": "invoice_number",
          "amount": "total",
          "status": "0",
          "tracked_at": "NOW()"
        }
      }
    ]
  }
}

Exemple : mouvement de stock + ecriture comptable

"hooks": {
  "on_order_completed": {
    "event": "@order.updated",
    "conditions": [
      { "field": "status", "changed_to": 3 }
    ],
    "actions": [
      {
        "type": "stock_movement",
        "item": "item_id",
        "quantity_formula": "quantity",
        "direction": "out"
      },
      {
        "type": "journal_entry",
        "debit": "601",
        "credit": "401",
        "amount_formula": "total",
        "label_formula": "CONCAT('Plugin order #', number)"
      },
      {
        "type": "send_email",
        "to_formula": "LOOKUP(contacts, id = client_id, email)",
        "subject": "Votre commande est prête",
        "body": "Bonjour, votre commande a été traitée."
      }
    ]
  }
}

Exemple : webhook + appel API externe

"hooks": {
  "notify_external": {
    "event": "payment.received",
    "actions": [
      {
        "type": "webhook",
        "url": "https://mon-erp.com/webhooks/iberis",
        "event_name": "payment.received"
      },
      {
        "type": "api_call",
        "url": "https://api.mon-service.com/sync",
        "method": "POST",
        "headers": { "Authorization": "Bearer MY_TOKEN" },
        "body": { "reference": "payment_number", "amount": "total" },
        "response_mapping": { "external_id": "data.id" },
        "target_model": "sync_log"
      }
    ]
  }
}

Événements disponibles

Pour les événements internes du plugin, préfixez avec @ : @model_name.created, @model_name.updated, @model_name.deleted

Notifications in-app et push

Envoyez des notifications aux utilisateurs depuis vos hooks. Les notifications apparaissent dans la cloche de l'interface, sur l'application mobile (push Firebase), et optionnellement par email.

Exemple : notification à l'approbation

"hooks": {
  "notify_on_approval": {
    "event": "@payment_request.updated",
    "conditions": [
      { "field": "status", "changed_to": 3 }
    ],
    "actions": [
      {
        "type": "send_notification",
        "recipients": "current_user",
        "title": { "fr": "Demande approuvée", "en": "Request approved" },
        "content_formula": "CONCAT('La demande #', number, ' a été approuvée.')",
        "link": {
          "route": "pluginPageRecord",
          "params": {
            "pluginSlug": "mon-plugin",
            "pageName": "request_form",
            "recordId": "hashed_id"
          }
        }
      }
    ]
  }
}

Destinataires

Exemple : notifier tous les managers

{
  "type": "send_notification",
  "recipients": "role",
  "role": "Manager",
  "title": { "fr": "Nouvelle demande de paiement" },
  "content_formula": "CONCAT('Demande #', number, ' - ', total, ' TND')",
  "email": true
}

الرموز المختصرة

Injectez des données plugin dans les PDFs, emails et templates Iberis.

Exemples

// Nombre total de tâches
{{plugin:task-manager:COUNT(task)}}

// Somme des montants des tâches terminées
{{plugin:task-manager:SUM(task.amount)}}

// Champ custom sur une facture (via extensions)
{{plugin:task-manager:project_code}}

// Expression conditionnelle
{{plugin:task-manager:IF(COUNT(task) > 10, "Beaucoup de tâches", "Peu de tâches")}}

امتدادات الكيانات

Ajoutez des champs custom aux entités Iberis existantes. Les champs s'affichent automatiquement dans les formulaires de création/edition.

Exemple : ajouter des champs sur les factures et dépenses

"extensions": {
  "invoice": {
    "custom_fields": {
      "project_code": {
        "type": "string",
        "label": { "fr": "Code projet", "en": "Project code" }
      },
      "is_billable": {
        "type": "boolean",
        "label": { "fr": "Facturable", "en": "Billable" },
        "default": true
      },
      "priority": {
        "type": "select",
        "label": { "fr": "Priorite" },
        "options": [
          { "value": "low", "label": { "fr": "Basse", "en": "Low" } },
          { "value": "medium", "label": { "fr": "Moyenne", "en": "Medium" } },
          { "value": "high", "label": { "fr": "Haute", "en": "High" } }
        ]
      }
    }
  },
  "expense": {
    "custom_fields": {
      "department": {
        "type": "string",
        "label": { "fr": "Departement", "en": "Department" }
      },
      "approved_amount": {
        "type": "decimal",
        "label": { "fr": "Montant approuvé", "en": "Approved amount" }
      }
    }
  }
}

Entités extensibles

أدوات لوحة المعلومات

Les widgets s'affichent en haut de la page liste de votre plugin. Ajoutez "dashboard": true sur un widget pour l'afficher aussi sur le tableau de bord principal de l'entreprise.

Exemple complet

"widgets": {
  "total": {
    "type": "stats_card",
    "model": "task",
    "aggregate": "COUNT",
    "label": { "fr": "Total", "en": "Total" },
    "icon": "fas fa-list",
    "color": "#667eea",
    "dashboard": true
  },
  "completed": {
    "type": "stats_card",
    "model": "task",
    "aggregate": "COUNT",
    "filter": { "status": 2 },
    "label": { "fr": "Terminées", "en": "Completed" },
    "icon": "fas fa-check",
    "color": "#10b981"
  },
  "total_amount": {
    "type": "stats_card",
    "model": "task",
    "aggregate": "SUM",
    "field": "amount",
    "label": { "fr": "Montant total", "en": "Total amount" },
    "icon": "fas fa-coins",
    "color": "#f59e0b"
  },
  "by_status": {
    "type": "chart",
    "chart_type": "donut",
    "model": "task",
    "group_by": "status",
    "aggregate": "COUNT",
    "label": { "fr": "Répartition", "en": "Distribution" },
    "color": "#667eea"
  }
}

Types de graphiques supportés : bar, donut, pie.

ألسنة على الصفحات الموجودة

Ajoutez un onglet dans les pages de synthèse des clients, fournisseurs, articles, ou dans la sidebar des documents (factures, dépenses, etc.). L'onglet affiche les records de votre plugin liés à l'entité.

Exemple : onglet "Deals" sur la fiche client

Le foreign_key doit correspondre à un champ de type reference déclaré dans votre model. C'est ce champ qui fait le lien entre votre record plugin et l'entité Iberis.

// 1. Déclarer le model avec un champ reference vers contacts
"models": {
  "deal": {
    "fields": {
      "title": { "type": "string", "required": true, "label": { "fr": "Titre" } },
      "amount": { "type": "decimal", "label": { "fr": "Montant" } },
      "status": { "type": "integer", "default": 0 },
      "client_id": {
        "type": "reference",
        "references": "contacts",
        "label": { "fr": "Client", "en": "Client" }
      }
    },
    "statuses": {
      "0": { "fr": "Nouveau", "en": "New" },
      "1": { "fr": "En cours", "en": "In progress" },
      "2": { "fr": "Gagné", "en": "Won" }
    }
  }
},

// 2. Déclarer l'onglet qui utilise ce champ comme foreign_key
"tabs": {
  "contact": {
    "label": { "fr": "Deals liés", "en": "Related deals" },
    "model": "deal",
    "foreign_key": "client_id",
    "columns": ["_number", "title", "amount", "status"]
  }
}

Autre exemple : suivi sur les factures

"models": {
  "invoice_tracking": {
    "fields": {
      "invoice_id": { "type": "reference", "references": "invoices" },
      "status": { "type": "integer", "default": 0 },
      "tracked_at": { "type": "date" },
      "notes": { "type": "text" }
    }
  }
},
"tabs": {
  "invoice": {
    "label": { "fr": "Suivi", "en": "Tracking" },
    "model": "invoice_tracking",
    "foreign_key": "invoice_id",
    "columns": ["status", "tracked_at", "notes"]
  }
}

Entités supportées

الإعدادات

Chaque entreprise peut configurer votre plugin via la page Paramètres. Les valeurs sont accessibles dans les hooks et formules.

Exemple

"settings": {
  "api_key": {
    "type": "string",
    "label": { "fr": "Clé API", "en": "API Key" },
    "help": { "fr": "Votre clé d'authentification externe", "en": "Your external auth key" },
    "default": ""
  },
  "mode": {
    "type": "select",
    "label": { "fr": "Mode" },
    "default": "production",
    "options": [
      { "value": "sandbox", "label": { "fr": "Test", "en": "Sandbox" } },
      { "value": "production", "label": { "fr": "Production" } }
    ]
  },
  "auto_sync": {
    "type": "boolean",
    "label": { "fr": "Synchronisation automatique", "en": "Auto sync" },
    "default": true
  },
  "daily_limit": {
    "type": "number",
    "label": { "fr": "Limite journalière", "en": "Daily limit" },
    "default": 100
  },
  "notes": {
    "type": "textarea",
    "label": { "fr": "Notes de configuration", "en": "Config notes" },
    "default": ""
  }
}

إجراءات على المستندات

Ajoutez des boutons dans le menu déroulant "Action" des documents Iberis (factures, dépenses, devis, etc.) et dans la page formulaire. Trois types d'actions sont disponibles :

Exemple : bouton "Créer une demande de paiement" sur les dépenses

// 1. Le model avec une référence vers expenses
"models": {
  "payment_request": {
    "fields": {
      "title": { "type": "string", "required": true },
      "expense_id": { "type": "reference", "references": "expenses" },
      "amount": { "type": "decimal" },
      "status": { "type": "integer", "default": 0 }
    }
  }
},

// 2. La page formulaire
"pages": {
  "request_form": { "type": "form", "model": "payment_request" }
},

// 3. L'action qui apparaît dans le dropdown de chaque dépense
"actions": {
  "create_payment_request": {
    "entity_type": "expense",
    "label": { "fr": "Créer demande de paiement", "en": "Create payment request" },
    "icon": "fas fa-file-invoice",
    "color": "primary",
    "type": "create_record",
    "target_page": "request_form",
    "prefill": {
      "expense_id": "_id",
      "amount": "total"
    }
  }
}

Exemple : générer un PDF depuis une facture

"actions": {
  "generate_tracking_pdf": {
    "entity_type": "invoice",
    "label": { "fr": "Fiche de suivi PDF", "en": "Tracking sheet PDF" },
    "icon": "fas fa-file-pdf",
    "color": "danger",
    "type": "generate_pdf",
    "pdf_template": "tracking_sheet"
  }
}

Exemple : naviguer vers une page du plugin

"actions": {
  "view_deals": {
    "entity_type": "contact",
    "label": { "fr": "Voir les deals", "en": "View deals" },
    "icon": "fas fa-handshake",
    "color": "info",
    "type": "navigate",
    "target_page": "deals_list"
  }
}

Entités supportées

Couleurs disponibles

حراس الإجراءات

تسمح الحراس لإضافتك بمنع إجراءات Iberis إذا لم تتحقق شروط معينة.

Exemple : bloquer un paiement sans demande approuvée

"guards": {
  "require_payment_request": {
    "event": "payment.before_create",
    "conditions": [],
    "check": {
      "type": "require_record",
      "model": "payment_request",
      "where": {
        "expense_id": "hashed_expense_id"
      },
      "status": 3
    },
    "message": {
      "fr": "Un paiement ne peut être effectué sans demande de paiement approuvée.",
      "en": "Payment cannot be made without an approved payment request."
    }
  }
}

Exemple : bloquer la suppression si champ non vide

"guards": {
  "prevent_delete_if_linked": {
    "event": "invoice.before_delete",
    "check": {
      "type": "require_field",
      "field": "external_ref"
    },
    "message": {
      "fr": "Cette facture est liée à un système externe et ne peut pas être supprimée."
    }
  }
}

Exemple : bloquer la validation avec expression

"guards": {
  "min_amount": {
    "event": "expense.before_validate",
    "check": {
      "type": "expression",
      "expression": "total >= 10"
    },
    "message": {
      "fr": "Le montant minimum pour valider une dépense est de 10 TND."
    }
  }
}

Événements guard disponibles

قوالب PDF

أنشئ مستندات PDF مخصصة من بيانات نماذجك باستخدام HTML/CSS.

Exemple : demande de paiement PDF

"pdf_templates": {
  "demande_paiement": {
    "model": "payment_request",
    "format": "A4",
    "orientation": "P",
    "margin_top": 15,
    "margin_bottom": 15,
    "margin_left": 10,
    "margin_right": 10,
    "data": {
      "lines": {
        "model": "@request_line",
        "type": "list",
        "where": { "request_id": "id" },
        "order_by": "created_at"
      },
      "bank": {
        "model": "company_banks",
        "type": "single",
        "where": { "id": "bank_id" }
      }
    },
    "css": "body { font-family: Arial, sans-serif; font-size: 12px; } .header { text-align: center; margin-bottom: 20px; } .title { font-size: 18px; font-weight: bold; } table { width: 100%; border-collapse: collapse; margin: 15px 0; } th, td { border: 1px solid #ddd; padding: 8px; text-align: left; } th { background: #f5f5f5; } .signatures { display: flex; justify-content: space-between; margin-top: 40px; } .sig-block { text-align: center; width: 30%; } .sig-line { border-top: 1px solid #333; margin-top: 50px; padding-top: 5px; }",
    "html": "<div class='header'><div class='title'>DEMANDE DE PAIEMENT</div><div>N: {{number}} - Date: {{date}}</div><div>{{company.title}}</div></div><table><tr><th>#</th><th>Description</th><th>Montant</th></tr>{{#each related.lines}}<tr><td>{{_index}}</td><td>{{item.description}}</td><td>{{item.amount}} TND</td></tr>{{/each}}</table><p><strong>Total: {{total}} TND</strong></p><p>Banque: {{related.bank.title}} - RIB: {{related.bank.rib}}</p><div class='signatures'><div class='sig-block'><div class='sig-line'>Charge des moyens généraux</div></div><div class='sig-block'><div class='sig-line'>Direction Générale</div></div><div class='sig-block'><div class='sig-line'>Direction Financière</div></div></div>"
  }
}

Variables simples

Formatage

// Formater un nombre (3 décimales par défaut)
{{number:amount:2}}         → 1 500.00
{{number:item.price:3}}     → 25.500

// Formater une date (format PHP)
{{date:created_at:d/m/Y}}  → 19/03/2026
{{date:item.due:Y-m-d}}    → 2026-03-19

// Somme d'un champ dans une collection
{{sum:related.lines.amount:2}}   → 4 250.00

// Nombre d'éléments
{{count:related.lines}}          → 5

// Image dynamique (logo, signature)
{{image:company.logo:200}}       → <img> 200px de large
{{image:company.stamp:150:150}}  → <img> 150x150px

Conditions

// Afficher un bloc si la condition est vraie
{{#if status == 3}}
  <div class="badge-success">APPROUVÉ</div>
{{#else}}
  <div class="badge-warning">EN ATTENTE</div>
{{/if}}

// Masquer si la condition est vraie
{{#unless total == 0}}
  <p>Total: {{number:total:3}} TND</p>
{{/unless}}

// Conditions dans les boucles
{{#each related.lines}}
  <tr>
    <td>{{item.description}}</td>
    <td>{{number:item.amount:2}}</td>
    {{#if item.status == 1}}
      <td class="text-success">Payé</td>
    {{#else}}
      <td class="text-danger">Impayé</td>
    {{/if}}
  </tr>
{{/each}}

Boucles

{{#each related.lines}}
  <tr>
    <td>{{_index}}</td>
    <td>{{item.description}}</td>
    <td>{{number:item.quantity:0}}</td>
    <td>{{number:item.unit_price:3}}</td>
    <td>{{number:item.line_total:3}}</td>
  </tr>
{{/each}}

Opérateurs de comparaison

API

// Générer le PDF (retourne le chemin du fichier)
POST /api/private/company/{companyId}/plugins/{slug}/pdf/{templateName}/{recordId}

// Télécharger directement le PDF
GET /api/private/company/{companyId}/plugins/{slug}/pdf/{templateName}/{recordId}/download

Modèles personnalisés (documents Iberis)

À ne pas confondre avec pdf_templates (qui sert à générer des PDF à partir de vos models de plugin), la section custom_templates permet d'installer des modèles HTML/CSS qui s'ajoutent au sélecteur de modèles natif d'Iberis pour les documents du cœur Iberis (factures, devis, livraisons, etc.). C'est le moyen idéal pour vendre des packs de designs premium.

Cycle de vie

Types de documents supportés

La valeur de document_type doit être l'une des suivantes (chaîne ou tableau) :

Structure du manifest

{
  "plugin": {
    "id": "premium-invoice-templates",
    "name": { "fr": "Modèles de Factures Premium" },
    "description": { "fr": "3 modèles de factures conçus professionnellement." },
    "version": "1.0.0",
    "category": "finance",
    "module": "finance"
  },
  "custom_templates": [
    {
      "name": "Tribune",
      "document_type": ["invoice", "estimate", "expense"],
      "css_content": "body { font-family: Helvetica; ... }",
      "html_content": "<div class='wrap'>...</div>",
      "preview_image": null
    },
    {
      "name": "Boutique",
      "document_type": "invoice",
      "css_content": "body { font-family: Arial; ... }",
      "html_content": "<div class='bar'>...</div>"
    }
  ]
}

Champs d'une entrée

Variables disponibles dans le HTML/CSS

Le moteur de rendu utilise un remplacement {{variable.path}} simple (pas de Handlebars complet — pas de {{#each}} ni de {{#if}} dans les custom_templates). Les tableaux dynamiques sont insérés via des macros spéciales.

// Entreprise
{{company.name}}             {{company.address}}        {{company.phone}}
{{company.email}}            {{company.fiscal_id}}      {{company.website}}
{{company.city}}             {{company.postal_code}}    {{company.country}}
{{company.logo}}             // se rend en <img> auto-dimensionné
{{company.stamp}}            // se rend en <img> auto-dimensionné

// Document (facture, devis, etc.)
{{document.number}}          {{document.date}}          {{document.due_date}}
{{document.object}}          {{document.reference}}     {{document.currency}}
{{document.subtotal}}        {{document.tax_total}}     {{document.discount}}
{{document.total}}           {{document.paid}}          {{document.balance}}
{{document.credits}}         {{document.withholding}}   {{document.total_words}}
{{document.notes}}           {{document.conditions}}

// Contact (client / fournisseur)
{{contact.name}}             {{contact.organisation}}   {{contact.address}}
{{contact.phone}}            {{contact.email}}          {{contact.fiscal_id}}
{{contact.city}}             {{contact.postal_code}}    {{contact.country}}
{{contact.billing_address}}  {{contact.delivery_address}}

// Banque (depuis la facture)
{{bank.name}}                {{bank.iban}}              {{bank.bic}}
{{bank.rib}}

// Date
{{date.today}}               {{date.year}}

// Tableaux dynamiques (rendus en <table> complet)
{{items.table}}              // lignes du document
{{taxes.table}}              // récapitulatif TVA
{{payment.table}}            // historique des paiements
{{inventory.table}}          // mouvements d'inventaire
{{journal_entry.table}}      // écritures comptables
{{disbursement.table}}       // détails d'un décaissement

Masquage automatique des lignes vides

Le moteur de rendu masque automatiquement les lignes ou éléments dont la seule valeur dynamique est vide — aucun besoin de CSS :empty ou de logique conditionnelle. Écrivez simplement votre libellé et sa variable dans la même structure et le moteur fait le ménage.

Exemple complet d'une entrée

Cet exemple utilise un seul document_type en tableau pour cibler facture, devis et facture fournisseur en une seule entrée. Notez l'usage de vraies balises <table> avec des attributs width HTML — mPDF rend les tables natives bien plus fiablement que les divs avec display:table-cell. Aucun CSS :empty n'est nécessaire : les lignes de totaux dont la variable est vide (remise, retenue, crédits…) disparaissent d'elles-mêmes grâce au masquage automatique décrit plus haut.

{
  "name": "Tribune",
  "document_type": ["invoice", "estimate", "expense"],
  "css_content": "body{font-family:Helvetica,Arial,sans-serif;font-size:10pt;color:#0a0a0a} .head{background:#0a0a0a;color:#fff;padding:24px} .num{font-size:32pt;font-weight:bold;letter-spacing:-1px} .row td{padding:8px 0;border-bottom:1px solid #eee} .row .l{color:#737373;text-transform:uppercase;font-size:8pt;letter-spacing:1px;padding-right:14px} .row .v{text-align:right;font-weight:600} .grand td{border-top:2px solid #0a0a0a;font-size:14pt;font-weight:bold}",
  "html_content": "<table width='100%' cellpadding='0' cellspacing='0'><tr><td class='head'><strong>{{company.name}}</strong> &middot; MF {{company.fiscal_id}}<br><span class='num'>{{document.number}}</span></td></tr></table><table width='100%' cellpadding='0' cellspacing='0'><tr><td>Émise à</td><td>{{contact.name}}</td></tr><tr><td>Organisation</td><td>{{contact.organisation}}</td></tr><tr><td>Adresse</td><td>{{contact.address}}</td></tr><tr><td>Date</td><td>{{document.date}}</td></tr><tr><td>Échéance</td><td>{{document.due_date}}</td></tr></table>{{items.table}}{{taxes.table}}<table width='100%' cellpadding='0' cellspacing='0'><tr><td width='50%'></td><td width='50%'><table width='100%' cellpadding='0' cellspacing='0'><tr class='row'><td class='l'>Sous-total HT</td><td class='v'>{{document.subtotal}}</td></tr><tr class='row'><td class='l'>Remise</td><td class='v'>{{document.discount}}</td></tr><tr class='row'><td class='l'>TVA</td><td class='v'>{{document.tax_total}}</td></tr><tr class='row'><td class='l'>Retenue à la source</td><td class='v'>{{document.withholding}}</td></tr><tr class='row'><td class='l'>Avoirs appliqués</td><td class='v'>{{document.credits}}</td></tr><tr class='row grand'><td class='l'>Total TTC</td><td class='v'>{{document.total}}</td></tr></table></td></tr></table><p><em>{{document.total_words}}</em></p><table width='100%' cellpadding='0' cellspacing='0'><tr><td>Banque</td><td>{{bank.name}}</td></tr><tr><td>RIB</td><td>{{bank.rib}}</td></tr></table>{{company.stamp}}"
}

Validation à la soumission

مسارات الموافقة

أضف مسار تحقق على نماذجك مع خطوات موافقة وأدوار محددة.

Exemple : circuit DG → DFC

"models": {
  "payment_request": {
    "fields": {
      "title": { "type": "string", "required": true },
      "total": { "type": "decimal" },
      "status": { "type": "integer", "default": 0 },
      "expense_id": { "type": "reference", "references": "expenses" }
    },
    "statuses": {
      "0": { "fr": "Brouillon", "en": "Draft" },
      "1": { "fr": "Soumis", "en": "Submitted" },
      "2": { "fr": "Approuvé DG", "en": "CEO Approved" },
      "3": { "fr": "Valide DFC", "en": "CFO Validated" },
      "4": { "fr": "Rejeté", "en": "Rejected" }
    },
    "approval_workflow": {
      "approval_mode": "sequential",
      "steps": [
        {
          "label": { "fr": "Validation Direction Générale", "en": "CEO Approval" },
          "role": "manager"
        },
        {
          "label": { "fr": "Validation Direction Financière", "en": "CFO Approval" },
          "role": "accountant"
        }
      ],
      "on_approve": { "set_status": 3 },
      "on_reject": { "set_status": 4 }
    }
  }
}

Modes d'approbation

API

// Consulter l'état du workflow
GET /api/private/company/{companyId}/plugins/{slug}/{model}/{recordId}/approval

// Approuver (status=1) ou rejeter (status=2) une étape
POST /api/private/company/{companyId}/plugins/{slug}/{model}/{recordId}/approval
Body: { "step_index": 0, "status": 1, "comment": "OK" }

محولات (تحويل البيانات)

Les mutators permettent de modifier automatiquement les données d'un document Iberis avant sa sauvegarde. Contrairement aux guards qui bloquent, les mutators transforment.

Exemple : forcer une valeur par défaut

"mutators": {
  "default_payment_terms": {
    "event": "invoice.before_save",
    "default": {
      "conditions": "Paiement à 30 jours"
    }
  }
}

Exemple : calculer et forcer une valeur

"mutators": {
  "auto_reference": {
    "event": "expense.before_save",
    "conditions": [
      { "field": "status", "equals": 0 }
    ],
    "set": {
      "reference": "CONCAT('REF-', order_number)"
    }
  }
}

Événements disponibles

صفحات لوحة المعلومات

Créez des pages qui affichent des widgets et des tableaux de données de plusieurs models en une seule vue. Idéal pour les tableaux de bord, les rapports, ou les vues d'ensemble.

Exemple

"pages": {
  "crm_dashboard": {
    "type": "dashboard",
    "title": { "fr": "Tableau de bord CRM", "en": "CRM Dashboard" },
    "widgets": ["total_deals", "won_deals", "deals_by_status"],
    "sections": [
      {
        "model": "deal",
        "title": { "fr": "Deals récents", "en": "Recent deals" },
        "columns": ["_number", "title", "amount", "status"],
        "limit": 5,
        "filter": {}
      },
      {
        "model": "activity",
        "title": { "fr": "Dernières activités", "en": "Latest activities" },
        "columns": ["_number", "type", "description", "date"],
        "limit": 10
      }
    ]
  }
}

Structure

استيراد / تصدير CSV

Chaque page liste d'un plugin dispose automatiquement de boutons d'export et d'import CSV. Aucune configuration n'est nécessaire dans le manifest.

Export

Import

API

// Export CSV
GET /api/private/company/{companyId}/plugins/{slug}/{model}/export
→ Retourne un fichier CSV en téléchargement

// Import CSV
POST /api/private/company/{companyId}/plugins/{slug}/{model}/import
Body: FormData avec champ "file" (CSV)
→ Retourne: { imported: 15, errors: ["Line 3: column count mismatch"] }

علاقات رئيسية-تفصيلية

Créez des relations parent-enfant entre vos models. Par exemple, une commande avec des lignes de commande, ou une demande de paiement avec des factures liées. Les lignes enfant sont éditables directement dans le formulaire du parent.

Exemple : commande avec lignes

"models": {
  "order": {
    "numbering": { "prefix": "CMD", "pattern": "{prefix}-{YYYY}-{sequence}" },
    "fields": {
      "title": { "type": "string", "required": true, "label": { "fr": "Titre" } },
      "client_id": { "type": "reference", "references": "contacts", "label": { "fr": "Client" } },
      "date": { "type": "date", "label": { "fr": "Date" } },
      "status": { "type": "integer", "default": 0 },
      "total": {
        "type": "computed",
        "formula": "SUM(order_line.quantity * order_line.unit_price)",
        "label": { "fr": "Total" }
      }
    },
    "statuses": {
      "0": { "fr": "Brouillon" },
      "1": { "fr": "Confirmée" },
      "2": { "fr": "Livrée" }
    }
  },
  "order_line": {
    "label": { "fr": "Lignes de commande", "en": "Order lines" },
    "parent": {
      "model": "order",
      "foreign_key": "order_id"
    },
    "fields": {
      "order_id": { "type": "reference", "references": "@order" },
      "description": { "type": "string", "required": true, "label": { "fr": "Description" } },
      "quantity": { "type": "integer", "default": 1, "label": { "fr": "Quantité" } },
      "unit_price": { "type": "decimal", "label": { "fr": "Prix unitaire" } },
      "line_total": {
        "type": "computed",
        "formula": "quantity * unit_price",
        "label": { "fr": "Total ligne" }
      }
    }
  }
}

Comportement

Déclaration

Autre exemple : demande de paiement avec factures liées

"models": {
  "payment_request": {
    "fields": {
      "title": { "type": "string", "required": true },
      "total": { "type": "computed", "formula": "SUM(request_line.amount)" },
      "status": { "type": "integer", "default": 0 }
    }
  },
  "request_line": {
    "label": { "fr": "Factures liées", "en": "Linked invoices" },
    "parent": { "model": "payment_request", "foreign_key": "request_id" },
    "fields": {
      "request_id": { "type": "reference", "references": "@payment_request" },
      "expense_id": { "type": "reference", "references": "expenses", "label": { "fr": "Facture" } },
      "amount": { "type": "decimal", "label": { "fr": "Montant" } },
      "description": { "type": "string", "label": { "fr": "Description" } }
    }
  }
}

الصلاحيات حسب الدور

Contrôlez l'accès aux fonctionnalités de votre plugin par rôle d'utilisateur. Par défaut, 4 permissions sont créées automatiquement : canRead, canCreate, canUpdate, canDelete.

Permissions par défaut

Si vous ne déclarez pas de section permissions, les 4 permissions standard sont utilisées. Elles sont automatiquement ajoutées au rôle "Propriétaire" lors de l'installation.

// Implicite (pas besoin de le déclarer) :
"permissions": ["canRead", "canCreate", "canUpdate", "canDelete"]

// Les clés générées seront :
// plugin:mon-plugin:canRead
// plugin:mon-plugin:canCreate
// plugin:mon-plugin:canUpdate
// plugin:mon-plugin:canDelete

Permissions personnalisées

"permissions": [
  "canRead",
  "canCreate",
  "canUpdate",
  "canDelete",
  "canExport",
  "canApprove",
  "canManageSettings"
]

Comportement

Utiliser dans les menus

"menus": [{
  "section": {
    "title": { "fr": "Mon plugin" },
    "items": [
      {
        "label": { "fr": "Liste" },
        "page": "list_page",
        "permission": "canRead"
      },
      {
        "label": { "fr": "Paramètres" },
        "page": "settings_page",
        "permission": "canManageSettings"
      }
    ]
  }
}]

Si permission n'est pas déclaré sur un item de menu, canRead est utilisé par défaut.

الحدود والأمان

Sécurité