{
  "openapi": "3.1.1",
  "info": {
    "title": "Umbral PLD · Integración",
    "description": "Con esta API su sistema de ventas (DMS) manda cada venta a Umbral PLD y recibe su\ncalificación de riesgo (EBR) según la matriz vigente de su empresa.\n\n**Guía con ejemplos** (cURL, JavaScript, Python, PHP y C#): https://umbral-pld.com/desarrolladores\n\n**Autenticación.** Cree una llave en Umbral (*Configuración → Integración con su\nsistema*; en una cuenta solo del motor, el botón «Ir a las llaves» de *Motor EBR*) y mándela en la cabecera `X-Api-Key` de cada llamada. La llave solo sirve para los\nendpoints de esta página.\n\n**Límites.** Hasta 120 llamadas por minuto por llave (si se pasa, la respuesta es 429).\nCada llamada puede traer hasta 5,000 ventas.\n\n**Errores.** Siguen RFC 9457 (`application/problem+json`): 400 con `errors` por campo,\n401 sin llave válida, 403 fuera de su alcance, 402 si la cuenta tiene el pago vencido\n(`payment-required`) o si el saldo de evaluaciones no alcanza (`insufficient-credit`).\n\n**Expedientes.** Con cada venta guardada se crea el expediente del cliente si no tiene\n(lo decide la empresa en Configuración). Mande `customerEmail` para que se le pueda enviar\nel enlace para completarlo. La respuesta trae `customerFiles` con lo que pasó en cada venta.\nSi el cliente ya tiene expediente, **sus datos mandan**: países, estado, actividad y PEP se\ntoman del expediente (lo revisa el oficial) y lo que la venta trae distinto vuelve en\n`discrepancies` (`field`, `sent`, `onFile`), con el expediente en `customerFileCode`. Si el\noficial corrige el expediente, sus ventas vigentes se recalifican solas y llega otro\n`operation.evaluated` con `origin: \"customerFileChange\"`.\n\n**Avisos (webhooks).** En *Configuración → Avisos a su sistema* registre una dirección https\ny Umbral le manda un `POST` JSON `{ id, event, createdAt, data }` con los eventos\n`operation.evaluated` (venta calificada) y `customer_file.status_changed` (expediente que\nse crea o cambia de estado). Cabeceras: `Umbral-Event`, `Umbral-Delivery` (el `id`, igual\nen cada reintento) y `Umbral-Signature: t=<unix>,v1=<hex>`, donde\n`v1 = HMAC-SHA256(secreto, \"<t>.<cuerpo>\")`. Responda 2xx en menos de 10 segundos; si no,\nse reintenta a los 1 min, 5 min, 30 min, 2 h, 6 h y 12 h.",
    "version": "v1"
  },
  "paths": {
    "/api/ebr/evaluations": {
      "post": {
        "tags": [
          "EBR - Evaluacion"
        ],
        "summary": "Mandar ventas y calificarlas",
        "description": "Guarda cada venta (crea o actualiza por `operationId`) y la califica con la matriz vigente.\nLa respuesta trae, por venta, su nivel de riesgo, el puntaje de cada criterio y los avisos.\nPara operaciones anteriores que no necesitan calificarse, mándelas en `history`.\nCon `simulate=true` solo calcula: no guarda nada.\nCuentas con saldo prepagado: cada venta nueva o que llega con datos distintos descuenta\n1 evaluación (un reenvío idéntico, cancelar o reactivar no descuentan; la simulación\ndescuenta 1 por venta). Si el saldo no alcanza responde 402 con tipo `insufficient-credit`\n(`needed` y `available`) y no califica ni guarda nada. Consulte el saldo en `GET /api/ebr/balance`.",
        "parameters": [
          {
            "name": "simulate",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvaluationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvaluationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpValidationProblemDetails"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/ebr/operations": {
      "post": {
        "tags": [
          "EBR - Operaciones"
        ],
        "summary": "Mandar ventas sin calificarlas",
        "description": "Guarda el historial (crea o actualiza por operationId) sin calificarlo; cuenta para la ventana de 12 meses de las siguientes ventas del cliente.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OperationsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OperationsSaved"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpValidationProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/ebr/operations/{operationId}": {
      "get": {
        "tags": [
          "EBR - Operaciones"
        ],
        "summary": "Consultar una venta",
        "description": "La venta por su folio, con todas sus calificaciones (la más reciente primero).",
        "parameters": [
          {
            "name": "operationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OperationHistory"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/ebr/balance/movements": {
      "get": {
        "tags": [
          "EBR - Saldo"
        ],
        "summary": "Consultar los cobros del mes",
        "description": "Cada cobro de evaluaciones del mes (202611; el actual si no se manda): cuándo, cuántas, el motivo, los folios de las ventas que lo causaron y quién lo hizo. Para cuadrar el consumo con tu sistema.",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvaluationMovementsDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/ebr/balance/movements/excel": {
      "get": {
        "tags": [
          "EBR - Saldo"
        ],
        "summary": "Descargar los cobros del mes en Excel",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/ebr/balance": {
      "get": {
        "tags": [
          "EBR - Saldo"
        ],
        "summary": "Consultar el saldo de evaluaciones",
        "description": "Las evaluaciones disponibles del motor (de los paquetes vigentes), cuándo vence el siguiente paquete y cuántas vencen con él, lo usado en el mes y cada paquete.",
        "responses": {
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvaluationBalanceDto"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CriterionEvaluation": {
        "required": [
          "criterionCode",
          "criterionName",
          "source",
          "weight",
          "valueRead",
          "option",
          "riskLevel",
          "percentage",
          "weighted",
          "outcome"
        ],
        "type": "object",
        "properties": {
          "criterionCode": {
            "type": "string"
          },
          "criterionName": {
            "type": "string"
          },
          "source": {
            "$ref": "#/components/schemas/CriterionSource"
          },
          "weight": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "format": "double"
          },
          "valueRead": {
            "type": [
              "null",
              "string"
            ]
          },
          "option": {
            "type": [
              "null",
              "string"
            ]
          },
          "riskLevel": {
            "type": [
              "null",
              "string"
            ]
          },
          "percentage": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "format": "double"
          },
          "weighted": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "format": "double"
          },
          "outcome": {
            "$ref": "#/components/schemas/CriterionOutcome"
          }
        },
        "description": "Un criterio calificado. `ValueRead` es lo que se leyo de la operacion (o el\nconteo / monto calculado), para auditar el empate. `Weighted` es peso x\nporcentaje del nivel / 100 (8 % x 50 % = 4.00)."
      },
      "CriterionOutcome": {
        "enum": [
          "resolved",
          "noOptions",
          "emptyValue",
          "noMatch",
          "noActivity",
          "activityWithoutRisk",
          "noIdentification",
          "noField"
        ],
        "description": "Como termino la resolucion de un criterio. Todo lo que no es CriterionOutcome.Resolved queda pendiente y pondera 0."
      },
      "CriterionSource": {
        "enum": [
          "field",
          "fixed",
          "economicActivity",
          "pep",
          "operationCount",
          "operationAmount",
          "watchlist"
        ],
        "description": "De donde sale el valor que califica un criterio.\n\nEn ProjectoX esto se decidia por el codigo del criterio (EBR-7, EBR-8,\nEBR-11...); aqui cada criterio declara su origen, asi que un cliente puede\narmar su propia matriz sin que el motor conozca sus codigos."
      },
      "CustomerDataDiscrepancy": {
        "required": [
          "field",
          "sent",
          "onFile"
        ],
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "sent": {
            "type": "string"
          },
          "onFile": {
            "type": "string"
          }
        },
        "description": "Un dato del cliente que la venta traia distinto a su expediente: se califico con `OnFile`."
      },
      "EvaluationBalanceDto": {
        "required": [
          "available",
          "nextExpiry",
          "nextExpiryUnits",
          "usedThisMonth",
          "lots"
        ],
        "type": "object",
        "properties": {
          "available": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "nextExpiry": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "nextExpiryUnits": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "usedThisMonth": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "lots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EvaluationLotDto"
            }
          }
        },
        "description": "El saldo del motor EBR de una empresa: las evaluaciones disponibles (de los lotes vigentes),\ncuando vence el siguiente lote y cuantas vencen con el, lo usado en el mes y los lotes (del que\nvence antes al que vence despues)."
      },
      "EvaluationCreditSource": {
        "enum": [
          "purchase",
          "grant"
        ],
        "description": "De donde salio un lote de evaluaciones del motor EBR."
      },
      "EvaluationLotDto": {
        "required": [
          "id",
          "source",
          "packCode",
          "units",
          "remaining",
          "createdAt",
          "expiresAt",
          "expired"
        ],
        "type": "object",
        "properties": {
          "id": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "source": {
            "$ref": "#/components/schemas/EvaluationCreditSource"
          },
          "packCode": {
            "type": [
              "null",
              "string"
            ]
          },
          "units": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "remaining": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "expired": {
            "type": "boolean"
          },
          "note": {
            "type": [
              "null",
              "string"
            ]
          },
          "frozen": {
            "type": "boolean",
            "default": false
          },
          "cancelled": {
            "type": "boolean",
            "default": false
          }
        },
        "description": "Un lote del saldo del motor EBR. `Note` (nota interna) solo la ve la plataforma.\n`Expired`: ya vencio (lo que le quedaba ya no cuenta). `Frozen`: congelado por un\ncontracargo o una disputa de su pago. `Cancelled`: lo que quedaba se anulo (reembolso)."
      },
      "EvaluationMovementDto": {
        "required": [
          "id",
          "createdAt",
          "units",
          "reason",
          "operationIds",
          "actor"
        ],
        "type": "object",
        "properties": {
          "id": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "units": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "reason": {
            "type": "string"
          },
          "operationIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "actor": {
            "type": [
              "null",
              "string"
            ]
          }
        },
        "description": "El saldo prepagado del motor EBR (cuentas «solo API»): la empresa lo consulta y la plataforma\nlo consulta y da cortesias. Las compras estan en IEvaluationPackService."
      },
      "EvaluationMovementsDto": {
        "required": [
          "month",
          "used",
          "movements"
        ],
        "type": "object",
        "properties": {
          "month": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "used": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "movements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EvaluationMovementDto"
            }
          }
        },
        "description": "Los cobros de un mes (como 202611, hora de México), del más viejo al más nuevo, y su suma."
      },
      "EvaluationOrigin": {
        "enum": [
          "unknown",
          "integration",
          "manual",
          "excel",
          "customerFileChange",
          "listMatch"
        ],
        "description": "Por que existe una evaluacion: de donde llego la venta o que la recalifico.",
        "default": "unknown"
      },
      "EvaluationRequest": {
        "required": [
          "operations"
        ],
        "type": "object",
        "properties": {
          "operations": {
            "maxItems": 5000,
            "minItems": 1,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OperationInput"
            }
          },
          "history": {
            "maxItems": 50000,
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/OperationInput"
            }
          }
        },
        "description": "Operaciones a calificar y, opcionalmente, su historial.\n\nLa ventana de 12 meses de cada operacion se arma con las facturadas que vienen en\nla peticion (de las dos listas) MAS las que el tenant ya tiene guardadas. Si un\nfolio viene en la peticion y tambien esta guardado, vale lo de la peticion.\nIReadOnlyList&lt;OperationInput&gt;? EvaluationRequest.History sirve para mandar operaciones anteriores sin que salgan calificadas."
      },
      "EvaluationResponse": {
        "required": [
          "operations",
          "portfolio"
        ],
        "type": "object",
        "properties": {
          "operations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OperationEvaluation"
            }
          },
          "portfolio": {
            "$ref": "#/components/schemas/PortfolioSummary"
          },
          "customerFiles": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/SaleCustomerFile"
            }
          }
        },
        "description": "Respuesta de una evaluacion: cada operacion, en el orden en que llego, y el resumen de cartera.\n`CustomerFiles`: el expediente del cliente de cada venta guardada (si la empresa los crea solos)."
      },
      "HttpValidationProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": [
              "null",
              "string"
            ]
          },
          "title": {
            "type": [
              "null",
              "string"
            ]
          },
          "status": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "detail": {
            "type": [
              "null",
              "string"
            ]
          },
          "instance": {
            "type": [
              "null",
              "string"
            ]
          },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      },
      "OperationEvaluation": {
        "required": [
          "operationId",
          "businessUnit",
          "customerNumber",
          "customerName",
          "customerKey",
          "invoiceDate",
          "amount",
          "score",
          "weightSum",
          "criteriaCount",
          "resolvedCount",
          "isComplete",
          "rating",
          "ratingLevelCode",
          "isFinancialEntity",
          "outOfTable",
          "pending",
          "criteria"
        ],
        "type": "object",
        "properties": {
          "operationId": {
            "type": "string"
          },
          "businessUnit": {
            "type": "string"
          },
          "customerNumber": {
            "type": [
              "null",
              "string"
            ]
          },
          "customerName": {
            "type": [
              "null",
              "string"
            ]
          },
          "customerKey": {
            "type": [
              "null",
              "string"
            ]
          },
          "invoiceDate": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          },
          "amount": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "format": "double"
          },
          "score": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "format": "double"
          },
          "weightSum": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "format": "double"
          },
          "criteriaCount": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "resolvedCount": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "isComplete": {
            "type": "boolean"
          },
          "rating": {
            "type": [
              "null",
              "string"
            ]
          },
          "ratingLevelCode": {
            "type": [
              "null",
              "string"
            ]
          },
          "isFinancialEntity": {
            "type": "boolean"
          },
          "outOfTable": {
            "type": "boolean"
          },
          "pending": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "criteria": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CriterionEvaluation"
            }
          },
          "evaluationId": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "customerFileCode": {
            "type": [
              "null",
              "string"
            ]
          },
          "discrepancies": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/CustomerDataDiscrepancy"
            }
          },
          "mandatoryHigh": {
            "type": [
              "null",
              "string"
            ]
          }
        },
        "description": "            La calificacion de una operacion.\n            * CustomerKey: llave con la que se juntaron las operaciones del cliente; nula sin identificacion.\n* Score: suma de lo ponderado, en escala 0-100. WeightSum: suma de los pesos evaluados; deberia ser 100.\n* Rating y RatingLevelCode: el nivel de riesgo que le toca; nulos si no hay tabulador.\n* IsFinancialEntity: la calificacion se fijo por ser entidad financiera, no por el tabulador.\n* OutOfTable: todo resolvio pero no hay tabulador de cliente configurado.\n* Pending: codigos de los criterios que no se resolvieron.\n* EvaluationId: la evaluacion congelada que quedo guardada; nulo en una simulacion.\n* CustomerFileCode: el expediente del que salieron los datos del cliente; nulo si no tiene.\n* Discrepancies: lo que la venta traia distinto al expediente (se califico con lo del expediente).\n* MandatoryHigh: por que la calificacion se fijo en el nivel mas alto (riesgo alto obligatorio); nulo si salio del tabulador."
      },
      "OperationHistory": {
        "required": [
          "operation",
          "evaluations"
        ],
        "type": "object",
        "properties": {
          "operation": {
            "$ref": "#/components/schemas/OperationInput"
          },
          "evaluations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StoredEvaluation"
            }
          }
        },
        "description": "Una operacion guardada y todas sus evaluaciones, de la mas nueva a la mas vieja."
      },
      "OperationInput": {
        "required": [
          "operationId",
          "businessUnit",
          "personType"
        ],
        "type": "object",
        "properties": {
          "operationId": {
            "maxLength": 50,
            "minLength": 0,
            "type": "string",
            "description": "Folio de la operacion en el sistema del cliente. Unico dentro de una peticion."
          },
          "businessUnit": {
            "maxLength": 100,
            "minLength": 0,
            "type": "string",
            "description": "Unidad de negocio (marca, agencia) que realizo la operacion. La ventana de\n12 meses cuenta solo las operaciones del cliente con la misma unidad."
          },
          "customerNumber": {
            "maxLength": 50,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "customerName": {
            "maxLength": 300,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "personType": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PersonType"
              }
            ]
          },
          "rfc": {
            "maxLength": 13,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ],
            "description": "Identifica al cliente en persona moral, y en fisica cuando no trae CURP."
          },
          "curp": {
            "maxLength": 18,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ],
            "description": "Identifica al cliente en persona fisica."
          },
          "uifActivity": {
            "type": [
              "null",
              "string"
            ],
            "description": "La actividad vulnerable de la operacion (clave de Umbral: VEH, INM, DIN, JYR, OBA, BLI, MPC,\nARI, JYS o DON), para la empresa con varias. Nula: la primera de la empresa (o la que ya tenia)."
          },
          "productType": {
            "maxLength": 200,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "operationType": {
            "maxLength": 200,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "birthCountry": {
            "maxLength": 200,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "nationality": {
            "maxLength": 200,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ],
            "description": "En persona moral sustituye al pais de nacimiento."
          },
          "residenceCountry": {
            "maxLength": 200,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "residenceState": {
            "maxLength": 200,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "economicActivityKey": {
            "maxLength": 20,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ],
            "description": "Clave SAT de la actividad economica preponderante. Si no empata, se busca por string? OperationInput.EconomicActivity."
          },
          "economicActivity": {
            "maxLength": 600,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ],
            "description": "Descripcion de la actividad, para quien no maneja la clave SAT. Se compara sin acentos ni mayusculas."
          },
          "isPep": {
            "type": [
              "null",
              "boolean"
            ],
            "description": "¿El cliente desempena o desempeno un cargo publico? Nulo = no se capturo."
          },
          "isPepRelated": {
            "type": [
              "null",
              "boolean"
            ],
            "description": "¿Un familiar o asociado cercano es PEP? Nulo = no se capturo."
          },
          "channel": {
            "maxLength": 200,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ],
            "description": "Canal por el que se realizo (p. ej. Presencial)."
          },
          "currency": {
            "maxLength": 200,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ],
            "description": "Moneda de la operacion (p. ej. Peso mexicano)."
          },
          "invoiceNumber": {
            "maxLength": 50,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ]
          },
          "invoiceDate": {
            "type": [
              "null",
              "string"
            ],
            "description": "Fecha de facturacion. Nula = todavia no se factura. Si llega con hora y zona (un DMS que manda\n`2026-10-31T19:00:00-06:00`), cuenta el dia en la Ciudad de Mexico: el 31 no se vuelve 1 de\nnoviembre (otro mes de aviso). Ver DateTime? InvoiceDates.OfMexico(DateTime? value).",
            "format": "date-time"
          },
          "amount": {
            "maximum": 999999999999,
            "minimum": 0,
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "description": "Importe SIN impuestos (el subtotal de la factura): con el se miden la identificacion y el aviso\n(Reglamento art. 6). Nulo = no se capturo (no suma al monto de 12 meses).",
            "format": "double"
          },
          "taxes": {
            "maximum": 999999999999,
            "minimum": 0,
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "description": "Impuestos de la operacion (IVA y otros; 0 si va exenta). Con ellos se mide el limite de efectivo\n(art. 32). Nulo = no se mandan aparte: el importe se toma como total para todo.",
            "format": "double"
          },
          "paymentMethod": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "Forma de pago (la que cubre la mayor parte). No entra a la calificacion: decide que pide\nel expediente de venta. Nula = no se manda (se conserva la que se haya capturado en Umbral).",
                "$ref": "#/components/schemas/PaymentMethod"
              }
            ]
          },
          "isCancelled": {
            "type": "boolean",
            "description": "Una operacion cancelada nunca cuenta en la ventana de 12 meses."
          },
          "customerEmail": {
            "maxLength": 254,
            "minLength": 0,
            "type": [
              "null",
              "string"
            ],
            "description": "Correo del cliente. No entra a la calificacion ni se guarda en la operacion: va al expediente\nque se crea con la venta y sirve para mandarle el enlace para completarlo."
          }
        },
        "description": "Una operacion tal como la manda el cliente del SaaS: el contrato de datos del\nEBR. Es todo lo que el motor necesita; no conoce el sistema de origen.\n\nLas operaciones FACTURADAS (con DateTime? OperationInput.InvoiceDate y sin\nbool OperationInput.IsCancelled) alimentan la ventana de 12 meses de las demas\noperaciones del mismo cliente."
      },
      "OperationsRequest": {
        "required": [
          "operations"
        ],
        "type": "object",
        "properties": {
          "operations": {
            "maxItems": 50000,
            "minItems": 1,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OperationInput"
            }
          }
        },
        "description": "Operaciones para guardar en el historial sin calificarlas (p. ej. la carga inicial\nde los ultimos 12 meses). Un folio que ya existe se actualiza."
      },
      "OperationsSaved": {
        "required": [
          "created",
          "updated"
        ],
        "type": "object",
        "properties": {
          "created": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "updated": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          }
        },
        "description": "Cuantas operaciones se crearon y cuantas ya existian y se actualizaron."
      },
      "PaymentMethod": {
        "enum": [
          "cash",
          "transfer",
          "card",
          "financing",
          "lease",
          null
        ]
      },
      "PersonType": {
        "enum": [
          "individual",
          "company",
          "trust",
          null
        ]
      },
      "PortfolioSummary": {
        "required": [
          "operations",
          "complete",
          "incomplete",
          "totalAmount",
          "averageScore",
          "rating",
          "outOfTable",
          "byRating"
        ],
        "type": "object",
        "properties": {
          "operations": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "complete": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "incomplete": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "totalAmount": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "format": "double"
          },
          "averageScore": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "format": "double"
          },
          "rating": {
            "type": [
              "null",
              "string"
            ]
          },
          "outOfTable": {
            "type": "boolean"
          },
          "byRating": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RatingCount"
            }
          }
        },
        "description": "Resumen de cartera de las operaciones calificadas. `AverageScore` es el\npromedio de los puntajes redondeado a dos decimales (mitad hacia arriba), nulo sin\noperaciones; `Rating` lo califica con el tabulador de cartera, y\n`OutOfTable` avisa que hay operaciones pero no hay tabulador de cartera."
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": [
              "null",
              "string"
            ]
          },
          "title": {
            "type": [
              "null",
              "string"
            ]
          },
          "status": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "detail": {
            "type": [
              "null",
              "string"
            ]
          },
          "instance": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "RatingCount": {
        "required": [
          "rating",
          "operations",
          "percentage"
        ],
        "type": "object",
        "properties": {
          "rating": {
            "type": "string"
          },
          "operations": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "percentage": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "format": "double"
          }
        },
        "description": "Cuantas operaciones cayeron en una calificacion. `Percentage` es del total de\noperaciones, redondeado a un decimal (mitad hacia arriba)."
      },
      "SaleCustomerFile": {
        "required": [
          "operationId",
          "outcome",
          "customerFileId",
          "customerFileCode",
          "isComplete",
          "linkSent",
          "problem"
        ],
        "type": "object",
        "properties": {
          "operationId": {
            "type": "string"
          },
          "outcome": {
            "$ref": "#/components/schemas/SaleCustomerFileOutcome"
          },
          "customerFileId": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "customerFileCode": {
            "type": [
              "null",
              "string"
            ]
          },
          "isComplete": {
            "type": "boolean"
          },
          "linkSent": {
            "type": "boolean"
          },
          "problem": {
            "type": [
              "null",
              "string"
            ]
          }
        },
        "description": "El expediente de una venta. bool SaleCustomerFile.LinkSent: se le mando al cliente el enlace para\ncompletarlo. string? SaleCustomerFile.Problem dice por que no se creo o no se mando."
      },
      "SaleCustomerFileOutcome": {
        "enum": [
          "created",
          "existing",
          "failed"
        ],
        "description": "Que paso con el expediente del cliente de una venta guardada."
      },
      "StoredEvaluation": {
        "required": [
          "id",
          "evaluatedAt",
          "isCurrent",
          "result"
        ],
        "type": "object",
        "properties": {
          "id": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "evaluatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "isCurrent": {
            "type": "boolean"
          },
          "result": {
            "$ref": "#/components/schemas/OperationEvaluation"
          },
          "origin": {
            "$ref": "#/components/schemas/EvaluationOrigin"
          },
          "triggeredBy": {
            "type": [
              "null",
              "string"
            ]
          }
        },
        "description": "Una evaluacion guardada, tal como quedo congelada. `IsCurrent` dice si es la\nvigente de su operacion; las anteriores son su historial. `Origin` y\n`TriggeredBy`: por que se califico y quien lo provoco."
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "description": "La llave de integración (empieza con umb_).",
        "name": "X-Api-Key",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "ApiKey": [ ]
    }
  ],
  "tags": [
    {
      "name": "EBR - Evaluacion"
    },
    {
      "name": "EBR - Operaciones"
    },
    {
      "name": "EBR - Saldo"
    }
  ]
}