# Colissimo Web Service Affranchissement — Documentation de référence

## Authentification

Deux modes possibles :

### Mode 1 : contractNumber + password (dans le body JSON)
```json
{
  "contractNumber": "123456",
  "password": "monMotDePasse",
  ...
}
```

### Mode 2 : API Key (dans le header)
```
apikey: MA_CLE_API
```

## Endpoints

| Environnement | URL |
|--------------|-----|
| **Production** | `https://ws.colissimo.fr/sls-ws/SlsServiceWSRest/3.1/generateLabel` |
| **Sandbox** | `https://ws.colissimo.fr/sls-ws/SlsServiceWSRest/3.1/checkGenerateLabel` |

`checkGenerateLabel` = même requête mais sans générer de vrai colis (pas de suivi, pas de facturation).

## Générer une étiquette (generateLabel)

**POST** `https://ws.colissimo.fr/sls-ws/SlsServiceWSRest/3.1/generateLabel`

```json
{
  "contractNumber": "123456",
  "password": "monMotDePasse",
  "outputFormat": {
    "x": 0,
    "y": 0,
    "outputPrintingType": "PDF_10x15_300dpi"
  },
  "letter": {
    "service": {
      "productCode": "DOM",
      "depositDate": "2026-02-20",
      "orderNumber": "123-4567890-1234567",
      "commercialName": "Localiztoi"
    },
    "parcel": {
      "weight": 0.5
    },
    "sender": {
      "address": {
        "companyName": "Localiztoi",
        "line2": "Adresse de l'entrepôt",
        "countryCode": "FR",
        "city": "Ville",
        "zipCode": "00000"
      }
    },
    "addressee": {
      "address": {
        "lastName": "Dupont",
        "firstName": "Jean",
        "line2": "10 avenue des Champs",
        "countryCode": "FR",
        "city": "Lyon",
        "zipCode": "69001"
      }
    }
  }
}
```

## Champs obligatoires

| Bloc | Champs |
|------|--------|
| Racine | `contractNumber` + `password` |
| outputFormat | `outputPrintingType` |
| service | `productCode`, `depositDate` |
| parcel | `weight` (max 30 kg) |
| sender.address | `countryCode`, `zipCode`, `city` |
| addressee.address | `lastName`, `line2`, `countryCode`, `city`, `zipCode` |

## Formats d'étiquette

| Format | Description |
|--------|------------|
| `PDF_A4_300dpi` | PDF pleine page A4 |
| `PDF_10x15_300dpi` | PDF étiquette 10x15 cm |
| `ZPL_10x15_300dpi` | ZPL (Zebra) 10x15 |

## Réponse

La réponse est **multipart MIME (MTOM)** contenant :
1. Une partie JSON avec le statut + numéro de suivi
2. Une partie binaire avec le PDF de l'étiquette

```json
{
  "messages": [{ "id": "0", "type": "INFOS" }],
  "labelResponse": {
    "parcelNumber": "6A12345678901",
    "parcelNumberPartner": ""
  }
}
```

## Codes produits

| Code | Service |
|------|---------|
| **DOM** | Colissimo Domicile sans signature |
| **DOS** | Colissimo Domicile avec signature |
| **HD** | Hors Domicile (point relais) |
| **CECO** | Colissimo Eco France |
| **COM** | Colissimo International |

## Stockage credentials (notre app)

Dans la table `api_keys` :
- `provider=laposte`, `label=contract_number`
- `provider=laposte`, `label=password`

## Parsing MTOM

La réponse multipart contient :
- Le JSON entre les délimiteurs MIME
- Le PDF délimité par `%PDF` et `%%EOF`

Il faut parser les parties MIME pour extraire les deux.

## Méthodes utiles

| Méthode | Description |
|---------|------------|
| `checkGenerateLabel` | Test sans générer de vrai colis |
| `getLabel` | Ré-imprimer une étiquette existante |
| `generateBordereauByParcelsNumbers` | Bordereau de dépôt |