# `POST /v1/convert` — exemples par langage

Conversions entre sérialisations, via `?from=&to=` :

| from | to | Paramètre additionnel | Résultat |
|---|---|---|---|
| `cii` | `ubl` | `variant` (requis) | XML UBL |
| `ubl` | `cii` | — | XML CII |
| `cii` | `facturx` | `profile` (requis) | PDF/A-3 Factur-X |
| `facturx` | `cii` | — | XML CII brut (distinct du JSON de `/extract`) |

## curl — CII vers UBL

```bash
curl -X POST "https://api.example/v1/convert?from=cii&to=ubl&variant=peppol-bis" \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  --data-binary @facture.cii.xml \
  -o facture.ubl.xml
```

## curl — Emballer un CII en Factur-X

```bash
curl -X POST "https://api.example/v1/convert?from=cii&to=facturx&profile=EN16931" \
  -H "Authorization: Bearer $FACTURX_API_KEY" \
  --data-binary @facture.cii.xml \
  -o facture.pdf
```

## Python — UBL vers CII

```python
import requests, os

with open("facture.ubl.xml", "rb") as f:
    resp = requests.post(
        "https://api.example/v1/convert",
        params={"from": "ubl", "to": "cii"},
        headers={"Authorization": f"Bearer {os.environ['FACTURX_API_KEY']}"},
        data=f,
    )
with open("facture.cii.xml", "wb") as out:
    out.write(resp.content)
```

## Go — extraire le CII brut d'un Factur-X existant

```go
package main

import (
	"net/http"
	"os"
)

func main() {
	f, _ := os.Open("facture.pdf")
	defer f.Close()

	req, _ := http.NewRequest(http.MethodPost, "https://api.example/v1/convert?from=facturx&to=cii", f)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("FACTURX_API_KEY"))

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	out, _ := os.Create("facture.cii.xml")
	defer out.Close()
	_, _ = out.ReadFrom(resp.Body)
}
```

## Pertes de données (`X-Conversion-Warnings`)

Toute perte de données lors d'une conversion serait signalée dans
l'en-tête `X-Conversion-Warnings` (JSON), jamais silencieuse (FR-7). À ce
jour, cet en-tête est **toujours `[]`** : CII et UBL partagent exactement
le même socle de champs modélisés par `core.Invoice` — il n'existe
actuellement aucun champ propre à l'un ou l'autre format qui serait perdu
lors d'une conversion.

## Erreurs

| Code | Cause |
|---|---|
| 400 | Combinaison `from`/`to` non supportée, ou paramètre requis (`variant`/`profile`) manquant |
| 422 | Document source invalide/mal formé pour le format déclaré par `from` |
| 413 | Document > 20 Mo |