> ## 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. # Confirmar un desembolso ya pagado al trabajador > Registra el hecho duradero propio de la pasarela de que un banco cliente ya pagó a un trabajador. No es una operación de Dataprev: no se utiliza ninguna credencial de red, no se cruza ningún límite gubernamental y Dataprev no publica ninguna operación de confirmación de desembolso mediante proxy. La pasarela registra lo que afirmó el cliente; no consulta a ningún producto posterior si el pago es plausible. Acepta confirmaciones huérfanas (dinero para un contrato que esta implementación nunca registró localmente), y un contrato puede desembolsarse en más de un pago. La identidad de una confirmación es (tenant, numero_contrato, payment_reference), por lo que un segundo pago con una referencia diferente en el mismo contrato es una primera aceptación con su propio hecho, nunca un conflicto. X-Idempotency es obligatorio, opaco, de 1 a 128 bytes y nunca está predeterminado. Dos claves que difieren en un byte son dos claves y no existe un alias X-Idempotency-Key. | caso | estado | X-Idempotency-Replayed | |---|---|---| | primera aceptación | 202 | ausente | | misma clave, misma solicitud, atendida desde la caché de transporte | 202, los bytes idénticos | true | | misma clave, misma solicitud, atendida desde la autoridad duradera | 202, los bytes idénticos | ausente | | misma clave, solicitud divergente | 422 — nunca el cuerpo anterior | lo que sea que escribió el middleware compartido | | nueva clave, mismo pago | 202, el mismo cuerpo | ausente | | nueva clave, misma referencia de pago, diferente dinero | 409 | lo que sea que escribió el middleware compartido | PostgreSQL es la autoridad de cada fila. La caché de idempotencia de transporte es un acelerador de mejor esfuerzo sobre ella, en ambos sentidos: tanto si la caché falla antes de que se decida la solicitud como si falla después de que la confirmación ya esté confirmada, la respuesta procede de la autoridad duradera y la única diferencia en la comunicación es que el encabezado de repetición está ausente. Una falla de caché nunca convierte un pago registrado en un 503. Es una falla distinta de una interrupción compartida de Redis, que el limitador de tarifas del tenant rechaza primero. ## OpenAPI ````yaml es/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/disbursement-confirmation openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: >- Superficie OpenAPI 3.1 para Lerian Consignado — Dataprev. API cubre las credenciales y la configuración de red de tenant, el margen de los trabajadores, las subastas y ofertas de préstamos, el registro y el ciclo de vida de los contratos, la confirmación de desembolsos, la portabilidad, la refinanciación, la renegociación, las garantías de FGTS, la conciliación, los fondos, las asignaciones, el uso, el rendimiento y las suscripciones a eventos. El material secreto se escribe en el almacén secreto tenant y ninguna operación lo devuelve nunca. license: name: Lerian Studio General License title: Lerian Consignado API version: v1.0.0 servers: - url: https://consignado.sandbox.lerian.net security: - BearerAuth: [] tags: - description: >- Custodia de credenciales de Dataprev y configuración pública del rail por tenant (carga, estado, rotación, revocación, código del solicitante y URL base del portal del trabajador) name: Credentials - description: >- Uso de la gateway del consignado en el ámbito del tenant: agregación de unidades facturables con precio por competencia name: Consignado Usage - description: >- Plano de control de suscripción al hub de streaming per-tenant (enumerar, crear, obtener, rotar, revocar y probar la entrega) name: Subscriptions - description: >- Superficie de rail de nómina Dataprev: lecturas de saldo y autorización FGTS, ejecución de garantía FGTS, suspensión de contrato, reactivación y cambios de términos, documentos de contrato propios de la red y lecturas bajo demanda de leilão solicitações, escriturações, repasses y terminaciones de empleo. name: Consignado Rail - description: >- Superficie de comando de red síncrona: las operaciones de un bancarizador sin que el prestamista conduzca sobre HTTP. Cada uno comparte su implementación de comando con el activador de evento de prestamista equivalente. name: Consignado Rail Commands - description: >- Confirmación de desembolso propiedad de la gateway: un banco cliente que registra el dinero que ya pagó a un trabajador. No cruza ninguna frontera gubernamental y no representa ninguna operación Dataprev. name: Consignado Disbursement - description: > Rendimiento de red Dataprev saliente de autoservicio per-tenant: lea y configure el requests-per-second propio de este tenant, incluida una pausa deliberada en cero name: Consignado Throughput paths: /v1/consignado/contracts/{numero_contrato}/disbursement-confirmation: post: tags: - Consignado Disbursement summary: Confirmar un desembolso ya pagado al trabajador description: >- Registra el hecho duradero propio de la pasarela de que un banco cliente ya pagó a un trabajador. No es una operación de Dataprev: no se utiliza ninguna credencial de red, no se cruza ningún límite gubernamental y Dataprev no publica ninguna operación de confirmación de desembolso mediante proxy. La pasarela registra lo que afirmó el cliente; no consulta a ningún producto posterior si el pago es plausible. Acepta confirmaciones huérfanas (dinero para un contrato que esta implementación nunca registró localmente), y un contrato puede desembolsarse en más de un pago. La identidad de una confirmación es (tenant, numero_contrato, payment_reference), por lo que un segundo pago con una referencia diferente en el mismo contrato es una primera aceptación con su propio hecho, nunca un conflicto. X-Idempotency es obligatorio, opaco, de 1 a 128 bytes y nunca está predeterminado. Dos claves que difieren en un byte son dos claves y no existe un alias X-Idempotency-Key. | caso | estado | X-Idempotency-Replayed | |---|---|---| | primera aceptación | 202 | ausente | | misma clave, misma solicitud, atendida desde la caché de transporte | 202, los bytes idénticos | true | | misma clave, misma solicitud, atendida desde la autoridad duradera | 202, los bytes idénticos | ausente | | misma clave, solicitud divergente | 422 — nunca el cuerpo anterior | lo que sea que escribió el middleware compartido | | nueva clave, mismo pago | 202, el mismo cuerpo | ausente | | nueva clave, misma referencia de pago, diferente dinero | 409 | lo que sea que escribió el middleware compartido | PostgreSQL es la autoridad de cada fila. La caché de idempotencia de transporte es un acelerador de mejor esfuerzo sobre ella, en ambos sentidos: tanto si la caché falla antes de que se decida la solicitud como si falla después de que la confirmación ya esté confirmada, la respuesta procede de la autoridad duradera y la única diferencia en la comunicación es que el encabezado de repetición está ausente. Una falla de caché nunca convierte un pago registrado en un 503. Es una falla distinta de una interrupción compartida de Redis, que el limitador de tarifas del tenant rechaza primero. operationId: confirmConsignadoDisbursement parameters: - description: >- The rail contract number the money was paid against (Manual 004 §2.2.2 p.18: Texto, 15). Exact, control-free UTF-8, bounded in BYTES: no trimming and no case folding. Nothing looks it up — an orphan confirmation for a contract this deployment never registered is first-class. in: path name: numero_contrato required: true schema: description: >- The rail contract number the money was paid against (Manual 004 §2.2.2 p.18: Texto, 15). Exact, control-free UTF-8, bounded in BYTES: no trimming and no case folding. Nothing looks it up — an orphan confirmation for a contract this deployment never registered is first-class. examples: - 99999999999AN1 maxLength: 15 minLength: 1 type: string - description: >- Mandatory opaque replay key, 1..128 bytes of valid UTF-8, preserved byte for byte. There is no default, no X-Idempotency-Key alias, no case folding and no normalization: two keys differing in one byte are two keys. in: header name: X-Idempotency required: true schema: description: >- Mandatory opaque replay key, 1..128 bytes of valid UTF-8, preserved byte for byte. There is no default, no X-Idempotency-Key alias, no case folding and no normalization: two keys differing in one byte are two keys. examples: - idem-desembolso-0001 maxLength: 128 minLength: 1 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DisbursementConfirmationRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/DisbursementConfirmationResponse' description: >- The confirmation is durably recorded. A replay of the same payment — under the same key or a new one — answers with the identical body. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Authentication is required to access this resource. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: You do not have permission to access this resource. '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The key is in flight, or this payment reference already holds an immutable confirmation carrying different money. '413': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: The raw body exceeds the 1 KiB wire guard. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The transport key, the contract number or the body is refused. A key that already bought a DIFFERENT confirmation lands here too, and the earlier body is never returned. '501': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: This deployment records no disbursement confirmations. '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Disbursement confirmation persistence is temporarily unavailable. Only mandatory persistence counts — PostgreSQL and the outbox. An idempotency-cache failure never produces this answer, in either direction: before the request is decided the cache is bypassed, and after the confirmation is committed the recorded 202 stands. security: - BearerAuth: [] components: schemas: DisbursementConfirmationRequest: additionalProperties: false properties: amount: description: >- The BRL amount already paid to the worker, as a canonical positive decimal string matching ^[1-9][0-9]*\.[0-9]{2}$ (at most 13 bytes). A string, never a JSON number: money never passes through a float. examples: - '2000.00' maxLength: 13 type: string paid_at: description: >- When the money was paid, strict RFC 3339 UTC with a literal Z (2026-08-01T12:00:00Z). Exactly one spelling per instant: a +00:00 offset, a lowercase z, fractional seconds or a missing zone are refused, never normalized. examples: - '2026-08-01T12:00:00Z' maxLength: 20 type: string payment_reference: description: >- The client's opaque payment reference — a Pix EndToEndId, a TED protocol number, an internal settlement id. Valid UTF-8, 1..256 bytes, preserved byte for byte with no trimming, case folding or normalization. examples: - E32074986202608011200A1B2C3D4E5F maxLength: 256 type: string required: - amount - paid_at - payment_reference type: object DisbursementConfirmationResponse: additionalProperties: false properties: amount: description: The confirmed amount, echoed verbatim. examples: - '2000.00' type: string confirmation_id: description: The gateway's identity for this immutable confirmation. examples: - 1f5b9c26-6f5a-4f77-9c1c-5d1c0f0a9b21 type: string confirmed_at: description: >- When the gateway durably recorded the confirmation, strict RFC 3339 UTC. examples: - '2026-08-01T12:00:05Z' type: string numero_contrato: description: >- The rail contract number the confirmation was addressed to, echoed from the path. examples: - 99999999999AN1 type: string paid_at: description: When the money was paid, echoed verbatim. examples: - '2026-08-01T12:00:00Z' type: string payment_reference: description: The client's payment reference, echoed verbatim. examples: - E32074986202608011200A1B2C3D4E5F type: string required: - confirmation_id - numero_contrato - amount - paid_at - payment_reference - confirmed_at 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 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 ````