Synchronisations bancaires
Une synchronisation (bank_sync) est une exécution qui va chercher les données bancaires d'une entreprise chez notre agrégateur : comptes découverts, opérations importées. Vous en démarrez une, puis vous l'interrogez.
Une connexion bancaire est ce qui donne l'accès (Connexions bancaires) ; une synchronisation est ce qui s'en sert.
La chose à comprendre avant tout le reste
Un 202 ne signifie jamais que le travail est terminé. Il signifie qu'une exécution existe et qu'elle vous appartient. Rien n'a encore été compté, rien n'a encore été importé.
C'est en interrogeant l'exécution que vous apprenez ce qui s'est passé - y compris l'échec. Un échec terminal est rapporté sur l'exécution elle-même, jamais seulement dans un journal que vous ne voyez pas.
Démarrer une synchronisation
Un token portant le scope write est requis, ainsi qu'un en-tête Idempotency-Key.
curl -X POST https://app.scribee.tech/api/v1/workspaces/YOUR_WORKSPACE_ID/companies/YOUR_COMPANY_ID/bank_syncs \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Idempotency-Key: 9d2b1f30-6c44-4b8b-9d55-1f0a7e2c9a31"
Il n'y a pas de corps de requête. Une synchronisation couvre toutes les connexions de l'entreprise : le travailleur les parcourt toutes, et nous préférons ne pas vous offrir un paramètre de restriction qu'il n'honorerait pas. Le champ bank_connection_id de la réponse vaut donc null aujourd'hui ; il est présent pour que la forme ne change pas le jour où une exécution ciblée devient possible.
Réponse 202 :
{
"data": {
"id": 9012,
"company_id": 34,
"bank_connection_id": null,
"bank_account_id": null,
"kind": "manual",
"state": "pending",
"progress": null,
"error_code": null,
"error_message": null,
"retryable": false,
"started_at": null,
"finished_at": null,
"accounts_discovered_count": 0,
"operations_imported_count": 0,
"created_at": "2026-08-21T11:15:00+02:00",
"updated_at": "2026-08-21T11:15:00+02:00"
}
}
Une seule exécution à la fois par entreprise. Si l'une est déjà en vol, l'appel est refusé en 422 avec le code sync_in_progress : attendez qu'elle se termine plutôt que d'en lancer une autre. Nous ne vous rendons pas l'identifiant de l'exécution en cours - vous l'avez reçu de votre propre 202.
Interroger l'exécution
Un token read suffit.
curl https://app.scribee.tech/api/v1/bank_syncs/9012 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
state prend l'une de ces cinq valeurs :
state | Ce qu'il signifie |
|---|---|
pending | L'exécution est acceptée et attend son tour |
running | Elle est en cours |
completed | Elle s'est terminée avec un jeu de données complet |
partial | Elle s'est terminée en sachant ses données incomplètes |
failed | Elle a échoué |
partial n'est pas un arrondi de completed. L'exécution s'est achevée avec un jeu de résultats qu'elle sait incomplet : des données manquent réellement, et une nouvelle synchronisation vaut la peine. Traiter partial comme un succès est exactement l'erreur que cette valeur existe pour empêcher.
L'incomplétude n'a pas toujours la même cause - une page que l'exécution n'a pas lue, une opération qu'elle a refusé d'enregistrer - et partial ne vous dit pas laquelle. Il vous dit ce qui suffit pour agir : il manque des données. Aucun mouvement bancaire n'est perdu pour autant, une opération refusée reste dans le champ des synchronisations suivantes et elle est reprise dès qu'elle devient exploitable ; une exécution peut donc rester partial tant que la donnée en cause n'a pas changé chez l'agrégateur.
Une opération non importée parce qu'un relevé tient déjà son jour n'est pas une cause de partial. Rien ne manque : pour ce jour, les opérations du compte sont les lignes du relevé (voir Relevés bancaires). Si le relevé rend ce jour plus tard et qu'aucune autre ligne de relevé ne le tient, la synchronisation suivante relit le compte depuis le début et l'importe.
kind dit pourquoi l'exécution existe : initial (le premier remplissage après une connexion), webhook (l'agrégateur nous a signalé un changement), scheduled (le rafraîchissement périodique), manual (vous l'avez demandée).
include=bank_connection ajoute l'id et le status de la connexion concernée.
Quand une exécution échoue
error_code vaut operation_failed dès que l'exécution porte un diagnostic, et null sinon : un failed en porte toujours un, un partial peut en porter ou non selon la cause de son incomplétude. retryable dit si relancer la même synchronisation peut plausiblement finir autrement.
Ce qu'il faut faire d'un échec se lit sur la connexion, pas sur l'exécution. Si la banque a retiré son autorisation, c'est le status de la connexion qui passe à expired, et le remède est reconnect. L'exécution vous dit qu'elle a échoué et si une nouvelle tentative a un sens ; la connexion vous dit pourquoi et quoi faire.
progress et error_message valent actuellement toujours null : rien ne produit de pourcentage, et un message d'exception n'a pas sa place sur un champ publié. Nous préférons ne rien publier plutôt qu'une valeur que vous bâtiriez en barre de progression.
Les erreurs
| Statut | code | Quand |
|---|---|---|
422 | validation_failed | L'en-tête Idempotency-Key manque |
422 | sync_in_progress | Une exécution est déjà en vol pour cette entreprise |
409 | idempotency_key_reuse | La même Idempotency-Key a déjà servi pour un corps différent |
404 | - | L'exécution n'est pas atteignable par vos habilitations |