> ## 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 capacidade de transação > Use este endpoint para reservar capacidade de transação contra os limites de gastos — fase um do fluxo de reserva em duas fases. Informe o `transactionId` do ledger no qual a reserva é indexada; a resposta devolve um ID de reserva para cada limite respaldado por contador que você deve confirmar ou liberar mais tarde. Quando um limite de gastos seria excedido, a resposta é devolvida com `denied` em `true` e nenhuma capacidade é retida. As reservas são idempotentes por `transactionId` — repetir a mesma reserva devolve o mesmo identificador. ## OpenAPI ````yaml pt/openapi/v3-current/tracer.yaml post /v1/reservations openapi: 3.1.0 info: title: API Tracer description: >- Referência completa da API para os serviços do Tracer, incluindo validação de transações, gerenciamento de regras, limites de gastos e eventos de auditoria para conformidade SOX/GLBA. version: 1.0.1 servers: - url: https://tracer.sandbox.lerian.net security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Health API description: >- Endpoints de verificação de integridade para sondas de vivacidade e prontidão. Estes endpoints não requerem autenticação. - name: Validations API description: >- Endpoints de validação de transações. A meta de desempenho é inferior a 80ms (p99). As validações são idempotentes por `requestId` — uma requisição duplicada retorna o resultado em cache com HTTP 200, enquanto uma requisição nova retorna HTTP 201. Nenhum header de idempotência é necessário. - name: Rules API description: >- Endpoints de gerenciamento de regras de validação. As regras utilizam expressões CEL (Common Expression Language). - name: Limits API description: >- Endpoints de gerenciamento de limites de gastos. Os limites controlam os valores das transações por escopo e período. - name: Reservations API description: >- Endpoints de reserva de capacidade de transação em duas fases. Uma reserva retém capacidade contra os limites de gastos; uma confirmação a consolida e uma liberação a devolve. Confirmar e liberar são idempotentes. - name: Audit Events API description: >- Endpoints de trilha de auditoria para conformidade SOX/GLBA. Todas as decisões de validação e alterações de configuração são registradas. paths: /v1/reservations: post: tags: - Reservations API summary: Reservar capacidade de transação description: >- Use este endpoint para reservar capacidade de transação contra os limites de gastos — fase um do fluxo de reserva em duas fases. Informe o `transactionId` do ledger no qual a reserva é indexada; a resposta devolve um ID de reserva para cada limite respaldado por contador que você deve confirmar ou liberar mais tarde. Quando um limite de gastos seria excedido, a resposta é devolvida com `denied` em `true` e nenhuma capacidade é retida. As reservas são idempotentes por `transactionId` — repetir a mesma reserva devolve o mesmo 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 a reserva foi processada. Verifique `denied` para confirmar se a capacidade foi concedida ou rejeitada por um limite de gastos. 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: Não Autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: ErrorUnauthenticated: $ref: '#/components/examples/ErrorUnauthenticated' '500': description: Erro Interno do Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0004: $ref: '#/components/examples/Error0004' components: parameters: ContentType: name: Content-Type in: header description: O tipo de mídia do recurso. Deve ser `application/json`. required: true example: application/json schema: type: string XApiKey: name: X-API-Key in: header description: >- A chave de API para autenticação. **Este header é obrigatório para todos os endpoints, exceto verificações de integridade**. required: true schema: type: string XRequestId: name: X-Request-Id in: header description: Um identificador único usado para rastrear cada requisição. required: false example: 019c96a0-10ce-75fc-a273-dc799079a99c schema: type: string format: uuid schemas: ReserveRequest: type: object description: >- Requisição de reserva para a fase um. Espelha a carga útil de validação de transação e adiciona o `transactionId` do ledger no qual o ciclo de vida da reserva é indexado. Para reservas, `transactionType` e `account` são opcionais porque o ledger pode não conhecer o trilho de pagamento ou um UUID de conta interno no ponto de reserva; `requestId`, `amount`, `currency` e `transactionTimestamp` permanecem obrigatórios. required: - transactionId - requestId - amount - currency - transactionTimestamp properties: transactionId: type: string format: uuid description: >- ID de correlação da transação do ledger no qual a reserva é indexada. Também é o grão de idempotência para reservas repetidas. longLived: type: boolean default: false description: >- Seleciona o tempo de vida da reserva. Use `true` para uma transação pendente que não deve expirar enquanto permanecer válida; `false` (o valor padrão) para uma transação direta. requestId: type: string format: uuid description: >- ID único gerado pelo cliente para idempotência e correlação da trilha de auditoria. transactionType: type: string enum: - CARD - WIRE - Pix - CRYPTO description: Tipo de transação (método de pagamento). Opcional para reservas. subType: type: string maxLength: 50 description: >- Subtipo de transação para contexto adicional (por exemplo, débito, crédito, pré-pago). amount: type: string description: >- Valor da transação como cadeia decimal (por exemplo, "1500.00"). Deve ser um valor decimal positivo. currency: type: string minLength: 3 maxLength: 3 description: >- Código de moeda ISO 4217 (maiúsculas). Códigos em minúsculas são rejeitados. transactionTimestamp: type: string format: date-time description: >- Carimbo de data/hora da transação no formato RFC3339 com fuso horário. 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 chave-valor personalizados para as expressões de regras. ReserveResponse: type: object description: >- Identificador devolvido em uma reserva bem-sucedida. Quando `denied` é true nenhuma capacidade foi retida e `reservationIds` está vazio; caso contrário, `reservationIds` contém um ID para cada limite respaldado por contador que o ledger deve confirmar ou liberar mais tarde. required: - transactionId - denied - reservationIds properties: transactionId: type: string format: uuid description: O ID de correlação da transação do ledger da requisição. denied: type: boolean description: >- Se a reserva foi rejeitada porque um limite de gastos seria excedido. Quando é true, nenhuma capacidade é retida. reservationIds: type: array items: type: string format: uuid description: >- Um ID de reserva para cada limite respaldado por contador que confirmar ou liberar na fase dois. Vazio quando rejeitada. ErrorFormat: type: object description: A mensagem de erro da resposta. required: - code - title - message properties: code: type: string description: Um identificador único e estável para o erro. title: type: string description: Um breve resumo do problema. message: type: string description: Orientação detalhada para resolver o erro. fields: type: object additionalProperties: true description: Informações adicionais sobre os campos que causaram o erro. AccountContext: type: object description: Contexto da conta para validação. required: - accountId properties: accountId: type: string format: uuid description: Identificador da conta (obrigatório). type: type: string description: Tipo da conta. enum: - checking - savings - credit status: type: string description: Status da conta. enum: - active - suspended - closed metadata: type: object additionalProperties: true description: Atributos adicionais da conta para avaliação de regras. SegmentContext: type: object description: Contexto do segmento (opcional). Se fornecido, segmentId é obrigatório. properties: segmentId: type: string format: uuid description: >- Identificador do segmento (obrigatório se o objeto segment for fornecido). name: type: string description: Nome do segmento para expressões de regras. metadata: type: object additionalProperties: true description: Atributos adicionais do segmento para avaliação de regras. PortfolioContext: type: object description: >- Contexto do portfólio (opcional). Se fornecido, portfolioId é obrigatório. properties: portfolioId: type: string format: uuid description: >- Identificador do portfólio (obrigatório se o objeto portfolio for fornecido). name: type: string description: Nome do portfólio para expressões de regras. metadata: type: object additionalProperties: true description: Atributos adicionais do portfólio para avaliação de regras. MerchantContext: type: object description: >- Contexto do estabelecimento (opcional, recomendado para transações de cartão). Se fornecido, merchantId é obrigatório. properties: merchantId: type: string format: uuid description: >- Identificador do estabelecimento (obrigatório se o objeto merchant for fornecido). name: type: string description: Nome do estabelecimento. category: type: string description: >- Código de Categoria do Estabelecimento (MCC). Deve ser um código de 4 dígitos conforme ISO 18245. pattern: ^[0-9]{4}$ country: type: string description: >- País do estabelecimento. Deve ser um código ISO 3166-1 alpha-2 (2 letras maiúsculas). pattern: ^[A-Z]{2}$ metadata: type: object additionalProperties: true description: Atributos adicionais do estabelecimento para avaliação de regras. 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: >- Autenticação por API Key. Usada por implantações single-tenant (`MULTI_TENANT_ENABLED=false`). Enviada em todas as requisições `/v1/*`. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Autenticação JWT bearer. Usada por implantações multi-tenant (`MULTI_TENANT_ENABLED=true`). O JWT é emitido pelo Access Manager e deve conter o claim `tenantId` — o Tracer resolve o tenant a partir do token, não de qualquer cabeçalho ou campo do corpo. ````