> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkare.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Workflow
> Pilotage du workflow de recouvrement IA : démarrage, pause, reprise, escalade et consultation de l'historique des actions.
**Tester en direct** — Essayez ces endpoints dans la [documentation interactive Scalar](https://api.finkare.io/docs).
## Statut du workflow
Récupère le statut actuel du workflow de recouvrement pour une facture.
**Scope requis :** `workflow:read`
ID de la facture (UUID)
```bash cURL theme={null}
curl -H "X-API-Key: fk_live_xxx" \
https://api.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab
```
```typescript SDK theme={null}
const status = await finkare.workflow.getStatus(
'c3d4e5f6-a1b2-7890-cdef-1234567890ab'
);
```
```json theme={null}
{
"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"
}
```
Statut du workflow : `pending`, `in_recovery`, `paused`, `completed`, `cancelled`, `judicial`
Étape actuelle de la cascade de relances (ex : `relance_email_2`, `sms_reminder`, `ai_call`)
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`
ID de la facture (UUID)
```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
https://api.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab/history
```
```json theme={null}
{
"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`
ID de la facture (UUID)
Action à déclencher : `start`, `pause`, `resume`, `cancel`, `escalate`
Motif de l'action (recommandé pour la traçabilité)
```bash cURL — Pause theme={null}
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é"
}'
```
```bash cURL — Escalade theme={null}
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"
}'
```
```typescript SDK theme={null}
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`
ID de la facture (UUID)
```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
https://api.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab/next-action
```
```json theme={null}
{
"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`
```bash theme={null}
curl -H "X-API-Key: fk_live_xxx" \
https://api.finkare.io/api/v1/workflow/stats
```
```json theme={null}
{
"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"
}
```