Workflow - Finkare API

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

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

const status = await finkare.workflow.getStatus(
  '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"
}

string

Statut du workflow : pending, in_recovery, paused, completed, cancelled, judicial

string

Étape actuelle de la cascade de relances (ex : relance_email_2, sms_reminder, ai_call)

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

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

string

required

ID de la facture (UUID)

string

required

Action à déclencher : start, pause, resume, cancel, escalate

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é"
  }'

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" \
  -d '{
    "action": "escalate",
    "reason": "Aucune réponse après 3 relances — passage au niveau supérieur"
  }'

await finkare.workflow.trigger('c3d4e5f6-a1b2-7890-cdef-1234567890ab');

Actions disponibles

Action	Description	Pré-requis
`start`	Démarre le workflow (si pas encore actif)	Statut `pending`
`pause`	Met en pause les relances automatiques	Statut `in_recovery`
`resume`	Reprend les relances après une pause	Statut `paused`
`cancel`	Annule définitivement le workflow	Statut `in_recovery` ou `paused`
`escalate`	Escalade au niveau supérieur (canal plus intrusif ou judiciaire)	Statut `in_recovery`

Codes d’erreur possibles

Code	HTTP	Description
`BIZ_004`	400	Transition de statut invalide (ex : `resume` sur un workflow actif)
`BIZ_002`	400	Workflow déjà démarré (pour `start`)
`AUTH_004`	403	Scope `workflow:trigger` requis
`RES_001`	404	Facture 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

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"
}

​Statut du workflow

​Historique du workflow

​Déclencher une action

​Actions disponibles

​Codes d’erreur possibles

​Prochaine action planifiée

​Statistiques des workflows

Statut du workflow

Historique du workflow

Déclencher une action

Actions disponibles

Codes d’erreur possibles

Prochaine action planifiée

Statistiques des workflows