> ## 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. # Fetch a worker's available consignable margin > Opens or reuses the worker's authorization and reads available payroll margin — the rail's autorizar-consulta-dados-trabalhador (Manual 002 v1.15 §3.1) and consultar-dados-trabalhador (Manual 002 v1.15 §3.3) behind ONE operation, because the adapter performs them as one. POST, not GET: it opens a consent, and the consent evidence plus the CPF must travel in a body rather than in a path or query string. The worker's authorization token is NEVER returned. A consignado.margin.fetched fact is emitted on this path exactly as on the lender event path, so a client integrating by API keeps its other consumers fed. CONSENT WINDOW (Manual 002 v1.15 §5.6). dataHoraAutorizacaoDigital starts two clocks, measured in calendar days from the worker's signature: the authorization may be CONSULTED for 30 days, and a request may be MADE against it for 45. Both boundaries are INCLUSIVE — the instant exactly 30 or 45 days after the signature is still inside its window, and only the next nanosecond is outside. Outside either window the gateway refuses LOCALLY, before a byte reaches the rail: 422 with code MYS-0006 and a detail telling you to obtain a fresh worker authorization. THAT REFUSAL IS NOT RETRYABLE. Repeating the request performs the very read the lapsed authorization withdrew; only new authorization evidence makes it succeed. A dataHoraAutorizacaoDigital carrying a non-UTC offset, or dated ahead of the gateway's clock, is the same 422 with a different detail — correct the timestamp; the worker's consent is not in question. Contrast the rail's OWN consent rejection (Dataprev EX/IV on a stale tokenAutorizacao): that is 503 and IS retryable, because the gateway drops the cached token and the next attempt opens a fresh consent from the same evidence. ## OpenAPI ````yaml en/openapi/v3-current/consignado.yaml post /v1/consignado/workers/margin openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: >- OpenAPI 3.1 surface for Lerian Consignado — Dataprev. The API covers tenant credentials and rail configuration, worker margin, loan auctions and bids, contract registration and lifecycle, disbursement confirmation, portability, refinancing, renegotiation, FGTS guarantees, reconciliation, funds, assignments, usage, throughput, and event subscriptions. Secret material is written to the tenant secret store and is never returned by any operation. 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: >- Per-tenant Dataprev credential custody and public rail configuration (upload, status, rotation, revoke, requester code, and worker portal base URL) name: Credentials - description: >- Tenant-scoped consignado gateway usage: priced billable-unit aggregation per competência name: Consignado Usage - description: >- Per-tenant streaming-hub subscription control-plane (list, create, get, rotate, revoke, and test delivery) name: Subscriptions - description: >- Dataprev payroll-rail surface: FGTS balance and authorization reads, the FGTS guarantee execution, contract suspension, reactivation and term changes, the rail's own contract documents, and the on-demand reads of leilão solicitações, escriturações, repasses and employment terminations name: Consignado Rail - description: >- Synchronous rail command surface: the operations a bancarizador without the lender drives over HTTP. Each shares its command implementation with the equivalent lender event trigger. name: Consignado Rail Commands - description: >- Gateway-owned disbursement confirmation: a client bank recording money it has ALREADY paid to a worker. It crosses no government boundary and proxies no Dataprev operation. name: Consignado Disbursement - description: >- Per-tenant self-service outbound Dataprev rail throughput: read and set this tenant's own requests-per-second, including a deliberate pause at zero name: Consignado Throughput paths: /v1/consignado/workers/margin: post: tags: - Consignado Rail Commands summary: Fetch a worker's available consignable margin description: >- Opens or reuses the worker's authorization and reads available payroll margin — the rail's autorizar-consulta-dados-trabalhador (Manual 002 v1.15 §3.1) and consultar-dados-trabalhador (Manual 002 v1.15 §3.3) behind ONE operation, because the adapter performs them as one. POST, not GET: it opens a consent, and the consent evidence plus the CPF must travel in a body rather than in a path or query string. The worker's authorization token is NEVER returned. A consignado.margin.fetched fact is emitted on this path exactly as on the lender event path, so a client integrating by API keeps its other consumers fed. CONSENT WINDOW (Manual 002 v1.15 §5.6). dataHoraAutorizacaoDigital starts two clocks, measured in calendar days from the worker's signature: the authorization may be CONSULTED for 30 days, and a request may be MADE against it for 45. Both boundaries are INCLUSIVE — the instant exactly 30 or 45 days after the signature is still inside its window, and only the next nanosecond is outside. Outside either window the gateway refuses LOCALLY, before a byte reaches the rail: 422 with code MYS-0006 and a detail telling you to obtain a fresh worker authorization. THAT REFUSAL IS NOT RETRYABLE. Repeating the request performs the very read the lapsed authorization withdrew; only new authorization evidence makes it succeed. A dataHoraAutorizacaoDigital carrying a non-UTC offset, or dated ahead of the gateway's clock, is the same 422 with a different detail — correct the timestamp; the worker's consent is not in question. Contrast the rail's OWN consent rejection (Dataprev EX/IV on a stale tokenAutorizacao): that is 503 and IS retryable, because the gateway drops the cached token and the next attempt opens a fresh consent from the same evidence. operationId: fetchConsignadoWorkerMargin requestBody: content: application/json: schema: $ref: '#/components/schemas/MarginRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/MarginResponse' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: MarginRequest: additionalProperties: false properties: codigoInscricaoEmpregador: description: 'Employer inscription TYPE code: 1 = CNPJ, 2 = CPF.' enum: - '1' - '2' examples: - '1' type: string consent: $ref: '#/components/schemas/MarginConsent' description: >- The worker's grupo-1 consent evidence. Relayed verbatim; never synthesized here. contractRef: description: >- Client-chosen correlation reference echoed onto the emitted consignado.margin.fetched fact. examples: - req-1 type: string cpf: description: >- Worker CPF, exactly 11 digits — a CPF is eleven digits by definition (Manual 002 v1.15 §3.1.1 p.8 types the request field Número, 11 algarismos). Body-only by design: a path or query CPF leaks into access logs and spans. examples: - '12345678901' pattern: ^[0-9]{11}$ type: string matricula: description: Employment bond matrícula. examples: - M-1 type: string numeroInscricaoEmpregador: description: >- Employer inscription number, relayed verbatim as Texto. Required: Manual 002 v1.15 §3.3.1 marks it Obrigatório on the worker data read. examples: - '12345678000199' minLength: 1 type: string required: - cpf - matricula - codigoInscricaoEmpregador - numeroInscricaoEmpregador - consent type: object MarginResponse: additionalProperties: false properties: activeOrSuspendedLoans: description: >- How many consignados already sit active or suspended on this bond. Manual 002 v1.15 §3.3.2 p.17 publishes the ceiling: 9 per employment bond, so a bond at 9 takes no tenth however much margin it shows. Absent when the rail said nothing; 0 is a live count. examples: - 2 format: int64 type: integer asOf: description: Instant the gateway observed this margin (UTC). examples: - '2026-07-30T12:00:00Z' format: date-time type: string availableMargin: description: Available consignable margin (decimal string, BRL). Never a float. examples: - '1234.56' type: string availableRemuneration: description: Disposable remuneration base (decimal string, BRL). Never a float. examples: - '5000.00' type: string blockType: $ref: '#/components/schemas/RailCodeDescription' description: >- The consignado block on this employment bond (Manual 002 v1.15 §3.3.2 table p.18: 0 no block, 1 blocked by the worker, 2 blocked by the MTE). A blocked bond can show a POSITIVE margin and still take no consignado, so this is not derivable from availableMargin. Code 0 is a live value. contractRef: description: The correlation reference the request supplied. examples: - req-1 type: string eligible: description: >- The rail's own eligibility verdict for this worker. ABSENT when the read carried no verdict — which is NOT the same statement as false. Decode into a nullable boolean: collapsing absence into false recreates a refusal the rail never made. examples: - true type: boolean grossPay: description: >- The worker's gross pay for the period the margin was computed against (decimal string, BRL). The denominator the margin is a slice of. Absent when the rail did not publish it — never "0". examples: - '7000.00' type: string ineligibilityReason: $ref: '#/components/schemas/RailCodeDescription' description: >- WHY the rail refused (Manual 002 v1.15 §3.3.2 code table p.16: 1 legacy loan in eSocial, 2 legacy loan reported by the institution, 3 zero remuneration, 4 bond has a termination date, 5 no remuneration in the last competência, 6 invalid labour regime, 7 invalid worker category, 8 bond whose previous loan closed on termination, 9 employer not in the programme). The codes are not one kind: 3 and 5 clear with the next payroll competência, 4 never clears. severanceAvailablePercent: description: >- The share of severance pay available as collateral on this bond (Manual 002 v1.15 §3.3.2 p.17, NÚMERO(3,2)) — a PERCENT PER the manual, as an exact decimal string relayed verbatim and never converted. 40.00 means forty percent, not 0.40. examples: - '40.00' type: string terminationDate: description: >- The BOND's termination date (Manual 002 v1.15 §3.3.2 p.15). A bond with one has no future payroll for an instalment to be discounted from. Absent when the bond is not terminated. examples: - '2026-06-30T00:00:00Z' format: date-time type: string terminationReasonCode: description: >- The eSocial termination-reason code, relayed VERBATIM and never interpreted. Manual 002 v1.15 §3.3.2 p.15 types it "Número, 2 algarismos" and points at the eSocial "Motivos de Desligamento" table rather than reproducing it; JSON has no leading-zero literal, so a code beginning with 0 arrives one digit short and travels that way. Zero-pad to the published width before looking it up. examples: - '2' type: string required: - availableMargin - availableRemuneration - asOf 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 MarginConsent: additionalProperties: false properties: canalAutorizacaoDigital: description: >- Digital channel the worker authorized through (1=ATM, 2=Agência, 3=Web Cliente, 4=Web Correspondente, 5=Mobile). Published enumeration: Manual 002 v1.15 §3.1.1 p.9. enum: - '1' - '2' - '3' - '4' - '5' examples: - '5' type: string dataHoraAutorizacaoDigital: description: Instant the worker authorized (RFC 3339, UTC). examples: - '2026-07-30T12:00:00Z' format: date-time type: string nsuAutorizacaoDigital: description: >- Authorization Número Sequencial Único, up to 19 digits (Manual 002 v1.15 §3.1.1 p.8: Número, 19 algarismos — a maximum, not an exact width). A STRING: 19 digits exceed a 64-bit integer. examples: - '1234567890123456789' pattern: ^[0-9]{1,19}$ type: string required: - canalAutorizacaoDigital - dataHoraAutorizacaoDigital - nsuAutorizacaoDigital type: object RailCodeDescription: additionalProperties: false properties: code: description: The rail's code, relayed verbatim. examples: - 5 format: int64 type: integer description: description: The rail's own label for the code, relayed verbatim. examples: - Sem remuneração na última competência type: string required: - code - description 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 ````