> ## 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. # Liquidar uma devolução por bloqueio agregado (Fase 1) > Inicia exatamente uma devolução agregada para todos os bloqueios PENDING vinculados ao relato de infração da devolução e altera esses bloqueios em conjunto para SETTLING. O processamento é selecionado automaticamente de acordo com o tipo de operação da infração e o formato da transação contestada. A devolução permanece OPEN durante esta fase. A requisição não tem corpo. Uma resposta bem-sucedida do SPI informa SETTLING, ou SETTLED em uma repetição idempotente; resultados rejeitados ou inesperados retornam erro. Somente o tenant do participante solicitante pode liquidar sua própria devolução. ## OpenAPI ````yaml pt/openapi/v3-current/pix-lerian-dict.yaml POST /dict/refunds/{id}/settle openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- API pública para chaves Pix, reivindicações, marcadores de fraude, relatos de infração e recuperação de valores do MED. license: name: Elastic License 2.0 url: https://www.elastic.co/licensing/elastic-license title: Pix Lerian — DICT version: release-candidate servers: - url: https://api.example.com/dict-hub/v1 description: Substitua o host de exemplo pela URL fornecida no onboarding do ambiente. security: - BearerAuth: [] tags: - description: Registro, consulta, listagem, atualização e remoção de chaves Pix. name: Entries - description: Consulta de chaves Pix e verificação de existência no diretório DICT. name: Keys - description: Gestão de reivindicações de posse e portabilidade de chaves Pix. name: Claims - description: Gestão de recuperações de valores do MED 2.0 no escopo do participante. name: Funds Recoveries - description: Gestão de relatos de infração do MED 2.0 para a organização autenticada. name: Infraction Reports - description: Criação, consulta, cancelamento e liquidação de devoluções do MED 2.0. name: Refunds - description: >- Criação, consulta, listagem e cancelamento de marcadores de fraude do DICT. name: Fraud Markers paths: /dict/refunds/{id}/settle: post: tags: - Refunds summary: Liquidar uma devolução por bloqueio agregado (Fase 1) description: >- Inicia exatamente uma devolução agregada para todos os bloqueios PENDING vinculados ao relato de infração da devolução e altera esses bloqueios em conjunto para SETTLING. O processamento é selecionado automaticamente de acordo com o tipo de operação da infração e o formato da transação contestada. A devolução permanece OPEN durante esta fase. A requisição não tem corpo. Uma resposta bem-sucedida do SPI informa SETTLING, ou SETTLED em uma repetição idempotente; resultados rejeitados ou inesperados retornam erro. Somente o tenant do participante solicitante pode liquidar sua própria devolução. operationId: settleRefund parameters: - description: >- Chave criada pelo cliente para repetir com segurança exatamente a mesma requisição. in: header name: Idempotency-Key required: true schema: maxLength: 64 minLength: 1 type: string description: >- Chave criada pelo cliente para repetir com segurança exatamente a mesma requisição. example: pix-demo-20260903-000001 - description: Refund internal ID (UUID format) in: path name: id required: true schema: description: Refund internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string example: 01960718-a213-2435-6078-901234567123 - description: >- Best-effort business correlation id (observability only; never fabricated). in: header name: X-Correlation-Id schema: description: >- Best-effort business correlation id (observability only; never fabricated). type: string example: 019606a1-3b4c-7d8e-9f01-234567890abc responses: '202': content: application/json: schema: $ref: '#/components/schemas/SettleRefundView' examples: exemploFicticio: summary: Exemplo fictício value: alreadySettled: '50.00' blocks: - amount: '120.00' lockId: b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f spiBlockId: 7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d blocksStatus: SETTLING endToEndId: 019606a1-3b4c-7d8e-9f01-234567890abc operationType: ROOT originalAmount: '200.00' refundId: 018f8c1d-1234-7abc-9def-000000000010 settleAmount: '150.00' settleReason: FR01 settleType: REFUND settled: false status: OPEN surplusAmount: '50.00' description: Accepted '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The Idempotency-Key header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Idempotency-Key absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The Idempotency-Key was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Idempotency-Key replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error x-codeSamples: - lang: bash label: cURL com dados fictícios source: |- curl --request POST \ --url https://api.example.com/dict-hub/v1/dict/refunds/01960718-a213-2435-6078-901234567123/settle \ --header 'Authorization: Bearer demo-access-token' \ --header 'Idempotency-Key: pix-demo-20260903-000001' \ --header 'X-Correlation-Id: 019606a1-3b4c-7d8e-9f01-234567890abc' components: schemas: SettleRefundView: additionalProperties: false properties: alreadySettled: examples: - '50.00' type: string blocks: items: $ref: '#/components/schemas/SettleBlockView' type: - array - 'null' blocksStatus: enum: - SETTLING - PENDING - SETTLED examples: - SETTLING type: string endToEndId: type: string operationType: enum: - ROOT - SUBSEQUENT - UNKNOWN examples: - ROOT type: string originalAmount: examples: - '200.00' type: string refundId: examples: - 018f8c1d-1234-7abc-9def-000000000010 type: string settleAmount: examples: - '150.00' type: string settleReason: examples: - FR01 type: string settleType: enum: - REFUND - MANUAL examples: - REFUND type: string settled: examples: - false type: boolean status: enum: - OPEN - CLOSED - CANCELLED examples: - OPEN type: string surplusAmount: examples: - '50.00' type: string required: - refundId - status - operationType - originalAmount - alreadySettled - blocksStatus type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string required: - code - title - message type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object SettleBlockView: additionalProperties: false properties: amount: examples: - '120.00' type: string lockId: examples: - b0f5c2a1-9e3d-4c7a-8f21-1a2b3c4d5e6f type: string spiBlockId: examples: - 7c9a1b2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: string required: - lockId - spiBlockId - amount type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````