YAPU SNAP — API de risque climatique brut

YAPU SNAP est l'API REST autonome de YAPU pour l'évaluation du risque climatique physique au niveau de l'emprunteur. Elle accepte une coordonnée géographique, un ensemble de secteurs économiques actifs et des paramètres de sensibilité spécifiques à chaque secteur, et retourne des scores de risque climatique structurés — Exposition, Sensibilité et un Risque Net Global — pour cinq types d'aléas climatiques, par secteur, en temps réel.

YAPU SNAP est conçue spécifiquement pour les institutions financières ayant besoin d'intégrer une intelligence standardisée du risque climatique dans leurs flux d'origination de prêts ou de surveillance de portefeuille, sans nécessiter la plateforme YAPU complète.

:::tip Environnement sandbox Un environnement sandbox est disponible pour les tests d'intégration. Contactez votre spécialiste d'intégration YAPU pour obtenir la clé API sandbox — n'utilisez pas les identifiants de production pour les tests. :::

Comment ça fonctionne

Votre système envoie une requête POST contenant :

Informations personnelles — identification de l'emprunteur (renvoyée en écho dans la réponse)
Activités économiques — les secteurs à évaluer (Yes / No par type d'activité)
Exposition — les coordonnées géographiques de la localisation du prêt
Sensibilité — paramètres détaillés pour chaque secteur actif (types de cultures, espèces animales, matériaux de construction, etc.)

L'API effectue une recherche géospatiale d'aléas climatiques aux coordonnées soumises et calcule des scores de risque climatique pour chaque secteur actif. Les secteurs non inclus dans loan_purposes avec la valeur "Yes" ne sont pas évalués.

[Votre système]
  │  POST /api/v2/fge/single/execute  (Bearer token + payload JSON complet)
  ▼
[Passerelle API]
  │  Authentifie le token · Valide le payload
  ▼
[Moteur climatique]
  │  Recherche géospatiale d'aléas (5 aléas) · Résout l'Exposition par coordonnées
  │  Résout la Sensibilité par secteur actif + paramètres soumis
  ▼
[Couche de réponse]
  │  Regroupe les scores par secteur + risque net global · Renvoie les champs d'entrée en écho
  ▼
[Votre système]
  │  Reçoit le JSON structuré → affichage ou traitement en aval

URLs de base

Environnement	URL de base
Sandbox	`https://yapu-development-su.herokuapp.com`
Production	Fournie par votre responsable de compte YAPU lors de la validation en production

Authentification

Toutes les requêtes nécessitent un Bearer token valide dans l'en-tête Authorization. Les tokens sont émis par institution et par environnement — les clés sandbox et production ne sont pas interchangeables.

Authorization: Bearer <your_api_key>
Content-Type: application/json

:::warning Sécurisez votre clé API Les clés API confèrent des privilèges d'accès complets. Ne codez jamais une clé en dur dans le code source, ne la commitez jamais dans un système de contrôle de version et ne l'exposez jamais dans du code côté client. Les clés sont disponibles auprès de votre administrateur YAPU et peuvent être renouvelées sur demande. :::

Consultez Authentification et sécurité pour l'architecture de sécurité complète.

Endpoint

`POST /api/v2/fge/single/execute`

Soumet les informations de l'emprunteur, les secteurs économiques actifs, les coordonnées géographiques et les paramètres de sensibilité par secteur. Retourne les scores d'Exposition et de Sensibilité par secteur pour cinq types d'aléas climatiques, ainsi qu'un score de Risque Net Global.

En-têtes de requête

En-tête	Obligatoire	Valeur
`Authorization`	Oui	`Bearer <api_key>`
`Content-Type`	Oui	`application/json`

Structure du corps de la requête

Le corps de la requête comporte quatre sections de premier niveau :

Section	Obligatoire	Description
`personal_details`	Oui	Champs d'identification de l'emprunteur — renvoyés en écho dans la réponse
`economic_activities`	Oui	Définit les secteurs économiques à évaluer
`exposure`	Oui	Coordonnées géographiques de la localisation du prêt ou de l'actif
`sensitivity`	Oui	Paramètres spécifiques à chaque secteur utilisés pour calculer les scores de sensibilité

`personal_details`

Champ	Type	Description
`name`	string	Prénom de l'emprunteur
`last_name`	string	Nom de famille de l'emprunteur
`client_id_number`	string	Identifiant de l'emprunteur dans le système client
`gender`	string	Genre de l'emprunteur (`"Male"` ou `"Female"`)

`economic_activities.loan_purposes`

Définit les secteurs inclus dans l'évaluation du risque climatique. Définissez chaque secteur sur "Yes" pour l'inclure, ou omettez / définissez sur "No" pour l'exclure.

Champ	Type	Valeurs	Description
`agriculture`	string	`"Yes"` / `"No"`	Inclure l'agriculture basée sur les cultures dans l'évaluation
`livestock`	string	`"Yes"` / `"No"`	Inclure l'élevage / l'zootechnie
`trade`	string	`"Yes"` / `"No"`	Inclure les activités commerciales
`services`	string	`"Yes"` / `"No"`	Inclure les activités du secteur des services
`manufacturing`	string	`"Yes"` / `"No"`	Inclure les activités manufacturières
`housing`	string	`"Yes"` / `"No"`	Inclure le logement résidentiel

`exposure`

Champ	Type	Obligatoire	Description
`geolocation`	string	Oui	Coordonnées géographiques au format `"latitude,longitude"` en degrés décimaux (WGS84). Latitude : `-90.0` à `90.0`. Longitude : `-180.0` à `180.0`.

`sensitivity`

La section sensibilité contient une sous-section par secteur. N'incluez les sous-sections que pour les secteurs définis sur "Yes" dans loan_purposes. Les secteurs non utilisés sont ignorés.

sensitivity.agriculture — jusqu'à trois cultures :

Champ	Description
`crop_1.name`, `crop_2.name`, `crop_3.name`	Noms des espèces de cultures. Doivent correspondre aux valeurs de la liste de taxonomie YAPU.

sensitivity.livestock — jusqu'à trois types d'élevage :

Champ	Description
`item_1.name`, `item_2.name`, `item_3.name`	Noms des espèces animales. Doivent correspondre aux valeurs de la liste de taxonomie YAPU.

sensitivity.trade — jusqu'à trois activités commerciales :

Champ	Description
`activity_1.name`, `activity_2.name`, `activity_3.name`	Noms des activités commerciales. Doivent correspondre aux valeurs de la liste de taxonomie YAPU.

sensitivity.services — jusqu'à trois activités de services :

Champ	Description
`service_1.name`, `service_2.name`, `service_3.name`	Noms des types de services. Doivent correspondre aux valeurs de la liste de taxonomie YAPU.

sensitivity.manufacturing — jusqu'à trois activités manufacturières :

Champ	Description
`activity_1.name`, `activity_2.name`, `activity_3.name`	Noms des activités manufacturières. Doivent correspondre aux valeurs de la liste de taxonomie YAPU.

sensitivity.housing — paramètres de construction physique :

Champ	Description
`construction_quality`	Qualité générale de la construction (p. ex. `"Formal"`, `"Informal"`)
`foundation_type`	Type de fondation (p. ex. `"Shallow"`, `"Deep"`)
`walls_type`	Type structurel des murs (p. ex. `"Reinforced"`, `"Unreinforced"`)
`roof_type`	Type structurel de la toiture
`foundation_material`	Matériau de la fondation (p. ex. `"Concrete"`, `"Wood"`)
`wall_material`	Matériau des murs
`roof_material`	Matériau de la toiture (p. ex. `"Concrete tiles"`, `"Metal sheet"`)

:::note Valeurs de la taxonomie Tous les noms et valeurs catégorielles dans la section sensitivity doivent correspondre exactement aux entrées de la liste de taxonomie YAPU, fournie lors de l'intégration. Les valeurs ne correspondant pas à une entrée valide retournent une erreur 400 Bad Request. L'équipe d'intégration YAPU accompagne la correspondance entre vos libellés internes et les valeurs de la taxonomie. :::

Exemple de requête

POST /api/v2/fge/single/execute HTTP/1.1
Host: yapu-development-su.herokuapp.com
Authorization: Bearer <your_sandbox_api_key>
Content-Type: application/json

{
  "personal_details": {
    "name": "Maria",
    "last_name": "Lopez",
    "client_id_number": "12345678",
    "gender": "Female"
  },
  "economic_activities": {
    "loan_purposes": {
      "agriculture": "Yes",
      "livestock": "Yes",
      "trade": "Yes",
      "services": "Yes",
      "manufacturing": "Yes",
      "housing": "Yes"
    }
  },
  "exposure": {
    "geolocation": "-0.30890461568653893,-78.5483719923041"
  },
  "sensitivity": {
    "agriculture": {
      "crop_1": { "name": "Corn" },
      "crop_2": { "name": "Cucumber" },
      "crop_3": { "name": "Onions" }
    },
    "livestock": {
      "item_1": { "name": "Beef cattle" },
      "item_2": { "name": "Breeding pigs" },
      "item_3": { "name": "Dairy cattle" }
    },
    "trade": {
      "activity_1": { "name": "Bakery" },
      "activity_2": { "name": "Bookstores" },
      "activity_3": { "name": "Candy Sale" }
    },
    "services": {
      "service_1": { "name": "Construction" },
      "service_2": { "name": "Credits and finance" },
      "service_3": { "name": "Delivery Services" }
    },
    "manufacturing": {
      "activity_1": { "name": "Agricultural products" },
      "activity_2": { "name": "Agrochemical production" },
      "activity_3": { "name": "Alcohol production" }
    },
    "housing": {
      "construction_quality": "Formal",
      "foundation_type": "Shallow",
      "walls_type": "Reinforced",
      "roof_type": "Map",
      "foundation_material": "Wood",
      "wall_material": "Wood",
      "roof_material": "Concrete tiles"
    }
  }
}

Réponse en cas de succès

Statut HTTP : 200 OK

La réponse renvoie en écho le payload d'entrée complet et y ajoute un tableau yapu_result contenant :

Un objet customer_exposure avec les scores d'aléas au niveau de la localisation
Un objet de sensibilité par secteur actif
Un score agrégé GlobalNetRisk (échelle de 0 à 1)

{
  "personal_details": {
    "name": "Maria",
    "last_name": "Lopez",
    "client_id_number": "12345678",
    "gender": "Female"
  },
  "economic_activities": {
    "loan_purposes": {
      "agriculture": "Yes",
      "livestock": "Yes",
      "trade": "Yes",
      "services": "Yes",
      "manufacturing": "Yes",
      "housing": "Yes"
    }
  },
  "exposure": {
    "geolocation": "-0.30890461568653893,-78.5483719923041"
  },
  "sensitivity": { "...": "input echoed back" },
  "yapu_result": [
    {
      "customer_exposure": {
        "rowsTitles": ["Exposure"],
        "columnTitles": ["Drought", "Frost", "Heat", "Flood", "Storm"],
        "value": [[3, 1, 3.92, 2.83, 2.08]]
      }
    },
    {
      "agriculture": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[2.82, 2.76, 2.68, 2.44, 2.06]]
      }
    },
    {
      "livestock": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[2.78, 2.28, 2, 3.05, 2.9]]
      }
    },
    {
      "trade": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[2, 2, 2, 4.33, 3.33]]
      }
    },
    {
      "services": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[2, 2.33, 2.67, 3.67, 3]]
      }
    },
    {
      "manufacturing": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[4.27, 2.8, 3.6, 4.87, 3.37]]
      }
    },
    {
      "housing": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[1.05, 1.65, 1.2, 2.7, 2.4]]
      }
    },
    {
      "GlobalNetRisk": 0.26
    }
  ]
}

Champs de la réponse

Champs d'entrée renvoyés en écho

Le corps de la réponse répète personal_details, economic_activities, exposure et sensitivity exactement tels que soumis. Utilisez-les pour valider l'alignement requête/réponse dans votre système.

Tableau `yapu_result`

yapu_result est un tableau ordonné. Le premier élément est toujours customer_exposure. Les éléments suivants correspondent à un objet par secteur actif (dans l'ordre de soumission). Le dernier élément est toujours GlobalNetRisk.

Objet customer_exposure :

Champ	Type	Description
`rowsTitles`	string[]	Toujours `["Exposure"]`
`columnTitles`	string[]	Types d'aléas climatiques : `Drought`, `Frost`, `Heat`, `Flood`, `Storm`
`value`	number[][]	Ligne unique de cinq scores d'exposition, un par aléa. Les scores reflètent l'intensité de l'aléa physique aux coordonnées géographiques soumises.

Objets de sensibilité par secteur (agriculture, livestock, trade, services, manufacturing, housing) :

Champ	Type	Description
`rowsTitles`	string[]	Toujours `["Sensitivity"]`
`columnTitles`	string[]	Types d'aléas climatiques : `Drought`, `Frost`, `Extreme Heat`, `Flood`, `Storm`
`value`	number[][]	Ligne unique de cinq scores de sensibilité, moyennés sur les éléments soumis pour ce secteur.

Objet GlobalNetRisk :

Champ	Type	Description
`GlobalNetRisk`	number	Score de risque climatique net agrégé sur tous les secteurs actifs et tous les aléas. Plage : `0.0` (aucun risque) à `1.0` (risque maximum).

Lecture de la réponse

Scores d'exposition

Les valeurs de customer_exposure représentent l'intensité de l'aléa physique à la localisation soumise, sur une échelle de 1 à 5 :

Plage de score	Interprétation
1.0 – 2.0	Exposition faible
2.1 – 3.0	Exposition modérée
3.1 – 4.0	Exposition élevée
4.1 – 5.0	Exposition très élevée

Exemple tiré de la réponse d'exemple — aux coordonnées -0.309, -78.548 (Équateur) :

Aléa climatique	Score d'exposition	Interprétation
Drought	3.0	Élevée
Frost	1.0	Faible
Heat	3.92	Élevée
Flood	2.83	Modérée
Storm	2.08	Modérée

Scores de sensibilité par secteur

Chaque secteur actif retourne un score de sensibilité par aléa sur une échelle de 1 à 5. Des scores plus élevés indiquent une plus grande vulnérabilité de ce type d'activité à l'aléa concerné.

Exemple — sensibilité du secteur manufacturier :

Aléa climatique	Score	Interprétation
Drought	4.27	Sensibilité très élevée
Frost	2.80	Modérée
Extreme Heat	3.60	Élevée
Flood	4.87	Sensibilité très élevée
Storm	3.37	Élevée

Risque Net Global

GlobalNetRisk est un score composite unique qui combine l'Exposition et la Sensibilité de tous les secteurs actifs et de tous les aléas :

Plage de score	Interprétation
0.00 – 0.25	Risque climatique global faible
0.26 – 0.50	Modéré
0.51 – 0.75	Élevé
0.76 – 1.00	Très élevé

Dans la réponse d'exemple, GlobalNetRisk: 0.26 place cet emprunteur à la limite inférieure du risque modéré.

Risque climatique brut : définition conceptuelle

L'Exposition mesure dans quelle mesure une localisation géographique est physiquement affectée par chaque aléa climatique, basée sur la fréquence historique, l'intensité et la distribution spatiale aux coordonnées soumises. Les mêmes coordonnées produisent les mêmes scores d'exposition quel que soit le secteur.

La Sensibilité mesure la vulnérabilité d'une activité économique spécifique à chaque aléa, compte tenu des paramètres soumis (types de cultures, espèces animales, matériaux de construction, etc.). Deux emprunteurs au même endroit mais avec des activités différentes auront des profils de sensibilité différents.

Le Risque Net Global est l'indicateur composite de YAPU qui synthétise l'Exposition et la Sensibilité de tous les secteurs actifs et types d'aléas en un score unique de 0 à 1, permettant une comparaison et un reporting simplifiés au niveau du portefeuille.

:::note Évaluation brute vs. évaluation complète YAPU SNAP fournit une évaluation brute (rapide) du risque climatique. Pour une analyse complète du risque climatique incluant la modélisation de la capacité adaptative et la collecte complète de données basée sur un questionnaire, référez-vous à la plateforme YAPU standard et aux offres API. :::

Réponses d'erreur

Statut HTTP	Condition	Action recommandée
`400 Bad Request`	Champ obligatoire manquant, payload malformé, format de coordonnées invalide, ou valeur de taxonomie non reconnue	Vérifiez les noms et types de champs. Assurez-vous que toutes les valeurs dans `sensitivity` correspondent exactement à la liste de taxonomie YAPU.
`401 Unauthorized`	Bearer token manquant, invalide ou expiré	Confirmez que l'en-tête `Authorization: Bearer <clé>` est présent. Confirmez la clé correcte pour l'environnement cible.
`402 Payment Required`	Limite d'abonnement ou de quota atteinte	Contactez votre responsable de compte YAPU.
`403 Forbidden`	Token valide mais sans permission pour cette opération	Contactez votre administrateur YAPU pour vérifier les permissions d'accès.
`404 Not Found`	Chemin d'endpoint incorrect	Vérifiez le chemin d'endpoint exactement : `POST /api/v2/fge/single/execute`.
`429 Too Many Requests`	Limite de débit par clé dépassée	Lisez l'en-tête `Retry-After` et attendez la durée spécifiée.
`500 / 502 / 503 / 504`	Erreur côté serveur	Réessayez avec un backoff exponentiel (maximum 3 tentatives). Contactez le support YAPU si le problème persiste.

Scénarios d'échec courants

Symptôme	Cause probable	Résolution
`401` sur chaque requête	Préfixe `Bearer` manquant, mauvaise clé API, ou clé d'un mauvais environnement	Confirmez le format de l'en-tête : `Bearer <clé>` (espace après `Bearer`). Confirmez clé sandbox vs. production.
`400` sur un champ de sensibilité	La valeur de taxonomie ne correspond pas exactement	Vérifiez par rapport à la liste de taxonomie fournie lors de l'intégration. Les valeurs sont sensibles à la casse.
`400` sur les coordonnées	Coordonnées hors de la plage valide ou format incorrect	Confirmez le format : `"latitude,longitude"`. Latitude `-90.0` à `90.0`, longitude `-180.0` à `180.0`.
Aucun secteur évalué	Tous les `loan_purposes` définis sur `"No"` ou omis	Définissez au moins un secteur sur `"Yes"` dans `loan_purposes`.
`500` persistant	Problème d'infrastructure YAPU	Contactez le support YAPU.

Logique de réessai

Statut	Comportement
`429`	Lisez l'en-tête `Retry-After`. Attendez exactement ce nombre de secondes avant de réessayer.
`500 / 502 / 503 / 504`	Backoff exponentiel : 1s → 2s → 4s. Maximum 3 réessais avant d'escalader au support YAPU.
`400` / `401`	Déterministe — corrigez la cause racine avant de réessayer. La même requête retournera la même erreur.

Modèles d'intégration

Modèle	Description	Idéal pour
A — Évaluation en ligne (Recommandé)	API appelée de manière synchrone lors de la demande de prêt. Les scores sont affichés à l'agent de crédit avant la décision de crédit.	Plateformes LOS modernes et à priorité numérique.
B — Évaluation par lots	API appelée en masse pour les dossiers de portefeuille existants, séquentiellement ou en parallèle.	Environnements anciens où les appels en temps réel ne sont pas réalisables.
C — Actualisation périodique	Le risque climatique est réévalué pour les prêts actifs selon un calendrier défini (p. ex. trimestriel).	Surveillance continue au niveau du portefeuille.

Objectifs de performance

Métrique	Cible
Latence de réponse API (P95)	≤ 800 ms par requête
Débit système	500 requêtes simultanées sans dégradation
SLA de disponibilité mensuelle	≥ 99,5 %
Taux d'erreur système (5xx)	≤ 0,1 % des requêtes

Limitations et considérations

IP dynamique — YAPU ne prend pas en charge les adresses IP statiques. Ne configurez pas de listes blanches d'IP côté client sur des IPs YAPU fixes. Contactez YAPU lors de l'intégration si votre politique de sécurité informatique exige une liste blanche des flux sortants.
HTTPS obligatoire — toutes les requêtes doivent utiliser HTTPS. Les requêtes HTTP simples ne sont pas traitées.
Valeurs de taxonomie — toutes les valeurs de champs de sensibilité doivent correspondre exactement à la liste de taxonomie YAPU fournie lors de l'intégration. L'équipe d'intégration YAPU accompagne la correspondance entre vos libellés internes et les valeurs de la taxonomie.
Un seul questionnaire par intégration — applicable lors de la combinaison de SNAP avec les offres API standard.
Identifiants sandbox — les clés API sandbox sont fournies par YAPU et ne doivent pas être utilisées en environnement de production.

Ressources associées

Démarrage rapide — comment démarrer le processus d'intégration
Concepts API — REST, JSON, HTTPS et conventions de données YAPU
Authentification et sécurité — architecture de sécurité complète
Processus d'intégration — phases de livraison, calendriers et responsabilités
Assistance et contact — contacter votre représentant YAPU

Comment ça fonctionne​

URLs de base​

Authentification​

Endpoint​

POST /api/v2/fge/single/execute​

En-têtes de requête​

Structure du corps de la requête​

personal_details​

economic_activities.loan_purposes​

exposure​

sensitivity​

Exemple de requête​

Réponse en cas de succès​

Champs de la réponse​

Champs d'entrée renvoyés en écho​

Tableau yapu_result​

Lecture de la réponse​

Scores d'exposition​

Scores de sensibilité par secteur​

Risque Net Global​

Risque climatique brut : définition conceptuelle​

Réponses d'erreur​

Scénarios d'échec courants​

Logique de réessai​

Modèles d'intégration​

Objectifs de performance​

Limitations et considérations​

Ressources associées​