> ## 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. # Create a static BR Code > Creates a reusable static Pix BR Code and returns its EMV payload. The requested Pix key must belong to the account identified by `X-Account-Id` and is validated before the code is generated. ## OpenAPI ````yaml /es/openapi/v3-current/pix-lerian-cob.yaml post /brcodes/static openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- Public API for Pix BR Codes and immediate and due-date collections. This release provides a mock-provider integration for testing; live BACEN connectivity is not included. license: name: Lerian Studio General License title: Pix Lerian — Collections version: 1.0.0 servers: - url: https://api.example.com/cob-hub/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, retrieve, list, and decode static Pix BR Codes. name: BR Codes - description: Create, retrieve, list, and cancel due-date Pix collections. name: Due-Date Collections - description: Create, retrieve, list, and cancel immediate Pix collections. name: Immediate Collections paths: /brcodes/static: post: tags: - BR Codes summary: Create a static BR Code description: >- Creates a reusable static Pix BR Code and returns its EMV payload. The requested Pix key must belong to the account identified by `X-Account-Id` and is validated before the code is generated. operationId: createStaticBRCode 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. Replaying the same 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 - description: Merchant account UUID (scopes DICT key ownership validation) in: header name: X-Account-Id required: true schema: description: Merchant account UUID (scopes DICT key ownership validation) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateStaticBRCodeBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateStaticBRCodeOutput' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The Idempotency-Key header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0200 title: Bad Request status: 400 detail: Missing or malformed required fields. code: PIX-0200 schema: $ref: '#/components/schemas/Detail' description: >- Missing or malformed headers/body fields, an invalid Pix key shape, or another invalid create input (PIX-0001-0003, PIX-0017, PIX-0200). X-Idempotency absent or longer than 64 bytes (PIX-0030) uses the legacy {code,title,message} envelope; other 400 errors use application/problem+json. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The Idempotency-Key was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- X-Idempotency replayed with a divergent request -- a different method, URL or body, or a different X-Account-Id (PIX-0031). Evidence that an earlier request under this key already succeeded. Legacy {code,title,message} envelope, NOT problem+json. '415': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0016 title: Unsupported Media Type status: 415 detail: >- The request body must be sent with Content-Type: application/json. code: PIX-0016 schema: $ref: '#/components/schemas/Detail' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0201 title: Unprocessable Entity status: 422 detail: Pix key does not exist or is not active. code: PIX-0201 schema: $ref: '#/components/schemas/Detail' description: >- The Pix key is absent or inactive for the calling account (PIX-0201), or the key and description cannot fit in the BR Code merchant template (PIX-0207). '500': content: application/problem+json: example: 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 internal failure generating or persisting the BR Code (PIX-0000, PIX-0204). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0223 title: Bad Gateway status: 502 detail: Provider adapter is unreachable. code: PIX-0223 schema: $ref: '#/components/schemas/Detail' description: >- The DICT Hub is unreachable or returned an invalid ownership response (PIX-0223). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: CreateStaticBRCodeBody: additionalProperties: false properties: amount: description: Fixed amount in BACEN-canonical decimal form (omit for open value) examples: - '100.50' type: string description: description: Free-form description examples: - Pagamento type: string keyType: description: Pix key type examples: - CPF type: string keyValue: description: Pix key value examples: - '39053344705' type: string merchantCity: description: Merchant city examples: - Goiania type: string merchantName: description: Merchant name examples: - Loja Teste type: string postalCode: description: 8-digit postal code examples: - '74000000' type: string txId: description: Optional merchant transaction identifier examples: - TX12345 type: string required: - keyType - keyValue - merchantName - merchantCity type: object CreateStaticBRCodeOutput: additionalProperties: false properties: amount: examples: - '100.50' type: string createdAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string currency: enum: - BRL examples: - BRL type: string description: examples: - Pagamento do pedido 12345 type: string emvPayload: examples: - >- 00020101021126330014br.gov.bcb.pix0111390533447055204000053039865406100.505802BR5910Loja Teste6007Goiania62110507TX123456304AA54 type: string id: examples: - 0196a7b2-1c3d-7e4f-8a90-1234567890ab type: string keyType: enum: - CPF - CNPJ - PHONE - EMAIL - EVP examples: - CPF type: string keyValue: examples: - '39053344705' type: string merchantCity: examples: - Goiania type: string merchantName: examples: - Loja Teste type: string organizationId: examples: - 0196a7b2-2d4e-7f50-9b01-234567890abc type: string status: enum: - ACTIVE - CANCELLED examples: - ACTIVE type: string type: enum: - STATIC examples: - STATIC type: string updatedAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string required: - id - organizationId - type - keyType - keyValue - merchantName - merchantCity - emvPayload - status - createdAt - updatedAt type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string required: - code - title - message type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object 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 ````