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

# Quickstart

> Créez votre première facture et lancez un recouvrement en 5 minutes.

<Tip>
  Vous preferez explorer l'API visuellement ? Ouvrez la [documentation interactive Scalar](https://api.finkare.io/docs) pour tester les endpoints en direct.
</Tip>

## Pré-requis

1. Un compte Finkare avec accès API ([contactez-nous](mailto:hello@finkare.io))
2. Une clé API (préfixe `fk_test_` pour le sandbox, `fk_live_` pour la production)

## Étape 1 — Vérifier votre clé API

Testez la connexion avec le endpoint de santé :

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: fk_test_votre_cle_ici" \
    https://api-sandbox.finkare.io/health
  ```

  ```typescript SDK theme={null}
  import { FinkareClient } from '@finkare/api-sdk';

  const finkare = new FinkareClient('fk_test_votre_cle_ici', {
    baseUrl: 'https://api-sandbox.finkare.io',
  });
  ```
</CodeGroup>

Réponse attendue :

```json theme={null}
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-04-08T10:00:00Z"
}
```

## Étape 2 — Créer une facture

Importez votre première facture avec les informations du débiteur :

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-sandbox.finkare.io/api/v1/invoices \
    -H "X-API-Key: fk_test_votre_cle_ici" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: demo-facture-001" \
    -d '{
      "invoiceNumber": "FAC-2026-001",
      "amountCents": 150000,
      "currency": "EUR",
      "issueDate": "2026-03-01",
      "dueDate": "2026-03-31",
      "description": "Prestation de conseil - Mars 2026",
      "debtor": {
        "name": "Dupont & Fils SARL",
        "email": "comptabilite@dupont-fils.fr",
        "phone": "+33145678901",
        "siret": "44306184100047",
        "address": "12 rue de la Paix",
        "city": "Paris",
        "postalCode": "75002",
        "country": "FR"
      }
    }'
  ```

  ```typescript SDK theme={null}
  const invoice = await finkare.invoices.create({
    invoiceNumber: 'FAC-2026-001',
    amount: 150000,
    currency: 'EUR',
    issueDate: '2026-03-01',
    dueDate: '2026-03-31',
    debtor: {
      name: 'Dupont & Fils SARL',
      email: 'comptabilite@dupont-fils.fr',
      phone: '+33145678901',
      siret: '44306184100047',
      address: '12 rue de la Paix',
      city: 'Paris',
      postalCode: '75002',
      country: 'FR',
    },
  });

  console.log(invoice.data.id); // UUID de la facture créée
  ```
</CodeGroup>

Réponse :

```json theme={null}
{
  "success": true,
  "data": {
    "id": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "invoiceNumber": "FAC-2026-001",
    "amountCents": 150000,
    "currency": "EUR",
    "status": "imported",
    "workflowStarted": true,
    "createdAt": "2026-04-08T10:00:00Z"
  },
  "requestId": "req_abc123",
  "timestamp": "2026-04-08T10:00:00Z"
}
```

<Note>
  Le workflow de recouvrement démarre automatiquement à la création. L'IA analyse le profil du débiteur et planifie la cascade de relances optimale.
</Note>

## Étape 3 — Suivre le workflow

Consultez l'état du recouvrement :

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: fk_test_votre_cle_ici" \
    https://api-sandbox.finkare.io/api/v1/workflow/invoice/c3d4e5f6-a1b2-7890-cdef-1234567890ab
  ```

  ```typescript SDK theme={null}
  const status = await finkare.workflow.getStatus(
    'c3d4e5f6-a1b2-7890-cdef-1234567890ab'
  );
  console.log(status.data.currentStep); // ex: "relance_email_1"
  ```
</CodeGroup>

Réponse :

```json theme={null}
{
  "success": true,
  "data": {
    "invoiceId": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "status": "in_recovery",
    "currentStep": "relance_email_1",
    "startedAt": "2026-04-08T10:00:00Z",
    "actionsCompleted": 1,
    "nextActionAt": "2026-04-11T08:00:00Z"
  },
  "requestId": "req_def456",
  "timestamp": "2026-04-08T10:05:00Z"
}
```

## Étape 4 — Configurer un webhook

Recevez les notifications en temps réel :

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-sandbox.finkare.io/api/v1/webhooks \
    -H "X-API-Key: fk_test_votre_cle_ici" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://votre-serveur.com/webhooks/finkare",
      "events": ["payment.received", "invoice.status_changed", "workflow.action_triggered"],
      "description": "Webhook principal"
    }'
  ```

  ```typescript SDK theme={null}
  const webhook = await finkare.webhooks.create({
    url: 'https://votre-serveur.com/webhooks/finkare',
    events: ['payment.received', 'invoice.status_changed', 'workflow.action_triggered'],
    description: 'Webhook principal',
  });

  // Sauvegardez le secret — il ne sera plus affiché
  console.log(webhook.data.secret); // whsec_a1b2c3d4e5f6...
  ```
</CodeGroup>

<Warning>
  Le **secret de signature** est retourné une seule fois à la création. Sauvegardez-le immédiatement dans vos variables d'environnement.
</Warning>

## Et ensuite ?

<CardGroup cols={2}>
  <Card title="Authentification" icon="lock" href="/authentication">
    API Key vs OAuth 2.1, scopes, rate limiting
  </Card>

  <Card title="Import en masse" icon="upload" href="/guides/import-invoices">
    Importer 50+ factures depuis votre ERP
  </Card>

  <Card title="Webhooks avancés" icon="bell" href="/guides/webhook-setup">
    Vérification HMAC, retry, événements
  </Card>

  <Card title="SDK TypeScript" icon="code" href="/guides/sdk-typescript">
    Installation, configuration, pagination
  </Card>
</CardGroup>