YAPU SNAP — API de Riesgo Climático Bruto

YAPU SNAP es la API REST standalone de YAPU para la evaluación del riesgo climático físico a nivel de prestatario. Recibe una coordenada geográfica, un conjunto de sectores económicos activos y parámetros de sensibilidad específicos por sector, y devuelve puntuaciones estructuradas de riesgo climático — Exposición, Sensibilidad y un Riesgo Neto Global — en cinco tipos de amenaza, por sector, en tiempo real.

YAPU SNAP está diseñada específicamente para instituciones financieras que necesitan incorporar inteligencia climática estandarizada en sus flujos de originación de crédito o monitoreo de portafolio, sin requerir la plataforma completa de YAPU.

:::tip Entorno sandbox Existe un entorno sandbox disponible para pruebas de integración. Contacte a su especialista de implementación de YAPU para obtener la clave de API del sandbox — no utilice credenciales de producción para realizar pruebas. :::

Cómo funciona

Su sistema envía una solicitud POST que contiene:

Datos personales — identificación del prestatario (devuelta en la respuesta)
Actividades económicas — qué sectores evaluar (Yes / No por tipo de actividad)
Exposición — las coordenadas geográficas de la ubicación del crédito
Sensibilidad — parámetros detallados por cada sector activo (tipos de cultivo, especies ganaderas, materiales de construcción, etc.)

La API realiza una consulta geoespacial de amenazas en las coordenadas enviadas y calcula puntuaciones de riesgo climático para cada sector activo. Los sectores no incluidos en loan_purposes como "Yes" no son evaluados.

[Su Sistema]
  │  POST /api/v2/fge/single/execute  (Bearer token + payload JSON completo)
  ▼
[API Gateway]
  │  Autentica el token · Valida el payload
  ▼
[Motor Climático]
  │  Consulta geoespacial de amenazas (5 amenazas) · Resuelve Exposición por coordenadas
  │  Resuelve Sensibilidad por sector activo + parámetros enviados
  ▼
[Capa de Respuesta]
  │  Empaqueta puntuaciones por sector + riesgo neto global · Repite los campos de entrada
  ▼
[Su Sistema]
  │  Recibe JSON estructurado → visualización o procesamiento posterior

URLs base

Entorno	URL base
Sandbox	`https://yapu-development-su.herokuapp.com`
Producción	Proporcionada por su gestor de cuenta de YAPU al momento del cierre de producción

Autenticación

Todas las solicitudes requieren un Bearer token válido en el encabezado Authorization. Los tokens se emiten por institución y por entorno — las claves de sandbox y producción no son intercambiables.

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

:::warning Mantenga su clave de API segura Las claves de API otorgan privilegios de acceso completo. Nunca escriba una clave directamente en el código fuente, la incluya en un sistema de control de versiones ni la exponga en código del lado del cliente. Las claves están disponibles a través de su administrador de YAPU y pueden rotarse bajo solicitud. :::

Consulte Autenticación y Seguridad para conocer la arquitectura de seguridad completa.

Endpoint

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

Envía datos del prestatario, sectores económicos activos, coordenadas geográficas y parámetros de sensibilidad por sector. Devuelve puntuaciones de Exposición y Sensibilidad por sector en cinco tipos de amenaza, más una puntuación de Riesgo Neto Global.

Encabezados de la solicitud

Encabezado	Requerido	Valor
`Authorization`	Sí	`Bearer <api_key>`
`Content-Type`	Sí	`application/json`

Estructura del cuerpo de la solicitud

El cuerpo de la solicitud tiene cuatro secciones de nivel superior:

Sección	Requerida	Descripción
`personal_details`	Sí	Campos de identificación del prestatario — devueltos en la respuesta
`economic_activities`	Sí	Define qué sectores económicos evaluar
`exposure`	Sí	Coordenadas geográficas de la ubicación del crédito o activo
`sensitivity`	Sí	Parámetros específicos por sector utilizados para calcular las puntuaciones de sensibilidad

`personal_details`

Campo	Tipo	Descripción
`name`	string	Nombre del prestatario
`last_name`	string	Apellido del prestatario
`client_id_number`	string	Identificador del prestatario en el sistema del cliente
`gender`	string	Género del prestatario (`"Male"` o `"Female"`)

`economic_activities.loan_purposes`

Define qué sectores se incluyen en la evaluación de riesgo climático. Establezca cada sector en "Yes" para incluirlo, u omítalo o establézcalo en "No" para excluirlo.

Campo	Tipo	Valores	Descripción
`agriculture`	string	`"Yes"` / `"No"`	Incluir agricultura basada en cultivos en la evaluación
`livestock`	string	`"Yes"` / `"No"`	Incluir ganadería / cría de animales
`trade`	string	`"Yes"` / `"No"`	Incluir actividades de comercio
`services`	string	`"Yes"` / `"No"`	Incluir actividades del sector servicios
`manufacturing`	string	`"Yes"` / `"No"`	Incluir actividades manufactureras
`housing`	string	`"Yes"` / `"No"`	Incluir vivienda residencial

`exposure`

Campo	Tipo	Requerido	Descripción
`geolocation`	string	Sí	Coordenadas geográficas con el formato `"latitud,longitud"` en grados decimales (WGS84). Latitud: `-90.0` a `90.0`. Longitud: `-180.0` a `180.0`.

`sensitivity`

La sección de sensibilidad contiene una subsección por sector. Incluya únicamente las subsecciones de los sectores establecidos en "Yes" dentro de loan_purposes. Los sectores no utilizados se ignoran.

sensitivity.agriculture — hasta tres cultivos:

Campo	Descripción
`crop_1.name`, `crop_2.name`, `crop_3.name`	Nombres de especies de cultivo. Deben coincidir con los valores de la lista de taxonomía de YAPU.

sensitivity.livestock — hasta tres tipos de ganado:

Campo	Descripción
`item_1.name`, `item_2.name`, `item_3.name`	Nombres de especies ganaderas. Deben coincidir con los valores de la lista de taxonomía de YAPU.

sensitivity.trade — hasta tres actividades comerciales:

Campo	Descripción
`activity_1.name`, `activity_2.name`, `activity_3.name`	Nombres de actividades comerciales. Deben coincidir con los valores de la lista de taxonomía de YAPU.

sensitivity.services — hasta tres actividades de servicios:

Campo	Descripción
`service_1.name`, `service_2.name`, `service_3.name`	Nombres de tipos de servicio. Deben coincidir con los valores de la lista de taxonomía de YAPU.

sensitivity.manufacturing — hasta tres actividades manufactureras:

Campo	Descripción
`activity_1.name`, `activity_2.name`, `activity_3.name`	Nombres de actividades manufactureras. Deben coincidir con los valores de la lista de taxonomía de YAPU.

sensitivity.housing — parámetros físicos de construcción:

Campo	Descripción
`construction_quality`	Calidad general de la construcción (p. ej., `"Formal"`, `"Informal"`)
`foundation_type`	Tipo de cimentación (p. ej., `"Shallow"`, `"Deep"`)
`walls_type`	Tipo estructural de muros (p. ej., `"Reinforced"`, `"Unreinforced"`)
`roof_type`	Tipo estructural del techo
`foundation_material`	Material de cimentación (p. ej., `"Concrete"`, `"Wood"`)
`wall_material`	Material de los muros
`roof_material`	Material del techo (p. ej., `"Concrete tiles"`, `"Metal sheet"`)

:::note Valores de taxonomía Todos los nombres y valores categóricos en la sección sensitivity deben coincidir exactamente con las entradas de la lista de taxonomía de YAPU, la cual se proporciona durante la incorporación. Los valores que no coincidan con una entrada válida generarán un error 400 Bad Request. El equipo de incorporación de YAPU apoya el mapeo de sus etiquetas internas a los valores de taxonomía. :::

Ejemplo de solicitud

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"
    }
  }
}

Respuesta exitosa

Estado HTTP: 200 OK

La respuesta repite el payload completo de entrada y agrega un array yapu_result que contiene:

Un objeto customer_exposure con puntuaciones de amenaza a nivel de ubicación
Un objeto de sensibilidad por cada sector activo
Una puntuación agregada GlobalNetRisk (escala 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
    }
  ]
}

Campos de la respuesta

Campos de entrada repetidos

El cuerpo de la respuesta repite personal_details, economic_activities, exposure y sensitivity exactamente tal como fueron enviados. Utilícelos para validar la alineación solicitud/respuesta en su sistema.

Array `yapu_result`

yapu_result es un array ordenado. El primer elemento siempre es customer_exposure. Los elementos siguientes son un objeto por sector activo (en el orden de envío). El último elemento siempre es GlobalNetRisk.

Objeto customer_exposure:

Campo	Tipo	Descripción
`rowsTitles`	string[]	Siempre `["Exposure"]`
`columnTitles`	string[]	Tipos de amenaza: `Drought`, `Frost`, `Heat`, `Flood`, `Storm`
`value`	number[][]	Fila única con cinco puntuaciones de exposición, una por amenaza. Las puntuaciones reflejan la intensidad de la amenaza física en la geolocalización enviada.

Objetos de sensibilidad por sector (agriculture, livestock, trade, services, manufacturing, housing):

Campo	Tipo	Descripción
`rowsTitles`	string[]	Siempre `["Sensitivity"]`
`columnTitles`	string[]	Tipos de amenaza: `Drought`, `Frost`, `Extreme Heat`, `Flood`, `Storm`
`value`	number[][]	Fila única con cinco puntuaciones de sensibilidad, promediadas entre los elementos enviados para ese sector.

Objeto GlobalNetRisk:

Campo	Tipo	Descripción
`GlobalNetRisk`	number	Puntuación de riesgo climático neto agregada para todos los sectores activos y amenazas. Rango: `0.0` (sin riesgo) a `1.0` (riesgo máximo).

Interpretación de la respuesta

Puntuaciones de exposición

Los valores de customer_exposure representan la intensidad de la amenaza física en la ubicación enviada, en una escala del 1 al 5:

Rango de puntuación	Interpretación
1.0 – 2.0	Exposición baja
2.1 – 3.0	Exposición moderada
3.1 – 4.0	Exposición alta
4.1 – 5.0	Exposición muy alta

Ejemplo basado en la respuesta de muestra — en las coordenadas -0.309, -78.548 (Ecuador):

Amenaza	Puntuación de exposición	Interpretación
Drought	3.0	Alta
Frost	1.0	Baja
Heat	3.92	Alta
Flood	2.83	Moderada
Storm	2.08	Moderada

Puntuaciones de sensibilidad por sector

Cada sector activo devuelve una puntuación de sensibilidad por amenaza en una escala del 1 al 5. Puntuaciones más altas indican una mayor vulnerabilidad de ese tipo de actividad frente a la amenaza.

Ejemplo — sensibilidad en manufactura:

Amenaza	Puntuación	Interpretación
Drought	4.27	Sensibilidad muy alta
Frost	2.80	Moderada
Extreme Heat	3.60	Alta
Flood	4.87	Sensibilidad muy alta
Storm	3.37	Alta

Riesgo Neto Global

GlobalNetRisk es una puntuación compuesta única que combina Exposición y Sensibilidad de todos los sectores activos y amenazas:

Rango de puntuación	Interpretación
0.00 – 0.25	Riesgo climático global bajo
0.26 – 0.50	Moderado
0.51 – 0.75	Alto
0.76 – 1.00	Muy alto

En la respuesta de muestra, GlobalNetRisk: 0.26 sitúa a este prestatario en el límite inferior del riesgo moderado.

Riesgo climático bruto: definición conceptual

La Exposición mide en qué medida una ubicación geográfica se ve afectada físicamente por cada amenaza climática, basándose en la frecuencia histórica, la intensidad y la distribución espacial en las coordenadas enviadas. Las mismas coordenadas producen las mismas puntuaciones de exposición independientemente del sector.

La Sensibilidad mide cuán vulnerable es una actividad económica específica a cada amenaza, dados los parámetros enviados (tipos de cultivo, especies ganaderas, materiales de construcción, etc.). Dos prestatarios en la misma ubicación pero con diferentes actividades tendrán perfiles de sensibilidad distintos.

El Riesgo Neto Global es el indicador compuesto de YAPU que sintetiza la Exposición y la Sensibilidad de todos los sectores activos y tipos de amenaza en una puntuación única de 0 a 1, lo que permite una comparación y un reporte sencillos a nivel de portafolio.

:::note Evaluación bruta vs. evaluación integral YAPU SNAP proporciona una evaluación bruta (rápida). Para un análisis de riesgo climático integral que incluya modelado de capacidad adaptativa y recopilación completa de datos basada en cuestionarios, consulte la plataforma estándar de YAPU y los bundles de API. :::

Respuestas de error

Estado HTTP	Condición	Acción recomendada
`400 Bad Request`	Campo requerido faltante, payload con formato incorrecto, formato de geolocalización inválido o valor de taxonomía no reconocido	Verifique los nombres y tipos de campo. Confirme que todos los valores de `sensitivity` coincidan exactamente con la lista de taxonomía de YAPU.
`401 Unauthorized`	Bearer token ausente, inválido o expirado	Confirme que el encabezado `Authorization: Bearer <key>` esté presente. Confirme que la clave corresponde al entorno de destino.
`402 Payment Required`	Límite de suscripción o cuota alcanzado	Contacte a su gestor de cuenta de YAPU.
`403 Forbidden`	Token válido pero sin permisos para esta operación	Contacte a su administrador de YAPU para revisar los permisos de acceso.
`404 Not Found`	Ruta del endpoint incorrecta	Verifique la ruta exacta del endpoint: `POST /api/v2/fge/single/execute`.
`429 Too Many Requests`	Límite de tasa por clave superado	Lea el encabezado `Retry-After` y espere la duración indicada.
`500 / 502 / 503 / 504`	Error del lado del servidor	Reintente con retroceso exponencial (máximo 3 intentos). Contacte al soporte de YAPU si el error persiste.

Escenarios de fallo frecuentes

Síntoma	Causa probable	Resolución
`401` en cada solicitud	Falta el prefijo `Bearer`, clave de API incorrecta o clave del entorno equivocado	Confirme el formato del encabezado: `Bearer <key>` (espacio después de `Bearer`). Confirme si es clave de sandbox o de producción.
`400` en campo de sensibilidad	El valor de taxonomía no coincide exactamente	Verifique contra la lista de taxonomía proporcionada durante la incorporación. Los valores distinguen mayúsculas de minúsculas.
`400` en geolocalización	Coordenadas fuera del rango válido o formato incorrecto	Confirme el formato: `"latitud,longitud"`. Latitud `-90.0` a `90.0`, longitud `-180.0` a `180.0`.
Ningún sector evaluado	Todos los `loan_purposes` establecidos en `"No"` u omitidos	Establezca al menos un sector en `"Yes"` en `loan_purposes`.
`500` persistente	Problema en la infraestructura de YAPU	Contacte al soporte de YAPU.

Lógica de reintentos

Estado	Comportamiento
`429`	Lea el encabezado `Retry-After`. Espere exactamente esa cantidad de segundos antes de reintentar.
`500 / 502 / 503 / 504`	Retroceso exponencial: 1s → 2s → 4s. Máximo 3 reintentos antes de escalar al soporte de YAPU.
`400` / `401`	Determinístico — corrija la causa raíz antes de reintentar. La misma solicitud devolverá el mismo error.

Patrones de integración

Patrón	Descripción	Más adecuado para
A — Evaluación en línea (Recomendado)	API llamada de forma síncrona durante la solicitud del crédito. Las puntuaciones se muestran al oficial de crédito antes de la decisión crediticia.	Plataformas LOS modernas y orientadas a lo digital.
B — Evaluación por lotes	API llamada en bloque para registros existentes del portafolio, de forma secuencial o en paralelo.	Entornos heredados donde las llamadas en tiempo real no son factibles.
C — Actualización periódica	El riesgo climático se reevalúa para los créditos activos según un calendario definido (p. ej., trimestralmente).	Monitoreo continuo a nivel de portafolio.

Objetivos de rendimiento

Métrica	Objetivo
Latencia de respuesta de la API (P95)	≤ 800 ms por solicitud
Capacidad del sistema	500 solicitudes concurrentes sin degradación
SLA de disponibilidad mensual	≥ 99,5%
Tasa de error del sistema (5xx)	≤ 0,1% de las solicitudes

Limitaciones y consideraciones

IP dinámica — YAPU no admite direcciones IP estáticas. No configure listas de acceso de IP fijas hacia YAPU en el lado del cliente. Si su política de seguridad de TI requiere listas blancas de tráfico saliente, consúltelo con YAPU durante la incorporación.
HTTPS obligatorio — todas las solicitudes deben utilizar HTTPS. Las solicitudes HTTP planas no son procesadas.
Valores de taxonomía — todos los valores de campo en la sección de sensibilidad deben coincidir exactamente con la lista de taxonomía de YAPU proporcionada durante la incorporación. El equipo de incorporación de YAPU apoya el mapeo de sus etiquetas internas.
Cuestionario único por integración — aplica al combinar SNAP con bundles estándar de API.
Credenciales de sandbox — las claves de API de sandbox son proporcionadas por YAPU y no deben utilizarse en entornos de producción.

Recursos relacionados

Primeros Pasos — cómo iniciar el proceso de integración
Conceptos de API — REST, JSON, HTTPS y convenciones de datos de YAPU
Autenticación y Seguridad — arquitectura de seguridad completa
Proceso de Integración — fases de entrega, plazos y responsabilidades
Soporte y Contacto — contacte a su representante de YAPU

Cómo funciona​

URLs base​

Autenticación​

Endpoint​

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

Encabezados de la solicitud​

Estructura del cuerpo de la solicitud​

personal_details​

economic_activities.loan_purposes​

exposure​

sensitivity​

Ejemplo de solicitud​

Respuesta exitosa​

Campos de la respuesta​

Campos de entrada repetidos​

Array yapu_result​

Interpretación de la respuesta​

Puntuaciones de exposición​

Puntuaciones de sensibilidad por sector​

Riesgo Neto Global​

Riesgo climático bruto: definición conceptual​

Respuestas de error​

Escenarios de fallo frecuentes​

Lógica de reintentos​

Patrones de integración​

Objetivos de rendimiento​

Limitaciones y consideraciones​

Recursos relacionados​