> ## 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 clave > Registra una nueva clave Pix para una cuenta. Especifica el tipo de clave (keyType: 0=CPF, 1=CNPJ, 2=EMAIL, 3=PHONE, 4=EVP). Para EVP (tipo 4), el valor de la clave se genera automáticamente y puede omitirse. La respuesta devuelve el estado numérico de la clave (0=FINALIZED/pendiente de confirmación, 1=ACTIVE, etc.). ## OpenAPI ````yaml es/openapi/v3-current/pix.yaml POST /v1/entries openapi: 3.0.3 info: title: Plugin BR Pix Directo - API completa description: > API completa para el sistema de pagos instantáneos Pix de Brasil, que incluye operaciones del diccionario de claves Pix, generación/decodificación de códigos QR, transacciones y límites transaccionales. version: 1.0.0 servers: - url: https://plugin-pix-direct.api.lerian.net - url: https://plugin-pix-direct-qrcode.api.lerian.net security: - bearerAuth: [] paths: /v1/entries: post: tags: - Key DICT API summary: Crear clave description: > Registra una nueva clave Pix para una cuenta. Especifica el tipo de clave (keyType: 0=CPF, 1=CNPJ, 2=EMAIL, 3=PHONE, 4=EVP). Para EVP (tipo 4), el valor de la clave se genera automáticamente y puede omitirse. La respuesta devuelve el estado numérico de la clave (0=FINALIZED/pendiente de confirmación, 1=ACTIVE, etc.). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixKeyRequest' examples: phone_key: summary: Crear clave Pix de teléfono (keyType 3) value: key: '+5511987654321' keyType: 3 accountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 isValidated: false email_key: summary: Crear clave Pix de correo electrónico (keyType 2) value: key: user@example.com keyType: 2 accountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 isValidated: false cpf_key: summary: Crear clave Pix de CPF (keyType 0) value: key: '12345678901' keyType: 0 accountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 isValidated: true evp_key: summary: Crear clave aleatoria EVP (keyType 4) value: keyType: 4 accountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 isValidated: false responses: '201': description: Clave Pix creada correctamente content: application/json: schema: $ref: '#/components/schemas/PixKeyResponse' example: key: '+5511987654321' keyType: 3 keyTypeDescription: keyType 3 = PHONE status: 0 statusDescription: FINALIZED statusComment: status 0 = FINALIZED/pendiente de confirmación '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreatePixKeyRequest: type: object required: - keyType - accountId - isValidated properties: key: type: string description: > Valor de la clave Pix (opcional para claves EVP/aleatorias que se generan automáticamente). El formato depende de `keyType`: CPF (11 dígitos), CNPJ (14 dígitos), correo electrónico (email válido), teléfono (prefijo +55) o se omite para EVP. example: '+5511987654321' keyType: $ref: '#/components/schemas/KeyTypeEnum' accountId: type: string format: uuid description: Identificador de la cuenta. example: 019c96a0-0a98-7287-9a31-786e0809c769 isValidated: type: boolean description: >- Indica si la clave fue prevalidada (por ejemplo, correo/teléfono verificado). example: false PixKeyResponse: type: object required: - key - keyType - status - statusDescription properties: key: type: string description: Valor de la clave Pix. example: '+5511987654321' keyType: $ref: '#/components/schemas/KeyTypeEnum' status: $ref: '#/components/schemas/KeyStatusEnum' statusDescription: type: string description: Descripción legible del estado que corresponde al código numérico. example: PENDING_CONFIRMATION KeyTypeEnum: type: integer description: > Identificador del tipo de clave Pix. Códigos numéricos que especifican el tipo de clave Pix utilizada. **Valores válidos:** - `0` = CPF (Identificación tributaria de persona física con 11 dígitos, p. ej., "12345678901") - `1` = CNPJ (Identificación tributaria de empresa con 14 dígitos, p. ej., "12345678000190") - `2` = EMAIL (Dirección de correo electrónico, p. ej., "user@example.com") - `3` = PHONE (Número telefónico en formato internacional, p. ej., "+5511987654321") - `4` = EVP (Clave aleatoria UUID generada automáticamente, p. ej., "123e4567-e89b-12d3-a456-426614174000") enum: - 0 - 1 - 2 - 3 - 4 x-enum-varnames: - CPF - CNPJ - EMAIL - PHONE - EVP example: 3 KeyStatusEnum: type: integer description: > Código de estado del registro de la clave Pix. Indica el estado actual de una clave Pix en su ciclo de vida. **Valores válidos:** - `-1` = CANCELLED (El registro de la clave fue cancelado) - `0` = FINALIZED (La clave está finalizada/pendiente de confirmación) - `1` = ACTIVE (La clave está activa y operativa) - `2` = WAITING_OWNERSHIP_CONFIRMATION (En espera de la confirmación de titularidad por parte del usuario) - `3` = CREATING (La clave se está creando en el sistema) - `4` = IM_CLAIMER_PENDING_CONFIRM_CLAIM_REQUEST (Soy reclamante, pendiente de confirmación del reclamo) - `5` = IM_CLAIMER_PENDING_OWNER_GIVEWAY (Soy reclamante, esperando que el titular actual libere la clave) - `6` = IM_OWNER_PENDING_GIVEAWAY_CONFIRM (Soy titular, pendiente de aprobar la transferencia de la clave) - `7` = IM_CLAIMER_AND_OWNER_GAVEAWAY_PENDING_MY_CONFIRM (Transferencia iniciada, a la espera de mi confirmación) enum: - -1 - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 x-enum-varnames: - CANCELLED - FINALIZED - ACTIVE - WAITING_OWNERSHIP_CONFIRMATION - CREATING - IM_CLAIMER_PENDING_CONFIRM_CLAIM_REQUEST - IM_CLAIMER_PENDING_OWNER_GIVEWAY - IM_OWNER_PENDING_GIVEAWAY_CONFIRM - IM_CLAIMER_AND_OWNER_GAVEAWAY_PENDING_MY_CONFIRM example: 1 ErrorResponse: type: object properties: code: type: string description: Código de error message: type: string description: Mensaje de error details: type: array items: type: string description: Detalles adicionales del error responses: BadRequest: description: Solicitud Incorrecta - Parámetros inválidos content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_key_type: summary: Invalid key type value: code: INVALID_KEY_TYPE message: Key type must be between 0 and 4 details: - 'keyType: must be one of [0, 1, 2, 3, 4]' missing_required_field: summary: Missing required field value: code: VALIDATION_ERROR message: Required field is missing details: - 'accountId: field is required' invalid_document_format: summary: Invalid document format value: code: INVALID_DOCUMENT message: Document must be valid CPF (11 digits) or CNPJ (14 digits) details: - 'document: must match pattern ^\d{11}$|^\d{14}$' invalid_phone_format: summary: Invalid phone format value: code: INVALID_PHONE message: Phone must be in Brazilian format details: - 'phone: must match pattern ^\+55\d{2}\d{8,9}$' Unauthorized: description: No Autorizado - Autenticación inválida o ausente content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_token: summary: Missing authentication token value: code: MISSING_TOKEN message: Authorization header is required details: [] invalid_token: summary: Invalid token value: code: INVALID_TOKEN message: Invalid or expired access token details: [] expired_token: summary: Expired token value: code: TOKEN_EXPIRED message: Access token has expired. Please obtain a new token. details: [] InternalServerError: description: Error Interno del Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: generic_error: summary: Generic internal error value: code: INTERNAL_ERROR message: An internal error occurred. Please try again later. details: [] database_error: summary: Database error value: code: DATABASE_ERROR message: Database operation failed details: [] external_service_error: summary: External service error value: code: EXTERNAL_SERVICE_ERROR message: External service (JD PIX) is temporarily unavailable details: [] securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Autenticación con token JWT Bearer. Obtén el token desde el endpoint `/v1/login/oauth/access_token` usando credenciales de cliente (`clientId` y `clientSecret`). Incluye el token en el encabezado Authorization: `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` El token expira después de 3600 segundos (1 hora). ````