> ## 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.

# Factura proyectada

> Calcule un desglose de factura proyectado basado en los volúmenes esperados de acuñación y verificación.

```http theme={null}
POST /v1/billing/projected-invoice
```

Devuelve una proyección de factura detallada basada en los volúmenes de uso que proporcione. Se requiere autenticación. Utilice su clave API del espacio de trabajo. Úsela para calculadoras de precios, pronósticos de costos o herramientas de preventa.

Los ajustes de precios regionales se aplican cuando incluye un `country_code`. Este punto final utiliza la tarjeta de tarifas estándar, no un acuerdo negociado por el inquilino. Proporcione las cantidades **facturables** esperadas; esta calculadora no deduce asignaciones gratuitas ni clasifica la actividad de la zona de pruebas.

El precio por volumen es graduado. Cada banda solo valora las operaciones de esa banda. La respuesta identifica `billing_model: "pay_per_use"`, `volume_pricing: "graduated"`, `amount_unit: "cents"` y `estimate_only: true`. Una estimación no crea ni cobra una factura. Las definiciones de tarifas faltantes, superpuestas o incompletas devuelven `422 invalid_pricing`; las cantidades inseguras y los planes desconocidos devuelven `400 bad_request`.

Los precios aplicados exactos están en `line_items`. Los campos escalares de conveniencia `rates_used` se conservan para la compatibilidad con las tarjetas de tarifa plana; no son un precio combinado y no deben multiplicarse en las bandas de volumen.

## Respuesta

**line\_items** `object[]`

Desglose de los cargos proyectados.

**description** `string`

Descripción del artículo (por ejemplo, "Acuñaciones de credenciales").

**quantity** `integer`

Número de unidades.

**unit\_price\_cents** `integer`

Precio por unidad en centavos.

**total\_cents** `integer`

Costo total de este artículo en centavos.

**subtotal** `integer`

Subtotal de cargos por uso en centavos (antes de la tarifa de la plataforma).

**total** `integer`

Costo total proyectado en centavos (uso + tarifa de plataforma).

**currency** `string`

Código de moneda de la tarjeta de tarifas (actualmente `USD`).

**rates\_used** `object`

Las tarifas aplicadas a esta proyección.

**mint\_rate\_cents** `integer`

Tarifa por acuñación en centavos.

**verify\_rate\_cents** `integer`

Tarifa por verificación en centavos.

**platform\_fee** `integer`

Tarifa mensual de la plataforma en centavos.

**region** `string`

Nivel de región de precios aplicado.

**multiplier** `number`

Multiplicador de precio regional.

> [!NOTE]
>
> Todos los montos están en centavos. Divida por 100 para convertir a dólares. Los multiplicadores regionales se aplican automáticamente cuando incluye un `country_code`.


## OpenAPI

````yaml es/mint-openapi.yaml POST /v1/billing/projected-invoice
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/billing/projected-invoice:
    post:
      tags:
        - Billing
      summary: Próxima factura del proyecto
      description: >-
        Estima las cantidades facturables de acuñación y verificación utilizando
        la tarjeta de tarifas estándar y las bandas de volumen graduadas. No
        cobra, no resuelve precios negociados privados ni deduce asignaciones
        gratuitas. Los montos son centavos enteros.
      operationId: billing.projectedInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                country_code:
                  type: string
                mints:
                  type: integer
                  minimum: 0
                  maximum: 1000000000
                plan_key:
                  type: string
                verifications:
                  type: integer
                  minimum: 0
                  maximum: 1000000000
              type: object
      responses:
        '200':
          description: Factura proyectada
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  subtotal:
                    type: integer
                  amount_unit:
                    type: string
                    enum:
                      - cents
                  billing_model:
                    type: string
                    enum:
                      - pay_per_use
                  volume_pricing:
                    type: string
                    enum:
                      - graduated
                  estimate_only:
                    type: boolean
                  currency:
                    type: string
                  line_items:
                    type: array
                    items:
                      type: object
        '400':
          description: Cantidad no válida o plan desconocido
        '401':
          description: Autenticación requerida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Las tarifas configuradas no pueden tarificar este uso
      security:
        - APIKey: []
components:
  schemas:
    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.