NeahStable/TWENTY_CRM_INTEGRATION.md at 4de8eab879b239e29b02fde32e2657cd13d99349

alma/NeahStable

Fork 0

alma 4cb4cccf5d vision refactor

2026-01-15 22:27:51 +01:00

6.8 KiB

Raw Blame History

📋 Vue d'ensemble

Le widget "Devoirs" affiche maintenant les tâches en retard provenant de deux sources :

Leantime (agilite.slm-lab.net)
Twenty CRM (mediation.slm-lab.net)

Les tâches sont combinées, filtrées (uniquement celles en retard), triées par date d'échéance, et limitées à 7 tâches.

🔧 Configuration Requise

Variables d'Environnement

Ajoutez les variables suivantes à votre fichier .env.local (développement) ou à vos variables d'environnement de production :

# Twenty CRM API Configuration
TWENTY_CRM_API_URL=https://mediation.slm-lab.net/graphql
TWENTY_CRM_API_KEY=your_api_key_here
TWENTY_CRM_URL=https://mediation.slm-lab.net

Où obtenir la clé API :

Connectez-vous à Twenty CRM (mediation.slm-lab.net)
Allez dans Settings → APIs & Webhooks
Cliquez sur "+ Create key"
Donnez un nom à la clé (ex: "NeahStable Widget")
Copiez la clé (elle ne sera affichée qu'une seule fois)

📁 Fichiers Créés/Modifiés

Nouveau Fichier

app/api/twenty-crm/tasks/route.ts - Endpoint API pour récupérer les tâches Twenty CRM

Fichiers Modifiés

components/flow.tsx - Widget Devoirs modifié pour combiner les deux sources

🔄 Flow de Fonctionnement

1. Récupération des Tâches

Le widget fait deux appels API en parallèle :

const [leantimeResponse, twentyCrmResponse] = await Promise.allSettled([
  fetch('/api/leantime/tasks'),
  fetch('/api/twenty-crm/tasks'),
]);

Avantages :

✅ Appels parallèles = plus rapide
✅ Promise.allSettled = si une source échoue, l'autre continue de fonctionner
✅ Pas de dépendance entre les deux sources

2. Transformation des Tâches Twenty CRM

Les tâches Twenty CRM sont transformées pour correspondre au format Leantime :

{
  id: `twenty-${task.id}`, // Préfixe pour éviter les conflits
  headline: task.title,
  dateToFinish: task.dueAt,
  projectName: 'Twenty CRM',
  source: 'twenty-crm', // Identifiant de source
  url: `${TWENTY_CRM_URL}/object/activity/${task.id}`, // Lien direct
  // ... autres champs
}

3. Filtrage et Tri

Filtrage : Uniquement les tâches avec date d'échéance avant aujourd'hui (en retard)
Tri : Par date d'échéance (plus anciennes en premier)
Limite : Maximum 7 tâches affichées

4. Affichage

Les tâches Twenty CRM sont identifiées par un badge "(Twenty CRM)"
Le lien pointe vers la page de la tâche dans Twenty CRM
Le format d'affichage est identique pour les deux sources

🔍 Structure de l'API Twenty CRM

Endpoint GraphQL

URL : https://mediation.slm-lab.net/graphql

Méthode : POST

Headers :

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Requête GraphQL

query GetOverdueTasks {
  findManyActivities(
    filter: {
      type: { eq: Task }
      completedAt: { is: NULL }
      dueAt: { lt: "2026-01-15T00:00:00Z" }
    }
    orderBy: { dueAt: AscNullsLast }
  ) {
    edges {
      node {
        id
        title
        body
        dueAt
        completedAt
        type
        assigneeId
        assignee {
          id
          firstName
          lastName
          email
        }
      }
    }
  }
}

Filtres appliqués :

type: { eq: Task } - Uniquement les tâches (pas les autres activités)
completedAt: { is: NULL } - Uniquement les tâches non complétées
dueAt: { lt: "..." } - Uniquement les tâches avec date d'échéance avant aujourd'hui

🐛 Dépannage

Erreur : "TWENTY_CRM_API_URL is not set"

Solution : Ajoutez TWENTY_CRM_API_URL à vos variables d'environnement.

Erreur : "TWENTY_CRM_API_KEY is not set"

Solution : Ajoutez TWENTY_CRM_API_KEY à vos variables d'environnement.

Erreur : "401 Unauthorized"

Causes possibles :

Clé API invalide ou expirée
Clé API mal copiée (espaces, caractères invisibles)
Permissions insuffisantes sur la clé API

Solution :

Vérifiez que la clé API est correctement copiée
Régénérez la clé API dans Twenty CRM
Vérifiez les permissions de la clé API

Erreur : "GraphQL errors from Twenty CRM"

Causes possibles :

Structure de la requête GraphQL incorrecte
Version de Twenty CRM incompatible
Schéma GraphQL différent selon le workspace

Solution :

Vérifiez la documentation de votre version de Twenty CRM
Testez la requête GraphQL directement dans l'interface GraphQL de Twenty CRM
Ajustez la requête selon votre schéma

Aucune tâche Twenty CRM n'apparaît

Vérifications :

✅ Vérifiez qu'il existe des tâches en retard dans Twenty CRM
✅ Vérifiez que les tâches ont une date d'échéance (dueAt)
✅ Vérifiez que les tâches ne sont pas complétées (completedAt est NULL)
✅ Vérifiez les logs du serveur pour voir les erreurs éventuelles

📊 Logs et Debug

Logs Backend

Tous les logs sont préfixés avec [TWENTY_CRM_TASKS] :

logger.debug('[TWENTY_CRM_TASKS] Fetching tasks from Twenty CRM', {...});
logger.error('[TWENTY_CRM_TASKS] Failed to fetch tasks', {...});

Logs Frontend

Le widget affiche dans la console :

Nombre de tâches Leantime récupérées
Nombre de tâches Twenty CRM récupérées
Total combiné
Tâches triées avec leur source

🔄 Alternatives si GraphQL ne fonctionne pas

Si la requête GraphQL ne fonctionne pas avec votre version de Twenty CRM, vous pouvez utiliser l'API REST :

Option 1 : API REST (si disponible)

const response = await fetch(`${process.env.TWENTY_CRM_API_URL}/api/activities`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.TWENTY_CRM_API_KEY}`,
  },
});

Option 2 : Ajuster la requête GraphQL

La structure exacte peut varier. Consultez la documentation de votre instance Twenty CRM ou utilisez l'explorateur GraphQL intégré.

✅ Checklist de Déploiement

Variables d'environnement configurées :
- TWENTY_CRM_API_URL
- TWENTY_CRM_API_KEY
- TWENTY_CRM_URL (optionnel, pour les liens)
Clé API créée dans Twenty CRM
Permissions de la clé API vérifiées
Test de l'endpoint /api/twenty-crm/tasks effectué
Vérification que les tâches apparaissent dans le widget
Logs vérifiés pour détecter d'éventuelles erreurs

📝 Notes

Les tâches Twenty CRM sont préfixées avec twenty- dans leur ID pour éviter les conflits
Le widget continue de fonctionner même si une seule source échoue (grace à Promise.allSettled)
Le cache Redis n'est pas encore implémenté pour Twenty CRM (peut être ajouté plus tard)
La requête GraphQL peut nécessiter des ajustements selon votre version de Twenty CRM

6.8 KiB Raw Blame History

Intégration Twenty CRM dans le Widget Devoirs