doc: add import_csv API description (#56955)

help/fr/api-cards.page

@@ -21,10 +21,10 @@ données associés.
 </p>
 
 <section id="create">
-  <title>Création d'une fiche</title>
+  <title>Création d’une fiche</title>
 
   <p>
-   La création d'une fiche se fait par une requête <code>POST</code> à
+   La création d’une fiche se fait par une requête <code>POST</code> à
    l’adresse <code>/api/cards/<var>slug</var>/submit</code>, le contenu de
    la requête doit être un dictionnaire contenant obligatoirement un attribut
    <code>data</code>.
@@ -80,7 +80,7 @@ données associés.
   <p>
    L’exemple suivant crée une fiche « Parking », dont le modèle
    de fiche a comme identifiant « parkings », qui demanderait trois champs :
-   adresse (nom de variable <code>adresse</code>), date d'ouverture
+   adresse (nom de variable <code>adresse</code>), date d’ouverture
    (nom de variable <code>date_ouverture</code>) et nom (nom de variable
    <code>nom</code>).
   </p>
@@ -110,8 +110,96 @@ données associés.
 
 </section>
 
+<section id="card-import-csv">
+<title>Création d’un ensemble de fiches par import CSV</title>
+
+<p>
+Il est possible de créer un ensemble de fiches par import d’un fichier CSV.
+Cela s’effectue par une requête <code>PUT</code> à l’adresse
+<code>/api/cards/<var>slug</var>/import-csv</code>. Le contenu de la requête
+doit être un fichier CSV (text/csv).
+</p>
+
+<p>
+Chaque ligne du fichier va provoquer la création d’une nouvelle fiche et lancer
+le workflow correspondant.
+</p>
+
+<screen>
+<output style="prompt">$ </output><input>curl -X PUT -H "Content-Type: text/csv" \
+       -H "Accept: application/json" \
+       https://www.example.net/api/cards/<var>slug</var>/import-csv<var>?signature…</var>
+       --data-binary @fichier.csv</input>
+<output>{"err": 0}</output>
+</screen>
+
+<p>Le fichier CSV doit suivre le même format que celui utilisé lors d’un import
+CSV dans l’interface de gestion.</p>
+
+<section id="card-import-csv-async">
+<title>Import CSV asynchrone (recommandé)</title>
+
+<p>
+En plus de la création des fiches, le workflow va être exécuté pour chacune :
+sur un fichier CSV important le temps d’exécution de l’import peut dépasser la
+limite acceptée par le serveur HTTP (souvent 20 ou 30 secondes). Il est donc
+recommandé d’utiliser l’option asynchrone de l’import CSV.
+</p>
+
+<p>
+Pour faire un import asynchrone, ajouter <code>async=on</code> dans les
+paramètres de l’URL :
+</p>
+
+<screen>
+<output style="prompt">$ </output><input>curl -X PUT -H "Content-Type: text/csv" \
+       -H "Accept: application/json" \
+       https://www.example.net/api/cards/<var>slug</var>/import-csv<var>?async=on</var>
+       --data-binary @fichier.csv</input>
+<output>{
+    "err": 0,
+    "data": {
+        "job": {
+            "id": "1234",
+            "url": "https://www.example.net/api/jobs/1234/"
+        }
+    }
+}</output>
+</screen>
+
+<p>
+Cet appel envoie le fichier CSV, mais il n’est pas aussitôt importé. Une tâche
+(<em>job</em>) est lancée qui va effectivement faire l’import, et on peut en
+suivre la progression en appellant son URL indiquée en retour de l’appel PUT.
+</p>
+
+<screen>
+<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
+       https://www.example.net/api/jobs/1234/</input>
+<output>{
+    "err": 0,
+    "data": {
+        "status": "en cours",
+        "label": "Importation des données dans des fiches",
+        "creation_time": 1634910701,
+        "completion_time": null,
+        "completion_status": "23/46 (50%)"
+}
+}</output>
+</screen>
+
+<p>
+Pour suivre la bonne exécution de l’import, il faut appeler cette URL jusqu’à
+ce que la valeur <code>completion_time</code> soit renseignée. La valeur
+<code>status</code> permet de savoir alors si l’import s'est correctement
+déroulé.
+</p>
+
+</section>
+</section>
+
 <section id="card">
-<title>Récupération des données d’une fiches</title>
+<title>Récupération des données d’une fiche</title>
 
 <p>
 L’exemple suivant récupère les données d’une fiche « Parking », dont le modèle