> ## Documentation Index
> Fetch the complete documentation index at: https://help.firby.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# L’API Firby

> Interroger vos données — factures, logements, propriétaires, réservations, dépenses — depuis vos propres outils, avec une clé API.

Firby expose une **API REST** : tout ce que vous voyez dans l’application (factures,
logements, propriétaires, réservations, dépenses exceptionnelles) est interrogeable
depuis vos propres outils — un tableur connecté, un script, votre outil de reporting.

## Créer une clé API

1. Ouvrez **Réglages → API** (page **Clés API**).
2. Cliquez sur **Nouvelle clé** et nommez-la pour la reconnaître (ex. « Intégration
   compta »).
3. Copiez la clé immédiatement : pour des raisons de sécurité, elle ne sera **plus
   jamais affichée**.

Les clés commencent par `firby_sk_`. Le tableau des clés affiche leur date de création,
leur expiration éventuelle et leur dernier usage ; **Révoquer** coupe immédiatement les
intégrations qui utilisent la clé.

<Note>
  La gestion des clés est réservée aux rôles **propriétaire** et **administrateur** de la
  conciergerie. Chaque clé ne donne accès qu’aux données de **votre** conciergerie.
</Note>

## S’authentifier

Envoyez la clé dans l’en-tête **`x-api-key`** de chaque requête (l’en-tête
`Authorization: Bearer` est aussi accepté) :

```bash theme={null}
curl https://app.firby.fr/api/v1/invoices?period=2026-06 \
  -H "x-api-key: firby_sk_..."
```

Chaque clé est limitée à **120 requêtes par minute**.

## Ce que l’API permet

| Ressource                    | Opérations                                                                                                                                                 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Factures**                 | Lister (par période, par statut), consulter une facture **avec ses lignes** et leur trace de calcul.                                                       |
| **Dépenses exceptionnelles** | Lister par mois, **créer** une dépense (elle rejoint le brouillon comme depuis l’application — voir [Dépenses exceptionnelles](/factures/depenses)).       |
| **Logements**                | Lister, consulter, modifier le **nom** ou le **rattachement au propriétaire**. Les autres champs viennent du PMS et sont écrasés à la synchronisation.     |
| **Propriétaires**            | Lister, créer, consulter, modifier, supprimer. La suppression est refusée si des factures ou mandats y sont rattachés — désactivez plutôt le propriétaire. |
| **Réservations**             | Lister (par logement, par dates), les plus récentes d’abord.                                                                                               |

Les logements et propriétaires exposent aussi leur **identifiant côté PMS**
(`pmsListingId`, `pmsOwnerRef`) : pratique pour croiser les données Firby avec celles
de votre PMS.

Les listes sont **paginées** avec `limit` (100 par défaut, 500 maximum) et `offset`.

## La documentation interactive

La référence complète — chaque endpoint, ses paramètres et un mode « essayer » où vous
collez votre clé — est intégrée à l’application sur **`/docs`**. La spécification
OpenAPI est disponible sur `/api/v1/openapi.json`.

<Tip>
  Vous préférez poser vos questions en français plutôt qu’en HTTP ? Connectez **Claude ou
  ChatGPT** à votre espace Firby : voir
  [Connecter un assistant IA](/api/assistants-ia).
</Tip>