> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.robaws.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# API Robaws

Nous distinguons deux types d'intégrations : une intégration **sur mesure** et une intégration **marketplace**. 

* Une [intégration sur mesure](#2-je-souhaite-construire-une-integration-sur-mesure) est construite pour un client spécifique afin de soutenir un processus propre à ce client. 
* Une [intégration marketplace](#2-je-souhaite-construire-une-integration-marketplace) est une intégration standard mise à la disposition de tous les clients Robaws dans la marketplace des intégrations Robaws. 

La différence entre les deux réside dans la **méthode d'authentification**. Les exigences pour une intégration marketplace sont légèrement plus strictes.

| Découvrez comment accorder l'accès API aux utilisateurs dans [cet article](https://support.robaws.com/fr/article/comment-donner-a-un-utilisateur-lacces-a-lapi-7420v1/).

## Je souhaite construire une intégration sur mesure

Pour les intégrations sur mesure, l'authentification HTTP Basic est la méthode d'authentification recommandée. Nous vous recommandons de créer un utilisateur distinct dans l'environnement Robaws du client. Si vous cochez la case 'API only', l'utilisateur est gratuit. Il est considéré comme une bonne pratique de créer un rôle distinct pour cet utilisateur, en n'accordant l'accès qu'aux modules dont l'intégration a besoin.
Vous devez ensuite créer une clé d'accès pour cet utilisateur. Vous pouvez le faire sur la page de profil. Cette clé d'accès et le secret sont utilisés comme nom d'utilisateur et mot de passe pour l'authentification basique.

###### Pour commencer
* Des tenants de test peuvent être fournis gratuitement pendant 14 jours. Si nécessaire, cette période peut être prolongée.
* Les questions relatives à une nouvelle intégration peuvent être soumises via [ce formulaire](https://robaws.notion.site/0e778aad53ea4398a9b04f56f512cce9).

## Je souhaite construire une intégration marketplace

Pour les intégrations marketplace, le flux OAuth2 Authorization Code est la méthode d'authentification requise. Les exigences sont :

* Vous ne rafraîchissez pas les access tokens tant qu'ils ne sont pas (presque) expirés.
* Vous construisez d'abord l'intégration sur un tenant de test Robaws.
* Pour que votre intégration devienne disponible en production (dans la marketplace Robaws), une vidéo de démonstration sera requise dans laquelle vous démontrez l'intégration.
* Vous devrez nous fournir une URL vers la page où le client peut lancer le flux OAuth2 de votre côté.
* Le polling est déconseillé ! Si votre intégration doit être informée d'un changement qui s'est produit, vous devez utiliser les webhooks.

[Documentation OAuth](https://support.robaws.com/nl/article/oauth-endpoints-1tno5rl/)

###### Pour commencer
* Vous pouvez obtenir un environnement de test gratuit pendant 14 jours. Si nécessaire, cette période peut être prolongée d'un commun accord. Vous trouverez plus d'informations sur l'obtention d'un compte de test via [ce formulaire](https://www.robaws.com/integratie-aanvragen).
* Pour une intégration marketplace, vous aurez besoin d'un client ID & client secret OAuth2. Contactez-nous pour obtenir les identifiants via [ce formulaire](https://www.robaws.com/integratie-aanvragen).


## Documentation de référence

https://app.robaws.com/public/api-docs/robaws

Votre intégration API doit tenir compte des en-têtes de réponse de rate limiting de Robaws. Les erreurs HTTP 429 seront surveillées. Si elles se produisent trop souvent, l'équipe Robaws interviendra pour bloquer temporairement l'intégration jusqu'à ce que vous fournissiez une solution. Plus de détails sur le rate limiting sont disponibles dans la documentation de référence.


## Mises à jour

Voir le [changelog API](https://support.robaws.com/fr/article/api-changelog-qkm5g2/)


## Sujets spécifiques

[Webhooks](https://support.robaws.com/fr/article/webhooks-zfcg3m/)
[Idempotence des requêtes](https://support.robaws.com/fr/article/request-idempotency-1l885ya/)
[Rate limiting de l'API](https://support.robaws.com/fr/article/api-rate-limiting-19bcizp/)
[Filtrage, pagination et tri de l'API](https://support.robaws.com/fr/article/api-filtrage-pagination-tri-1bu5jpw/)
[Mise à jour des informations (PUT vs PATCH)](https://support.robaws.com/fr/article/updating-information-put-vs-patch-jr3jdq/)
[Envoi de fichiers](https://support.robaws.com/fr/article/uploading-files-tver66/)



## Exemples de cas d'usage

* [Créer un bon de travail](https://support.robaws.com/fr/article/creer-un-bon-de-travail-20kqje/)
* [Synchroniser les données d'articles avec votre propre base de données](https://support.robaws.com/fr/article/synchroniser-les-donnees-darticles-avec-votre-propre-base-de-donnees-rfui33/)

### Exemple : créer un client/lead à partir d'un formulaire de site web

Si un client possède un site web avec un formulaire de contact, il peut être pratique d'intégrer ce formulaire à l'API Robaws afin que les soumissions entrantes soient créées directement comme client dans Robaws.

Robaws vous permet d'ajouter des champs personnalisés à la plupart de ses entités. Cette fonctionnalité s'appelle « extra fields » (champs supplémentaires) et porte le même nom dans l'API. Si vous avez défini un ou plusieurs extra fields sur le module client, vous pouvez les remplir directement lors de la création du client avec une requête `POST /api/v2/clients` :

```
POST https://app.robaws.com/api/v2/clients
Authorization: Basic <base64(accessKey:secret)>
Content-Type: application/json

{
    "name": "John Doe",
    "extraFields": {
        "Contact via": {
            "stringValue": "Social media"
        }
    }
}
```

Chaque appel `/api/v2` doit être authentifié. Pour une intégration sur mesure, utilisez l'authentification HTTP Basic avec la clé d'accès et le secret d'un utilisateur API dédié. Les intégrations marketplace utilisent à la place un bearer token OAuth 2.

Par défaut, l'objet `extraFields` est indexé sur le **libellé** de l'extra field ; renommer un champ dans les paramètres casse donc votre intégration. Pour l'indexer plutôt sur la référence interne stable, envoyez l'en-tête `x-robaws-extra-fields-mode: id`.

La propriété de valeur à utiliser dépend du type de champ :

| Type d'extra field (FR / EN) | Propriété API |
| --- | --- |
| Texte / Text | `stringValue` |
| Champ de texte / Long text | `stringValue` |
| Boîte combo / Select | `stringValue` |
| Lien / URL | `stringValue` |
| E-mail / Email | `stringValue` |
| Téléphone / Telephone | `stringValue` |
| Date / Date | `dateValue` (par ex. `2020-12-17`) |
| Nombre décimal / Decimal | `decimalValue` |
| Entier / Integer | `integerValue` |
| Case à cocher / Checkbox | `booleanValue` |
| Client / Client | `clientValueId` (l'id du client) |
| Fournisseur / Supplier | `supplierValueId` (l'id du fournisseur) |

|| Remarque : il n'existe pas d'enregistrement « lead » distinct dans Robaws. Un lead est simplement une valeur de `status` sur le client ; un lead et un client sont donc la même entité. Pour créer le client directement comme lead, ajoutez le statut au payload, en utilisant une des valeurs de statut configurées dans vos paramètres clients : `{ "name": "John Doe", "status": "Lead", "extraFields": { ... } }`