> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Emitir una atestación

> Acuñe una atestación firmada utilizando un esquema y reclamaciones estructurados, o una carga útil codificada.
Conserve la misma Idempotency-Key y cuerpo al reintentar esta solicitud.


Firma una carga útil utilizando la clave de firma disponible de un emisor y registra la atestación resultante. La política del emisor, el estado de la clave, el entorno y los límites de uso pueden impedir la acuñación.

## Elegir un tipo de registro

Para un registro estructurado, elija `schema` del menú desplegable de tipo de registro e introduzca un objeto JSON en `claims`. Deje `payload_b64url` vacío. El servidor serializa estos campos en la carga JSON firmada. Esto identifica el tipo de registro; no establece de forma independiente que las afirmaciones sean verdaderas.

## Elegir un paquete de verificación

Los paquetes de verificación pertenecen a su espacio de trabajo. Utilice el selector a continuación con el mismo entorno y clave API que Probar, luego copie el ID seleccionado en `pack_id`. Omita ese campo para un registro independiente. También puede usar [Listar paquetes de verificación](https://docs.truthlocks.com/es/api-reference/verification-packs/list.md) o [Crear en Console](https://console.truthlocks.com/attestations/mint).

**Select a workspace verification pack**

This read-only lookup sends your key directly to the selected Truthlocks API. It keeps the key only in this componentâ€™s memory and does not mint a record.

API environment
Workspace API key

Clear key and results

Verification pack

## Usar una carga útil existente

Si ya tiene los bytes exactos para firmar, omita `schema` y `claims`. Codifique los bytes originales como **base64url sin relleno** en `payload_b64url`. Para JSON, serialice el objeto primero. Los campos de aplicación como `subject`, `claims` y `schema` pertenecen a esos bytes codificados; utilícelos a través de la entrada estructurada anterior o dentro de los bytes codificados, nunca ambos. Este endpoint no verifica de forma independiente la veracidad de las afirmaciones enviadas ni valida esquemas de credenciales arbitrarios.

Utilice el `kid` de la clave y el `alg` correspondiente. El registro de clave pública por sí solo no hace que una clave de firma privada esté disponible. Consulte [claves de emisor](https://docs.truthlocks.com/es/api-reference/issuers/keys.md).

## Caducidad opcional

Para `schema` y `claims` estructurados, establezca `expires_at_unix` en una marca de tiempo Unix futura en **segundos**. Truthlocks lo incluye en la raíz de la carga JSON firmada. Con `payload_b64url`, coloque este campo dentro de la carga JSON exacta antes de codificarlo y omita el campo de solicitud separado.

Después de ese instante, la verificación devuelve `EXPIRED`. La caducidad no se puede extender ni eliminar de un registro firmado existente; cree un reemplazo. Omítala cuando no desee una caducidad de atestación. Las fechas dentro de reclamaciones individuales, como el `expiry_date` de un pasaporte, son reclamaciones separadas y no establecen automáticamente la caducidad de la atestación. A los registros existentes no se les asigna una fecha retrospectivamente.

Conserve la carga útil y la caducidad exactas al reintentar. Un reintento idempotente devuelve el registro original incluso después de su caducidad.

## Reintentar de forma segura

`Idempotency-Key` es obligatorio. Genere un valor por acuñación prevista y consérvelo con la solicitud original para reintentos. No lo reutilice para contenido diferente.

## Integridad del documento

El hash del documento almacenado se selecciona en este orden:

1. `claims.document.sha256` dentro de una carga útil JSON.
2. El `document_hash` de la solicitud.
3. SHA-256 de los bytes de la carga útil decodificada.

Un hash incrustado tiene prioridad sobre el campo separado. Incluya el hash en la carga útil firmada cuando necesite vincular esa reclamación a la firma. Un hash enviado es una reclamación sobre un archivo; el servidor no puede establecer el contenido del archivo solo a partir del hash.

Pase `document_hash_hex` a [verification](https://docs.truthlocks.com/es/api-reference/verify.md) para comparar un hash de archivo. Conserve la carga útil original para la verificación de la integridad de la carga útil.

## Respuesta y entrega

HTTP 201 devuelve `attestation_id`, `issued_at_unix`, `signature` y `log`. La posición del registro es `log.leaf_index`, no un `log_index` de nivel superior.

`recipient_email` solicita notificación asíncrona. HTTP 201 confirma la acuñación, no la entrega del correo electrónico. Omítalo cuando distribuya el registro usted mismo.

Consulte el [inicio rápido](https://docs.truthlocks.com/es/quickstart.md) para una solicitud que utiliza los campos de entrada y respuesta reales.

## Guía de campos de tipo de registro

Estos campos son estructuras de reclamación sugeridas, no una garantía de validación de reclamación o verificación de identidad.

| ID de esquema | Nombre | Categoría | Campos de reclamación |
| - | - | - | - |
| `verifiable-id` | Identificación Verificable | Identidad | `full_name, employee_id, department, title, start_date` |
| `passport` | Pasaporte | Identidad | `full_name, nationality, passport_number, date_of_birth, expiry_date, issuing_country` |
| `drivers-license` | Licencia de Conducir | Identidad | `full_name, license_number, state, class, expiry_date, date_of_birth` |
| `government-id` | Identificación Gubernamental | Identidad | `full_name, id_number, id_type, issuing_authority, country, expiry_date` |
| `self-sovereign-id` | Identificación Auto-Soberana | Identidad | `did, display_name, created_at` |
| `employment-verification` | Verificación de Empleo | Empleo | `employee_name, employer, position, department, employment_type, start_date, end_date` |
| `professional-role` | Rol Profesional | Empleo | `full_name, title, organization, department, effective_date` |
| `membership-card` | Tarjeta de Membresía | Empleo | `member_name, organization, membership_id, tier, valid_from, valid_to` |
| `professional-certification` | Certificación profesional | Empleo | `holder_name, certification_name, issuing_body, certification_id, issued_date, expiry_date` |
| `license` | Licencia | Empleo | `holder_name, license_type, license_number, issuing_authority, jurisdiction, issued_date, expiry_date` |
| `accreditation` | Acreditación | Empleo | `entity_name, accreditation_body, standard, scope, valid_from, valid_to` |
| `degree` | Título | Educación | `student_name, institution, degree_type, field_of_study, graduation_date, honors` |
| `completion-cert` | Certificado de Finalización | Educación | `participant_name, program_name, institution, completion_date, hours` |
| `course-credit` | Crédito de Curso | Educación | `student_name, course_name, institution, credits, grade, semester` |
| `transcript` | Expediente Académico | Educación | `student_name, institution, program, gpa, total_credits, issue_date` |
| `micro-credential` | Micro-Credencial | Educación | `earner_name, credential_name, issuer, skills, earned_date` |
| `training-completion` | Finalización de Capacitación | Educación | `trainee_name, training_program, provider, completion_date, score, certificate_id` |
| `medical-license` | Licencia Médica | Salud | `practitioner_name, license_number, specialty, state, issued_date, expiry_date` |
| `dea-registration` | Registro DEA | Salud | `registrant_name, dea_number, schedules, business_activity, expiry_date` |
| `board-certification` | Certificación de la Junta | Salud | `physician_name, board, specialty, certification_date, expiry_date` |
| `health-credential` | Credencial de Salud | Salud | `patient_name, credential_type, provider, date, details` |
| `vaccination-record` | Registro de Vacunación | Salud | `patient_name, vaccine_name, manufacturer, lot_number, date_administered, dose_number, site` |
| `aml-kyc` | Verificación AML/KYC | Cumplimiento | `entity_name, check_type, result, risk_level, verified_by, verified_at` |
| `security-clearance` | Autorización de Seguridad | Cumplimiento | `holder_name, clearance_level, granting_agency, granted_date, expiry_date` |
| `sam-gov` | Registro SAM.gov | Cumplimiento | `entity_name, cage_code, uei, registration_status, expiry_date` |
| `jurisdiction-approval` | Aprobación de Jurisdicción | Cumplimiento | `entity_name, jurisdiction, approval_type, approved_date, conditions` |
| `attestation-of-will` | Atestación de Voluntad | Cumplimiento | `declarant_name, declaration, witness, date` |
| `bank-verification` | Verificación Bancaria | Financiero | `account_holder, bank_name, account_type, routing_number_last4, verified_date` |
| `credit-attestation` | Atestación de Crédito | Financiero | `entity_name, credit_score_range, reporting_agency, assessment_date` |
| `income-verification` | Verificación de Ingresos | Financiero | `individual_name, employer, annual_income_range, verification_date, tax_year` |
| `skill-badge` | Insignia de Habilidad | Habilidades y Capacitación | `earner_name, skill_name, proficiency_level, assessed_by, earned_date` |
| `competency` | Atestación de Competencia | Habilidades y Capacitación | `individual_name, competency, level, assessor, assessment_date` |
| `industry-cert` | Certificación de Industria | Habilidades y Capacitación | `holder_name, certification, issuing_body, cert_id, issued_date, expiry_date` |
| `product-authenticity` | Autenticidad del Producto | Cadena de Suministro | `product_name, sku, serial_number, manufacturer, manufactured_date, origin_country` |
| `chain-of-custody` | Cadena de Custodia | Cadena de Suministro | `item_description, from_entity, to_entity, transfer_date, location, condition` |
| `origin-verification` | Verificación de Origen | Cadena de Suministro | `product_name, origin_country, origin_region, certifying_body, verified_date` |
| `custom` | Personalizado | Otro | `subject, type, details` |
| `attestation` | Atestación Genérica | Otro | `subject, claim, evidence` |


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/attestations/mint
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks es una infraestructura de verificación universal para documentos,
    credenciales y activos digitales.

    Esta especificación define la API canónica para interactuar con los
    servicios de Truthlocks.


    ## URLs Base

    - **Producción**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Autenticación

    - **Claves API**: Use el encabezado `X-API-Key` para operaciones máquina a
    máquina

    - **Tokens Bearer**: Use `Authorization: Bearer <jwt>` para operaciones
    iniciadas por el usuario


    ## Identidad del Inquilino

    En producción, la identidad del inquilino se deriva del contexto autenticado
    (clave API o JWT).

    El encabezado `X-Tenant-ID` se ignora en producción para evitar la
    suplantación de identidad.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: API de producción
  - url: https://sandbox-api.truthlocks.com
    description: Entorno Sandbox
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: Gestión de claves y tokens de API
  - name: Issuers
    description: Registro del emisor y gestión de la confianza
  - name: Keys
    description: Gestión de claves criptográficas para emisores
  - name: Attestations
    description: Ciclo de vida de la atestación (acuñar, revocar, reemplazar)
  - name: Verification
    description: Verificación de atestación y paquetes de prueba
  - name: Governance
    description: Flujos de trabajo de gobernanza del emisor (solo administrador)
  - name: Identity
    description: Gestión de organización, usuarios y roles
  - name: Audit
    description: Consultas de eventos de auditoría
  - name: Tenant Console
    description: Puntos finales de perfil y ciclo de vida del inquilino
  - name: Health
    description: Endpoints de estado y preparación del servicio
  - name: Risk
    description: Ingesta de señales de riesgo y detección de fraude
  - name: Risk Enforcement
    description: >-
      Acciones de aplicación de riesgos: bloqueo, desafío, cuarentena y
      configuración
  - name: Billing
    description: Gestión de facturación, suscripciones y complementos
  - name: Machine Identity
    description: >-
      Protocolo de Identidad de Agente de Máquina (MAIP) — registro de agentes,
      sesiones, confianza, testigo, cumplimiento, orquestación y observabilidad
externalDocs:
  description: API de transparencia de solo lectura (especificación de servicio separada)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/attestations/mint:
    post:
      tags:
        - Attestations
      summary: Atestación de acuñación
      description: >
        Acuñe una atestación firmada utilizando un esquema y reclamaciones
        estructurados, o una carga útil codificada.

        Conserve la misma Idempotency-Key y cuerpo al reintentar esta solicitud.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: >-
            Conserve el mismo valor y cuerpo de la solicitud al reintentar una
            acuñación.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: >-
                Elija Registro estructurado para seleccionar un tipo de registro
                e ingresar reclamaciones, o Carga útil codificada para firmar
                bytes existentes. Nunca combine ambos formatos de entrada.
              oneOf:
                - title: Structured record
                  type: object
                  required:
                    - issuer_id
                    - kid
                    - alg
                    - schema
                    - claims
                  properties:
                    alg:
                      $ref: '#/components/schemas/SigningAlgorithm'
                      description: >-
                        Debe coincidir con la clave de firma del emisor
                        seleccionada.
                    attestation_id:
                      type: string
                    content_type:
                      type: string
                      description: >-
                        Tipo MIME de los bytes originales, como
                        application/json, application/pdf o image/png. La
                        entrada de esquema/declaraciones estructuradas requiere
                        application/json.
                      example: application/json
                    document_hash:
                      type: string
                      description: >-
                        Hash SHA-256 hexadecimal opcional del documento. Un
                        claims.document.sha256 incrustado tiene prioridad; de lo
                        contrario, se utiliza este campo, luego el hash de la
                        carga decodificada.
                    issuer_id:
                      type: string
                      description: El UUID del emisor que crea la atestación
                      format: uuid
                      example: 550e8400-e29b-41d4-a716-446655440000
                    kid:
                      type: string
                      description: Identificador de clave para la clave de firma
                      example: es256-key-1
                    pack_id:
                      type: string
                      description: >-
                        UUID opcional del paquete de verificación del espacio de
                        trabajo. Utilice List verification packs con la misma
                        clave API para seleccionar un paquete activo existente;
                        omítalo para un registro independiente.
                      format: uuid
                    expires_at_unix:
                      type: integer
                      format: int64
                      minimum: 1
                      maximum: 253402300799
                      description: >-
                        Marca de tiempo Unix futura opcional en segundos para la
                        entrada de esquema/reclamaciones estructuradas. Se
                        incluye en la carga JSON firmada. Para la entrada
                        payload_b64url, omita este campo de solicitud e incruste
                        expires_at_unix en la raíz de la carga JSON exacta. La
                        caducidad no se puede cambiar en su lugar.
                    recipient_email:
                      type: string
                      description: >-
                        Destinatario opcional para notificación asíncrona
                        después de la acuñación. Una respuesta de acuñación
                        exitosa no confirma la entrega.
                      format: email
                    schema:
                      type: string
                      description: >-
                        Tipo de registro para entrada estructurada. Proporcione
                        reclamaciones y omita payload_b64url. Esta etiqueta no
                        valida de forma independiente la veracidad de las
                        reclamaciones.
                      enum:
                        - verifiable-id
                        - passport
                        - drivers-license
                        - government-id
                        - self-sovereign-id
                        - employment-verification
                        - professional-role
                        - membership-card
                        - professional-certification
                        - license
                        - accreditation
                        - degree
                        - completion-cert
                        - course-credit
                        - transcript
                        - micro-credential
                        - training-completion
                        - medical-license
                        - dea-registration
                        - board-certification
                        - health-credential
                        - vaccination-record
                        - aml-kyc
                        - security-clearance
                        - sam-gov
                        - jurisdiction-approval
                        - attestation-of-will
                        - bank-verification
                        - credit-attestation
                        - income-verification
                        - skill-badge
                        - competency
                        - industry-cert
                        - product-authenticity
                        - chain-of-custody
                        - origin-verification
                        - custom
                        - attestation
                      example: verifiable-id
                    claims:
                      type: object
                      additionalProperties: true
                      description: >-
                        Campos de registro estructurados. Requerido con esquema;
                        no se puede combinar con payload_b64url.
                      example:
                        full_name: Example recipient
                        employee_id: QA-001
                - title: Encoded payload
                  type: object
                  required:
                    - issuer_id
                    - kid
                    - alg
                    - payload_b64url
                  properties:
                    alg:
                      $ref: '#/components/schemas/SigningAlgorithm'
                      description: >-
                        Debe coincidir con la clave de firma del emisor
                        seleccionada.
                    attestation_id:
                      type: string
                    content_type:
                      type: string
                      description: >-
                        Tipo MIME de los bytes originales, como
                        application/json, application/pdf o image/png. La
                        entrada de esquema/declaraciones estructuradas requiere
                        application/json.
                      example: application/json
                    document_hash:
                      type: string
                      description: >-
                        Hash SHA-256 hexadecimal opcional del documento. Un
                        claims.document.sha256 incrustado tiene prioridad; de lo
                        contrario, se utiliza este campo, luego el hash de la
                        carga decodificada.
                    issuer_id:
                      type: string
                      description: El UUID del emisor que crea la atestación
                      format: uuid
                      example: 550e8400-e29b-41d4-a716-446655440000
                    kid:
                      type: string
                      description: Identificador de clave para la clave de firma
                      example: es256-key-1
                    pack_id:
                      type: string
                      description: >-
                        UUID opcional del paquete de verificación del espacio de
                        trabajo. Utilice List verification packs con la misma
                        clave API para seleccionar un paquete activo existente;
                        omítalo para un registro independiente.
                      format: uuid
                    recipient_email:
                      type: string
                      description: >-
                        Destinatario opcional para notificación asíncrona
                        después de la acuñación. Una respuesta de acuñación
                        exitosa no confirma la entrega.
                      format: email
                    payload_b64url:
                      type: string
                      description: >-
                        Base64url sin relleno de los bytes exactos a firmar. Use
                        esto O el esquema más las reclamaciones.
      responses:
        '201':
          description: Atestación acuñada
          content:
            application/json:
              schema:
                type: object
                properties:
                  attestation_id:
                    type: string
                    format: uuid
                  issuer_id:
                    type: string
                    format: uuid
                  version:
                    type: string
                  status:
                    type: string
                  expires_at_unix:
                    type: integer
                    format: int64
                    nullable: true
                    description: >-
                      Caducidad firmada registrada en segundos Unix; nulo
                      significa que no se registra ninguna caducidad. A los
                      registros heredados no se les asigna una nueva caducidad.
                  issued_at_unix:
                    type: integer
                    format: int64
                  payload_hash:
                    type: string
                  signature:
                    type: object
                    properties:
                      alg:
                        type: string
                      kid:
                        type: string
                      value:
                        type: string
                  log:
                    type: object
                    properties:
                      log_id:
                        type: string
                      leaf_index:
                        type: integer
                        nullable: true
                        description: >-
                          Índice de hoja de transparencia basado en cero. Nulo
                          significa que no se pudo recuperar la referencia del
                          registro; cero es una entrada válida.
                      status:
                        type: string
                        enum:
                          - recorded
                          - unavailable
                        description: >-
                          Disponibilidad de la referencia del registro
                          almacenado; esto no establece un veredicto de
                          inclusión verificado.
                      leaf_hash:
                        type: string
                      proof_url:
                        type: string
                  governance:
                    type: object
                    nullable: true
        '400':
          description: Solicitud no válida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: Carga útil demasiado grande
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                code: PAYLOAD_TOO_LARGE
                message: Request body exceeds maximum size of 1MB
                http_status: 413
        '429':
          description: Límite de velocidad o cuota excedida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded
                http_status: 429
                retry_after_ms: 60000
      security:
        - APIKey: []
components:
  schemas:
    SigningAlgorithm:
      type: string
      enum:
        - Ed25519
        - ES256
        - ES384
        - ES512
        - RS256
        - RS384
        - RS512
        - PS256
        - PS384
        - PS512
      description: Algoritmo de firma para la generación de claves
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Código de error legible por máquina
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensaje de error legible por humanos
        http_status:
          type: integer
          description: Código de estado HTTP
        retry_after_ms:
          type: integer
          description: Milisegundos a esperar antes de reintentar (para límites de tasa)
        details:
          type: object
          description: Contexto de error adicional
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clave API para autenticación máquina a máquina
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT para operaciones iniciadas por el usuario

````

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