Import/export en masse via l’API
Ces routes font sortir les documents d’un doctype de Facet, puis les y renvoient, en CSV ou en JSON. Un export tourne sur un instantanéà : il lit un seul point dans le temps. Un import tourne dans une seule transaction : toutes les lignes arrivent, ou aucune.
Pour les agentsà : Exportà :
POST /Api/<domain>/<doctype>/export?format=csvrépond202 {job_id, status_url}. InterrogezGET /Api/<domain>/<doctype>/import_export/<job_id>, puis téléchargez depuisGET /Api/<domain>/<doctype>/import_export/<job_id>/download;wait=truerenvoie le fichier directement. Importà :POST /Api/<domain>/<doctype>/importavec le corps CSV ou JSONà; un422nomme la ligne et le problème. L’upsert se base sur la colonneid; une seule transactionà ; la première ligne en échec annule tout. Les POST exigentX-Requested-Withpour les sessions par cookie.
Quand l’utiliser
Section intitulée « Quand l’utiliser »Utilisez les routes d’import/export quandà :
- Vous déplacez un doctype vers une instance Facet, ou hors d’elle.
- Vous remettez une vue tableur d’un doctype à quelqu’un qui n’utilise pas Facet.
- Vous chargez un jeu de données initial depuis un autre système.
Avant de commencer
Section intitulée « Avant de commencer »- Les exports exigent le droit
readsur le doctype. Un import exige les droitscreateetupdate, car un upsert peut faire l’un ou l’autre. - Les routes refusent les doctypes enfants (
member_of) et les doctypes sidecar dans les deux sens. - Les sessions par cookie doivent envoyer
X-Requested-With: XMLHttpRequestsur les POST. Une authentification bearer sans cookie en est exemptée.
| Méthode | Route | Objectif |
|---|---|---|
POST |
/Api/<domain>/<doctype>/export |
Exporter un doctype entier. format=csv|json est requis. wait=true et les filtres de liste sont facultatifs. |
POST |
/Api/<domain>/<doctype>/export_view |
Exporter la vue tableau actuelle. Corps JSONà: {columns, sort, filters, timezone}. |
POST |
/Api/<domain>/<doctype>/import |
Importer un fichier CSV ou JSON. L’analyse structurelle tourne à la mise en file. |
GET |
/Api/<domain>/<doctype>/import_export/<job_id> |
Statut du jobà : {id, status, error, result}. |
GET |
/Api/<domain>/<doctype>/import_export/<job_id>/download |
Le fichier résultat. Exports réussis seulement. |
1. Exporter un doctype
Section intitulée « 1. Exporter un doctype »curl -s -X POST "https://facet.company.tld/Api/crm/Company/export?format=csv" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "X-Requested-With: XMLHttpRequest"La réponse est 202 :
{ "job_id": "01JBK2M4N6P8R0T2V4X6Z8B2D4", "status_url": "/Api/crm/Company/import_export/01JBK2M4N6P8R0T2V4X6Z8B2D4"}Interrogez la route de statut jusqu’à ce que status vaille succeeded ou
failed. Téléchargez ensuite le fichier depuis la route de téléchargement.
Avec wait=true, l’appel bloque jusqu’à la fin du jobà : en cas de succès la
réponse est le fichier lui-même, en cas d’échec c’est 500 avec
{"job_id", "error"}.
Les filtres suivent la grammaire de liste, par exemple
filters[status__eq]=active. sort, page, per_page et items répondent
422 : l’export est figé à l’ordre des id.
2. Exporter la vue tableau actuelle
Section intitulée « 2. Exporter la vue tableau actuelle »curl -s -X POST "https://facet.company.tld/Api/crm/Company/export_view" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Requested-With: XMLHttpRequest" \ -d '{"columns": ["name", "status", "amount"], "sort": ["-created_at", "id"], "filters": {"status__eq": "active"}, "timezone": "Europe/Paris"}'columnsest requis. Chaque clé doit être un champ du doctype ou une colonne système (id,created_at,updated_at). Une clé inconnue répond422et nomme la clé.sortutilise la grammaire de liste. Une entrée invalide répond422.- Les cellules
datetimese rendent dans latimezonedemandée. Sans elle, elles restent en UTC.
3. Importer un fichier
Section intitulée « 3. Importer un fichier »La route prend le format d’un paramètre format=, sinon du Content-Type,
sinon de la forme du corpsà : un [ en tête se lit comme du JSON.
curl -s -X POST "https://facet.company.tld/Api/crm/Company/import" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "Content-Type: text/csv" \ -H "X-Requested-With: XMLHttpRequest" \ --data-binary @companies.csvLa réponse est 202 avec {"job_id", "row_count", "status_url"}.
L’analyse structurelle tourne avant le job. Un fichier mal formé répond 422
et nomme la ligneà :
{ "error": "row 2: has 3 cells but the header declares 2 columns" }Mauvais guillemets, colonne d’en-tête inconnue, nombre de cellules qui ne correspond pas à l’en-têteà : tout échoue ici. Un problème au niveau d’une cellule, par exemple une valeur monétaire invalide à la ligne 900, apparaît plutôt dans le résultat du job.
Un aller-retour completà : exportez avec wait=true, ré-importez le fichier,
interrogez le jobà :
# 1. Exportez et attendezà : l’appel renvoie le fichier CSV directement.curl -s -X POST "https://facet.company.tld/Api/crm/Company/export?format=csv&wait=true" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "X-Requested-With: XMLHttpRequest" \ -o companies.csv
# 2. Ré-importez le fichier.curl -s -X POST "https://facet.company.tld/Api/crm/Company/import" \ -H "Authorization: Bearer $FACET_TOKEN" \ -H "Content-Type: text/csv" \ -H "X-Requested-With: XMLHttpRequest" \ --data-binary @companies.csv
# 3. Interrogez le statut du job (le job_id de la réponse d’import).curl -s "https://facet.company.tld/Api/crm/Company/import_export/01JBK2M4N6P8R0T2V4X6Z8B2D4" \ -H "Authorization: Bearer $FACET_TOKEN"Un job d’export réussi rapporteà :
{ "id": "01JBK2M4N6P8R0T2V4X6Z8B2D4", "status": "succeeded", "error": null, "result": { "artifact_id": "01JARQ5G7X9K2M3N4P5Q6R7S8T", "row_count": 128, "format": "csv" }}Le contrat d’import
Section intitulée « Le contrat d’import »-
Une seule transaction. La première ligne en échec annule l’import. Zéro ligne ne persiste.
-
L’échec nomme la ligne. Le rapport porte
{row, field, message}. -
Upsert sur la colonne
id. Un id vivant met le document à jour. Un id correspondant à un document supprimé (tombstone) est ignoréà ; un import ne ressuscite jamais un document supprimé. Un id absent en crée un. -
Les deux droits sont nécessaires. La première ligne que votre rôle ne peut pas écrire fait échouer le fichier.
-
Attribution. Chaque ligne enregistre
actioner_id: "import"dans l’audit. -
Les doctypes
genonlyrefusent les id fournis. Un doctype dont l’identifiant est généré par le système ne crée jamais un document à partir d’un id fourni.Un import en mode attente répond
200avec{row_count, created, updated, skipped}. Un échec de ligne attendu répond422avec la ligne en cause.
Le modèle de job
Section intitulée « Le modèle de job »- Un job tourne une seule fois. Corrigez l’entrée et soumettez de nouveau.
- Les routes de statut et de téléchargement ne répondent qu’au compte
demandeur. Les autres reçoivent
404: pas de fuite d’id de job. - À la fin, un événement est publié sur le flux du doctype, et le compte demandeur reçoit une notification avec un lien de téléchargement.
Conventions des cellules CSV
Section intitulée « Conventions des cellules CSV »| Cellule | Convention |
|---|---|
| Texte scalaire | Tel qu’il est stocké. |
| Types structurés | JSON dans la cellule. |
| Monétaire | USD 1.0 — le préfixe de devise est requis à l’import. |
| Booléen | true / false. |
| Référence | Id qualifié, par exemple crm.Company.abc. |
| Fichier | L’id d’artifact seulementà ; les octets ne bougent pas. |
| Cellule vide | Se décode en null ; elle vide le champ à la mise à jour. |
| Colonne absente | Laisse le champ intact. |
Texte commençant par =, +, -, @, ou une tabulation |
S’exporte avec un ' en tête — le garde-fou anti-formule. Le décodage retire un ' de tête. |
Dépannage
Section intitulée « Dépannage »Le POST d’import répond 413.
Le corps dépasse le plafond de téléversement. Découpez le fichier et importez les morceaux.
La mise en file répond 422 et nomme une ligne.
L’analyse structurelle a échouéà : problème de guillemets, colonne d’en-tête inconnue, ou nombre de cellules qui ne correspond pas à l’en-tête. Corrigez cette ligne et soumettez de nouveau.
Le job échoue sur un champ money.
Une cellule monétaire exige le préfixe de deviseà : USD 1.0, pas 1.0.
Certaines lignes sont skipped.
Leurs id pointent vers des documents supprimés. Un import ne ressuscite jamais un document. Retirez les id pour créer de nouveaux documents.
Le téléchargement répond 404.
Le fichier résultat a été purgé après la fenêtre de rétention — voir Rétention. Exportez de nouveau.
Voir aussi
Section intitulée « Voir aussi »- Utiliser l’API REST — la grammaire de filtres de liste que les filtres d’export réutilisent.
- Téléverser et servir des fichiers — comment le fichier résultat est stocké et relu.
- Rétention — la fenêtre qui borne un lien de téléchargement.
- Internes sur GitHubà : import-export.md.