# Périmètre

import { ApiExample, ApiResponse } from "../../src/ApiExample";

L'API partenaire expose une seule surface, `/v1/papi/*`. Votre clé y donne accès à **votre portefeuille, et à rien d'autre**.

## La règle

<Callout type="note" title="Le périmètre vient de la clé, jamais de la requête">
  Aucune opération n'accepte un identifiant de périmètre depuis le corps ou la query pour **élargir** ce que vous voyez.

  Un `companyId` en paramètre est toujours un filtre **restrictif** : il est intersecté avec votre portefeuille réel. S'il tombe en dehors, la réponse est `403` — jamais un silence, jamais les données d'autrui.
</Callout>

Avec un portefeuille contenant les entreprises 4832 et 4790, sans filtre, la réponse couvre les deux :

<ApiExample path="/v1/papi/transactions" query={{ perPage: 2 }} />

<ApiResponse
  status={200}
  body={{
    data: [
      {
        ref: "TRX-4B71E0A9",
        companyId: 4832,
        amountFcfa: 31875,
        status: "CONFIRMED",
        createdAt: "2026-08-30T07:41:19.000Z",
        confirmedAt: "2026-08-30T07:41:19.000Z",
      },
      {
        ref: "TRX-9D02C15E",
        companyId: 4790,
        amountFcfa: 26400,
        status: "CONFIRMED",
        createdAt: "2026-08-29T16:05:52.000Z",
        confirmedAt: "2026-08-29T16:05:52.000Z",
      },
    ],
    pagination: {
      page: 1,
      perPage: 2,
      total: 318,
      totalPages: 159,
    },
  }}
/>

Un `companyId` du portefeuille restreint la vue — `200`, entreprise 4832 uniquement :

<ApiExample path="/v1/papi/transactions" query={{ companyId: 4832 }} />

Un `companyId` hors portefeuille est refusé, sans fuite d'information sur l'entreprise visée :

<ApiExample path="/v1/papi/transactions" query={{ companyId: 5001 }} />

<ApiResponse
  status={404}
  body={{
    error: {
      code: "COMPANY_NOT_FOUND",
      message: "Entreprise introuvable",
    },
  }}
/>

Notez le `404` : la réponse ne dit pas si l'entreprise 5001 existe. Un `403` l'aurait confirmé, et une clé volée aurait pu énumérer les entreprises de la plateforme.

En écriture, même principe : les champs de périmètre présents dans un corps de requête sont **ignorés**, pas honorés. Onboarder une entreprise la rattache toujours à *votre* portefeuille, quel que soit l'identifiant d'apporteur que vous envoyez.

## Les trois niveaux de restriction

Une requête traverse trois filtres successifs. Chacun peut la refuser :

| Niveau | Question | Refus |
|---|---|---|
| Clé | la clé est-elle valide, active, appelée depuis une IP autorisée ? | `401`, `403 PAPI_IP_FORBIDDEN` |
| Droits | la clé porte-t-elle le droit requis par l'opération ? | `403 PAPI_SCOPE_MISSING` |
| Portefeuille | la ressource visée appartient-elle à votre portefeuille ? | `404 COMPANY_NOT_FOUND` |

Les droits (`COMPANIES_READ`, `COMPANIES_WRITE`, `CREDIT_REQUEST_WRITE`, `REPORTS_READ`) sont décrits dans [Clés d'API](/guides/cles-api).

## `403` ou `404` ?

La règle est simple, et sans exception sur cette API :

- **`403`** — vous êtes identifié, mais la **clé** n'a pas le droit demandé, ou l'appel vient d'une adresse non autorisée, ou votre compte est fermé. Le problème est votre autorisation.
- **`404`** — la ressource n'existe pas **ou** n'est pas dans votre portefeuille. Les deux cas sont volontairement indiscernables.

Un `404` sur un identifiant que vous croyez valide signifie donc en général qu'il appartient à quelqu'un d'autre. C'est délibéré : sonder l'API ne doit pas permettre de cartographier les données des autres.

## Ce qui n'est pas exposé

L'API partenaire ne donne accès ni aux stations, ni aux marketeurs, ni aux paramètres de la plateforme, ni aux données d'une entreprise sortie de votre portefeuille. Ces surfaces existent pour d'autres acteurs et ne sont pas publiques.

Une opération qui n'apparaît pas dans la [Référence API](/api) n'est pas accessible avec une clé `ifp_*`, quelle que soit l'URL essayée.

## Ce que vos clients voient de leur côté

Les comptes que vous créez pour vos clients — gestionnaire de flotte, directeur financier — se connectent au tableau de bord Instafuel avec leur propre mot de passe. Ils voient leur entreprise, pas votre portefeuille, et n'ont aucun accès à l'API partenaire.

Réciproquement, votre clé ne vous permet pas d'agir *en tant que* l'un de ces comptes. Voir [Rôles](/reference/roles).