> ## Documentation Index > Fetch the complete documentation index at: https://t3sa.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Vincular billetera > Borrador: especificación en curso. Los endpoints y campos pueden cambiar. Vincula una billetera de la empresa mediante su dirección pública. TESA almacena solo la dirección y los metadatos. Scope: `admin`. > [!WARNING] > > Borrador: especificación en curso. Los endpoints y campos pueden cambiar. ## OpenAPI ````yaml /es/api/openapi.yaml post /carteiras openapi: 3.1.0 info: title: TESA API version: 0.2.0-rascunho description: > **Borrador: especificación en curso. Los endpoints y campos pueden cambiar.** API del software de tesorería B2B de TESA. El USDC ingresa mediante CCTP de Circle (Ethereum y Solana) y se asigna a los Treasuries tokenizados (USDY y BUIDL) que define la política de la empresa. TESA no recomienda asignaciones, no administra portafolios ni ejecuta órdenes en nombre de la empresa: el software prepara las transacciones y la empresa las aprueba y las firma. La API es no custodial: nunca recibe una clave privada ni una transacción firmada. Devuelve transacciones sin firmar y solicitudes de aprobación, y quien firma es la empresa o su custodio. Las rutas de los recursos, los nombres de los campos, los nombres de los eventos y los códigos de error están en portugués por diseño. Los montos son cadenas decimales de USDC con dos decimales, las fechas están en ISO 8601 UTC y las listas usan paginación por cursor (`limite` y `apos`). Todos los valores de ejemplo son ilustrativos. contact: name: TESA email: contact@t3sa.com url: https://t3sa.com servers: - url: https://api.t3sa.com/v1 description: Producción (URL propuesta, aún no disponible) - url: https://sandbox.api.t3sa.com/v1 description: Sandbox (URL propuesta, aún no disponible) security: - bearerAuth: [] tags: - name: Organización description: La empresa cliente, titular de todas las claves y recursos. - name: Carteras description: >- Billeteras de la empresa vinculadas por dirección pública. Ninguna clave pasa por la API. - name: Posiciones description: Una instantánea de la posición de caja, igual a la del panel. - name: Política de asignación description: >- Activos, proporciones y reglas de rebalanceo definidos y aprobados por la empresa. TESA no recomienda asignaciones. - name: Propuestas description: >- Transacciones que el software prepara cuando se cumple una regla de la política de la empresa, o por solicitud de la propia empresa. Solo se ejecutan con la aprobación y la firma de la empresa. - name: Rescates description: Devolución de saldo en USDC a una billetera vinculada de la empresa. - name: Registros description: Pista de auditoría on-chain, con el hash de cada transacción. - name: Rendimiento y uso description: >- Rendimiento calculado por período, solo informativo, y facturas de uso de la API. No se cobra nada sobre saldo, rendimiento ni capital principal. - name: Webhooks description: Destinos que reciben los eventos de TESA. paths: /carteiras: post: tags: - Carteras summary: Vincular billetera description: > Borrador: especificación en curso. Los endpoints y campos pueden cambiar. Vincula una billetera de la empresa mediante su dirección pública. TESA almacena solo la dirección y los metadatos. Scope: `admin`. operationId: vincularCarteira parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CarteiraCriar' responses: '201': description: Billetera vinculada. content: application/json: schema: $ref: '#/components/schemas/Carteira' '400': $ref: '#/components/responses/RequisicaoInvalida' '401': $ref: '#/components/responses/NaoAutenticado' '403': $ref: '#/components/responses/SemPermissao' '409': $ref: '#/components/responses/Conflito' '429': $ref: '#/components/responses/LimiteExcedido' security: - bearerAuth: [] - bearerAuth: [] tesaTimestamp: [] tesaSignature: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Valor único generado por la integración. Repetir la clave con el mismo cuerpo devuelve la respuesta original. schema: type: string format: uuid schemas: CarteiraCriar: type: object required: - rotulo - rede - endereco - tipo_custodia properties: rotulo: type: string rede: $ref: '#/components/schemas/Rede' endereco: type: string tipo_custodia: type: string enum: - self_custody - custodiante_qualificado custodiante: type: string Carteira: type: object properties: id: type: string examples: - cart_3k9d rotulo: type: string examples: - Caixa operacional rede: $ref: '#/components/schemas/Rede' endereco: type: string description: Dirección pública de la billetera. tipo_custodia: type: string enum: - self_custody - custodiante_qualificado custodiante: type: - string - 'null' status: type: string enum: - ativa - desvinculada Rede: type: string enum: - ethereum - solana Erro: type: object properties: erro: type: object properties: codigo: type: string examples: - saldo_insuficiente mensagem: type: string campo: type: - string - 'null' requisicao_id: type: string examples: - req_9d8c7b responses: RequisicaoInvalida: description: Cuerpo malformado o parámetro ausente (`requisicao_invalida`). content: application/json: schema: $ref: '#/components/schemas/Erro' NaoAutenticado: description: Clave ausente, inválida o revocada, o firma HMAC inválida. content: application/json: schema: $ref: '#/components/schemas/Erro' SemPermissao: description: Scope insuficiente o IP fuera de la lista de permitidos. content: application/json: schema: $ref: '#/components/schemas/Erro' Conflito: description: Conflicto de idempotencia o acción incompatible con el estado actual. content: application/json: schema: $ref: '#/components/schemas/Erro' LimiteExcedido: description: Límite de solicitudes alcanzado. Respetar el encabezado `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Erro' securitySchemes: bearerAuth: type: http scheme: bearer description: >- La clave de API de la organización (`tesa_live_...` en producción, `tesa_test_...` en el sandbox). tesaTimestamp: type: apiKey in: header name: Tesa-Timestamp description: >- Opcional en la propuesta actual. Hora de la solicitud en segundos Unix, utilizada en la firma HMAC. tesaSignature: type: apiKey in: header name: Tesa-Signature description: >- Opcional en la propuesta actual. HMAC-SHA256 codificado en hexadecimal del mensaje canónico (timestamp, método, ruta y cuerpo sin procesar). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.