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.
Refonte des filtres de synchronisation : updatedSince devient lastChangedSince (les deux points de terminaison /v1/insurers/claims et /v1/experts/cases) — le filtre porte désormais le nom du champ qu'il filtre (LastChangedAt). Nouveau : lastReportApprovedSince sur /v1/insurers/claims ne renvoie que les sinistres dont la dernière approbation de rapport est au/apres l'instant donné (les sinistres sans rapport approuvé ne correspondent jamais). completedFrom/completedTo restent inchangés et filtrent le moment de la clôture la plus récente.
API Expert : nouveau point de terminaison pour rouvrir un dossier clôturé (POST /v1/experts/cases/{caseId}:reopen, renvoie 204). Les points de terminaison de liste ont reçu des filtres (recherche plein texte q, plages de dates de création/clôture) et un curseur updatedSince pour la synchronisation incrémentale. Les dossiers exposent désormais LastChangedAt ; les sinistres exposent en plus LastReportApprovedAt. Les points de terminaison de création et de téléversement renvoient désormais 201 Created. Chaque réponse renvoie désormais un en-tête X-Correlation-Id (une valeur entrante valide est répercutée) pour le traçage de bout en bout ; en cas d'erreur, il correspond aussi à l'instance ProblemDetails.
Ajout de la nouvelle catégorie « Expertises spéciales », incluant le schéma et la structure de payload.
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). Le jeton d'accès est lié à votre clé DPoP(cnf.jkt) : utilisez une seule clé pour toute la session — la demande de jeton et chaque appel API — et signez déjà la demande de jeton avec une preuve DPoP.
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) avec une preuve DPoP, qui lie le jeton émis à la clé DPoP.
- 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, signé avec la même clé que celle utilisée pour la demande de jeton.
- 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. Une nouvelle preuve est générée par requête et signée (ES256) pour lier la requête à la méthode + URL, mais toujours avec la même clé à laquelle le jeton d'accès est lié (cnf.jkt). Une preuve signée avec une autre clé est rejetée avec 401 "Access token is not bound to the DPoP proof key".
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 :
- •not bound : requête signée avec une clé différente de celle du jeton — réutilisez l'unique clé de session et envoyez une preuve DPoP sur la demande de jeton
- •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
Identifiant de corrélation
Chaque réponse renvoie un en-tête X-Correlation-Id. Claimity utilise le même identifiant dans ses journaux serveur et, en cas d'erreur, comme champ instance du corps application/problem+json — journalisez-le et indiquez-le dans vos demandes de support.
Vous pouvez aussi fournir votre propre identifiant pour tracer une requête de bout en bout : envoyez un en-tête de requête X-Correlation-Id avec un jeton court et imprimable (≤ 80 caractères). Une valeur valide est renvoyée telle quelle ; une valeur invalide ou trop longue est ignorée et Claimity en génère une. L'identifiant de corrélation est indépendant de DPoP (la preuve ne lie que la méthode + l'URL), l'ajout de cet en-tête n'affecte donc pas la signature.
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.
Validation anonyme
POST /v1/insurers/claims:validate est utilisable sans jeton et donc limité plus strictement.
- •FixedWindow : 10 requêtes/minute par client/IP
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.
Idempotence (Idempotency-Key)
Les requêtes POST peuvent porter l'en-tête Idempotency-Key (valeur unique librement choisie, p. ex. un UUID). Si la même requête est répétée — par exemple après un timeout — l'API renvoie la réponse enregistrée sans exécuter l'opération une seconde fois.
- •La clé est liée à la méthode, au chemin, au client et au hash du payload — la même clé avec un payload différent compte comme une nouvelle requête.
- •Les réponses enregistrées sont conservées 24 heures pour le replay.
- •Les corps de requête au-delà de 16 Mo contournent l'idempotence ; les réponses au-delà de 16 Mo ne sont pas enregistrées pour le replay (un retry ré-exécute l'opération).
- •Recommandation : toujours le définir sur POST /v1/insurers/claims — les retries après erreurs réseau sont alors garantis sans doublons.
Catalogue d'erreurs
Les erreurs suivent la structure ProblemDetails (title, status, detail). Les erreurs de validation du payload arrivent en ValidationProblemDetails avec une map errors ; chaque message nomme le chemin du champ et l'attente concrète.
| title | Signification |
|---|---|
| invalid_org_context | Le jeton n'est pas associé à une organisation (unique) du type attendu. |
| forbidden | L'accès à la ressource n'est pas autorisé avec ce jeton. |
| org_without_members | L'organisation n'a aucun membre — création/consultation impossible. |
| invalid_category | Catégorie de sinistre inconnue (autorisées : vehicle, appraiser, fraud, special). |
| invalid_payload | PayloadJson manquant ou JSON invalide. |
| invalid_state | L'action n'est pas autorisée dans le statut actuel du dossier (p. ex. rouvrir un dossier non clôturé). |
| invalid_document / missing_documents | Document invalide ou documents requis manquants. |
| unsupported_content_type / size_limit_exceeded | Type de fichier non autorisé ou limite d'upload dépassée. |
| upstream_timeout / upstream_error | Un service en aval n'a pas répondu (à temps) — retry avec backoff. |
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"PayloadJson": [
"PayloadJson does not match the required schema for the selected category.",
"counterparty.email: is required.",
"workshop.country: must be one of: CH, DE, AT, FR, IT, LI.",
"incidentDate: the incident date cannot be in the future — got 2099-01-15, today is 2026-08-02 (Europe/Zurich)."
]
}
}Experts
Points de terminaison pour les experts pour travailler avec des dossiers, des documents et des soumissions de rapports.
Horodatages & synchronisation incrémentale
Horodatages et filtres de synchronisation (inclusifs >=), nommés d'après le champ qu'ils filtrent :
- CreatedAt — Date de création du sinistre. Filtres : createdFrom / createdTo.
- completedFrom / completedTo filtrent sur le moment de la clôture la plus récente (événement Finalized ; pour les dossiers rouverts, la clôture la plus récente compte). Prévu pour des fenêtres d'analyse (« tous les dossiers clôturés au T2 ») — pas pour la synchronisation.
- LastChangedAt — Dernière modification pertinente pour le partenaire (statut, documents, rapports, commentaires). Filtre : lastChangedSince.
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.
Horodatages & synchronisation incrémentale
Quatre horodatages pilotent le filtrage des listes et la synchronisation. Les filtres de synchronisation portent le nom du champ qu'ils filtrent et comparent inclusivement (>=).
- CreatedAt — Date de création du sinistre. Filtres : createdFrom / createdTo.
- completedFrom / completedTo filtrent sur le moment de la clôture la plus récente (événement Finalized ; pour les dossiers rouverts, la clôture la plus récente compte). Prévu pour des fenêtres d'analyse (« tous les dossiers clôturés au T2 ») — pas pour la synchronisation.
- LastChangedAt — Dernière modification pertinente pour le partenaire (statut, documents, rapports, commentaires). Filtre : lastChangedSince.
- LastReportApprovedAt — Moment de la dernière approbation de rapport (null si aucune). Filtre : lastReportApprovedSince — les sinistres sans rapport approuvé ne correspondent jamais.
Recette de synchronisation (poller quotidien)
- Interroger avec lastChangedSince=<curseur enregistré> (premier passage : sans le filtre).
- Traiter les résultats de manière idempotente — la comparaison est inclusive, la valeur limite peut réapparaître.
- Enregistrer comme nouveau curseur le maximum des LastChangedAt observés.
- Seuls les nouveaux rapports approuvés vous intéressent ? Même déroulement avec lastReportApprovedSince et LastReportApprovedAt.
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