API partenaires Ematea

Contrat HTTP v1 pour créer un dossier, lancer le comparateur, analyser des documents et reprendre un dossier dans Ematea.

Base URL
https://ematea.fr/extranet/api/v1

API serveur à serveur. Ne mettez jamais une clé dans du JavaScript navigateur, une application mobile ou un dépôt de code.

Authentification, droits et isolation

Chaque appel protégé passe la clé délivrée pour le cabinet dans l’en-tête HTTP :

Authorization: Bearer emt_live_votre_cle

La clé est liée à un seul cabinet Ematea. Le cabinet n’est jamais pris dans le JSON : toutes les lectures, créations et tarifications sont forcées côté serveur sur celui de la clé.

DroitAutorise
tarifsComparateur multi-fournisseurs.
ocrDépôt et analyse de documents de prêt.
dossiersCréation idempotente et lecture des dossiers du cabinet.
ssoLien de reprise à usage unique vers Ematea.

La désactivation globale, le blocage de la clé ou la suspension du cabinet bloque les appels sans délai. La limite par minute est configurée par clé (1 à 240).

Exception Courtigo : la clé d’intégration couvre plusieurs cabinets. Courtigo transmet le cabinet et l’utilisateur issus de sa session dans X-Courtigo-Cabinet et X-Courtigo-User. Les routes PDF Courtigo utilisent le droit dossiers et exigent ces deux en-têtes.

Cycle d’intégration conseillé

  1. Créez un brouillon avec votre référence externe stable.
  2. Envoyez ce dossier_id au comparateur.
  3. Envoyez si besoin l’offre de prêt ou le tableau d’amortissement à l’OCR.
  4. Créez un lien SSO pour ouvrir le dossier et le finaliser dans Ematea.
Un fournisseur sans accès disponible pour ce cabinet, sans sous-code validé ou désactivé dans ses préférences n’est jamais appelé pendant une tarification.

Dossiers

POST/dossiers.php droit dossiers

Crée un brouillon pour le cabinet de la clé. La paire clé API + external_reference rend l’opération idempotente : une nouvelle tentative retourne le même dossier.

POST https://ematea.fr/extranet/api/v1/dossiers.php
Authorization: Bearer emt_live_votre_cle
Content-Type: application/json

{
  "external_reference": "partenaire-4182",
  "formData": {
    "projectType": "residence_principale", "loanType": "change", "bankId": "credit-agricole", "date_effet": "2026-10-01",
    "borrowers": [{
      "id": 1, "gender": "F", "firstName": "Jeanne", "lastName": "Martin", "birthDate": "1985-05-10", "postCode": "75001", "job": 1,
      "email": "jeanne.martin@example.fr", "phone": "0600000000", "smoker": false, "travelKm": "lt15", "heights": false, "manual": false, "sport": false, "riskyJob": false, "isPPE": false,
      "guarantees": [{"loan_id":1,"quotite":100,"type":"dc_ptia_itt_ipt","ipp":true,"mno":true,"franchise":90}]
    }],
    "loans": [{"id":1,"type":"amortissable","amount":250000,"duration":240,"rate":3.45,"deferred":0}]
  }
}
ChampRequisNotes
external_referenceouiVotre identifiant unique, maximum 191 caractères.
formData.borrowers[0].firstName, lastName, emailouiLe premier emprunteur est nécessaire. phone et quota sont optionnels.
formData.loansouiAu moins un prêt. Alias acceptés : montant, duree_mois, taux, differe_mois.
bankId, date_effetnonDate au format YYYY-MM-DD.

Réponse 201 (ou 200 si la référence existe déjà) :

{
  "ok": true,
  "data": {"dossier_id": 123, "created": true, "external_reference": "partenaire-4182"}
}

GET/dossiers.php?id=123 droit dossiers

Lit uniquement un dossier du cabinet de la clé.

{
  "ok": true,
  "data": {
    "id": 123, "status": "simulation", "montant_total": "250000.00",
    "banque_nom": "credit-agricole", "nb_assures": 1, "date_effet": "2026-10-01",
    "nom_produit_final": null, "last_step": 1,
    "created_at": "2026-09-23 10:15:00", "updated_at": "2026-09-23 10:15:00"
  }
}

Contrat formData complet

Pour une tarification partenaire, le profil est volontairement strict : Ematea refuse les valeurs par défaut silencieuses. Envoyez le même payload que le comparateur.

BlocChamps requis
RacineprojectType, loanType, bankId, date_effet au format YYYY-MM-DD.
loans[]id, amount, duration (mois), type, rate, deferred. Les alias durationMonths et deferredMonths sont acceptés.
borrowers[]Un ou deux assurés. Pour chacun : gender (M ou F), firstName, lastName, birthDate, postCode, job (code 1 à 13), email, smoker, travelKm, heights, manual, sport, riskyJob, isPPE.
borrowers[].guarantees[]Une entrée par prêt : loan_id, quotite, type, ipp, mno, franchise (30, 60, 90, 120 ou 180).
Options conservéesphone, birthName, birthCity, birthPostalCode, nationality, address, cityName, isPPEFamily, ainsi que les informations banque et assurance actuelle.

travelKm vaut lt15, 15_20, 20_25 ou gt25. Chaque fournisseur applique ensuite son propre seuil de déclaration.

POST et PUT créent ou remplacent le brouillon identifié par external_reference. La répétition est idempotente : aucun doublon n’est créé, mais les assurés, garanties et prêts du brouillon sont synchronisés avec le dernier payload.

PATCH/dossiers.php droit dossiers

Deux actions complètent le parcours sans modifier le profil :

{
  "action": "select_offer",
  "dossier_id": 123,
  "selected_offer": {"source_api":"simulassur","nom_produit":"Generali 7305","porteur_risque":"Generali","mensualite":32.4,"cout_total":7776}
}

{
  "action": "attach_documents",
  "dossier_id": 123,
  "batch_token": "jeton_retourne_par_l_ocr"
}

La première enregistre l’offre retenue. La seconde rattache les documents OCR du lot au dossier et au premier assuré.

La lecture GET /dossiers.php?id=... retourne le formData canonical, les assures synchronises, les loans, l'offre choisie, le compteur d'offres tarifees et les metadonnees des documents rattaches. Aucun dossier d'un autre cabinet ne peut etre lu.

Comparateur multi-fournisseurs

POST/tarification.php droit tarifs

Le body est le formData des dossiers, directement ou enveloppé dans {"formData": {...}}. Ajoutez dossier_id pour rattacher et sauvegarder les offres. Les alias durationMonths et deferredMonths sont pris en charge.

{
  "dossier_id": 123,
  "projectType": "residence_principale",
  "loanType": "change",
  "bankId": "credit-agricole",
  "date_effet": "2026-10-01",
  "borrowers": [{"gender":"F","firstName":"Jeanne","lastName":"Martin","birthDate":"1985-05-10","postCode":"75001","job":1,"email":"jeanne.martin@example.fr","smoker":false,"travelKm":"lt15","heights":false,"manual":false,"sport":false,"riskyJob":false,"isPPE":false,"guarantees":[{"loan_id":1,"quotite":100,"type":"dc_ptia_itt_ipt","ipp":true,"mno":true,"franchise":90}]}],
  "loans": [{"id":1,"amount":250000,"duration":240,"type":"amortissable","rate":3.45,"deferred":0}]
}

La réponse est un flux Content-Type: text/event-stream. Chaque message utilise ce format :

event: tarif
data: {"type":"tarif","data":{...}}

EvenementDonnees
startnb_produits, frais_par_assure, nb_assures, fournisseurs, code_commission.
tarifUne offre au fil de l’eau. Champs usuels : source_api, nom_produit, porteur_risque, mensualite, cout_total, taea, garanties, formalites. Ignorez les champs supplémentaires inconnus.
progressAvancement, sans valeur de résultat final.
donenb_offres, dossier_id, garanties_rejetees, puis un diagnostic par source : ugip, simulassur, exade, utwin, zenioo. Le diagnostic peut comporter configure, nb, erreur, acces.
error{"message":"..."}, suivi de done vide si le flux ne peut pas démarrer.
Attendez done avant de considérer la recherche terminée. Une absence d’offre n’est pas une erreur : consultez les diagnostics.

Logos des offres Courtigo

Chaque offre des événements SSE tarif et de GET /dossiers.php?id=123&include=offers expose logo_url, le logo de l’assureur (porteur_risque), et provider_logo_url, celui du grossiste (source_api). Ces champs sont également disponibles dans selected_offer, même sans include=offers.

{
  "porteur_risque": "AXA", "source_api": "ugip",
  "logo_url": "https://ematea.fr/public/images/logos/axa.png",
  "provider_logo_url": "https://ematea.fr/assets/logos/ugip.png"
}

URLs absolues publiques, utilisables directement dans une image sans clé API. Formats PNG ou SVG. Un logo inconnu ou absent vaut null : afficher le nom correspondant. Les logos sont résolus à la lecture, y compris pour les offres déjà enregistrées ; aucune nouvelle tarification n’est nécessaire. Sans offre retenue, selected_offer reste null.

PDF de devis et de comparatif Courtigo

POST/documents.php Courtigo · droit dossiers

Réservé à la clé d’intégration Courtigo. Envoyez Authorization: Bearer …, X-Courtigo-Cabinet avec le cabinet_id obtenu à l’activation, et X-Courtigo-User avec l’utilisateur connecté. Ces trois en-têtes sont requis à la génération et au téléchargement. Le serveur contrôle l’appartenance du dossier et les droits du collaborateur.

Après la fin de la tarification, générez un devis avec une offre, ou un comparatif avec deux à quatre offres distinctes. Utilisez les offer_id de la dernière tarification enregistrée, pas les id_produit. La sélection ne change pas l’offre retenue dans le dossier.

{"dossier_id":123,"type":"devis","offer_ids":["e621c447ea774a67b93b290478f83f29"]}

{"dossier_id":123,"type":"comparatif","offer_ids":["e621c447ea774a67b93b290478f83f29","c42d95216354fdf79f2bcdfaa8cc0e11"]}

Le profil, les prix et les garanties sont chargés côté Ematea. Le rendu utilise les modèles commerciaux et la marque blanche du cabinet. Réponse synchrone 201 Created ; Location contient l’URL de téléchargement. Exemple (taille et empreinte illustratives) :

{
  "ok": true,
  "data": {
    "document_id": 456, "dossier_id": 123, "type": "devis",
    "offer_ids": ["e621c447ea774a67b93b290478f83f29"],
    "priced_at": "2026-11-10T14:00:00.000000+01:00",
    "filename": "Devis_123_456.pdf", "content_type": "application/pdf",
    "size_bytes": 84231,
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "download_url": "https://ematea.fr/extranet/api/v1/documents.php?id=456"
  }
}

Conservez document_id. Chaque POST crée une archive ; réutilisez GET pour retélécharger les mêmes octets. Aucun e-mail ou transfert vers l’assureur n’est déclenché.

GET/documents.php?id=456 Courtigo · droit dossiers

Le serveur Courtigo appelle download_url avec les trois en-têtes d’authentification, puis relaie le fichier à l’utilisateur autorisé. Cette URL n’est pas un lien public. Réponse 200 OK, corps PDF binaire, Content-Type: application/pdf, Content-Disposition: attachment; filename="Devis_123_456.pdf" et Content-Length. Pour un comparatif : Comparatif_123_456.pdf.

Les réponses portent Cache-Control: private, no-store et X-Request-Id. L’archive est conservée après retarification ou modification du dossier ; l’accès est revérifié à chaque requête, y compris pour les dossiers supprimés.

HTTP / code JSONSituation
401 unauthorizedClé absente, invalide ou révoquée.
403 forbiddenClé non Courtigo, droit manquant, cabinet ou utilisateur absent/non autorisé.
404 not_foundDossier, document ou archive inaccessible/introuvable.
405 method_not_allowedUtiliser GET ou POST.
400 invalid_json / 422 invalid_requestJSON ou identifiant mal formé, type inconnu, sélection vide, doublons ou mauvais nombre d’offres.
409 conflictTarification absente, offre remplacée/inconnue ou tarification modifiée pendant le rendu. Relire les offres, retarifer si nécessaire, puis réessayer.
429 rate_limitedRespecter Retry-After.
503 document_unavailableRendu, stockage ou intégrité du PDF indisponible.

Les erreurs communes de disponibilité de l’API restent applicables. Vérifiez le statut et le type de contenu : une erreur renvoie du JSON, jamais un PDF.

OCR de documents de prêt

POST/ocr.php droit ocr

Envoyez un multipart/form-data, pas du JSON. Taille maximale : 12 Mo. Formats : PDF, JPG, PNG.

ChampRequisValeurs
documentouiLe fichier.
type_documentnonauto, offre_pret, tableau_amortissement.
upload_token / batch_tokennonJeton à réutiliser pour grouper les fichiers d’un même dossier.
curl -X POST "https://ematea.fr/extranet/api/v1/ocr.php" \
  -H "Authorization: Bearer emt_live_votre_cle" \
  -F "document=@offre.pdf" \
  -F "type_document=offre_pret"

Réponse :

{
  "status": "success", "document_id": 456,
  "upload_token": "token_de_lot", "batch_token": "token_de_lot",
  "data": {"...": "donnees extraites"},
  "completeness": {"...": "champs presents"},
  "quality": {"...": "indicateurs de qualite"},
  "_debug": {"...": "informations techniques optionnelles"}
}

data varie selon le document. Traitez les valeurs comme des propositions OCR à confirmer avant tarification.

Reprise automatique dans Ematea

POST/sso.php droit sso

Crée une URL à usage unique qui connecte le compte courtier choisi et ouvre le dossier. Le compte doit appartenir au même cabinet et être actif. courtier_user_id est facultatif seulement si un compte de reprise par défaut est configuré sur la clé.

{"dossier_id":123,"courtier_user_id":45}

{
  "ok": true,
  "data": {"dossier_id": 123, "expires_in": 300, "launch_url": "https://.../extranet/sso.php?token=..."}
}
Sensible : le lien expire dans 5 minutes, ne fonctionne qu’une fois et ouvre une session. Ne le journalisez pas, ne l’envoyez pas par email et ne le chargez pas dans une iframe.

Codes, erreurs et support

Les erreurs JSON suivent ce format :

{"ok":false,"error":{"code":"invalid_request","message":"..."}}
HTTPCode courantAction
400invalid_json, invalid_requestCorriger le JSON ou les paramètres.
401unauthorizedVérifier la clé et l’en-tête Bearer.
403forbiddenLe droit de la clé ou le compte SSO ne convient pas.
404not_foundLe dossier n’est pas dans le cabinet de la clé.
405method_not_allowedUtiliser la méthode documentée.
409 / 422conflict, invalid_requestCorriger le conflit ou les champs métier.
429rate_limitedRespecter Retry-After, puis réessayer.
500 / 503internal_error, api_disabled, api_not_initializedBackoff, puis support si le problème persiste.

Conservez l’en-tête X-Request-Id retourné sur les endpoints JSON et communiquez-le au support Ematea. N’envoyez jamais de clé API ni de document dans un ticket.

Compatibilité et sécurité