> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Reservar capacidad de transacción > Usa este endpoint para reservar capacidad de transacción frente a los límites de gasto — fase uno del flujo de reserva en dos fases. Proporciona el `transactionId` del ledger sobre el que se indexa la reserva; la respuesta devuelve un ID de reserva por cada límite respaldado por contador que debas confirmar o liberar más tarde. Cuando se excedería un límite de gasto, la respuesta se devuelve con `denied` en `true` y no se retiene capacidad. Las reservas son idempotentes por `transactionId` — reintentar la misma reserva devuelve el mismo identificador. ## OpenAPI ````yaml es/openapi/v3-current/tracer.yaml post /v1/reservations openapi: 3.1.0 info: title: API de Tracer description: >- Referencia completa de la API para los servicios de Tracer, incluyendo validacion de transacciones, gestion de reglas, limites de gasto y eventos de auditoria para cumplimiento SOX/GLBA. version: 1.0.1 servers: - url: https://tracer.sandbox.lerian.net security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Health API description: >- Endpoints de verificacion de salud para sondas de vida y preparacion. Estos endpoints no requieren autenticacion. - name: Validations API description: >- Endpoints de validación de transacciones. El objetivo de rendimiento es inferior a 80ms (p99). Las validaciones son idempotentes por `requestId` — una solicitud duplicada devuelve el resultado en caché con HTTP 200, mientras que una solicitud nueva devuelve HTTP 201. No se requiere encabezado de idempotencia. - name: Rules API description: >- Endpoints de gestion de reglas de validacion. Las reglas utilizan expresiones CEL (Common Expression Language). - name: Limits API description: >- Endpoints de gestion de limites de gasto. Los limites controlan los montos de transacciones por alcance y periodo. - name: Reservations API description: >- Endpoints de reserva de capacidad de transacción en dos fases. Una reserva retiene capacidad frente a los límites de gasto; una confirmación la consolida y una liberación la devuelve. Confirmar y liberar son idempotentes. - name: Audit Events API description: >- Endpoints de rastro de auditoria para cumplimiento SOX/GLBA. Todas las decisiones de validacion y cambios de configuracion son registrados. paths: /v1/reservations: post: tags: - Reservations API summary: Reservar capacidad de transacción description: >- Usa este endpoint para reservar capacidad de transacción frente a los límites de gasto — fase uno del flujo de reserva en dos fases. Proporciona el `transactionId` del ledger sobre el que se indexa la reserva; la respuesta devuelve un ID de reserva por cada límite respaldado por contador que debas confirmar o liberar más tarde. Cuando se excedería un límite de gasto, la respuesta se devuelve con `denied` en `true` y no se retiene capacidad. Las reservas son idempotentes por `transactionId` — reintentar la misma reserva devuelve el mismo identificador. operationId: createReservation parameters: - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XApiKey' - $ref: '#/components/parameters/XRequestId' requestBody: content: application/json: schema: $ref: '#/components/schemas/ReserveRequest' example: transactionId: 019c96a0-1071-7a0d-9916-a831221de252 requestId: 019c96a0-10ce-75fc-a273-dc799079a99c transactionType: CARD amount: '1500.00' currency: USD transactionTimestamp: '2026-01-30T10:00:00Z' account: accountId: 019c96a0-0c0d-7915-84b9-e497bfee9916 type: checking status: active responses: '201': description: >- Indica que la reserva fue procesada. Revisa `denied` para confirmar si se concedió capacidad o si fue rechazada por un límite de gasto. content: application/json: schema: $ref: '#/components/schemas/ReserveResponse' example: transactionId: 019c96a0-1071-7a0d-9916-a831221de252 denied: false reservationIds: - 019c96a0-10d2-7193-8841-0d7347efd09a '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0003: $ref: '#/components/examples/Error0003' Error0011: $ref: '#/components/examples/Error0011' Error0020: $ref: '#/components/examples/Error0020' '401': description: No autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorUnauthenticated: $ref: '#/components/examples/ErrorUnauthenticated' '500': description: Error Interno del Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0004: $ref: '#/components/examples/Error0004' components: parameters: ContentType: name: Content-Type in: header description: El tipo de medio del recurso. Debe ser `application/json`. required: true example: application/json schema: type: string XApiKey: name: X-API-Key in: header description: >- La clave API para autenticacion. **Este encabezado es requerido para todos los endpoints excepto verificaciones de salud**. required: true schema: type: string XRequestId: name: X-Request-Id in: header description: Un identificador unico usado para rastrear y seguir cada solicitud. required: false example: 019c96a0-10ce-75fc-a273-dc799079a99c schema: type: string format: uuid schemas: ReserveRequest: type: object description: >- Solicitud de reserva para la fase uno. Replica la carga útil de validación de transacción y añade el `transactionId` del ledger sobre el que se indexa el ciclo de vida de la reserva. Para las reservas, `transactionType` y `account` son opcionales porque el ledger puede no conocer el riel de pago o un UUID de cuenta interno en el punto de reserva; `requestId`, `amount`, `currency` y `transactionTimestamp` siguen siendo obligatorios. required: - transactionId - requestId - amount - currency - transactionTimestamp properties: transactionId: type: string format: uuid description: >- ID de correlación de la transacción del ledger sobre el que se indexa la reserva. También es el grano de idempotencia para reservas reintentadas. longLived: type: boolean default: false description: >- Selecciona la vida útil de la reserva. Usa `true` para una transacción pendiente que no debe expirar mientras siga siendo válida; `false` (el valor por defecto) para una transacción directa. requestId: type: string format: uuid description: >- ID único generado por el cliente para idempotencia y correlación del rastro de auditoría. transactionType: type: string enum: - CARD - WIRE - Pix - CRYPTO description: Tipo de transacción (método de pago). Opcional para las reservas. subType: type: string maxLength: 50 description: >- Subtipo de transacción para contexto adicional (p. ej., débito, crédito, prepago). amount: type: string description: >- Monto de la transacción como cadena decimal (p. ej., "1500.00"). Debe ser un valor decimal positivo. currency: type: string minLength: 3 maxLength: 3 description: >- Código de moneda ISO 4217 (mayúsculas). Los códigos en minúsculas se rechazan. transactionTimestamp: type: string format: date-time description: >- Marca de tiempo de la transacción en formato RFC3339 con zona horaria. account: $ref: '#/components/schemas/AccountContext' segment: $ref: '#/components/schemas/SegmentContext' portfolio: $ref: '#/components/schemas/PortfolioContext' merchant: $ref: '#/components/schemas/MerchantContext' metadata: type: object additionalProperties: true description: Pares clave-valor personalizados para las expresiones de reglas. ReserveResponse: type: object description: >- Identificador devuelto en una reserva exitosa. Cuando `denied` es true no se retuvo capacidad y `reservationIds` está vacío; de lo contrario, `reservationIds` contiene un ID por cada límite respaldado por contador que el ledger debe confirmar o liberar más tarde. required: - transactionId - denied - reservationIds properties: transactionId: type: string format: uuid description: El ID de correlación de la transacción del ledger de la solicitud. denied: type: boolean description: >- Si la reserva fue rechazada porque se excedería un límite de gasto. Cuando es true, no se retiene capacidad. reservationIds: type: array items: type: string format: uuid description: >- Un ID de reserva por cada límite respaldado por contador que confirmar o liberar en la fase dos. Vacío cuando se rechaza. ErrorFormat: type: object description: El mensaje de error de respuesta. required: - code - title - message properties: code: type: string description: Un identificador unico y estable para el error. title: type: string description: Un breve resumen del problema. message: type: string description: Orientacion detallada para resolver el error. fields: type: object additionalProperties: true description: Informacion adicional sobre los campos que causaron el error. AccountContext: type: object description: Contexto de cuenta para validacion. required: - accountId properties: accountId: type: string format: uuid description: Identificador de cuenta (requerido). type: type: string description: Tipo de cuenta. enum: - checking - savings - credit status: type: string description: Estado de la cuenta. enum: - active - suspended - closed metadata: type: object additionalProperties: true description: Atributos adicionales de cuenta para evaluacion de reglas. SegmentContext: type: object description: >- Contexto de segmento (opcional). Si se proporciona, segmentId es requerido. properties: segmentId: type: string format: uuid description: >- Identificador de segmento (requerido si se proporciona objeto segment). name: type: string description: Nombre del segmento para expresiones de reglas. metadata: type: object additionalProperties: true description: Atributos adicionales del segmento para evaluacion de reglas. PortfolioContext: type: object description: >- Contexto de portafolio (opcional). Si se proporciona, portfolioId es requerido. properties: portfolioId: type: string format: uuid description: >- Identificador de portafolio (requerido si se proporciona objeto portfolio). name: type: string description: Nombre del portafolio para expresiones de reglas. metadata: type: object additionalProperties: true description: Atributos adicionales del portafolio para evaluacion de reglas. MerchantContext: type: object description: >- Contexto de comerciante (opcional, recomendado para transacciones con tarjeta). Si se proporciona, merchantId es requerido. properties: merchantId: type: string format: uuid description: >- Identificador de comerciante (requerido si se proporciona objeto merchant). name: type: string description: Nombre del comerciante. category: type: string description: >- Codigo de Categoria de Comerciante (MCC). Debe ser un codigo de 4 digitos segun ISO 18245. pattern: ^[0-9]{4}$ country: type: string description: >- Pais del comerciante. Debe ser codigo ISO 3166-1 alpha-2 (2 letras mayusculas). pattern: ^[A-Z]{2}$ metadata: type: object additionalProperties: true description: Atributos adicionales del comerciante para evaluacion de reglas. examples: Error0003: summary: Invalid Request Body value: code: TRC-0003 title: Invalid Request Body message: >- The request body is invalid or malformed. Please verify the JSON format and try again. Error0011: summary: Payload Too Large value: code: TRC-0011 title: Payload Too Large message: >- The request payload exceeds the maximum size limit of 100KB. Please reduce the payload size and try again. Error0020: summary: Invalid Date Format value: code: TRC-0020 title: Invalid Date Format message: >- The date must be in RFC3339 format with timezone (e.g., 2026-01-28T10:30:00Z). Date-only format is not accepted. ErrorUnauthenticated: summary: Unauthorized value: code: Unauthenticated title: Unauthorized message: >- API Key missing or invalid. Provide a valid API Key in the X-API-Key header. Error0004: summary: Internal Server Error value: code: TRC-0004 title: Internal Server Error message: >- An unexpected error occurred. Please try again later or contact support if the issue persists. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- Autenticación por API Key. Utilizada por los despliegues de inquilino único (`MULTI_TENANT_ENABLED=false`). Se envía en cada solicitud `/v1/*`. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Autenticación JWT bearer. Utilizada por los despliegues multiinquilino (`MULTI_TENANT_ENABLED=true`). El JWT es emitido por Access Manager y debe incluir el claim `tenantId` — Tracer resuelve el inquilino a partir del token, no de ningún encabezado o campo del cuerpo. ````