---
title: API Client
slug: oip-next/v3/starter-utils/api-client
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T12:22:15.000Z
---

L'API client expose les éléments suivants (*named exports*) :

- la méthode `start` qui permet d'initialiser l'application *React*
- le hook `useProcess` qui permet la gestion des transitions et des tâches depuis les composants des vues de l'OAV
- le composant `Router` qui permet d'initialiser les routes de l'OAV
- l'objet `Tokens` qui permet la gestion des credentials et du token d'authentification de l'application client

Les imports depuis l'OAV :

```javascript
import {
  start,
  useProcess,
  Router,
  Tokens
} from '@fasstech/oip-starter-utils/app';
```

# Méthode start

La méthode `start` initialise l'application *React* de l'OAV. Elle prend en paramètre un objet de configuration. Ex. :

:::CodeblockTabs
index.js

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// Init client app
(async () => {
  startApp({ /* options */ })();
})();
```
:::

## Options requises

### app

Le composant `App` de l'OAV est attendu en valeur. Le composant `App` doit impérativement charger le composant `Router` fournit par la lib. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';
import { Router } from '@fasstech/oip-starter-utils/app';
import views from '../views/client.js';

// App component
const App = () => {
  // ...

  return (
    <>
      <OtherProvider>
        {/* Router component must be returned */}
        <Router views={views} />
      </OtherProvider>
    </>
  );
};

// Init client app
(async () => {
  startApp({
    app: App,
    // ...
  });
})();
```

### processFragment

La définition du fragment graphQL de l'obje&#x74;*&#x20;process* est attendue en valeur. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';
import { gql } from '@apollo/client';

// Process fragment def
const ProcessFragment = gql`
  fragment ProcessFragment on ExtendedProcess {
    # required fields (do not remove)
    projectId
    viewId
    metadata
    sessionId

    # additional fields
    # requested fields must match type definition at server/graphql/types/extended-process-type.mjs
    # add your custom fields here
    # ...
  }
`;

// Init client app
(async () => {
  startApp({
    processFragment: ProcessFragment,
    // ...
  });
})();
```

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/process) pour plus de détails.

### useCustomHandlers

Le hook qui définit les handlers personnalisés est attendu en valeur. Ex. :

```javascript
// hook declaration
const useCustomHandlers = () => {
  const myCustomHandler = () => {
    // some logic
  };

  const customHandlers = {
    myCustomHandler
  };

  // the hook must return an object `customHandlers`
  return {
    customHandlers
  };
};

// Init client app
(async () => {
  startApp({
    useCustomHandlers,
    // ...
  });
})();
```

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/process-handlers#lK4DV) pour plus de détails.

## Options optionnelles

### ctxPolicy

Option disponible à partir de la version 3.4.2

Le support de la valeur `shadow-crm` est disponible à partir de la version 3.6.0 (voir plus bas)

Définit la manière dont la lib cherchera le token du contexte client lors du décrochage. Valeurs possibles : `parameters | local-storage | session-storage | url-params | shadow-crm`

Par défaut, la lib cherche le token dans les paramètres de l'URL (paramètre `token` ou `projectId`)

Exemple :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// from local storage
(async () => {
  localStorage.setItem('ctxToken', 'my-ctx-client-token');
  // or
  localStorage.setItem('fasstProjectId', 'my-fasst-project-id');

  startApp({
    // ...
    ctxPolicy: 'local-storage'
  });
})();

// from session storage
(async () => {
  sessionStorage.setItem('ctxToken', 'my-ctx-client-token');
  // or
  sessionStorage.setItem('fasstProjectId', 'my-fasst-project-id');

  startApp({
    // ...
    ctxPolicy: 'session-storage'
  });
})();

// as parameter
(async () => {
  const ctx = {
    token: 'my-ctx-client-token',
    // or
    projectId: 'my-fasst-project-id'
  };

  startApp({
    // ...
    ctxPolicy: 'parameters',
    ctx
  });
})();

// default like
// URL: https://my.oav.fasst/?token=my-ctx-client-token
// or
// URL: https://my.oav.fasst/?projectId=my-fasst-project-id
(async () => {
  startApp({
    // ...
    ctxPolicy: 'url-params'
  });
})();
```

**Shadow CRM**

Utiliser la valeur `shadow-crm` pour activer le support du *shadow CRM* lors du décrochage sur l'OAV. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// shadow CRM support
(async () => {
  startApp({
    // ...
    ctxPolicy: 'shadow-crm',
  });
})();
```

Attention, la prise en charge du *Shadow CRM* nécessite également la définition des variables d'environnement suivantes :

:::CodeblockTabs
Env

```none
SHADOW_CRM_URL
SHADOW_CRM_TEAM_API_KEY
```
:::

### ctx

Option disponible à partir de la version 3.4.2

Un objet qui définit le contexte client est attendu en valeur. Doit être utilisé avec l'option `ctxPolicy` définit par `parameters`. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

(async () => {
  const ctx = {
    token: 'my-ctx-client-token',
    // or
    projectId: 'my-fasst-project-id'
  };

  startApp({
    // ...
    ctxPolicy: 'parameters',
    ctx
  });
})();
```

### badRequestPage

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur **400** lors de la navigation sur l'OAV. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// bad request component
const BadRequestPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Bad request!</p>
    </div>
  );
};

(async () => {
  startApp({
    // ...
    badRequestPage: BadRequestPage
  });
})();
```

### unauthorizedPage

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur **401** lors de la navigation sur l'OAV. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// unauthorized component
const UnauthorizedPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Unauthorized!</p>
    </div>
  );
};

// init
(async () => {
  startApp({
    // ...
    unauthorizedPage: UnauthorizedPage
  });
})();
```

### forbiddenPage

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur **403** lors de la navigation sur l'OAV. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// forbidden component
const ForbiddenPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Forbidden!</p>
    </div>
  );
};

// init
(async () => {
  startApp({
    // ...
    forbiddenPage: ForbiddenPage
  });
})();
```

### notFoundPage

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur **404** lors de la navigation sur l'OAV. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// not found component
const NotFoundPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Not found!</p>
    </div>
  );
};

// init
(async () => {
  startApp({
    // ...
    notFoundPage: NotFoundPage
  });
})();
```

### internalServerError

Option disponible à partir de la version 3.4.2

Un composant React ou un élément JSX est attendu en valeur. Ce composant sera chargé lors de la redicrection en cas d'erreur **500** lors de la navigation sur l'OAV. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// internal server error component
const InternalServerErrorPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Internal server error!</p>
    </div>
  );
};

// init
(async () => {
  startApp({
    // ...
    internalServerError: InternalServerErrorPage
  });
})();
```

### redirectOnError

Option disponible à partir de la version 3.4.2

*Boolean*. Permet d'activer ou de désactiver la redirection vers la page d'erreur relative lors d'une erreur HTTP lors de la navigation sur l'OAV. Activé par défaut

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// init
(async () => {
  startApp({
    // ...
    redirectOnError: false
  });
})();
```

### rootDivId

Option disponible à partir de la version 3.4.2

*String*. Permet de définir l'id de l'élément root de l'application client. Par défaut l'id de l'élément root attendu est `fasst-oav-root`

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// index.html file
<!doctype html>
<html lang="fr">
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- change root id here -->
    <div id="my-custom-root-id"></div>
    <script type="module" src="/app/index.jsx"></script>
  </body>
</html>

// init
(async () => {
  startApp({
    // ...
    rootDivId: 'my-custom-root-id'
  });
})();
```

### isBundle

Option disponible à partir de la version 3.4.3

Cette option est corrélée avec l'utilisation de la propriété `bundle` du composant `Router`. [cf Router Component](https://doc.fasst.tech/oip-starter-utils/api-client#RldNt)

*Boolean*, `false` par défaut. Si défini à `true` l'application client sera démarrée en mode *bundle*. Ex. :

```javascript
import { start as startApp } from '@fasstech/oip-starter-utils/app';

// init
(async () => {
  startApp({
    // ...
    isBundle: true
  });
})();
```

# Hook useProcess

À partir de la version 3.4.3, `processHandlers` expose également l'handler `destroyApp` utile en mode *bundle* pour libérer la mémoire lors d'une transition d'un bundle de vues à un autre. `context` contient également une propriété `isBundle` qui indique si l'application client a été démarrée en mode *bundle* ou non.

À partir de la version 3.4.4, `processHandlers` expose également l'handler [onLogout](https://doc.fasst.tech/oip-project-starter/process-handlers#iuTrR) qui permet de détruire la session de navigation actuelle.

Le hook `useProcess` exposé par la lib permet de récupérer le contexte (*Process*) de l'OAV et permet la gestion des transitions et des tâches depuis les composants des vues de l'OAV. Ex. :

:::CodeblockTabs
MyView\.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const MyView = () => {
  const { context, processHandlers } = useProcess();

  const onNext = () => {
    processHandlers.onNext();
  };

  return (
    <div>
      <h2>{context.viewId}</h2>

      <button onClick={onNext}>NEXT</button>
    </div>
  );
};

export default MyView;
```
:::

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/process-handlers) pour plus de détails.

# Composant Router

Le composant `Router` exposé par la lib permet d'initialiser les routes des vues de l'OAV. Ce composant doit être impérativement définit en tant que *children* du composant `App` de l'OAV.&#x20;

## Propriétés

### views

Les vues de l'OAV sont attendues en valeur. Ex. :

:::CodeblockTabs
App.jsx

```javascript
import { Router } from '@fasstech/oip-starter-utils/app';
import views from '../views/client.js';

export const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router views={views} />
      </SomeProvider>
    </>
  );
};
```
:::

### bundle

Propriété disponible à partir de la version 3.4.3

Dans le cas d'un démarrage de l'application client en mode *bundle*, il est alors nécessaire d'utiliser la propriété `bundle` (et non la propriété `views`) pour passer les vues à chargées.

Dans ce cas d'usage, il est également nécessaire de définir l'option `isBundle` à `true` lors de l'appel à la méthode `start` de l'API Client. [cf Option isBundle](https://doc.fasst.tech/oip-starter-utils/api-client#x67eE)

Ex. :

:::CodeblockTabs
App.jsx

```javascript
import { Router } from '@fasstech/oip-starter-utils/app';
import MyBundle from '../views/my-bundle.js';

export const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router bundle={MyBundle} />
      </SomeProvider>
    </>
  );
};
```

my-bundle.js

```javascript
// les imports des composants des vues de l'OAV qui composeront ce bundle
import Home from './home/client/Home';
import Customer from './customer/client/Customer';

// la définition du bundle
export default [
  { component: Home, pathname: '/', viewId: 'home' },
  { component: Customer, pathname: '/customer', viewId: 'customer' }
];
```
:::

### disableQueryStringParams

**Propriété disponible à partir de la version 3.5.0**

Propriété optionnelle `disableQueryStringParams` (boolean) *false* par défaut. Si définie à *true*, le paramètre d'URL *projectId* n'est plus affiché au niveau de l'URL de l'OAV.

Ex. :

:::CodeblockTabs
App.jsx

```javascript
import { Router } from '@fasstech/oip-starter-utils/app';
import views from '../views/client.js';

export const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router views={views} disableQueryStringParams={true} />
      </SomeProvider>
    </>
  );
};
```
:::

# Objet Tokens

L'objet `Tokens` exposé par la lib permet la gestion des credentials et du token d'authentification du client (de l'application React) de l'OAV.

Pour plus de détails concernant l'authentification client se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/auth-et-logique-de-session#xcw2X)

Il n'est logiquement pas nécessaire que le code de l'OAV interagit directement avec cette API

`Tokens` expose 3 méthodes :

- `getAccessToken = async (refresh: boolean) => tokens` : retourne un objet contenant l'*access token* et le *refresh token*. Prend en paramètre optionnel un booléen pour rafraîchir ou non les tokens avant de les retourner (*false* par défaut)
- `setKey = (clientId: string, key: string) => void` : permet de définir les credentials de l'application React *clientId* et *key*. Cette méthode est appelée dans le corps de la méthode `start` pour initialiser l'authentification client
- `setUseToken = (useToken: boolean) => void` : ne pas utiliser cette méthode, comportement indéfini !
