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

# Reopen a closed reference month

> Moves the closed month in the `period` of the body back to open, so that the facts and the declarations recorded after the close, and the corrections, enter the next close. Use it to rectify a report that you already sent. Until the month is closed again, the report route answers `404` (`PIX-0711`). A month that is not closed answers `409` (`PIX-0714`), and so does a reopen that lost the race to another. A future month answers `422` (`PIX-0710`). An absent `period` answers `400` (`PIX-0002`), and a `period` that is not `YYYY-MM` or is before 2020-11 answers `400` (`PIX-0003`).



## OpenAPI

````yaml /es/openapi/v3-current/pix-lerian-spi.yaml post /regulatory/apix001/reopen
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/reopen:
    post:
      tags:
        - APIX001 Periods
      summary: Reopen a closed reference month
      description: >-
        Moves the closed month in the `period` of the body back to open, so that
        the facts and the declarations recorded after the close, and the
        corrections, enter the next close. Use it to rectify a report that you
        already sent. Until the month is closed again, the report route answers
        `404` (`PIX-0711`). A month that is not closed answers `409`
        (`PIX-0714`), and so does a reopen that lost the race to another. A
        future month answers `422` (`PIX-0710`). An absent `period` answers
        `400` (`PIX-0002`), and a `period` that is not `YYYY-MM` or is before
        2020-11 answers `400` (`PIX-0003`).
      operationId: reopenApix001Period
      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:
                period: 2026-10
                status: OPEN
              schema:
                $ref: '#/components/schemas/ApixPeriod'
          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-0714:
                  value:
                    type: https://errors.lerian.studio/v1/PIX-0714
                    title: Conflict
                    status: 409
                    detail: The month is not closed, so there is nothing to reopen.
                    code: PIX-0714
              schema:
                $ref: '#/components/schemas/Detail'
          description: The month is not CLOSED, so there is nothing to reopen (PIX-0714).
        '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
              schema:
                $ref: '#/components/schemas/Detail'
          description: The reference month is in the future (PIX-0710).
        '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'
          description: >-
            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.
        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
    ApixPeriod:
      additionalProperties: false
      properties:
        period:
          description: Reference month, YYYY-MM.
          examples:
            - 2026-10
          type: string
        status:
          description: >-
            OPEN until a close freezes the month; CLOSED while a report is in
            force.
          enum:
            - OPEN
            - CLOSED
          examples:
            - OPEN
          type: string
      required:
        - period
        - status
      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
    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

````

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