Activepieces est une plateforme d'automatisation de workflows open-source sous licence MIT qui gagne rapidement du terrain auprès des équipes arabophones et des entreprises de la région MENA. Contrairement à de nombreux outils d'automatisation qui facturent à la tâche ou à l'exécution, Activepieces peut être entièrement auto-hébergé sans coût marginal. Et contrairement à n8n — dont le contenu arabe pour débutants est omniprésent — Activepieces est TypeScript-first de bout en bout : chaque intégration (appelée piece) est construite et typée avec le même TypeScript que vous écrivez déjà.

Dans ce tutoriel, vous allez :

Auto-héberger Activepieces avec Docker Compose en moins de 10 minutes
Créer votre premier flow reliant Google Sheets à WhatsApp
Développer une pièce TypeScript personnalisée avec le SDK @activepieces/pieces-framework
Déployer un cas réel MENA : un calculateur de délai de déclaration ZATCA qui envoie automatiquement des rappels WhatsApp en arabe

Prérequis

Avant de commencer, assurez-vous de disposer de :

Docker et Docker Compose installés
Node.js 20 ou supérieur avec npm
Un serveur ou une machine locale avec au moins 2 Go de RAM
Un compte WhatsApp Business ou un accès au WhatsApp Cloud API de Meta
Des bases en TypeScript (async/await, interfaces, génériques)

Qu'est-ce qu'Activepieces ?

Activepieces est une plateforme d'automatisation visuelle (drag-and-drop). Chaque automatisation s'appelle un flow et se compose de :

Un déclencheur (Trigger) — ce qui lance le flow (un webhook, un planning cron, ou un événement applicatif)
Des actions (Actions) — ce qui se passe ensuite (envoyer un message, mettre à jour une base de données, appeler une API)

Chaque déclencheur ou action est une piece — l'unité de base d'intégration dans Activepieces. Il existe plus de 400 pièces intégrées couvrant Google Workspace, Slack, WhatsApp, Notion, PostgreSQL, et bien d'autres.

Pourquoi Activepieces pour les développeurs MENA ?

Fonctionnalité	Activepieces	n8n	Zapier
Licence	MIT (gratuit pour toujours)	Fair-code (restreinte)	SaaS uniquement
Auto-hébergement	Oui	Oui	Non
SDK en TypeScript	Oui (natif)	JS/TS	Pas de SDK
Tarification à la tâche	Non	Non	Oui
Interface en arabe	Oui	Non	Non

Activepieces est le choix pragmatique quand vous avez besoin de souveraineté totale sur les données, d'une extension TypeScript-native et d'une liberté par rapport à la facturation à l'usage.

Étape 1 : Auto-hébergement avec Docker

Créez un répertoire de déploiement :

mkdir activepieces-deploy
cd activepieces-deploy

Créez un fichier docker-compose.yml :

version: "3"
services:
  activepieces:
    image: activepieces/activepieces:latest
    ports:
      - "8080:80"
    depends_on:
      - postgres
      - redis
    environment:
      - AP_DB_TYPE=POSTGRES
      - AP_POSTGRES_DATABASE=activepieces
      - AP_POSTGRES_HOST=postgres
      - AP_POSTGRES_PORT=5432
      - AP_POSTGRES_USERNAME=activepieces
      - AP_POSTGRES_PASSWORD=mot_de_passe_fort_ici
      - AP_REDIS_URL=redis://redis:6379
      - AP_ENCRYPTION_KEY=cle_hex_32_caracteres_ici
      - AP_JWT_SECRET=secret_jwt_ici
      - AP_FRONTEND_URL=http://localhost:8080
      - AP_SIGN_UP_ENABLED=true
      - AP_TELEMETRY_ENABLED=false
    volumes:
      - activepieces_data:/root/.activepieces
 
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=activepieces
      - POSTGRES_USER=activepieces
      - POSTGRES_PASSWORD=mot_de_passe_fort_ici
    volumes:
      - postgres_data:/var/lib/postgresql/data
 
  redis:
    image: redis:7
    volumes:
      - redis_data:/data
 
volumes:
  activepieces_data:
  postgres_data:
  redis_data:

Générez une clé de chiffrement sécurisée de 32 caractères :

openssl rand -hex 16

Remplacez cle_hex_32_caracteres_ici par la sortie et définissez un AP_JWT_SECRET robuste. Démarrez ensuite la stack :

docker compose up -d

Après environ 60 secondes, ouvrez http://localhost:8080 dans votre navigateur et créez votre compte administrateur.

Étape 2 : Premier Flow — Notifications WhatsApp depuis Google Sheets

Ce flow se déclenche lorsqu'une nouvelle ligne est ajoutée dans un Google Sheet (par exemple, un formulaire de demande client) et envoie un message WhatsApp à votre équipe.

Dans le tableau de bord Activepieces :

Cliquez sur New Flow et nommez-le "Notification nouvelle demande"
Cliquez sur Trigger → recherchez Google Sheets → sélectionnez New Row Added
Connectez votre compte Google, puis choisissez le tableur et la feuille cibles
Cliquez sur le bouton + pour ajouter une action
Recherchez WhatsApp Business Cloud → sélectionnez Send Text Message
Dans le champ message, mappez les colonnes de la ligne — exemple : "Nouvelle demande de [Nom] — Tél : [Téléphone]"
Cliquez sur Test Step pour chaque étape afin de valider les connexions
Activez le flow en basculant le commutateur sur Active

Votre flow est maintenant actif. Aucun code écrit, aucune gestion de serveur supplémentaire.

Étape 3 : Créer une Pièce TypeScript Personnalisée

Les pièces intégrées couvrent la plupart des cas d'usage, mais les pièces personnalisées vous permettent de connecter n'importe quelle API propre à votre marché ou secteur. C'est là que le SDK TypeScript-first d'Activepieces brille.

Mise en place de l'environnement de développement

Clonez le monorepo Activepieces :

git clone https://github.com/activepieces/activepieces.git
cd activepieces
npm install

Générez une nouvelle pièce avec le CLI :

npm run create-piece

Entrez zatca-reminder comme nom. Le CLI génère cette structure :

packages/pieces/custom/zatca-reminder/
├── src/
│   ├── index.ts
│   └── lib/
│       ├── actions/
│       │   └── get-next-deadline.ts
│       └── triggers/
├── package.json
└── tsconfig.json

Point d'entrée de la pièce

Ouvrez src/index.ts :

import { createPiece, PieceAuth } from '@activepieces/pieces-framework';
import { getNextDeadlineAction } from './lib/actions/get-next-deadline';
 
export const zatcaReminder = createPiece({
  displayName: 'ZATCA Reminder',
  auth: PieceAuth.None(),
  minimumSupportedRelease: '0.20.0',
  logoUrl: 'https://your-cdn.com/zatca-logo.png',
  authors: ['your-name'],
  actions: [getNextDeadlineAction],
  triggers: [],
});

Aucune authentification n'est nécessaire ici car cette pièce effectue uniquement des calculs de dates en local. Pour les pièces qui appellent des APIs externes, utilisez PieceAuth.SecretText() ou PieceAuth.CustomAuth().

Construire l'action : Calculateur de délai ZATCA

Remplacez le contenu de src/lib/actions/get-next-deadline.ts :

import {
  createAction,
  Property,
} from '@activepieces/pieces-framework';
 
export const getNextDeadlineAction = createAction({
  name: 'get_next_deadline',
  displayName: 'Calculer la prochaine échéance ZATCA',
  description:
    "Calcule la prochaine date limite de dépôt de la déclaration TVA ou de la facture électronique auprès de la ZATCA en Arabie Saoudite.",
  props: {
    filingPeriod: Property.StaticDropdown({
      displayName: "Période de déclaration",
      description: "L'entreprise dépose-t-elle mensuellement ou trimestriellement ?",
      required: true,
      options: {
        options: [
          { label: "Mensuelle", value: "monthly" },
          { label: "Trimestrielle", value: "quarterly" },
        ],
      },
    }),
    referenceDate: Property.ShortText({
      displayName: "Date de référence (YYYY-MM-DD)",
      description: "Date de base pour le calcul. Laissez vide pour utiliser aujourd'hui.",
      required: false,
    }),
  },
 
  async run(context) {
    const { filingPeriod, referenceDate } = context.propsValue;
 
    const base = referenceDate ? new Date(referenceDate) : new Date();
    const year = base.getFullYear();
    const month = base.getMonth(); // 0-indexé
 
    let deadlineDate: Date;
 
    if (filingPeriod === "monthly") {
      // Déclarants mensuels : dépôt avant la fin du mois suivant
      deadlineDate = new Date(year, month + 2, 0);
    } else {
      // Déclarants trimestriels : T1 (jan-mars) échéance 30 avril, etc.
      const quarter = Math.floor(month / 3);
      const deadlineMonth = (quarter + 1) * 3;
      deadlineDate = new Date(year, deadlineMonth + 1, 0);
    }
 
    const formatted = deadlineDate.toISOString().split("T")[0];
    const msPerDay = 1000 * 60 * 60 * 24;
    const daysRemaining = Math.ceil(
      (deadlineDate.getTime() - base.getTime()) / msPerDay
    );
 
    const arabicMessage =
      filingPeriod === "monthly"
        ? `تذكير ZATCA: موعد الإقرار الشهري ${formatted} — بعد ${daysRemaining} يوم`
        : `تذكير ZATCA: موعد الإقرار الفصلي ${formatted} — بعد ${daysRemaining} يوم`;
 
    return {
      deadlineDate: formatted,
      daysRemaining,
      arabicMessage,
      isUrgent: daysRemaining <= 7,
    };
  },
});

Ce que retourne cette action :

deadlineDate — la date de l'échéance au format ISO
daysRemaining — nombre de jours restants
arabicMessage — message WhatsApp en arabe prêt à l'envoi
isUrgent — booléen passant à true quand l'échéance est dans 7 jours ou moins

Étape 4 : Tester votre pièce en local

Compilez la pièce :

npm run build -- --filter=@activepieces/piece-zatca-reminder

Démarrez le serveur de développement avec votre pièce chargée :

AP_DEV_PIECES=zatca-reminder npm run start

Ouvrez http://localhost:4200. Votre pièce apparaît dans la recherche du flow builder — cherchez "ZATCA".

Construction du flow de rappel complet :

Déclencheur : Schedule → configurez-le pour s'exécuter le 20 de chaque mois
Action 1 : ZATCA Reminder → Calculer la prochaine échéance → Période : Mensuelle
Action 2 : Filtre — continuer uniquement si isUrgent est true
Action 3 : WhatsApp Business Cloud → Send Text Message → corps : la valeur arabicMessage de l'action 1

L'équipe financière reçoit désormais un rappel WhatsApp automatique en arabe chaque fois qu'une échéance ZATCA approche à moins de 7 jours.

Étape 5 : Déploiement de la pièce en production

Après les tests, packagez la pièce pour votre instance Activepieces de production.

Créez un Dockerfile personnalisé étendant l'image officielle :

FROM activepieces/activepieces:latest
COPY packages/pieces/custom/zatca-reminder/dist /root/custom-pieces/zatca-reminder

Ajoutez le chemin des pièces personnalisées dans Docker Compose :

environment:
  - AP_CUSTOM_PIECES_PATH=/root/custom-pieces

Reconstruisez et redémarrez :

docker compose build
docker compose up -d

La pièce ZATCA Reminder est désormais disponible dans votre flow builder de production aux côtés de toutes les pièces intégrées.

Résolution des problèmes courants

Le conteneur ne démarre pas : Exécutez docker compose logs activepieces pour lire les logs de démarrage. La cause la plus fréquente est un AP_ENCRYPTION_KEY mal formé — il doit contenir exactement 32 caractères hexadécimaux (sortie de openssl rand -hex 16).

La pièce personnalisée ne s'affiche pas : Après la compilation, redémarrez le conteneur et videz le cache du navigateur. Vérifiez que la valeur de AP_DEV_PIECES correspond au nom du package dans package.json, pas au displayName.

Les messages WhatsApp ne sont pas envoyés : Les tokens temporaires de Meta expirent toutes les 24 heures. En production, générez un token système permanent depuis Meta Business Manager sous Business Settings → System Users.

Erreurs TypeScript dans votre pièce : Exécutez npx tsc --noEmit dans le répertoire de la pièce. Les types du framework sont stricts — toutes les valeurs Property retournent unknown par défaut ; convertissez-les explicitement ou utilisez le type utilitaire PiecePropValueSchema.

Prochaines étapes

Le même pattern de pièce personnalisée s'applique à n'importe quelle API spécifique à la région MENA :

Surveillance de la conformité Qiwa — interrogez périodiquement l'API Qiwa sur les bandes Nitaqat et alertez automatiquement les RH en cas de changement
Déclencheur de paiement Moyasar — recevez un webhook Moyasar et lancez un flow qui met à jour votre CRM automatiquement
Suivi des réclamations NPHIES — vérifiez quotidiennement le statut des réclamations de santé et notifiez l'équipe de facturation à chaque changement

Pour aller plus loin sur la dimension métier, consultez le guide Automatisation des workflows IA pour les PME et l'analyse Coût de l'automatisation des workflows en Arabie Saoudite.

Si votre équipe utilise WhatsApp comme canal client principal, le tutoriel WhatsApp Cloud API en TypeScript vous montrera comment traiter les messages entrants de manière intelligente.

Prêt à automatiser les workflows de votre entreprise en Arabie Saoudite ou dans la région MENA avec une configuration Activepieces sur mesure ? Notre équipe est spécialisée dans l'intégration d'API et les solutions d'automatisation TypeScript pour les marchés arabophones. Contactez-nous pour discuter de votre projet.