# Consulter des centaines de lots à partir d'un fichier CSV

Envoyez à l'API un CSV de lots ou de matricules (POST /v1/batches), suivez le lot groupé, puis récupérez les inscriptions en CSV. 0,99 $ par index excluant frais du registre.

Cette page décrit la consultation en lot **par l'API** : un développeur envoie un fichier CSV de lots ou de matricules, suit le lot groupé, puis récupère les inscriptions de l'index en CSV. Le Studio n'a pas de téléversement en lot : cette route est réservée à l'API. Un cabinet sans développeur passe par le [programme de consultation en lot de fonciq.ca](https://fonciq.ca/consultation-en-lot).

## Prérequis

- Une clé d'API et un compte du Registre de votre organisation. Voir [Premier appel](/plateforme/demarrage).
- Un fichier CSV avec une colonne `lot` ou `matricule`, au plus **500 lignes de données** par requête.

```csv
lot
1234567
7654321
```

## 1. Envoyer le CSV

`POST /v1/batches` (portée `batches:write`) accepte le corps `text/csv`. L'en-tête `Idempotency-Key` est obligatoire et conservé 24 heures.

```bash
curl -X POST https://api.fonciq.ca/v1/batches \
  -H "Authorization: Bearer $FONCIQ_API_KEY" \
  -H "Content-Type: text/csv" \
  -H "Idempotency-Key: 8c2a1d4e-1b6f-4a90-9e3c-2f5d7a8b9c01" \
  --data-binary @lots.csv
```

La réponse est `202` avec un `job_id`. Au-delà de 500 lots, la réponse est `409` avec le code `batch_too_large`. Avec un corps CSV, le lot groupé est réparti entre les comptes du Registre actifs de l'organisation. Pour épingler un compte, utilisez le corps JSON avec `account_id` : voir [Lots groupés](/registre/lots-groupes).

## 2. Suivre le lot groupé

Lisez `GET /v1/jobs/{id}` jusqu'à `succeeded`. Chaque compte garde son plafond de 540 index par jour : un lot groupé plus gros que la capacité restante attend (`capacity_wait`) que le compte retrouve de la capacité. Le jour est celui de Toronto : le compteur revient à zéro à minuit, heure de Toronto. La capacité de chaque compte est dans la réponse de la tâche.

## 3. Récupérer les inscriptions en CSV

```bash
curl "https://api.fonciq.ca/v1/jobs/job_batch_01HZX/results?format=csv" \
  -H "Authorization: Bearer $FONCIQ_API_KEY" -o inscriptions.csv
```

Le CSV compte une rangée par ligne d'index structurée. Colonnes : `lot`, `matricule`, `inscription`, `date`, `nature`, `parties`, `document_url`, `read_method`, `confidence`, `needs_review`, `page_status`.

```csv
lot,matricule,inscription,date,nature,parties,document_url,read_method,confidence,needs_review,page_status
1234567,,"21 014 436",2024-03-12,Vente,"Vendeur: EXEMPLE, MARIE",https://api.fonciq.ca/v1/documents/42,,unscored,,
```

`confidence` vaut `unscored`. Le PDF de chaque index (`document_url`) fait foi. Sans `format=csv`, la même route renvoie le JSON : un bloc par lot dans `indexes`.

### Python

```python
import os, time, uuid, requests

BASE = "https://api.fonciq.ca"
HEADERS = {"Authorization": f"Bearer {os.environ['FONCIQ_API_KEY']}"}

with open("lots.csv", "rb") as handle:
    job = requests.post(
        f"{BASE}/v1/batches",
        headers={**HEADERS, "Content-Type": "text/csv", "Idempotency-Key": str(uuid.uuid4())},
        data=handle.read(),
    ).json()

while requests.get(f"{BASE}/v1/jobs/{job['job_id']}", headers=HEADERS).json()["status"] not in ("succeeded", "failed"):
    time.sleep(30)

csv_text = requests.get(f"{BASE}/v1/jobs/{job['job_id']}/results", params={"format": "csv"}, headers=HEADERS).text
open("inscriptions.csv", "w", encoding="utf-8").write(csv_text)
```

### Node

```js
import { readFile, writeFile } from 'node:fs/promises';

const BASE = 'https://api.fonciq.ca';
const headers = { Authorization: `Bearer ${process.env.FONCIQ_API_KEY}` };

const job = await fetch(`${BASE}/v1/batches`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'text/csv', 'Idempotency-Key': crypto.randomUUID() },
  body: await readFile('lots.csv'),
}).then((r) => r.json());

let state;
do {
  await new Promise((resolve) => setTimeout(resolve, 30_000));
  state = await fetch(`${BASE}/v1/jobs/${job.job_id}`, { headers }).then((r) => r.json());
} while (!['succeeded', 'failed'].includes(state.status));

await writeFile('inscriptions.csv', await fetch(`${BASE}/v1/jobs/${job.job_id}/results?format=csv`, { headers }).then((r) => r.text()));
```

## Coût

Chaque index coûte 0,99 $ par lot excluant frais du registre, et consulte toujours le Registre (1,50 $ par index, facturé au titulaire du compte). Un index consulté coûte donc 2,49 $. Il n'y a pas de rabais de volume. Voir [Coûts](/plateforme/couts-par-appel).

## À voir aussi

- [Comment extraire l'index des immeubles via l'API](/guides/index-des-immeubles-json) : le détail des lignes et du PDF source.
- [Lots groupés](/registre/lots-groupes) : la référence, avec le corps JSON et le compte épinglé.