Claimity API
Documentation API
Référence technique et guides pour l'intégration avec Claimity.
Vue d'ensemble
L'API utilise des méthodes HTTPS et des points de terminaison RESTful pour créer, modifier et gérer des ressources dans le système. JSON est utilisé comme format d'échange.
Premiers pas
Cette API offre un accès complet aux fonctions principales. Qu'il s'agisse d'intégrations, d'automatisation ou d'applications personnalisées, l'API offre la flexibilité nécessaire pour connecter Claimity à vos systèmes.
Extension des interfaces
- •Consultez régulièrement le journal des modifications pour rester à jour.
- •Des modifications non rétrocompatibles peuvent être introduites sans changer la version de l'API.
- •Vous serez informé à temps des changements importants.
Premiers pas
Comment démarrer avec l'API :
Créer une paire de clés
En tant qu'administrateur de l'organisation, vous pouvez créer une paire de clés dans les paramètres de l'organisation de votre compte Claimity. Ensuite, téléchargez la clé privée et conservez-la en lieu sûr.
S'authentifier
À l'aide de la paire de clés créée et de votre identifiant client, vous pouvez vous authentifier auprès de l'API Claimity et ainsi obtenir un jeton d'accès pour vos requêtes.
Préparer l'en-tête DPoP
Pour envoyer une requête à l'API, il est nécessaire de créer un en-tête DPoP. Cet en-tête est signé avec la clé privée et sécurise la requête contre les risques de sécurité potentiels.
Première requête
Envoyez une requête authentifiée à un point de terminaison avec votre jeton d'accès et l'en-tête DPoP.
Exemple de requête
curl -X GET \
https://app.claimity.ch/v1/experts/cases \
-H 'Accept: application/json' \
-H 'Authorization: DPoP {access-token}' \
-H 'DPoP: {dpop-header}Notebooks Python
Pour un démarrage rapide, nous mettons à votre disposition des notebooks Python avec lesquels vous pouvez exécuter des requêtes API et consulter directement les réponses.
Voir les notebooks sur GitHubSignaler un problème
Si vous avez rencontré une erreur, nous vous aiderons. Assurez-vous au préalable que le problème est reproductible.
Avant de signaler
- ✓Vérifier la reproductibilité
- ✓Effectuer des tests API avec Postman/Insomnia
- ✓Recueillir des détails sur la requête et la réponse
- ✗Ne pas envoyer de données d'accès dans le rapport
Soumettre un rapport
Veuillez décrire les étapes pour reproduire. Notre support examinera le cas rapidement et vous répondra dès que possible.
Signaler un problèmeRemarque : L'API est fournie sur la base de cette documentation. Il n'y a pas d'implémentation guidée ou de support de code.
Journal des modifications
Toutes les modifications et mises à jour de la version actuelle de l'API en un coup d'œil.
Ajout d'un nouveau point de terminaison à l'API assureur pour valider la structure du dossier.
Première version de l'API publiée.
Authentification
L'API Partenaire Claimity utilise **OAuth 2.0 Client Credentials** avec **JWT Client Assertion (RS256)** et sécurise chaque requête avec **DPoP Proof-of-Possession (ES256)**. Cela lie le jeton d'accès à la requête spécifique.
Flux d'authentification
Comment fonctionne le flux OAuth2 Client-Credentials.
Processus
- Paire de clés : L'organisation crée une paire de clés RSA dans Claimity (la clé privée est stockée en toute sécurité).
- JWT Client Assertion : Le client génère un JWT de courte durée (RS256).
- Demande de jeton : Le client envoie POST /v1/oauth/token (Client-Credentials + Assertion).
- Validation : Le serveur d'authentification vérifie la signature de l'assertion et les autorisations et renvoie la réponse du jeton.
- URL de requête : Le client crée l'URL de requête (y compris les paramètres de requête).
- Preuve DPoP : Le client crée un JWT DPoP (ES256) par requête lié à la méthode + URL.
- Appel API : Le client appelle le point de terminaison avec Authorization: DPoP access_token et DPoP: ….
- Réponse : L'API vérifie le jeton/DPoP et traite la demande / renvoie la réponse.
Lire le jeton d'accès
Pour les intégrations partenaires, votre organisation s'authentifie via une JWT Client Assertion signée.
Prérequis
- •Client ID (par ex. org-expo-00001) lisible dans les paramètres de l'organisation Claimity
- •Clé privée RSA des paramètres de l'organisation Claimity (à conserver en lieu sûr et ne jamais partager)
Point de terminaison de jeton
| URL | POST https://app.claimity.ch/v1/oauth/token |
| Content-Type | application/x-www-form-urlencoded |
| Champs de formulaire | grant_type = client_credentials client_id = <Votre client id> client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-bearer client_assertion = <JWT (RS256)> scope (optionnel) |
URL
Content-Type
Champs de formulaire
JWT Client Assertion (RS256)
L'assertion est un JWT de courte durée (10 minutes) et est signée avec votre clé privée RSA.
- •iss/sub = client_id
- •aud = https://app.claimity.ch/realms/claimity/protocol/openid-connect/token
- •jti = UUID (unique)
- •iat/exp = “now” / “now+90s”
- •kid (optionnel)
curl -X POST \
'https://app.claimity.ch/v1/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'client_id=org-expo-00001' \
-d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
-d 'client_assertion=<RS256-JWT-CLIENT-ASSERTION>' \
-d 'scope=roles'Réponse du jeton
La réponse contient un access_token. Important : Pour les appels API, ce jeton est utilisé comme jeton DPoP.
Envoyer des requêtes API
Chaque requête nécessite en plus un JWT de preuve DPoP. Celui-ci est généré par requête et signé (ES256) et lie la requête à la méthode + URL.
En-têtes requis
| Authorization | DPoP {access_token} |
| DPoP | {dpop_proof_jwt} |
| Accept | application/json |
| Content-Type | application/json |
Authorization
DPoP
Accept
Content-Type
Contenu de la preuve DPoP
- •htu doit être l'URL exacte y compris la chaîne de requête
- •htm doit correspondre exactement à la méthode HTTP (GET/POST/PUT/DELETE)
- •jti doit être nouveau par requête (pas de relectures)
- •iat doit être dans la fenêtre de temps autorisée (éviter le décalage d'horloge)
- •ath = base64url(SHA-256(access_token))
curl -X GET \
'https://app.claimity.ch/v1/experts/cases?page=1&size=50' \
-H 'Accept: application/json' \
-H 'Authorization: DPoP {access_token}' \
-H 'DPoP: {dpop_proof_jwt}'Dépannage : 401 invalid_dpop
Causes courantes :
- •htu mismatch : L'URL doit être exacte y compris la requête
- •htm mismatch : La méthode doit correspondre
- •iat hors fenêtre : Corriger l'heure système
- •replay : jti doit être nouveau par requête
- •ath mismatch : SHA-256(access_token) base64url
Bases de l'API
Concepts et conventions de base utilisés dans toute l'API.
Format de requête
Chaque requête se compose de **Méthode**, **URL**, **Paramètres de requête** optionnels, **En-têtes** et (pour POST/PUT) un Corps JSON.
Structure de l'URL
Méthodes HTTP
En-têtes typiques
- •Accept: application/json
- •Content-Type: application/json (pour le corps JSON)
- •Authorization: DPoP <access_token>
- •DPoP: <dpop_proof_jwt>
Format de réponse
Les réponses sont généralement en JSON (Content-Type: application/json) et utilisent des codes d'état HTTP pour signaler le succès/l'erreur.
Réponses de succès
- •2xx (par ex. 200, 201, 204)
- •Le corps contient généralement un objet ou une liste
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "…",
"…": "…"
}Réponses d'erreur (ProblemDetails)
- •4xx/5xx (par ex. 400, 401, 403, 404, 429, 500)
- •Le corps suit une structure de type ProblemDetails
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "…"
}Limitation de débit
L'API Partenaire est protégée par une limitation de débit pour garantir une utilisation équitable et la stabilité. Les limites sont appliquées par partition client.
Standard pour l'API Partenaire
Pour les points de terminaison standard, le nombre de requêtes est légèrement limité.
- •TokenBucket : env. 60 Requêtes/Minute, Rafale jusqu'à 20, File d'attente 0
Routes de documents
Pour les points de terminaison avec .../documents..., des limites plus strictes s'appliquent (par ex. pour le téléchargement).
- •TokenBucket : env. 20 Requêtes/Minute, Rafale jusqu'à 10, File d'attente 0
Point de terminaison de jeton
Le point de terminaison de jeton est strictement limité pour empêcher d'éventuelles attaques.
- •Fenêtre fixe : 10 Requêtes/Minute par Client
Lorsqu'une limite est atteinte (HTTP 429)
- •Réponse : 429 Too Many Requests (Code de rejet 429)
- •En-tête optionnel : Retry-After
- •Indice de diagnostic/politique : X-RateLimit-Policy
- •Corps : JSON Problème
Recommandations pour les clients
- •Réessayer les requêtes 429 avec backoff et respecter Retry-After.
- •Limiter les téléchargements de documents.
- •Les rafales sont limitées (pas de file d'attente) – une forte parallélisation entraîne plus rapidement des 429.
Experts
Points de terminaison pour les experts pour travailler avec des dossiers, des documents et des soumissions de rapports.
Dossiers
Documents du dossier
Rapports & Soumissions
Documents de soumission
Assureurs
Points de terminaison pour les assureurs pour créer/valider/récupérer des sinistres, des documents et des aperçus de rapports.
Sinistres
Documents de sinistre
Rapports sur les sinistres
Structure du dossier & Validation
Chaque catégorie décrit précisément quels champs le payloadJson peut contenir.
Catégorie
Expert automobile
Cette structure est destinée aux charges utiles pour la catégorie Expert automobile.
Expert automobile
Tester PayloadJson directement
Envoyez une requête à l'API de validation Claimity et obtenez un retour immédiat sur votre charge utile.
Attend une structure JSON valide.
Réponse
PrêtLa réponse de l'API de validation apparaît ici.
- Sélectionner une catégorie
- Insérer le JSON de charge utile ou utiliser l'exemple
- Valider la charge utile