# Factures

## GET `/invoices`

**Lister les factures de l’espace**

Montants en centimes de CHF. Une facture émise ne change plus (sauf son statut payé ou annulé).

Demande une clé d’API avec la portée `portal:read`.

### Paramètres de requête

| Champ    | Type                                         | Obligatoire | Description                          |
| -------- | -------------------------------------------- | ----------- | ------------------------------------ |
| `status` | “draft” \| “issued” \| “paid” \| “cancelled” | Non         |                                      |
| `limit`  | integer                                      | Non         | Par défaut : `20`. min. 1, max. 100. |
| `cursor` | string                                       | Non         |                                      |

### Réponses

| Code  | Description              | Corps     |
| ----- | ------------------------ | --------- |
| `200` | Succès                   | `objet`   |
| `400` | Requête invalide         | `Problem` |
| `401` | Authentification requise | `Problem` |
| `403` | Accès refusé             | `Problem` |
| `429` | Trop de requêtes         | `Problem` |
| `500` | Erreur interne           | `Problem` |

### Champs de la réponse `200`

| Champ                        | Type                                         | Description                                                                         |
| ---------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| `data`                       | objet\[]                                     |                                                                                     |
| `data[].id`                  | string                                       | Identifiant Portal.                                                                 |
| `data[].object`              | string                                       |                                                                                     |
| `data[].status`              | “draft” \| “issued” \| “paid” \| “cancelled” |                                                                                     |
| `data[].number`              | string ou null                               |                                                                                     |
| `data[].project_id`          | string                                       | Identifiant Portal.                                                                 |
| `data[].client_id`           | string                                       | Identifiant Portal.                                                                 |
| `data[].currency`            | string                                       |                                                                                     |
| `data[].subtotal`            | integer                                      | min. -9007199254740991, max. 9007199254740991.                                      |
| `data[].vat_total`           | integer                                      | min. -9007199254740991, max. 9007199254740991.                                      |
| `data[].total`               | integer                                      | Total TTC en centimes. min. -9007199254740991, max. 9007199254740991.               |
| `data[].issue_date`          | string ou null                               | AAAA-MM-JJ.                                                                         |
| `data[].due_date`            | string ou null                               | AAAA-MM-JJ.                                                                         |
| `data[].paid_at`             | string ou null                               |                                                                                     |
| `data[].reference`           | string ou null                               | Référence QR de paiement.                                                           |
| `data[].lines`               | objet\[]                                     |                                                                                     |
| `data[].lines[].description` | string                                       |                                                                                     |
| `data[].lines[].quantity`    | number                                       | Quantité, trois décimales au plus.                                                  |
| `data[].lines[].unit_price`  | integer                                      | Prix unitaire en centimes. min. -9007199254740991, max. 9007199254740991.           |
| `data[].lines[].vat_rate`    | integer                                      | TVA en points de base (810 = 8,1 %). min. -9007199254740991, max. 9007199254740991. |
| `data[].created_at`          | string                                       | Date et heure ISO 8601 (UTC).                                                       |
| `next_cursor`                | string ou null                               | À renvoyer en `cursor` pour la page suivante.                                       |
| `has_more`                   | boolean                                      |                                                                                     |

### Exemple

```bash
curl -X GET "https://app.hgdc.ch/portal/api/v1/invoices" \
  -H "Authorization: Bearer $HGDC_PORTAL_API_KEY"
```

Réponse `200` :

```json
{
  "data": [
    {
      "id": "exemple",
      "object": "exemple",
      "status": "draft",
      "number": "exemple",
      "project_id": "exemple",
      "client_id": "exemple",
      "currency": "exemple",
      "subtotal": -9007199254740991,
      "vat_total": -9007199254740991,
      "total": -9007199254740991,
      "issue_date": "exemple",
      "due_date": "exemple",
      "paid_at": "exemple",
      "reference": "exemple",
      "lines": [
        {}
      ],
      "created_at": "exemple"
    }
  ],
  "next_cursor": "exemple",
  "has_more": true
}
```

## GET `/invoices/{id}`

**Lire une facture**

Demande une clé d’API avec la portée `portal:read`.

### Paramètres de chemin

| Champ | Type   | Obligatoire | Description |
| ----- | ------ | ----------- | ----------- |
| `id`  | string | Oui         |             |

### Réponses

| Code  | Description              | Corps     |
| ----- | ------------------------ | --------- |
| `200` | Succès                   | `objet`   |
| `400` | Requête invalide         | `Problem` |
| `401` | Authentification requise | `Problem` |
| `403` | Accès refusé             | `Problem` |
| `404` | Ressource introuvable    | `Problem` |
| `429` | Trop de requêtes         | `Problem` |
| `500` | Erreur interne           | `Problem` |

### Champs de la réponse `200`

| Champ                 | Type                                         | Description                                                                         |
| --------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| `id`                  | string                                       | Identifiant Portal.                                                                 |
| `object`              | string                                       |                                                                                     |
| `status`              | “draft” \| “issued” \| “paid” \| “cancelled” |                                                                                     |
| `number`              | string ou null                               |                                                                                     |
| `project_id`          | string                                       | Identifiant Portal.                                                                 |
| `client_id`           | string                                       | Identifiant Portal.                                                                 |
| `currency`            | string                                       |                                                                                     |
| `subtotal`            | integer                                      | min. -9007199254740991, max. 9007199254740991.                                      |
| `vat_total`           | integer                                      | min. -9007199254740991, max. 9007199254740991.                                      |
| `total`               | integer                                      | Total TTC en centimes. min. -9007199254740991, max. 9007199254740991.               |
| `issue_date`          | string ou null                               | AAAA-MM-JJ.                                                                         |
| `due_date`            | string ou null                               | AAAA-MM-JJ.                                                                         |
| `paid_at`             | string ou null                               |                                                                                     |
| `reference`           | string ou null                               | Référence QR de paiement.                                                           |
| `lines`               | objet\[]                                     |                                                                                     |
| `lines[].description` | string                                       |                                                                                     |
| `lines[].quantity`    | number                                       | Quantité, trois décimales au plus.                                                  |
| `lines[].unit_price`  | integer                                      | Prix unitaire en centimes. min. -9007199254740991, max. 9007199254740991.           |
| `lines[].vat_rate`    | integer                                      | TVA en points de base (810 = 8,1 %). min. -9007199254740991, max. 9007199254740991. |
| `created_at`          | string                                       | Date et heure ISO 8601 (UTC).                                                       |

### Exemple

```bash
curl -X GET "https://app.hgdc.ch/portal/api/v1/invoices/<id>" \
  -H "Authorization: Bearer $HGDC_PORTAL_API_KEY"
```

Réponse `200` :

```json
{
  "id": "exemple",
  "object": "exemple",
  "status": "draft",
  "number": "exemple",
  "project_id": "exemple",
  "client_id": "exemple",
  "currency": "exemple",
  "subtotal": -9007199254740991,
  "vat_total": -9007199254740991,
  "total": -9007199254740991,
  "issue_date": "exemple",
  "due_date": "exemple",
  "paid_at": "exemple",
  "reference": "exemple",
  "lines": [
    {
      "description": "exemple",
      "quantity": 1,
      "unit_price": -9007199254740991,
      "vat_rate": -9007199254740991
    }
  ],
  "created_at": "exemple"
}
```