Saltar al contenido
Umbral PLD
Integración Blog Referencia de la API

Contenido

  1. 1. Empieza en 5 minutos
  2. 2. Tu primera venta
  3. 3. Cómo leer la respuesta
  4. 4. Los campos de cada venta
  5. 5. Simular, reenviar, saldo y cobros
  6. 6. Consultar una venta
  7. 7. Errores
  8. 8. Avisos a tu sistema
  9. 9. Buenas prácticas
  10. 10. Preguntas frecuentes

API del motor EBR: guía para desarrolladores

Última actualización: 17 de noviembre de 2026. El detalle de cada campo y cada respuesta está en la referencia completa de la API; esta guía te lleva de cero a tu primera venta calificada.

Tu sistema de ventas manda cada venta a Umbral y recibe, en la misma respuesta, su nivel de riesgo calificado con la matriz de tu empresa. Si lo configuras, Umbral además le avisa a tu sistema cada vez que una venta se califica. En las cuentas con plan, con cada venta se crea también el expediente del cliente.

Dirección base
https://api.umbral-pld.com/api
Autenticación
Cabecera X-Api-Key con tu llave de integración (umb_…)
Formato
JSON en UTF-8, nombres en camelCase y opciones como texto ("individual", "transfer")
Límites
120 peticiones por minuto por llave; hasta 5,000 ventas por petición
Errores
RFC 9457 (application/problem+json)

¿Aún no tienes cuenta? Da de alta tu empresa en la API del motor EBR y paga tu primer paquete de evaluaciones en línea; tu oficial recibe la invitación al confirmarse el pago.

Las rutas de un vistazo

Para qué Ruta Descuenta saldo
Calificar ventas y guardarlas POST /ebr/evaluations 1 por venta nueva o con cambios (detalle)
Probar sin guardar POST /ebr/evaluations?simulate=true 1 por venta
Cargar tus ventas del último año POST /ebr/operations No
Consultar una venta GET /ebr/operations/{operationId} No
Ver tu saldo GET /ebr/balance No
Ver cada cobro del mes con sus folios GET /ebr/balance/movements?month=202611 No
Los mismos cobros en Excel GET /ebr/balance/movements/excel?month=202611 No

Todas llevan la cabecera X-Api-Key y van sobre la dirección base. Para probar tu llave, empieza por GET /ebr/balance: responde tu saldo y no gasta nada.

1. Empieza en 5 minutos

  1. Crea tu llave. Entra a Umbral con el usuario del oficial de cumplimiento (es el único rol que administra llaves). En la barra lateral, abajo, abre Configuración y baja a Integración con su sistema. Escribe un nombre que reconozcas (p. ej. «Sistema de ventas») y pulsa Crear llave. Cópiala en ese momento: empieza con umb_ y no se vuelve a mostrar. Si la pierdes, revócala y crea otra. Si tu cuenta es solo del motor EBR, en la pantalla Motor EBR el botón Ir a las llaves te lleva directo.
  2. Revisa el nombre de tu sucursal. Cada venta trae en businessUnit el nombre de una sucursal activa de tu empresa. Los ves en la barra lateral, en Matriz de riesgo, pestaña Sucursales. Se compara sin importar mayúsculas, acentos ni espacios de más.
  3. Manda tu primera venta con el ejemplo de abajo y lee rating en la respuesta: ese es su nivel de riesgo. Tu integración paso a paso, arriba de la pantalla Motor EBR, va marcando sola lo que ya hizo tu sistema (llave, primera llamada, primera venta, saldo) y te dice qué sigue.

Guarda la llave en una variable de entorno o en el almacén de secretos de tu servidor. No la pongas en el código, en el repositorio ni en una página web: quien la tenga puede mandar ventas a nombre de tu empresa. Los ejemplos la leen de UMBRAL_API_KEY.

2. Tu primera venta

POST /ebr/evaluations guarda cada venta (la crea o la actualiza por su operationId) y la califica con la matriz vigente. Manda una lista en operations, aunque sea de una venta. Elige tu lenguaje:

cURL

Guarda el cuerpo en venta.json (UTF-8) y mándalo desde la misma carpeta. En archivo, los acentos llegan bien en cualquier sistema operativo.

venta.json
{
  "operations": [
    {
      "operationId": "F-2026-0001",
      "businessUnit": "Sucursal Centro",
      "customerNumber": "C-1045",
      "customerName": "Ana López Ruiz",
      "personType": "individual",
      "curp": "LORA850312MJCPZN09",
      "rfc": "LORA850312AB1",
      "customerEmail": "[email protected]",
      "uifActivity": "VEH",
      "productType": "Vehículo nuevo",
      "operationType": "Operación propia",
      "birthCountry": "México",
      "residenceCountry": "México",
      "residenceState": "Jalisco",
      "economicActivityKey": "7140200",
      "isPep": false,
      "isPepRelated": false,
      "channel": "Presencial",
      "currency": "Peso mexicano",
      "invoiceNumber": "A-5531",
      "invoiceDate": "2026-11-10",
      "amount": 400000,
      "taxes": 64000,
      "paymentMethod": "transfer"
    }
  ]
}
Terminal
curl -X POST "https://api.umbral-pld.com/api/ebr/evaluations" \
  -H "X-Api-Key: $UMBRAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @venta.json

JavaScript

Con fetch, sin librerías. Corre en tu servidor, no en el navegador.

primera-venta.mjs
// primera-venta.mjs · Node 18 o más reciente: node primera-venta.mjs
const API = 'https://api.umbral-pld.com/api';

const venta = {
  operationId: 'F-2026-0001',
  businessUnit: 'Sucursal Centro',
  customerNumber: 'C-1045',
  customerName: 'Ana López Ruiz',
  personType: 'individual',
  curp: 'LORA850312MJCPZN09',
  rfc: 'LORA850312AB1',
  customerEmail: '[email protected]',
  uifActivity: 'VEH',
  productType: 'Vehículo nuevo',
  operationType: 'Operación propia',
  birthCountry: 'México',
  residenceCountry: 'México',
  residenceState: 'Jalisco',
  economicActivityKey: '7140200',
  isPep: false,
  isPepRelated: false,
  channel: 'Presencial',
  currency: 'Peso mexicano',
  invoiceNumber: 'A-5531',
  invoiceDate: '2026-11-10',
  amount: 400000,
  taxes: 64000,
  paymentMethod: 'transfer',
};

const res = await fetch(`${API}/ebr/evaluations`, {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.UMBRAL_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ operations: [venta] }),
});

const data = await res.json();
if (!res.ok) {
  console.error(res.status, data); // RFC 9457: title, detail y, en un 400, errors por campo
  process.exit(1);
}

for (const op of data.operations) {
  console.log(op.operationId, op.rating, op.isComplete ? 'completa' : `pendientes: ${op.pending.join(', ')}`);
}

Python

Solo biblioteca estándar (urllib): no hay que instalar nada.

primera_venta.py
# primera_venta.py · Python 3.8 o más reciente, solo biblioteca estándar
import json
import os
import urllib.error
import urllib.request

API = "https://api.umbral-pld.com/api"

venta = {
    "operationId": "F-2026-0001",
    "businessUnit": "Sucursal Centro",
    "customerNumber": "C-1045",
    "customerName": "Ana López Ruiz",
    "personType": "individual",
    "curp": "LORA850312MJCPZN09",
    "rfc": "LORA850312AB1",
    "customerEmail": "[email protected]",
    "uifActivity": "VEH",
    "productType": "Vehículo nuevo",
    "operationType": "Operación propia",
    "birthCountry": "México",
    "residenceCountry": "México",
    "residenceState": "Jalisco",
    "economicActivityKey": "7140200",
    "isPep": False,
    "isPepRelated": False,
    "channel": "Presencial",
    "currency": "Peso mexicano",
    "invoiceNumber": "A-5531",
    "invoiceDate": "2026-11-10",
    "amount": 400000,
    "taxes": 64000,
    "paymentMethod": "transfer",
}

req = urllib.request.Request(
    f"{API}/ebr/evaluations",
    data=json.dumps({"operations": [venta]}).encode("utf-8"),
    headers={
        "X-Api-Key": os.environ["UMBRAL_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(req, timeout=60) as res:
        data = json.load(res)
except urllib.error.HTTPError as err:
    # RFC 9457: title, detail y, en un 400, errors por campo
    raise SystemExit(f"{err.code} {err.read().decode('utf-8')}")

for op in data["operations"]:
    estado = "completa" if op["isComplete"] else "pendientes: " + ", ".join(op["pending"])
    print(op["operationId"], op["rating"], estado)

PHP

Con la extensión curl que trae PHP.

primera-venta.php
<?php
// primera-venta.php · PHP 7.4 o más reciente con la extensión curl
$api = 'https://api.umbral-pld.com/api';

$venta = [
    'operationId' => 'F-2026-0001',
    'businessUnit' => 'Sucursal Centro',
    'customerNumber' => 'C-1045',
    'customerName' => 'Ana López Ruiz',
    'personType' => 'individual',
    'curp' => 'LORA850312MJCPZN09',
    'rfc' => 'LORA850312AB1',
    'customerEmail' => '[email protected]',
    'uifActivity' => 'VEH',
    'productType' => 'Vehículo nuevo',
    'operationType' => 'Operación propia',
    'birthCountry' => 'México',
    'residenceCountry' => 'México',
    'residenceState' => 'Jalisco',
    'economicActivityKey' => '7140200',
    'isPep' => false,
    'isPepRelated' => false,
    'channel' => 'Presencial',
    'currency' => 'Peso mexicano',
    'invoiceNumber' => 'A-5531',
    'invoiceDate' => '2026-11-10',
    'amount' => 400000,
    'taxes' => 64000,
    'paymentMethod' => 'transfer',
];

$ch = curl_init("$api/ebr/evaluations");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('UMBRAL_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['operations' => [$venta]], JSON_UNESCAPED_UNICODE),
]);
$body = curl_exec($ch);
if ($body === false) {
    exit('Sin conexión: ' . curl_error($ch) . PHP_EOL);
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($status !== 200) {
    exit("$status $body" . PHP_EOL); // RFC 9457: title, detail y, en un 400, errors por campo
}

$data = json_decode($body, true);
foreach ($data['operations'] as $op) {
    $estado = $op['isComplete'] ? 'completa' : 'pendientes: ' . implode(', ', $op['pending']);
    echo $op['operationId'], ' ', $op['rating'], ' ', $estado, PHP_EOL;
}

C#

Con HttpClient. En una aplicación real, reutiliza una sola instancia.

Program.cs
// Program.cs · .NET 8 o más reciente (dotnet new console)
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.umbral-pld.com/api/") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("UMBRAL_API_KEY"));

var venta = new
{
    operationId = "F-2026-0001",
    businessUnit = "Sucursal Centro",
    customerNumber = "C-1045",
    customerName = "Ana López Ruiz",
    personType = "individual",
    curp = "LORA850312MJCPZN09",
    rfc = "LORA850312AB1",
    customerEmail = "[email protected]",
    uifActivity = "VEH",
    productType = "Vehículo nuevo",
    operationType = "Operación propia",
    birthCountry = "México",
    residenceCountry = "México",
    residenceState = "Jalisco",
    economicActivityKey = "7140200",
    isPep = false,
    isPepRelated = false,
    channel = "Presencial",
    currency = "Peso mexicano",
    invoiceNumber = "A-5531",
    invoiceDate = "2026-11-10",
    amount = 400000m,
    taxes = 64000m,
    paymentMethod = "transfer",
};

using var response = await http.PostAsJsonAsync("ebr/evaluations", new { operations = new[] { venta } });
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    // RFC 9457: title, detail y, en un 400, errors por campo
    Console.WriteLine($"{(int)response.StatusCode} {body}");
    return;
}

using var data = JsonDocument.Parse(body);
foreach (var op in data.RootElement.GetProperty("operations").EnumerateArray())
{
    var estado = op.GetProperty("isComplete").GetBoolean()
        ? "completa"
        : "pendientes: " + string.Join(", ", op.GetProperty("pending").EnumerateArray().Select(code => code.GetString()));
    Console.WriteLine($"{op.GetProperty("operationId")} {op.GetProperty("rating")} {estado}");
}

Si todo sale bien, la terminal muestra la venta y su nivel:

F-2026-0001 Bajo pendientes: EBR-09

3. Cómo leer la respuesta

Esta es la respuesta real de la venta de arriba. Los criterios vienen recortados a dos; en tu respuesta llegan todos los de tu matriz.

200 OK
{
  "operations": [
    {
      "operationId": "F-2026-0001",
      "businessUnit": "Sucursal Centro",
      "customerNumber": "C-1045",
      "customerName": "Ana López Ruiz",
      "invoiceDate": "2026-11-10T00:00:00",
      "amount": 400000,
      "score": 37.25,
      "criteriaCount": 14,
      "resolvedCount": 13,
      "isComplete": false,
      "rating": "Bajo",
      "ratingLevelCode": "NR-03",
      "isFinancialEntity": false,
      "outOfTable": false,
      "pending": [
        "EBR-09"
      ],
      "criteria": [
        {
          "criterionCode": "EBR-01",
          "criterionName": "Producto o servicio",
          "valueRead": "Vehículo nuevo",
          "option": "Vehiculo nuevo",
          "riskLevel": "Alto",
          "outcome": "resolved"
        },
        {
          "criterionCode": "EBR-09",
          "criterionName": "Antecedentes en listas (ONU, OFAC, SAT 69-B y 69)",
          "valueRead": null,
          "option": null,
          "riskLevel": null,
          "outcome": "emptyValue"
        }
      ],
      "evaluationId": 1,
      "customerFileCode": null,
      "discrepancies": [],
      "mandatoryHigh": null
    }
  ],
  "portfolio": {
    "operations": 1,
    "complete": 0,
    "incomplete": 1,
    "totalAmount": 400000,
    "averageScore": 37.25,
    "rating": "Bajo",
    "outOfTable": false,
    "byRating": [
      {
        "rating": "Bajo",
        "operations": 1,
        "percentage": 100
      }
    ]
  },
  "customerFiles": [
    {
      "operationId": "F-2026-0001",
      "outcome": "created",
      "customerFileId": 1,
      "customerFileCode": "EXP-00001",
      "isComplete": false,
      "linkSent": true,
      "problem": null
    }
  ]
}

Lo que vas a usar en cada venta

Campo Qué significa
operations Una por venta, en el mismo orden en que las mandaste.
rating El nivel de riesgo de la venta, con el nombre que tiene en tu matriz (p. ej. «Alto», «Medio», «Bajo»). Vacío si tu matriz todavía no tiene tabulador.
ratingLevelCode El código de ese nivel (p. ej. NR-03). Compara contra el código en tu sistema: el nombre lo puede cambiar el oficial.
score El puntaje de la venta, de 0 a 100. Tu tabulador lo convierte en el nivel.
isComplete, pending isComplete es true si se resolvieron todos los criterios. Si no, pending trae los códigos de los que faltaron y la venta se calificó sin ellos. En criteria ves por qué (outcome); manda el dato que falta y reenvía la venta.
mandatoryHigh Si viene con texto, la venta quedó en el nivel más alto por regla (riesgo alto obligatorio, p. ej. un cliente en la lista de la ONU o una persona políticamente expuesta en el extranjero), y el texto dice por qué. Vacío si el nivel salió del tabulador.
evaluationId La calificación que quedó guardada. Vacío en una simulación.
customerFileCode El expediente del que salieron los datos del cliente. En la primera venta de un cliente nuevo viene vacío: su expediente se crea después de calificar y lo ves en customerFiles.
discrepancies Si el cliente ya tiene expediente, su expediente manda: países, estado, actividad económica y PEP se toman de ahí, porque los revisa el oficial. Lo que tu venta traía distinto llega aquí como { "field": "residenceState", "sent": "Jalisco", "onFile": "Nuevo León" }. La venta se calificó con lo del expediente: corrige el dato en tu sistema.
criteria El detalle de cada criterio de tu matriz: valueRead (lo que se leyó de tu venta), option (la opción de tu matriz con la que empató), riskLevel y outcome. Sirve para revisar una calificación, no para recalcularla.
portfolio El resumen del lote que mandaste: cuántas ventas, cuántas completas, monto total, puntaje promedio, su nivel con el tabulador de cartera y cuántas cayeron en cada nivel (byRating).
customerFiles Qué pasó con el expediente del cliente de cada venta: outcome "created" (se creó), "existing" (ya tenía) o "failed" (no se pudo crear; la venta sí se guardó y problem dice por qué). linkSent indica si se le mandó al cliente el enlace para completarlo. Llega vacío si tu empresa no crea expedientes solos (se decide en Configuración) o si tu cuenta es solo del motor EBR, y como null en una simulación.

También trae isFinancialEntity (el nivel se fijó por ser entidad financiera), outOfTable (se resolvió todo, pero tu matriz no tiene tabulador de cliente) y campos de auditoría que no necesitas para integrarte (customerKey, weightSum y, en cada criterio, weight, percentage y weighted).

Por qué un criterio queda pendiente (outcome)

Valor Qué pasó
resolved Se resolvió.
emptyValue La venta no trae el dato. En el criterio de listas, que no había listas cargadas para revisar al cliente.
noMatch El dato no empata con ninguna opción de tu matriz (p. ej. un error de dedo). Revisa las opciones del criterio en Matriz de riesgo.
noActivity No hay actividad económica, o su clave no está en el catálogo de tu matriz.
activityWithoutRisk La actividad existe, pero no tiene nivel de riesgo asignado.
noIdentification Sin RFC ni CURP no se pueden juntar las ventas del cliente (afecta los criterios de 12 meses).
noOptions, noField El criterio no está terminado de configurar en tu matriz: avisa al oficial.

Además de la respuesta, Umbral le avisa al oficial de cumplimiento cuando una venta sale en el nivel más alto o llega con datos distintos a su expediente, para que la revise.

4. Los campos de cada venta

Solo tres son obligatorios: operationId, businessUnit y personType. Los demás alimentan los criterios de tu matriz: cada uno que falte puede dejar un criterio pendiente.

Campo Tipo Qué es
operationId (obligatorio) texto, hasta 50 El folio de la venta en tu sistema. Con él se crea o se actualiza: mandarlo dos veces no duplica la venta.
businessUnit (obligatorio) texto, hasta 100 El nombre de una sucursal activa de tu empresa.
personType (obligatorio) "individual", "company" o "trust" Persona física, persona moral o fideicomiso.
curp o rfc (recomendado) texto, hasta 18 y 13 Identifican al cliente: la CURP a la persona física; el RFC a la persona moral y a la física sin CURP. Sin ninguno, la venta se guarda, pero no se juntan las ventas del cliente para los criterios de 12 meses.
customerNumber, customerName texto, hasta 50 y 300 Tu número de cliente y su nombre o razón social.
customerEmail correo No se califica ni se guarda en la venta: va al expediente del cliente para mandarle el enlace para completarlo.
uifActivity clave (tabla de abajo) La actividad vulnerable de la venta. Solo hace falta si tu empresa tiene varias; sin ella se usa la primera de tu empresa (o la que la venta ya tenía).
productType, operationType, channel, currency texto, hasta 200 Producto, tipo de operación, canal y moneda, con las palabras de las opciones de tu matriz.
birthCountry, nationality, residenceCountry, residenceState texto, hasta 200 País de nacimiento, nacionalidad (en persona moral sustituye al país de nacimiento), país y estado de residencia.
economicActivityKey o economicActivity texto, hasta 20 y 600 La clave SAT de la actividad económica o, si no la manejas, su descripción. Si la clave no empata, se busca por la descripción.
isPep, isPepRelated true, false o null Si el cliente, o un familiar o asociado cercano, es persona políticamente expuesta. null: no se capturó.
invoiceNumber, invoiceDate texto; fecha "AAAA-MM-DD" La factura. Sin fecha, la venta cuenta como no facturada. Si mandas fecha con hora y zona, cuenta el día en la Ciudad de México.
amount, taxes número amount es el importe sin impuestos (el subtotal); taxes, los impuestos (0 si va exenta). Si no mandas taxes, el importe se toma como total.
paymentMethod "cash", "transfer", "card", "financing" o "lease" Efectivo, transferencia SPEI, tarjeta, crédito o arrendamiento: la que cubre la mayor parte del pago.
isCancelled true o false Una venta cancelada no cuenta en los criterios de 12 meses del cliente.

Los textos se comparan con las opciones de tu matriz sin importar mayúsculas, acentos ni espacios de más: «Vehículo nuevo» empata con «VEHICULO NUEVO». Las opciones de cada criterio las ves en Matriz de riesgo, pestaña Criterios.

Claves de actividad vulnerable (uifActivity)

Clave Actividad
VEH Comercialización o distribución de vehículos (art. 17, fr. VIII)
INM Construcción, desarrollo o intermediación en la compraventa de inmuebles (art. 17, fr. V)
DIN Recepción de recursos para un desarrollo inmobiliario (art. 17, fr. V Bis)
JYR Metales y piedras preciosas, joyas y relojes (art. 17, fr. VI)
OBA Subasta o comercialización de obras de arte (art. 17, fr. VII)
BLI Blindaje de vehículos o inmuebles (art. 17, fr. IX)
MPC Préstamos, créditos, mutuos o garantías (sin ser entidad financiera) (art. 17, fr. IV)
ARI Arrendamiento de inmuebles (art. 17, fr. XV)
JYS Juegos con apuesta, concursos o sorteos (art. 17, fr. I)
DON Recepción de donativos (asociaciones sin fines de lucro) (art. 17, fr. XIII)
TSC Tarjetas de servicios o de crédito (art. 17, fr. II)
TPP Tarjetas prepagadas, vales o cupones (art. 17, fr. II)
TDR Tarjetas de devolución o recompensas (art. 17, fr. II)
CHV Cheques de viajero (art. 17, fr. III)
TCV Traslado o custodia de dinero o valores (art. 17, fr. X)
SPR Servicios profesionales independientes (art. 17, fr. XI)
AVI Intercambio de activos virtuales (sin ser entidad financiera) (art. 17, fr. XVI)

5. Simular, reenviar, saldo y cobros

Con ?simulate=true la venta se califica igual, pero no se guarda nada: ni la venta, ni su calificación, ni el expediente. Sirve para probar tu integración o para cotizar el riesgo antes de cerrar una venta.

curl -X POST "https://api.umbral-pld.com/api/ebr/evaluations?simulate=true" \
  -H "X-Api-Key: $UMBRAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @venta.json

Si tu cuenta es de saldo prepagado (solo el motor por API), cada evaluación descuenta de tu saldo así. Las cuentas con plan no usan saldo. Los paquetes y el alta en línea están en API del motor EBR.

Lo que mandas Descuenta
Una venta nueva (folio que no existe) 1 evaluación
Una venta que ya existe, con cualquier dato distinto 1 evaluación
La misma venta, idéntica a la que ya se calificó Nada (se vuelve a calificar con la matriz vigente)
Solo cancelarla o reactivarla (isCancelled) Nada
Historial en history o en POST /ebr/operations Nada al guardarla (no se califica). Si después la mandas a calificar, cuenta como venta nueva: 1 evaluación, aunque llegue idéntica.
Una simulación (?simulate=true) 1 por venta, aunque ya exista y sea igual
Las recalificaciones automáticas (cambió el expediente o su situación en listas) Nada

Si el saldo no alcanza para toda la petición, responde 402 con needed (lo que necesitaba) y available (lo que tienes), y no se califica ni se guarda ninguna venta del lote. Consulta tu saldo antes de un envío grande:

curl "https://api.umbral-pld.com/api/ebr/balance" \
  -H "X-Api-Key: $UMBRAL_API_KEY"
200 OK
{
  "available": 4870,
  "nextExpiry": "2027-11-02T18:20:11+00:00",
  "nextExpiryUnits": 4870,
  "usedThisMonth": 130,
  "lots": [
    {
      "id": 7,
      "source": "purchase",
      "packCode": "eval-5000",
      "units": 5000,
      "remaining": 4870,
      "createdAt": "2026-11-02T18:20:11+00:00",
      "expiresAt": "2027-11-02T18:20:11+00:00",
      "expired": false,
      "frozen": false,
      "cancelled": false,
      "note": null
    }
  ]
}

available son las evaluaciones que puedes usar hoy; nextExpiry y nextExpiryUnits, cuándo vence el siguiente paquete y cuántas vencen con él; usedThisMonth, lo usado en el mes, y lots, cada paquete (source: "purchase" comprado o "grant" cortesía; frozen: congelado por una disputa de su pago, y cancelled: anulado por un reembolso; en ambos casos lo que le queda no cuenta). Se gasta primero el paquete que vence antes. En una cuenta con plan todo viene en cero.

Cuadra tus cobros

Cada vez que una petición descuenta saldo queda un cobro con la fecha, cuántas evaluaciones, el motivo, los folios (operationId) que lo causaron y quién llamó (el nombre de tu llave y la IP). Pide los de un mes con month en formato AAAAMM; sin él, el mes en curso (hora de la Ciudad de México).

curl "https://api.umbral-pld.com/api/ebr/balance/movements?month=202611" \
  -H "X-Api-Key: $UMBRAL_API_KEY"
200 OK
{
  "month": 202611,
  "used": 3,
  "movements": [
    {
      "id": 412,
      "createdAt": "2026-11-17T16:02:45+00:00",
      "units": 2,
      "reason": "Evaluación (2 ventas nuevas o con cambios)",
      "operationIds": ["F-2026-1043", "F-2026-1044"],
      "actor": "Integración «Sistema de ventas» · 203.0.113.10"
    },
    {
      "id": 415,
      "createdAt": "2026-11-17T16:40:03+00:00",
      "units": 1,
      "reason": "Simulación (1 venta)",
      "operationIds": ["COT-77"],
      "actor": "Integración «Sistema de ventas» · 203.0.113.10"
    }
  ]
}

used es la suma de units del mes y coincide con usedThisMonth de tu saldo. Los cobros vienen del más antiguo al más reciente. Para cuadrar con tu sistema, cruza operationIds con tus folios: un folio que reenviaste idéntico, una cancelación o una recalificación automática no aparecen porque no cobraron. Con /excel al final de la ruta recibes lo mismo en una hoja de cálculo; también la descargas en la pantalla Motor EBR, en Cobros del mes. Un mes mal escrito responde 400.

Ventas anteriores (historial)

Los criterios de 12 meses (número y monto de operaciones del cliente con la sucursal) cuentan las ventas facturadas y no canceladas. Al arrancar, carga tus ventas del último año con POST /ebr/operations (hasta 50,000 por petición): se guardan sin calificarse y no descuentan saldo (si luego mandas una de ellas a calificar, esa sí descuenta 1). Responde cuántas se crearon y cuántas se actualizaron. También puedes mandarlas en history, junto a operations, en la misma llamada de evaluación.

curl -X POST "https://api.umbral-pld.com/api/ebr/operations" \
  -H "X-Api-Key: $UMBRAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @historial.json

# historial.json: las ventas con los mismos campos, p. ej.
# { "operations": [ { "operationId": "F-2025-0832", "businessUnit": "Sucursal Centro",
#     "personType": "individual", "curp": "LORA850312MJCPZN09",
#     "invoiceDate": "2025-12-03", "amount": 250000 } ] }

# Respuesta: { "created": 1, "updated": 0 }

6. Consultar una venta

GET /ebr/operations/{operationId} devuelve la venta como quedó guardada y todas sus calificaciones, de la más reciente a la más vieja. La vigente trae isCurrent: true; origin dice por qué se calificó ("integration", "manual", "excel", "customerFileChange" o "listMatch"). Codifica el folio si trae caracteres especiales.

curl "https://api.umbral-pld.com/api/ebr/operations/F-2026-0001" \
  -H "X-Api-Key: $UMBRAL_API_KEY"
200 OK (recortada)
{
  "operation": {
    "operationId": "F-2026-0001",
    "businessUnit": "Sucursal Centro",
    "customerNumber": "C-1045",
    "customerName": "Ana López Ruiz",
    "personType": "individual",
    "rfc": "LORA850312AB1",
    "curp": "LORA850312MJCPZN09",
    "uifActivity": "VEH",
    "productType": "Vehículo nuevo",
    "operationType": "Operación propia",
    "birthCountry": "México",
    "nationality": null,
    "residenceCountry": "México",
    "residenceState": "Jalisco",
    "economicActivityKey": "7140200",
    "economicActivity": null,
    "isPep": false,
    "isPepRelated": false,
    "channel": "Presencial",
    "currency": "Peso mexicano",
    "invoiceNumber": "A-5531",
    "invoiceDate": "2026-11-10T00:00:00",
    "amount": 400000,
    "taxes": 64000,
    "paymentMethod": "transfer",
    "isCancelled": false,
    "customerEmail": null
  },
  "evaluations": [
    {
      "id": 2,
      "evaluatedAt": "2026-11-13T21:29:04.7243+00:00",
      "isCurrent": true,
      "result": {
        "operationId": "F-2026-0001",
        "score": 37.25,
        "rating": "Bajo",
        "ratingLevelCode": "NR-03",
        "isComplete": false,
        "pending": [
          "EBR-09"
        ]
      },
      "origin": "integration",
      "triggeredBy": "Integración «DMS»"
    },
    {
      "id": 1,
      "evaluatedAt": "2026-11-13T21:29:04.4862+00:00",
      "isCurrent": false,
      "result": {
        "operationId": "F-2026-0001",
        "score": 37.25,
        "rating": "Bajo",
        "ratingLevelCode": "NR-03",
        "isComplete": false,
        "pending": [
          "EBR-09"
        ]
      },
      "origin": "integration",
      "triggeredBy": "Integración «DMS»"
    }
  ]
}

Una calificación guardada no cambia aunque después cambie la matriz: queda como evidencia. Si quieres calificar otra vez con la matriz vigente, reenvía la venta.

7. Errores

Todos los errores llegan como application/problem+json con status, title, detail y un traceId. Con un error 4xx no se guardó ninguna venta del lote: un solo error de validación rechaza la petición completa.

Código Qué significa Qué hacer
400 Datos no válidos. Con errors, la lista por campo y posición (operations[3].businessUnit). Sin errors, el JSON no se pudo leer: una opción que no existe ("wire" en paymentMethod), una fecha o un número mal escritos. Corrige y reenvía. No reintentes igual.
401 Falta la llave, está mal copiada o fue revocada. Revisa la cabecera X-Api-Key o crea otra llave.
402 insufficient-credit Tu saldo prepagado no alcanza para la petición. Trae needed y available. Compra un paquete o manda un lote más chico.
402 payment-required La cuenta de tu empresa tiene un pago vencido. El oficial de cumplimiento paga en Plan y pagos.
403 La llave de integración no sirve para ese endpoint: solo manda ventas y consulta sus resultados. Usa solo los endpoints de esta guía.
403 plan-scope Esa función es del plan completo de Umbral; tu cuenta del motor por API no la incluye. Usa los endpoints del motor de esta guía, o contrata el plan completo.
404 No existe una venta con ese folio en tu empresa. Revisa el folio (y que esté codificado en la dirección).
409 Ya existe un registro con esos datos y no se pudo guardar. Lee detail; reintentar igual no lo arregla.
429 Pasaste de 120 peticiones en el minuto con esa llave. Espera y reintenta; junta más ventas por petición.
5xx Falla de nuestro lado o de la red. Reintenta con espera creciente. Si sigue, escríbenos con el traceId.

Así se ven un 400 y un 402 de saldo:

400 Bad Request
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Datos no validos",
  "status": 400,
  "errors": {
    "operations[0].businessUnit": [
      "La sucursal Sucursal Norte no existe, esta inactiva o no la tienes asignada."
    ]
  },
  "traceId": "00-fd9e28cddb0bcbb2fa76e75dc49c1b77-b3b59f7a1d003f33-00"
}
402 Payment Required
{
  "type": "https://umbral-pld.com/problems/insufficient-credit",
  "title": "Saldo insuficiente",
  "status": 402,
  "detail": "Tu saldo no alcanza: esta petición necesita 1 evaluación y tienes 0. Compra un paquete de evaluaciones para seguir.",
  "needed": 1,
  "available": 0,
  "traceId": "00-21efcca00c158d5e7a2bcfc54aa65468-61f31a9bcd289330-00"
}

Un manejo completo en JavaScript: reintenta solo lo que vale la pena reintentar y distingue los dos 402 por su type.

umbral.mjs
// umbral.mjs · manda un lote y decide qué hacer con cada error
const API = 'https://api.umbral-pld.com/api';
const INSUFFICIENT_CREDIT = 'https://umbral-pld.com/problems/insufficient-credit';
const PAYMENT_REQUIRED = 'https://umbral-pld.com/problems/payment-required';

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function sendSales(operations, { attempts = 5 } = {}) {
  for (let attempt = 1; ; attempt++) {
    let res;
    try {
      res = await fetch(`${API}/ebr/evaluations`, {
        method: 'POST',
        headers: { 'X-Api-Key': process.env.UMBRAL_API_KEY, 'Content-Type': 'application/json' },
        body: JSON.stringify({ operations }),
      });
    } catch (error) {
      if (attempt >= attempts) throw error; // sin red: se reintenta como un 5xx
      await sleep(backoff(attempt));
      continue;
    }

    if (res.ok) return res.json();

    const problem = await res.json().catch(() => ({}));

    // 429 y 5xx: espera y reintenta el MISMO lote (los folios no se duplican).
    if ((res.status === 429 || res.status >= 500) && attempt < attempts) {
      await sleep(backoff(attempt));
      continue;
    }

    if (res.status === 400 && problem.errors) {
      // { "operations[0].businessUnit": ["La sucursal ... no existe ..."] }
      throw new Error(`Corrige estas ventas: ${JSON.stringify(problem.errors)}`);
    }
    if (res.status === 402 && problem.type === INSUFFICIENT_CREDIT) {
      throw new Error(`Saldo insuficiente: necesitas ${problem.needed} y tienes ${problem.available}.`);
    }
    if (res.status === 402 && problem.type === PAYMENT_REQUIRED) {
      throw new Error('La cuenta tiene un pago pendiente: avisa al oficial de cumplimiento.');
    }
    // 400 sin errors (JSON que no se pudo leer), 401, 403, 404, 409...
    throw new Error(`${res.status} ${problem.title ?? ''}: ${problem.detail ?? ''}`);
  }
}

// 2, 4, 8, 16... segundos (máximo 60), con algo de azar para no reintentar todos a la vez.
function backoff(attempt) {
  return Math.min(60, 2 ** attempt) * 1000 + Math.random() * 1000;
}

8. Avisos a tu sistema (webhooks)

En vez de preguntar, deja que Umbral te avise. En Configuración, sección Avisos a su sistema (webhooks), agrega la dirección de tu sistema (https, pública, puerto 443 u 8443) y elige los eventos. El secreto (whsec_…) se ve una sola vez: guárdalo junto a tu llave. El botón Probar manda un aviso ping.

Evento Cuándo llega
operation.evaluated Cada venta guardada y calificada (por la API, captura o Excel), y cada recalificación automática: si el oficial corrige el expediente (origin: "customerFileChange") o el cliente aparece en una lista ("listMatch"). Las simulaciones no avisan.
customer_file.status_changed Un expediente se crea o cambia de estado: "incomplete", "complete" o "alert" (algo pide revisión reforzada, p. ej. es PEP). missing trae los campos que le faltan.

Cada aviso es un POST con JSON { id, event, createdAt, data } y tres cabeceras: Umbral-Event (el evento), Umbral-Delivery (el id, igual en cada reintento) y Umbral-Signature: t=<unix>,v1=<hex>.

operation.evaluated

{
  "id": "4f6c2b1e-0d7a-4c55-9a51-2f0e8b7c9d10",
  "event": "operation.evaluated",
  "createdAt": "2026-11-13T21:29:05.1032+00:00",
  "data": {
    "operationId": "F-2026-0001",
    "businessUnit": "Sucursal Centro",
    "customerName": "Ana López Ruiz",
    "invoiceDate": "2026-11-10T00:00:00",
    "amount": 400000,
    "score": 37.25,
    "rating": "Bajo",
    "ratingLevelCode": "NR-03",
    "isComplete": false,
    "pending": [
      "EBR-09"
    ],
    "customerFile": {
      "code": "EXP-00001",
      "outcome": "created",
      "isComplete": false,
      "linkSent": true
    },
    "origin": "integration",
    "customerFileCode": null,
    "discrepancies": []
  }
}

customer_file.status_changed

{
  "id": "9b1d7e3a-52c4-4f0e-8d6b-1a2c3e4f5a6b",
  "event": "customer_file.status_changed",
  "createdAt": "2026-11-14T16:02:47.5518+00:00",
  "data": {
    "code": "EXP-00001",
    "businessUnit": "Sucursal Centro",
    "name": "Ana López Ruiz",
    "personType": "individual",
    "curp": "LORA850312MJCPZN09",
    "rfc": "LORA850312AB1",
    "previousStatus": "incomplete",
    "status": "complete",
    "missing": []
  }
}

Comprueba la firma

v1 es HMAC-SHA256(secreto, "<t>.<cuerpo>") en hexadecimal: el valor de t, un punto y el cuerpo exactamente como llegó, sin volver a serializarlo. Usa el secreto completo, con su prefijo whsec_. Compara en tiempo constante y descarta avisos con un t muy viejo. Cada reintento llega con un t nuevo.

JavaScript

avisos.mjs
// avisos.mjs · Node 18 o más reciente, sin dependencias
import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';

const SECRET = process.env.UMBRAL_WEBHOOK_SECRET; // whsec_... (completo, con el prefijo)
const TOLERANCE_SECONDS = 300; // descarta avisos firmados hace más de 5 minutos

export function isValidSignature(rawBody, header, secret, now = Date.now() / 1000) {
  const parts = {};
  for (const piece of String(header ?? '').split(',')) {
    const at = piece.indexOf('=');
    if (at > 0) parts[piece.slice(0, at).trim()] = piece.slice(at + 1).trim();
  }
  if (!/^\d+$/.test(parts.t ?? '') || !/^[0-9a-f]{64}$/.test(parts.v1 ?? '')) return false;
  if (Math.abs(now - Number(parts.t)) > TOLERANCE_SECONDS) return false;

  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest();
  return timingSafeEqual(expected, Buffer.from(parts.v1, 'hex'));
}

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const rawBody = Buffer.concat(chunks).toString('utf8'); // el cuerpo tal cual llegó
    if (!isValidSignature(rawBody, req.headers['umbral-signature'], SECRET)) {
      res.writeHead(400).end();
      return;
    }
    const notice = JSON.parse(rawBody);
    // notice.id es igual en cada reintento: si ya lo procesaste, solo responde 200.
    console.log(notice.event, notice.data);
    res.writeHead(200).end(); // responde en menos de 10 segundos; lo pesado, después
  });
}).listen(3000);

Python

avisos.py
# avisos.py · Python 3.8 o más reciente, solo biblioteca estándar
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300  # descarta avisos firmados hace más de 5 minutos


def is_valid_signature(raw_body: bytes, header: str, secret: str, now: float = None) -> bool:
    parts = {}
    for piece in (header or "").split(","):
        key, sep, value = piece.partition("=")
        if sep:
            parts[key.strip()] = value.strip()
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1:
        return False
    if abs((now or time.time()) - int(t)) > TOLERANCE_SECONDS:
        return False

    signed = t.encode() + b"." + raw_body  # el cuerpo tal cual llegó, en bytes
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Responde con un 2xx en menos de 10 segundos y procesa después. Si no, se reintenta a los 1 min, 5 min, 30 min, 2 h, 6 h y 12 h. Guarda el id de los avisos que ya procesaste para no hacerlo dos veces. En Configuración ves cada envío y lo puedes reenviar.

9. Buenas prácticas

Antes de salir a producción, revisa que:

  1. Tu llave está en una variable de entorno de tu servidor, no en el código.
  2. Cada sucursal que mandas en businessUnit existe y está activa en Matriz de riesgo › Sucursales.
  3. Probaste con ?simulate=true una venta de persona física y una de persona moral, y leíste su rating.
  4. Tu código distingue un 402 (sin saldo: compra un paquete, no reintentes) de un 429 o un 5xx (reintenta con espera).
  5. Cargaste tus ventas del último año con POST /ebr/operations, para que los criterios de 12 meses cuenten desde el primer día.
  6. Si usas webhooks, tu sistema comprueba la firma y responde 2xx rápido.
  • Un operationId por venta, siempre el mismo. Es lo que hace seguro reintentar: la misma venta se actualiza, no se duplica, y si llega igual a la ya calificada no descuenta saldo. No uses folios aleatorios por intento. Dentro de una petición, cada folio va una sola vez.
  • Manda la venta completa cada vez. Al actualizar, un campo que no mandas queda vacío; solo uifActivity, paymentMethod y, si el importe no cambia, taxes conservan lo que ya tenían.
  • Agrupa. Una petición con 200 ventas cuenta como una para el límite de 120 por minuto. Para cargas grandes, lotes de hasta 5,000.
  • Reintenta con espera ante 429, 5xx o falta de red: 2, 4, 8, 16 segundos, hasta 60. Un 400, 401, 403 o 404 no se arregla reintentando.
  • La llave, solo en tu servidor. Variable de entorno o almacén de secretos; nunca en el navegador, en una app móvil ni en el repositorio. Usa una llave por sistema: cada llamada queda en la bitácora a nombre de su llave y la puedes revocar sin afectar a las demás.
  • Guarda el ratingLevelCode junto a la venta en tu sistema y decide con él, no con el nombre del nivel.

10. Preguntas frecuentes

¿Cómo pruebo sin guardar nada?

Con ?simulate=true: califica igual y no guarda la venta, su calificación ni el expediente. En una cuenta de saldo prepagado descuenta 1 evaluación por venta.

¿Puedo llamar a la API desde el navegador o una app móvil?

No. La llave quedaría a la vista de cualquiera. Llama desde tu servidor y, si hace falta, que tu aplicación hable con tu servidor.

¿Qué pasa si revoco una llave?

Deja de servir al momento: las peticiones con ella responden 401. Crea otra y cámbiala en tu sistema.

Mandé una venta con datos distintos al expediente. ¿Cuál vale?

El expediente. La venta se guarda tal como llegó, se califica con los datos del expediente y la diferencia llega en discrepancies. Si el oficial corrige el expediente, la venta se recalifica sola y te llega otro operation.evaluated, sin costo.

¿Por qué el criterio de listas sale pendiente?

Ese dato no lo mandas tú: Umbral lo pone al calificar, con las listas que tiene cargadas. Si sale pendiente, no había listas cargadas para revisar al cliente en ese momento.

¿Cómo cancelo una venta?

Reenvíala igual, con "isCancelled": true. No descuenta saldo y deja de contar en los criterios de 12 meses del cliente.

¿Dónde está el detalle de cada campo?

En la referencia completa de la API, generada del código: cada endpoint, cada campo y cada respuesta, y la puedes probar con tu llave. El esquema OpenAPI está en /api/docs/integracion-v1.json.

¿Te atoraste? Escríbenos a [email protected] con el traceId de la respuesta y lo revisamos.

Consulta también: Conecta tu sistema de ventas Consulta también: Solo el motor por API, desde $990 · Seguridad · Precios · Términos y condiciones.