> ## 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.

# Close a reference month into an immutable report

> Closes a month that has ended and freezes its result as an immutable report, which the call returns.

The close fixes a cutoff 60 seconds before an instant that it reads from the database clock, and it reads the read replica when one is configured, and the primary otherwise. The replica must be a physical standby of the SPI database. A node that is not in recovery answers `503` (`PIX-0727`) before anything is claimed. A replica that has not applied every commit up to the cutoff answers `503` (`PIX-0715`) with `Retry-After`, and nothing is frozen. The cutoff is fixed on the first attempt, and every resend of the same close reuses it. A fact, a correction or a declaration recorded less than 60 seconds before the first attempt is after the cutoff: the report leaves it out, and it counts only after a reopen and a new close.

`transactions` comes from the settlements outside SPI and the outbound fraud refusals that you recorded as facts, each settlement classified by the declarations in force at the cutoff. `refunds` comes from the refunds outside SPI that you recorded as facts, and it is `UNAVAILABLE` when the month has none. `transactionTimes` comes from the SPI transfers and the settlements that the tenant paid. `dictLookups` and the `p99KeyLookupTime` indicator come from the key lookups recorded on key and QR code initiations, and their coverage is always `PARTIAL` or `UNAVAILABLE`. Every other block and indicator is `UNAVAILABLE` with its reason.

Only a past month can be closed. A future month answers `422` (`PIX-0710`) and the current month answers `422` (`PIX-0713`). A month already closed answers its current report with `200`. A close under another `X-Idempotency` key while one runs, or a resend while the claim of an earlier failed attempt holds, answers `409` (`PIX-0712`) with `Retry-After`. Each serving instance computes one close for each tenant at a time, and each database one close at a time. When no slot is free, the route answers `429` (`PIX-0006`) with `Retry-After` before it claims anything. The month goes in the `period` of the body. An absent `period` answers `400` (`PIX-0002`). A `period` that is not `YYYY-MM`, or is before 2020-11, answers `400` (`PIX-0003`).



## OpenAPI

````yaml /pt/openapi/v3-current/pix-lerian-spi.yaml post /regulatory/apix001/close
openapi: 3.1.0
info:
  contact:
    name: Lerian Studio
    url: https://lerian.studio
  description: Public API for outbound Pix transfers, refunds, and scheduled payments.
  license:
    name: Lerian Studio General License
  title: Pix Lerian — Payments
  version: 1.5.0
servers:
  - url: https://api.example.com/spi/v1
    description: >-
      Replace the example host with the URL provided during environment
      onboarding.
security:
  - BearerAuth: []
tags:
  - description: Create, list, and retrieve Pix refunds.
    name: Refunds
  - name: Scheduled Payments
    description: Register, list, retrieve, and cancel scheduled Pix payments.
  - description: >-
      Initiate, process, list, and retrieve outbound Pix transfers, and cancel
      or decide a sent Pix held in fraud analysis.
    name: Transfers
  - description: >-
      Register, list, retrieve, and cancel recurring series of scheduled Pix
      payments.
    name: Scheduled Payment Recurrences
  - description: >-
      Hold the funds of a received Pix in a cautionary block (MED 2.0), return
      them to the payer, or give them back to the account holder.
    name: Balance Locks
  - description: Read the APIX001 report of a closed month.
    name: APIX001 Reports
  - description: Close a reference month into an immutable report, and reopen it.
    name: APIX001 Periods
  - description: >-
      Record and correct the facts that only the participant knows, for the
      APIX001 report.
    name: APIX Client Facts
  - description: >-
      Declare the indirect participants that the tenant settles for, and end the
      declarations.
    name: APIX Settled Participants
paths:
  /regulatory/apix001/close:
    post:
      tags:
        - APIX001 Periods
      summary: Close a reference month into an immutable report
      description: >-
        Closes a month that has ended and freezes its result as an immutable
        report, which the call returns.


        The close fixes a cutoff 60 seconds before an instant that it reads from
        the database clock, and it reads the read replica when one is
        configured, and the primary otherwise. The replica must be a physical
        standby of the SPI database. A node that is not in recovery answers
        `503` (`PIX-0727`) before anything is claimed. A replica that has not
        applied every commit up to the cutoff answers `503` (`PIX-0715`) with
        `Retry-After`, and nothing is frozen. The cutoff is fixed on the first
        attempt, and every resend of the same close reuses it. A fact, a
        correction or a declaration recorded less than 60 seconds before the
        first attempt is after the cutoff: the report leaves it out, and it
        counts only after a reopen and a new close.


        `transactions` comes from the settlements outside SPI and the outbound
        fraud refusals that you recorded as facts, each settlement classified by
        the declarations in force at the cutoff. `refunds` comes from the
        refunds outside SPI that you recorded as facts, and it is `UNAVAILABLE`
        when the month has none. `transactionTimes` comes from the SPI transfers
        and the settlements that the tenant paid. `dictLookups` and the
        `p99KeyLookupTime` indicator come from the key lookups recorded on key
        and QR code initiations, and their coverage is always `PARTIAL` or
        `UNAVAILABLE`. Every other block and indicator is `UNAVAILABLE` with its
        reason.


        Only a past month can be closed. A future month answers `422`
        (`PIX-0710`) and the current month answers `422` (`PIX-0713`). A month
        already closed answers its current report with `200`. A close under
        another `X-Idempotency` key while one runs, or a resend while the claim
        of an earlier failed attempt holds, answers `409` (`PIX-0712`) with
        `Retry-After`. Each serving instance computes one close for each tenant
        at a time, and each database one close at a time. When no slot is free,
        the route answers `429` (`PIX-0006`) with `Retry-After` before it claims
        anything. The month goes in the `period` of the body. An absent `period`
        answers `400` (`PIX-0002`). A `period` that is not `YYYY-MM`, or is
        before 2020-11, answers `400` (`PIX-0003`).
      operationId: closeApix001Period
      parameters:
        - description: >-
            REQUIRED. Client-supplied replay key, at most 64 bytes. A request
            without it is refused with PIX-0030 @ 400 before the handler runs.
            An identical resend within 1 hour returns the original response,
            status included, with X-Idempotency-Replayed: true. Reusing the key
            with a divergent method, URL or body is PIX-0031 @ 412.
          in: header
          name: X-Idempotency
          required: true
          schema:
            maxLength: 64
            minLength: 1
            type: string
      requestBody:
        content:
          application/json:
            examples: {}
            schema:
              $ref: '#/components/schemas/ApixPeriodBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                reportId: 0193a6f0-7c1e-7b4a-9d2e-5f6a7b8c9d0e
                period: 2026-10
                ispb: '12345678'
                layoutVersion: '2.7'
                blocks:
                  transactions:
                    rows:
                      - transactionDetail: 5
                        transactionPurpose: 1
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 5
                        transactionPurpose: 2
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 5
                        transactionPurpose: 3
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 5
                        transactionPurpose: 4
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 6
                        transactionPurpose: 1
                        transactionCount: 1
                        transactionAmount: '150.00'
                        cashAmount: '0.00'
                      - transactionDetail: 6
                        transactionPurpose: 2
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 6
                        transactionPurpose: 3
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 6
                        transactionPurpose: 4
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 7
                        transactionPurpose: 1
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 7
                        transactionPurpose: 2
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 7
                        transactionPurpose: 3
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                      - transactionDetail: 7
                        transactionPurpose: 4
                        transactionCount: 0
                        transactionAmount: '0.00'
                        cashAmount: '0.00'
                    detailCoverage:
                      - transactionDetail: 5
                        coverage:
                          status: NOT_APPLICABLE
                          reason: >-
                            no indirect participant declaration valid in the
                            month
                      - transactionDetail: 6
                        coverage:
                          status: COMPLETE
                      - transactionDetail: 7
                        coverage:
                          status: UNAVAILABLE
                          reason: no outbound fraud refusal informed for the month
                  refunds:
                    rows:
                      - refundDetail: 1
                        refundCount: 0
                        refundAmount: '0.00'
                      - refundDetail: 2
                        refundCount: 1
                        refundAmount: '89.90'
                    coverage:
                      status: COMPLETE
                  cautionaryBlocks:
                    rows:
                      - cautionaryBlockDetail: 1
                        cautionaryBlockCount: 0
                        cautionaryBlockAmount: '0.00'
                      - cautionaryBlockDetail: 2
                        cautionaryBlockCount: 0
                        cautionaryBlockAmount: '0.00'
                      - cautionaryBlockDetail: 3
                        cautionaryBlockCount: 0
                        cautionaryBlockAmount: '0.00'
                      - cautionaryBlockDetail: 4
                        cautionaryBlockCount: 0
                        cautionaryBlockAmount: '0.00'
                    coverage:
                      status: UNAVAILABLE
                      reason: not computed by Pix Lerian
                  revenues:
                    rows:
                      - revenueSource: 1
                        revenueAmount: '0.00'
                      - revenueSource: 2
                        revenueAmount: '0.00'
                      - revenueSource: 3
                        revenueAmount: '0.00'
                      - revenueSource: 4
                        revenueAmount: '0.00'
                    coverage:
                      status: UNAVAILABLE
                      reason: not computed by Pix Lerian
                  transactionTimes:
                    p50SpiUserExperienceTime:
                      value: '2.84'
                      coverage:
                        status: PARTIAL
                        reason: >-
                          measured from the client call to the result delivery;
                          ends before t6a (Manual de Tempos v7.0 4.1.2)
                    p99SpiUserExperienceTime:
                      value: '7.91'
                      coverage:
                        status: PARTIAL
                        reason: >-
                          measured from the client call to the result delivery;
                          ends before t6a (Manual de Tempos v7.0 4.1.2)
                    p50OutsideSpiUserExperienceTime:
                      value: '1.37'
                      coverage:
                        status: COMPLETE
                    p99OutsideSpiUserExperienceTime:
                      value: '1.37'
                      coverage:
                        status: COMPLETE
                    maxCautionaryBlockTime:
                      value: '0.00'
                      coverage:
                        status: UNAVAILABLE
                        reason: not computed by Pix Lerian
                  dictTimes:
                    p99KeyLookupTime:
                      value: '0.42'
                      coverage:
                        status: PARTIAL
                        reason: >-
                          lower bound: only the DICT hub call inside the
                          initiate is measured, not the participant channel nor
                          the rest of the initiate; a key lookup the client
                          makes before the initiate is not seen; lookups that
                          failed technically (timeout, connection, 5xx) are left
                          out; negative answers are not measured; Pix Agendado
                          key lookups are not measured
                    p95KeyRegistrationCodeSendTime:
                      value: '0.00'
                      coverage:
                        status: UNAVAILABLE
                        reason: not computed by Pix Lerian
                    p95KeyRegistrationUserExperienceTime:
                      value: '0.00'
                      coverage:
                        status: UNAVAILABLE
                        reason: not computed by Pix Lerian
                    p95KeyDeletionUserExperienceTime:
                      value: '0.00'
                      coverage:
                        status: UNAVAILABLE
                        reason: not computed by Pix Lerian
                    p95PortabilityNotificationTime:
                      value: '0.00'
                      coverage:
                        status: UNAVAILABLE
                        reason: not computed by Pix Lerian
                    p95PortabilitySendTime:
                      value: '0.00'
                      coverage:
                        status: UNAVAILABLE
                        reason: not computed by Pix Lerian
                    p95MedOpeningTime:
                      value: '0.00'
                      coverage:
                        status: UNAVAILABLE
                        reason: not computed by Pix Lerian
                  dictLookups:
                    lookupCount: 48210
                    coverage:
                      status: PARTIAL
                      reason: >-
                        a key lookup the client makes before the initiate is not
                        seen; negative answers are not measured; Pix Agendado
                        key lookups are not measured
                  availability:
                    availabilityIndex: '0.00'
                    coverage:
                      status: UNAVAILABLE
                      reason: not computed by Pix Lerian
                  authorizationTimes:
                    p95AuthorizationTime:
                      value: '0.00'
                      coverage:
                        status: UNAVAILABLE
                        reason: not computed by Pix Lerian
                  authorizations:
                    rows:
                      - payerType: 1
                        authorizationCount: 0
                        activeAuthorizationCount: 0
                      - payerType: 2
                        authorizationCount: 0
                        activeAuthorizationCount: 0
                    coverage:
                      status: UNAVAILABLE
                      reason: not computed by Pix Lerian
              schema:
                $ref: '#/components/schemas/ApixReport'
          description: OK
          headers:
            X-Idempotency-Fenced:
              description: >-
                Present only when the request committed but its receipt could
                not be stored. true: a resend under the key within the hour is
                412 PIX-0031, so read the resource instead. false: a resend
                under the key may run again.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            X-Idempotency-Replayed:
              description: >-
                true when the idempotency gate answered from the receipt of an
                earlier request under the same X-Idempotency; absent on a first
                execution.
              schema:
                enum:
                  - 'true'
                type: string
        '400':
          content:
            application/json:
              example:
                code: PIX-0030
                title: Idempotency Key Required
                message: >-
                  The X-Idempotency header is required for this operation and
                  must be within the accepted length.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              examples:
                PIX-0002:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0002
                    title: Bad Request
                    status: 400
                    detail: Your request is missing one or more required fields.
                    errors:
                      - message: period is a required field
                        location: period
                    code: PIX-0002
                PIX-0003:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0003
                    title: Bad Request
                    status: 400
                    detail: >-
                      Your request contains one or more fields with an invalid
                      data type.
                    errors:
                      - message: period does not match the 2006-01 format
                        location: period
                    code: PIX-0003
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            `period` absent (PIX-0002), or not YYYY-MM or before 2020-11, when
            Pix started (PIX-0003). X-Idempotency absent or longer than 64 bytes
            (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json.
            Route-guard refusals (PIX-0010) answer in the legacy
            {code,title,message} envelope too.
        '401':
          description: >-
            Missing, malformed or expired bearer token, refused ahead of this
            operation by the authorization middleware in the legacy
            {code,title,message} envelope over application/json, with the
            generic client-error code PIX-0010. In a multi-tenant deployment the
            tenant middleware refuses a token it cannot read, or one with no
            usable tenantId claim, in the same shape with a code outside the
            PIX-NNNN catalogue: MISSING_TOKEN, INVALID_TOKEN, MISSING_TENANT or
            INVALID_TENANT. Branch on the status, not the body code.
        '403':
          content:
            application/problem+json:
              examples:
                PIX-0005:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0005
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to perform this operation.
                    errors:
                      - message: >-
                          the token names no identity lib-auth can attribute; an
                          operator conclusion records who concluded, so it
                          requires one
                        location: principal
                    code: PIX-0005
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            With authorization on, a token that names no identity that Access
            Manager can attribute (PIX-0005, errors[] at principal): each report
            version records who closed or reopened the month, so nothing was
            read or written. The token lacks the permission this operation's
            resource and action require, refused ahead of it by the
            authorization middleware in the legacy {code,title,message} envelope
            over application/json, with the generic client-error code PIX-0010.
            The tenant middlewares also answer 403 with a code outside the
            PIX-NNNN catalogue: TENANT_SUSPENDED or TENANT_ACCESS_DENIED in a
            multi-tenant deployment, in the same shape, and
            TENANT_CONFIG_NOT_FOUND, in a {code,message} body, when the tenant's
            configuration cannot be resolved. Branch on the status, not the body
            code.
        '409':
          content:
            application/problem+json:
              examples:
                PIX-0712:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0712
                    title: Conflict
                    status: 409
                    detail: >-
                      Another close of this month is running. Read the month
                      again shortly.
                    code: PIX-0712
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            A close of the month holds its claim (PIX-0712): another close under
            a different X-Idempotency is still running, or an earlier attempt
            ended in an error and its claim stays held until its lease ends.
            This request did not conclude the close; resend the identical
            request after Retry-After to get the report.
          headers:
            Retry-After:
              description: Seconds until the lease of the close in flight ends, at least 1.
              schema:
                minimum: 1
                type: integer
        '412':
          content:
            application/json:
              example:
                code: PIX-0031
                title: Idempotency Key Conflict
                message: >-
                  The X-Idempotency header is held by a request still running or
                  whose receipt could not be stored, or was already used with a
                  different request.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: >-
            Refused under this X-Idempotency (PIX-0031): the first request under
            it is still running (with Retry-After: 1), its receipt could not be
            stored and the key is held for the hour, or the request differs from
            the first (method, URL, body or identity header). An earlier request
            under this key may already have executed. Legacy
            {code,title,message} envelope, NOT problem+json.
        '413':
          content:
            application/json:
              example:
                code: PIX-0034
                title: Payload Too Large
                message: >-
                  The request body exceeds the maximum size allowed for this
                  operation.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: >-
            A body over 1 KiB (PIX-0034). Route-guard refusals (PIX-0034) answer
            in the legacy {code,title,message} envelope over application/json,
            NOT problem+json.
        '415':
          content:
            application/json:
              example:
                code: PIX-0016
                title: Unsupported Media Type
                message: >-
                  The request body must be sent with Content-Type:
                  application/json.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
          description: >-
            The non-empty request body is missing an accepted JSON Content-Type
            (PIX-0016), answered in the legacy {code,title,message} envelope
            over application/json, NOT problem+json.
        '422':
          content:
            application/problem+json:
              examples:
                PIX-0710:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0710
                    title: Unprocessable Entity
                    status: 422
                    detail: The reference month has not started.
                    code: PIX-0710
                PIX-0713:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0713
                    title: Unprocessable Entity
                    status: 422
                    detail: The current month can only be closed after it ends.
                    code: PIX-0713
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Only past months can be closed: a future month is PIX-0710, the
            current month PIX-0713.
        '429':
          content:
            application/problem+json:
              examples:
                PIX-0006:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0006
                    title: Too Many Requests
                    status: 429
                    detail: >-
                      Rate limit exceeded. Please wait before making additional
                      requests.
                    code: PIX-0006
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            The tenant's close slot on the serving instance stayed busy for 5
            seconds, or another close computes on the same database from any
            instance (PIX-0006): each instance computes one close per tenant and
            two across tenants, and each database one close at a time. Nothing
            was claimed or written and the gate freed the key: resend the
            identical request after Retry-After.
          headers:
            Retry-After:
              description: Seconds to wait before sending the same request again.
              schema:
                minimum: 1
                type: integer
        '500':
          content:
            application/json:
              example:
                code: PIX-0000
                title: Internal Server Error
                message: >-
                  The server encountered an unexpected error. Please try again
                  later.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              examples:
                PIX-0000:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0000
                    title: Internal Server Error
                    status: 500
                    detail: >-
                      The server encountered an unexpected error. Please try
                      again later.
                    code: PIX-0000
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Unexpected server error (PIX-0000). The middleware ahead of this
            operation answers this status too (see default), in the legacy
            {code,title,message} envelope over application/json, NOT
            problem+json.
        '503':
          content:
            application/json:
              example:
                code: PIX-0032
                title: Idempotency Unavailable
                message: >-
                  The request was not processed because the idempotency store is
                  unavailable. Please retry.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              examples:
                PIX-0062:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0062
                    title: Service Unavailable
                    status: 503
                    detail: >-
                      A dependency of this service is temporarily unavailable.
                      Retry as the route's guidance for an unknown outcome says.
                    code: PIX-0062
                PIX-0715:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0715
                    title: Service Unavailable
                    status: 503
                    detail: >-
                      The read replica has not reached the cutoff and nothing
                      was frozen. Retry later.
                    code: PIX-0715
                PIX-0727:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0727
                    title: Service Unavailable
                    status: 503
                    detail: >-
                      No APIX read pool is configured, or the configured read
                      replica is not a standby in recovery.
                    code: PIX-0727
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            PIX-0715: the read replica has not applied every commit up to the
            cutoff plus the settle margin or has left recovery since the close
            opened its connection, or, for a few seconds after the month becomes
            closable, the database clock is behind the serving instance's;
            nothing was frozen and the month stays OPEN. Retry after
            Retry-After, the larger of the claim's lease left and the measured
            lag. PIX-0727: there is no APIX read pool, or the configured read
            replica is not in recovery, so not a physical streaming standby of
            the SPI primary; nothing was claimed or frozen. PIX-0062: a database
            connection failed or was lost. The close may have concluded; a
            resend returns its report. In multi-tenant mode the tenant
            middleware refuses a request with no tenant (401) or an unknown
            tenant (404) before this operation, and answers a tenant without the
            SPI module with 503 SERVICE_UNAVAILABLE; the close's own answers to
            those cases (PIX-0062, and PIX-0727 for a tenant without the SPI
            module) are reached only in a race. Replay cache unavailable on this
            fail-closed route, so the mutation was refused rather than executed
            without replay protection (PIX-0032). Legacy {code,title,message}
            envelope, NOT problem+json.
          headers:
            Retry-After:
              description: 'With PIX-0715 only: seconds to wait, at least 1.'
              schema:
                minimum: 1
                type: integer
        default:
          content:
            application/json:
              example:
                code: PIX-0000
                title: Internal Server Error
                message: >-
                  The server encountered an unexpected error. Please try again
                  later.
              schema:
                $ref: '#/components/schemas/LegacyErrorEnvelope'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Error. Middleware ahead of this operation also refuses in the legacy
            {code,title,message} envelope over application/json: a body over the
            server's 4 MiB limit with 413 PIX-0010; a query value holding the
            NUL character (%00) or invalid UTF-8 with 400 PIX-0020; the Access
            Manager unavailable (503) or timing out (504) with PIX-0000; and, in
            a multi-tenant deployment, the tenant middleware with 404
            TENANT_NOT_FOUND, 500 TENANT_DB_ERROR, 503
            TENANT_MANAGER_UNAVAILABLE or SERVICE_UNAVAILABLE, and 504
            TENANT_MANAGER_TIMEOUT. Branch on the status; these middleware 503
            and 504 refusals are retryable. Any operation that uses the database
            also answers 503 PIX-0062 when its Postgres connection is lost; that
            request may or may not have been processed, so repeat it only as
            this operation's own guidance for an unknown outcome allows.
components:
  schemas:
    ApixPeriodBody:
      additionalProperties: false
      properties:
        period:
          description: >-
            Reference month, YYYY-MM. Absent is 400 PIX-0002; not YYYY-MM, or a
            month before 2020-11, when Pix started, is 400 PIX-0003.
          examples:
            - 2026-10
          pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
          type: string
      required:
        - period
      type: object
    ApixReport:
      additionalProperties: false
      properties:
        blocks:
          $ref: '#/components/schemas/ApixBlocks'
          description: The ten APIX001 blocks in layout order, each with explicit coverage.
        ispb:
          description: ISPB of the participant the report is for.
          examples:
            - '12345678'
          type: string
        layoutVersion:
          description: APIX001 layout version the blocks follow.
          examples:
            - '2.7'
          type: string
        period:
          description: Reference month, YYYY-MM.
          examples:
            - 2026-10
          type: string
        reportId:
          description: >-
            Immutable identifier of this report; a reopen and a new close
            produce another.
          examples:
            - 0193a6f0-7c1e-7b4a-9d2e-5f6a7b8c9d0e
          type: string
      required:
        - reportId
        - period
        - ispb
        - layoutVersion
        - blocks
      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
        fields:
          additionalProperties:
            type: string
          description: Per-field detail, keyed by the field or header the refusal names
          type: object
        headers:
          additionalProperties:
            type: string
          description: Per-header detail, keyed by the request header the refusal names
          type: object
      required:
        - code
        - title
        - message
      type: object
    Detail:
      additionalProperties: true
      properties:
        code:
          description: >-
            Stable, machine-readable domain error code scoped to the emitting
            service (format: <SERVICE>-NNNN).
          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
    ApixBlocks:
      additionalProperties: false
      properties:
        authorizationTimes:
          $ref: '#/components/schemas/ApixAuthorizationTimesBlock'
        authorizations:
          $ref: '#/components/schemas/ApixAuthorizationsBlock'
        availability:
          $ref: '#/components/schemas/ApixAvailabilityBlock'
        cautionaryBlocks:
          $ref: '#/components/schemas/ApixCautionaryBlocksBlock'
        dictLookups:
          $ref: '#/components/schemas/ApixDICTLookupsBlock'
        dictTimes:
          $ref: '#/components/schemas/ApixDICTTimesBlock'
        refunds:
          $ref: '#/components/schemas/ApixRefundsBlock'
        revenues:
          $ref: '#/components/schemas/ApixRevenuesBlock'
        transactionTimes:
          $ref: '#/components/schemas/ApixTransactionTimesBlock'
        transactions:
          $ref: '#/components/schemas/ApixTransactionsBlock'
      required:
        - transactions
        - refunds
        - cautionaryBlocks
        - revenues
        - transactionTimes
        - dictTimes
        - dictLookups
        - availability
        - authorizationTimes
        - authorizations
      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
    ApixAuthorizationTimesBlock:
      additionalProperties: false
      properties:
        p95AuthorizationTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
      required:
        - p95AuthorizationTime
      type: object
    ApixAuthorizationsBlock:
      additionalProperties: false
      properties:
        coverage:
          $ref: '#/components/schemas/ApixCoverage'
          description: Whether the rows are data or fillers.
        rows:
          description: >-
            APIX001 layout Autorizacao: one row per payerType, zero rows
            included.
          items:
            $ref: '#/components/schemas/ApixAuthorizationRow'
          type:
            - array
            - 'null'
      required:
        - rows
        - coverage
      type: object
    ApixAvailabilityBlock:
      additionalProperties: false
      properties:
        availabilityIndex:
          description: >-
            APIX001 layout IndiceDisponibilidade, a percentage with two decimal
            places.
          examples:
            - '99.98'
          type: string
        coverage:
          $ref: '#/components/schemas/ApixCoverage'
          description: Whether availabilityIndex is data or a filler.
      required:
        - availabilityIndex
        - coverage
      type: object
    ApixCautionaryBlocksBlock:
      additionalProperties: false
      properties:
        coverage:
          $ref: '#/components/schemas/ApixCoverage'
          description: Whether the rows are data or fillers.
        rows:
          description: >-
            APIX001 layout cautionary blocks: one row per cautionaryBlockDetail,
            zero rows included.
          items:
            $ref: '#/components/schemas/ApixCautionaryBlockRow'
          type:
            - array
            - 'null'
      required:
        - rows
        - coverage
      type: object
    ApixDICTLookupsBlock:
      additionalProperties: false
      properties:
        coverage:
          $ref: '#/components/schemas/ApixCoverage'
          description: >-
            Whether lookupCount is data or a filler. PARTIAL whenever a lookup
            was measured, because a key lookup the client makes before the
            initiate is not seen; the reason also says negative answers are not
            measured and the Pix Agendado key lookups are not measured, plus the
            count of lookups without measurement. A month with lookups and none
            measured is UNAVAILABLE; a month with no lookup is 0 PARTIAL, never
            COMPLETE while the Pix Agendado lookups are not measured.
        lookupCount:
          description: >-
            APIX001 layout QtdConsultas. DICT key lookups Pix Lerian makes to
            start a Pix by key or by QR code in the month (America/Sao_Paulo)
            answered by the participant's own DICT copy: origins CACHE and
            LOCAL_COPY count, DICT does not. The population is the key and QR
            code initiations, whether or not the payment settled; a negative
            answer and a technical failure are not recorded and do not count.
          examples:
            - 48210
          format: int64
          type: integer
      required:
        - lookupCount
        - coverage
      type: object
    ApixDICTTimesBlock:
      additionalProperties: false
      properties:
        p95KeyDeletionUserExperienceTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p95KeyRegistrationCodeSendTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p95KeyRegistrationUserExperienceTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p95MedOpeningTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p95PortabilityNotificationTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p95PortabilitySendTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p99KeyLookupTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
          description: >-
            APIX001 layout Perc99TempoUsuarioConsulta. P99 of the DICT key
            lookups Pix Lerian makes to start a Pix by key or by QR code in the
            month (America/Sao_Paulo), whatever answered them (CACHE, LOCAL_COPY
            or DICT), in seconds rounded up to 2 places (nearest rank). The
            population is the key and QR code initiations. A lookup with a
            negative answer (key not found, refused by DICT) and a lookup that
            failed technically (timeout, connection, 5xx) start no initiation
            and are left out. The duration runs from the lookup request to the
            DICT hub to the decoded answer, retries included, so the value is a
            LOWER BOUND of the layout indicator: the participant's channel steps
            and the rest of the initiate are not in it. Whether to report it is
            the client's decision. Coverage is PARTIAL whenever a lookup was
            measured; the reason names the lower bound, a key lookup the client
            makes before the initiate, technical failures, negative answers and
            the Pix Agendado key lookups, which Pix Lerian does not measure,
            plus the count of lookups without measurement. A month with lookups
            and none measured is UNAVAILABLE; a month with no lookup is 0.00
            PARTIAL, never COMPLETE.
      required:
        - p99KeyLookupTime
        - p95KeyRegistrationCodeSendTime
        - p95KeyRegistrationUserExperienceTime
        - p95KeyDeletionUserExperienceTime
        - p95PortabilityNotificationTime
        - p95PortabilitySendTime
        - p95MedOpeningTime
      type: object
    ApixRefundsBlock:
      additionalProperties: false
      properties:
        coverage:
          $ref: '#/components/schemas/ApixCoverage'
          description: >-
            Whether the rows are data or fillers: UNAVAILABLE, never COMPLETE,
            when no refund outside SPI was informed for the month.
        rows:
          description: >-
            APIX001 layout Devolucao: one row per refundDetail, zero rows
            included. Only the OUTSIDE_SPI_REFUND facts current at the cutoff
            count, in the month of their settledAt; refunds settled in the SPI
            never do.
          items:
            $ref: '#/components/schemas/ApixRefundRow'
          type:
            - array
            - 'null'
      required:
        - rows
        - coverage
      type: object
    ApixRevenuesBlock:
      additionalProperties: false
      properties:
        coverage:
          $ref: '#/components/schemas/ApixCoverage'
          description: Whether the rows are data or fillers.
        rows:
          description: >-
            APIX001 layout Receita: one row per revenueSource, zero rows
            included.
          items:
            $ref: '#/components/schemas/ApixRevenueRow'
          type:
            - array
            - 'null'
      required:
        - rows
        - coverage
      type: object
    ApixTransactionTimesBlock:
      additionalProperties: false
      properties:
        maxCautionaryBlockTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p50OutsideSpiUserExperienceTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p50SpiUserExperienceTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p99OutsideSpiUserExperienceTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
        p99SpiUserExperienceTime:
          $ref: '#/components/schemas/ApixTimeIndicator'
      required:
        - p50SpiUserExperienceTime
        - p99SpiUserExperienceTime
        - p50OutsideSpiUserExperienceTime
        - p99OutsideSpiUserExperienceTime
        - maxCautionaryBlockTime
      type: object
    ApixTransactionsBlock:
      additionalProperties: false
      properties:
        detailCoverage:
          description: Coverage per transactionDetail; the block has none of its own.
          items:
            $ref: '#/components/schemas/ApixDetailCoverage'
          type:
            - array
            - 'null'
        rows:
          description: >-
            APIX001 layout Transacao: one row per transactionDetail and
            transactionPurpose, zero rows included.
          items:
            $ref: '#/components/schemas/ApixTransactionRow'
          type:
            - array
            - 'null'
      required:
        - rows
        - detailCoverage
      type: object
    ApixTimeIndicator:
      additionalProperties: false
      properties:
        coverage:
          $ref: '#/components/schemas/ApixCoverage'
          description: Whether value is data or a filler.
        value:
          description: >-
            Time with two decimal places, in seconds (in hours for
            maxCautionaryBlockTime); 0.00 when coverage is UNAVAILABLE. At most
            999999.99, the APIX001 layout tipoValorTempo ceiling: a longer time
            is reported as 999999.99 and the coverage is PARTIAL with the count
            of journeys above it.
          examples:
            - '2.84'
          type: string
      required:
        - value
        - coverage
      type: object
    ApixCoverage:
      additionalProperties: false
      properties:
        reason:
          description: Why the value is not COMPLETE. Absent when status is COMPLETE.
          examples:
            - not computed by Pix Lerian
          type: string
        status:
          description: >-
            COMPLETE: the value is data; PARTIAL: data with a known gap;
            UNAVAILABLE: the value is a filler, never a measured zero;
            NOT_APPLICABLE: the value does not apply to the tenant in the month
            and is a zero filler, as transactionDetail 5 with no
            settled-participant declaration in force in the month.
          enum:
            - COMPLETE
            - PARTIAL
            - UNAVAILABLE
            - NOT_APPLICABLE
          examples:
            - COMPLETE
          type: string
      required:
        - status
      type: object
    ApixAuthorizationRow:
      additionalProperties: false
      properties:
        activeAuthorizationCount:
          description: APIX001 layout QtdEstoqueAutorizacoes.
          examples:
            - 412
          format: int64
          type: integer
        authorizationCount:
          description: APIX001 layout QtdAutorizacoes.
          examples:
            - 57
          format: int64
          type: integer
        payerType:
          description: APIX001 layout TipoPagador.
          enum:
            - 1
            - 2
          examples:
            - 1
          format: int64
          type: integer
      required:
        - payerType
        - authorizationCount
        - activeAuthorizationCount
      type: object
    ApixCautionaryBlockRow:
      additionalProperties: false
      properties:
        cautionaryBlockAmount:
          description: APIX001 layout ValorBloqCaut, two decimal places.
          examples:
            - '1250.00'
          type: string
        cautionaryBlockCount:
          description: APIX001 layout QtdeBloqCaut.
          examples:
            - 3
          format: int64
          type: integer
        cautionaryBlockDetail:
          description: APIX001 layout DetalhamentoTransacoesBloqCaut.
          enum:
            - 1
            - 2
            - 3
            - 4
          examples:
            - 1
          format: int64
          type: integer
      required:
        - cautionaryBlockDetail
        - cautionaryBlockCount
        - cautionaryBlockAmount
      type: object
    ApixRefundRow:
      additionalProperties: false
      properties:
        refundAmount:
          description: >-
            APIX001 layout ValorDevolucoes, two decimal places. At most
            9999999999999.99, the layout ceiling: a larger sum is reported as
            9999999999999.99 and the coverage is PARTIAL with the count of rows
            above it.
          examples:
            - '310.00'
          type: string
        refundCount:
          description: APIX001 layout QtdDevolucoes.
          examples:
            - 12
          format: int64
          type: integer
        refundDetail:
          description: >-
            APIX001 layout DetalhamentoDevolucoes: 1 fraud (reasonCode FR01), 2
            other (MD06, SL02, BE08).
          enum:
            - 1
            - 2
          examples:
            - 1
          format: int64
          type: integer
      required:
        - refundDetail
        - refundCount
        - refundAmount
      type: object
    ApixRevenueRow:
      additionalProperties: false
      properties:
        revenueAmount:
          description: APIX001 layout ValorReceita, two decimal places.
          examples:
            - '980.40'
          type: string
        revenueSource:
          description: APIX001 layout FonteReceita.
          enum:
            - 1
            - 2
            - 3
            - 4
          examples:
            - 1
          format: int64
          type: integer
      required:
        - revenueSource
        - revenueAmount
      type: object
    ApixDetailCoverage:
      additionalProperties: false
      properties:
        coverage:
          $ref: '#/components/schemas/ApixCoverage'
          description: Coverage of every row with this transactionDetail.
        transactionDetail:
          description: APIX001 layout DetalhamentoTransacoes the coverage applies to.
          enum:
            - 5
            - 6
            - 7
          examples:
            - 5
          format: int64
          type: integer
      required:
        - transactionDetail
        - coverage
      type: object
    ApixTransactionRow:
      additionalProperties: false
      properties:
        cashAmount:
          description: >-
            APIX001 layout ValorEspecie, two decimal places. At most
            9999999999999.99, the layout ceiling: a larger sum is reported as
            9999999999999.99 and the coverage is PARTIAL with the count of rows
            above it.
          examples:
            - '0.00'
          type: string
        transactionAmount:
          description: >-
            APIX001 layout ValorTransacoes, two decimal places. At most
            9999999999999.99, the layout ceiling: a larger sum is reported as
            9999999999999.99 and the coverage is PARTIAL with the count of rows
            above it.
          examples:
            - '38450.75'
          type: string
        transactionCount:
          description: APIX001 layout QtdTransacoes.
          examples:
            - 1520
          format: int64
          type: integer
        transactionDetail:
          description: APIX001 layout DetalhamentoTransacoes.
          enum:
            - 5
            - 6
            - 7
          examples:
            - 5
          format: int64
          type: integer
        transactionPurpose:
          description: APIX001 layout FinalidadeTransacoes.
          enum:
            - 1
            - 2
            - 3
            - 4
          examples:
            - 1
          format: int64
          type: integer
      required:
        - transactionDetail
        - transactionPurpose
        - transactionCount
        - transactionAmount
        - cashAmount
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: JWT bearer token issued by the identity provider.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.