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-Keycon tu llave de integración (umb_…) - Formato
-
JSON en UTF-8, nombres en
camelCasey 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
-
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. -
Revisa el nombre de tu sucursal. Cada venta trae en
businessUnitel 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. -
Manda tu primera venta con el ejemplo de abajo y lee
ratingen 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.
{
"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"
}
]
}
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 · 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 · 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.
<?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 · .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.
{
"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"
{
"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"
{
"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"
{
"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:
{
"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"
}
{
"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 · 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 · 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 · 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:
- Tu llave está en una variable de entorno de tu servidor, no en el código.
-
Cada sucursal que mandas en
businessUnitexiste y está activa en Matriz de riesgo › Sucursales. -
Probaste con
?simulate=trueuna venta de persona física y una de persona moral, y leíste surating. -
Tu código distingue un
402(sin saldo: compra un paquete, no reintentes) de un429o un5xx(reintenta con espera). -
Cargaste tus ventas del último año con
POST /ebr/operations, para que los criterios de 12 meses cuenten desde el primer día. -
Si usas webhooks, tu sistema comprueba la firma y responde
2xxrápido.
-
Un
operationIdpor 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,paymentMethody, si el importe no cambia,taxesconservan 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
ratingLevelCodejunto 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.