Skip to main content
Tester en direct — Essayez ces endpoints dans la documentation interactive Scalar.

​
Statut du workflow

Récupère le statut actuel du workflow de recouvrement pour une facture. Scope requis : workflow:read
​
invoiceId
string
required
ID de la facture (UUID)
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab

{
  "success": true,
  "data": {
    "invoiceId": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "status": "in_recovery",
    "currentStep": "relance_email_2",
    "startedAt": "2026-02-20T09:00:00Z",
    "actionsCompleted": 3,
    "nextActionAt": "2026-04-10T08:00:00Z"
  },
  "requestId": "req_w1x2y3",
  "timestamp": "2026-04-08T10:00:00Z"
}
​
data.status
string
Statut du workflow : pending, in_recovery, paused, completed, cancelled, judicial
​
data.currentStep
string
Étape actuelle de la cascade de relances (ex : relance_email_2, sms_reminder, ai_call)
​
data.nextActionAt
string
Date/heure planifiée de la prochaine action (respecte les horaires légaux 8h-20h, pas de dimanche ni jours fériés)

​
Historique du workflow

Récupère l’historique complet des actions de recouvrement. Scope requis : workflow:read
​
invoiceId
string
required
ID de la facture (UUID)
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab/history

{
  "success": true,
  "data": [
    {
      "action": "email_prise_en_charge",
      "channel": "email",
      "executedAt": "2026-02-20T09:00:00Z",
      "status": "delivered",
      "details": "Email de prise en charge envoyé"
    },
    {
      "action": "relance_email_1",
      "channel": "email",
      "executedAt": "2026-02-23T09:00:00Z",
      "status": "delivered",
      "details": "Première relance email — ton informatif"
    },
    {
      "action": "sms_reminder",
      "channel": "sms",
      "executedAt": "2026-02-26T10:00:00Z",
      "status": "delivered",
      "details": "SMS de rappel avec lien de paiement"
    },
    {
      "action": "relance_email_2",
      "channel": "email",
      "executedAt": "2026-03-01T09:00:00Z",
      "status": "delivered",
      "details": "Deuxième relance email — ton ferme"
    }
  ],
  "requestId": "req_h1i2j3",
  "timestamp": "2026-04-08T10:00:00Z"
}
L’historique respecte les contraintes anti-harcèlement : vous pouvez vérifier que les règles (max 1 com/jour, cooldown 3 jours par canal, horaires légaux) sont appliquées.

​
Déclencher une action

Déclenche manuellement une action sur le workflow. Scope requis : workflow:trigger
​
invoiceId
string
required
ID de la facture (UUID)
​
action
string
required
Action à déclencher : start, pause, resume, cancel, escalate
​
reason
string
Motif de l’action (recommandé pour la traçabilité)
curl -X POST https://api.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab/trigger \
  -H "X-API-Key: fk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pause-fac-001-2026-04-08" \
  -d '{
    "action": "pause",
    "reason": "Négociation en cours avec le débiteur — échéancier proposé"
  }'

​
Actions disponibles

ActionDescriptionPré-requis
startDémarre le workflow (si pas encore actif)Statut pending
pauseMet en pause les relances automatiquesStatut in_recovery
resumeReprend les relances après une pauseStatut paused
cancelAnnule définitivement le workflowStatut in_recovery ou paused
escalateEscalade au niveau supérieur (canal plus intrusif ou judiciaire)Statut in_recovery

​
Codes d’erreur possibles

CodeHTTPDescription
BIZ_004400Transition de statut invalide (ex : resume sur un workflow actif)
BIZ_002400Workflow déjà démarré (pour start)
AUTH_004403Scope workflow:trigger requis
RES_001404Facture ou workflow non trouvé

​
Prochaine action planifiée

Récupère la prochaine action de recouvrement planifiée par l’IA. Scope requis : workflow:read
​
invoiceId
string
required
ID de la facture (UUID)
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab/next-action

{
  "success": true,
  "data": {
    "invoiceId": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "nextAction": "sms_reminder",
    "scheduledAt": "2026-04-10T08:00:00Z",
    "channel": "sms",
    "reason": "Aucune réponse aux 2 emails de relance précédents"
  },
  "requestId": "req_n1a2b3",
  "timestamp": "2026-04-08T10:00:00Z"
}
L’IA choisit le canal optimal en fonction du profil du débiteur, de l’historique des interactions et du score de solvabilité. Vous pouvez consulter la prochaine action avant de décider de la maintenir ou de la modifier via trigger.

​
Statistiques des workflows

Scope requis : reports:read 
curl -H "X-API-Key: fk_live_xxx" \
  https://api.finkare.io/api/v1/workflow/stats

{
  "success": true,
  "data": {
    "active": 45,
    "paused": 8,
    "completed": 280,
    "cancelled": 12,
    "averageDaysToPayment": 18,
    "recoveryRate": 87.4
  },
  "requestId": "req_ws_01",
  "timestamp": "2026-04-08T10:00:00Z"
}