> ## 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. # Crear un registro de clave Pix > Se registra una nueva entrada de clave Pix en el directorio DICT. Presupone que el cliente completó la validación de Receita Federal y la autenticación MFA de la titularidad antes de la solicitud. ## OpenAPI ````yaml es/openapi/v3-current/pix-lerian-dict.yaml POST /entries openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- API pública para claves Pix, reclamos, marcadores de fraude, reportes de infracción y recuperación de fondos del MED. license: name: Elastic License 2.0 url: https://www.elastic.co/licensing/elastic-license title: Pix Lerian — DICT version: release-candidate servers: - url: https://api.example.com/dict-hub/v1 description: >- El host de ejemplo debe reemplazarse por la URL proporcionada durante el onboarding del entorno. security: - BearerAuth: [] tags: - description: Registro, consulta, listado, actualización y eliminación de claves Pix. name: Entries - description: >- Consulta de claves Pix y verificación de su existencia en el directorio DICT. name: Keys - description: Gestión de reclamaciones de titularidad y portabilidad de claves Pix. name: Claims - description: Gestión de recuperaciones de fondos de MED 2.0 asociadas al participante. name: Funds Recoveries - description: >- Gestión de reportes de infracción de MED 2.0 para la organización autenticada. name: Infraction Reports - description: Creación, consulta, cancelación y liquidación de devoluciones de MED 2.0. name: Refunds - description: Creación, consulta, listado y cancelación de marcadores de fraude de DICT. name: Fraud Markers paths: /entries: post: tags: - Entries summary: Crear un registro de clave Pix description: >- Se registra una nueva entrada de clave Pix en el directorio DICT. Presupone que el cliente completó la validación de Receita Federal y la autenticación MFA de la titularidad antes de la solicitud. operationId: createEntry parameters: - description: >- Clave generada por el cliente para reintentar exactamente la misma solicitud de forma segura. in: header name: Idempotency-Key required: true schema: maxLength: 64 minLength: 1 type: string description: >- Clave generada por el cliente para reintentar exactamente la misma solicitud de forma segura. example: pix-demo-20260903-000001 - description: UUID de la cuenta asociada a la operación. in: header name: X-Account-Id required: true schema: description: UUID de la cuenta asociada a la operación. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string example: 019606a1-3b4c-7d8e-9f01-234567890abc - description: >- Motivo de la operación. Se utiliza USER_REQUESTED para una solicitud del cliente. in: header name: X-Reason required: true schema: examples: - USER_REQUESTED type: string description: >- Motivo de la operación. Se utiliza USER_REQUESTED para una solicitud del cliente. example: USER_REQUESTED requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateEntryBody' examples: ejemploFicticio: summary: Ejemplo ficticio value: keyType: CPF keyValue: '52998224725' metadata: source: mobile required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateEntryOutput' examples: ejemploFicticio: summary: Ejemplo ficticio value: account: branch: '0001' number: '0007654321' openingDate: '2010-01-10T03:00:00Z' participant: '12345678' type: CACC createdAt: '2019-11-18T03:00:00Z' holderId: 019606e5-7f80-9102-3d45-678901234ef0 id: 019606c3-5d6e-7f80-1b23-456789012cde keyCreationDate: '2019-11-18T03:00:00Z' keyOwnershipDate: '2019-11-18T03:00:00Z' keyType: CPF keyValue: '52998224725' metadata: field: field-example organizationId: 019606d4-6e7f-8091-2c34-567890123def owner: document: '52998224725' name: João Silva personType: NATURAL tradeName: Silva ME requestId: a946d533-7f22-42a5-9a9b-e87cd55c0f4d status: ACTIVE updatedAt: '2019-11-18T03:00:00Z' 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' description: >- Idempotency-Key absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT 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: >- Idempotency-Key replayed with a divergent request -- a different method, URL (including the path parameter), body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id (PIX-0031). Legacy {code,title,message} envelope, 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/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error x-codeSamples: - lang: bash label: cURL con datos ficticios source: |- curl --request POST \ --url https://api.example.com/dict-hub/v1/entries \ --header 'Authorization: Bearer demo-access-token' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: pix-demo-20260903-000001' \ --header 'X-Account-Id: 019606a1-3b4c-7d8e-9f01-234567890abc' \ --header 'X-Reason: USER_REQUESTED' \ --data '{ "keyType": "CPF", "keyValue": "52998224725", "metadata": { "source": "mobile" } }' components: schemas: CreateEntryBody: additionalProperties: false properties: keyType: description: Pix key type examples: - CPF type: string keyValue: description: Pix key value examples: - '52998224725' type: string metadata: additionalProperties: {} description: >- Free-form, single-level key/value pairs persisted with the entry. Keys up to 100 characters, values up to 2000 characters, at most 25 entries; nested objects are rejected. examples: - source: mobile maxProperties: 25 type: object required: - keyType type: object CreateEntryOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/EntryAccountOutput' createdAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string holderId: examples: - 019606e5-7f80-9102-3d45-678901234ef0 type: string id: examples: - 019606c3-5d6e-7f80-1b23-456789012cde type: string keyCreationDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyOwnershipDate: examples: - '2019-11-18T03:00:00Z' format: date-time type: string keyType: examples: - CPF type: string keyValue: examples: - '52998224725' type: string metadata: additionalProperties: {} type: object organizationId: examples: - 019606d4-6e7f-8091-2c34-567890123def type: string owner: $ref: '#/components/schemas/EntryOwnerOutput' requestId: examples: - a946d533-7f22-42a5-9a9b-e87cd55c0f4d type: string status: examples: - ACTIVE type: string updatedAt: examples: - '2019-11-18T03:00:00Z' format: date-time type: string required: - id - organizationId - holderId - keyType - keyValue - status - requestId - keyCreationDate - keyOwnershipDate - account - owner - 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 EntryAccountOutput: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string openingDate: examples: - '2010-01-10T03:00:00Z' format: date-time type: string participant: examples: - '12345678' type: string type: examples: - CACC type: string required: - branch - number - type - participant type: object EntryOwnerOutput: additionalProperties: false properties: document: examples: - '52998224725' type: string name: examples: - João Silva type: string personType: examples: - NATURAL type: string tradeName: examples: - Silva ME type: string required: - document - personType - name 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 ````