> ## 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 paquete de facturación

> Crea un paquete de billing para cobros basados en periodos. Soporta dos tipos — `volume` (basado en conteo de transacciones) y `maintenance` (tarifa fija por cuenta).



## OpenAPI

````yaml es/openapi/v3-current/fees-engine.yaml post /v1/billing-packages
openapi: 3.1.0
info:
  title: Fees Engine
  description: ''
  version: 3.3.0
servers:
  - url: https://fees.sandbox.lerian.net
security: []
tags:
  - name: Fees Engine
paths:
  /v1/billing-packages:
    post:
      tags:
        - Billing Packages API
      summary: Crear un paquete de billing
      description: >-
        Crea un paquete de billing para cobros basados en periodos. Soporta dos
        tipos — `volume` (basado en conteo de transacciones) y `maintenance`
        (tarifa fija por cuenta).
      parameters:
        - $ref: '#/components/parameters/XOrganizationId'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillingPackageRequest'
            examples:
              volume:
                summary: Paquete de billing por volumen
                value:
                  label: Pix Send Monthly Billing
                  description: Monthly volume billing for Pix transactions
                  ledgerId: ldg_01HZ...
                  type: volume
                  enable: true
                  eventFilter:
                    transactionRoute: pix-send
                    status: APPROVED
                  pricingModel: tiered
                  tiers:
                    - minQuantity: 1
                      maxQuantity: 100
                      unitPrice: '0.50'
                    - minQuantity: 101
                      maxQuantity: 500
                      unitPrice: '0.35'
                    - minQuantity: 501
                      maxQuantity: null
                      unitPrice: '0.20'
                  freeQuota: 10
                  discountTiers:
                    - minQuantity: 200
                      discountPercentage: '5.00'
                    - minQuantity: 400
                      discountPercentage: '10.00'
                  countMode: perAccount
                  assetCode: BRL
                  debitAccountAlias: client-wallet
                  creditAccountAlias: fees-revenue
              maintenance:
                summary: Paquete de billing por mantenimiento
                value:
                  label: PF Account Maintenance
                  description: Monthly maintenance fee for active PF accounts
                  ledgerId: ldg_01HZ...
                  type: maintenance
                  enable: true
                  feeAmount: '9.90'
                  assetCode: BRL
                  maintenanceCreditAccount: fees-maintenance-pf
                  accountTarget:
                    segmentId: seg_pf_01HZ...
      responses:
        '201':
          description: Paquete de billing creado exitosamente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPackageResponse'
              example:
                id: bpkg_01HZ...
                label: Pix Send Monthly Billing
                type: volume
                enable: true
                organizationId: org_01HZ...
                ledgerId: ldg_01HZ...
                createdAt: '2026-03-01T00:00:00Z'
                updatedAt: '2026-03-01T00:00:00Z'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Error0001:
                  $ref: '#/components/examples/Error0001'
                Error0002:
                  $ref: '#/components/examples/Error0002'
                Error0019:
                  $ref: '#/components/examples/Error0019'
                Error0020:
                  $ref: '#/components/examples/Error0020'
                Error0041:
                  $ref: '#/components/examples/Error0041'
                Error0053:
                  $ref: '#/components/examples/Error0053'
                Error0054:
                  $ref: '#/components/examples/Error0054'
                Error0055:
                  $ref: '#/components/examples/Error0055'
                Error0056:
                  $ref: '#/components/examples/Error0056'
                Error0057:
                  $ref: '#/components/examples/Error0057'
                Error0058:
                  $ref: '#/components/examples/Error0058'
                Error0064:
                  $ref: '#/components/examples/Error0064'
                Error0065:
                  $ref: '#/components/examples/Error0065'
                Error0067:
                  $ref: '#/components/examples/Error0067'
                Error0069:
                  $ref: '#/components/examples/Error0069'
                Error0070:
                  $ref: '#/components/examples/Error0070'
        '409':
          description: Conflicto — ya existe un paquete de billing con la misma clave.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Error0004:
                  $ref: '#/components/examples/Error0004'
      security: []
components:
  parameters:
    XOrganizationId:
      name: X-Organization-Id
      in: header
      description: Identificador único de la organización asociada a la solicitud.
      required: true
      schema:
        type: string
        example: 019c96a0-0a98-7287-9a31-786e0809c769
    Authorization:
      name: Authorization
      in: header
      description: >-
        El token de autorización en formato 'Bearer <token>'.


        **Importante:** Este encabezado es obligatorio si su entorno tiene
        habilitado Access Manager. Para obtener más información, consulte la
        documentación de [Access Manager](/es/access-manager).
      required: false
      schema:
        type: string
    ContentType:
      name: Content-Type
      in: header
      description: Tipo de medio del recurso. Debe ser `application/json`.
      required: true
      schema:
        type: string
        example: application/json
  schemas:
    CreateBillingPackageRequest:
      description: >
        Cuerpo de la solicitud para crear un paquete de billing. El conjunto de
        campos requeridos depende de `type`.

        - Los paquetes `volume` requieren `eventFilter`, `pricingModel`, al
        menos una entrada en `tiers`, `assetCode`, `debitAccountAlias` y
        `creditAccountAlias`.

        - Los paquetes `maintenance` requieren `feeAmount`, `assetCode`,
        `maintenanceCreditAccount` y `accountTarget`.

        `enable` es opcional; cuando se omite, el servicio lo establece en
        `true` por defecto.
      type: object
      required:
        - label
        - ledgerId
        - type
      properties:
        label:
          type: string
          description: Nombre del paquete de billing.
        description:
          type: string
          description: Descripción opcional.
        ledgerId:
          type: string
          description: Ledger que registra las transacciones de billing.
        type:
          type: string
          enum:
            - volume
            - maintenance
          description: 'Tipo de billing: `volume` o `maintenance`.'
        enable:
          type: boolean
          default: true
          description: >-
            Si el paquete está activo. Opcional. Si se omite, el valor
            predeterminado es `true`.
        eventFilter:
          type: object
          description: (Solo volumen) Filtro para determinar qué transacciones contar.
          required:
            - transactionRoute
            - status
          properties:
            transactionRoute:
              type: string
              description: Ruta de transacción asociada al paquete.
            status:
              type: string
              description: Estado de transacción a contar (por ejemplo, `APPROVED`).
        pricingModel:
          type: string
          enum:
            - tiered
            - fixed
          description: (Solo volumen) Modelo de precios.
        tiers:
          type: array
          minItems: 1
          description: >-
            (Solo volumen) Rangos de cantidad y precios unitarios. Se requiere
            al menos un tramo.
          items:
            type: object
            required:
              - minQuantity
              - unitPrice
            properties:
              minQuantity:
                type: integer
                description: Cantidad mínima (inclusive) para la que aplica el tramo.
              maxQuantity:
                type: integer
                nullable: true
                description: >-
                  Cantidad máxima (inclusive) del tramo, o `null` para un límite
                  superior abierto.
              unitPrice:
                type: string
                description: >-
                  Precio unitario aplicado a las transacciones dentro del tramo.
                  Valor decimal como string (por ejemplo, `"0.50"`).
        freeQuota:
          type: integer
          description: (Solo volumen) Transacciones exentas antes de cobrar.
        discountTiers:
          type: array
          description: (Solo volumen) Umbrales de descuento progresivo.
          items:
            type: object
            properties:
              minQuantity:
                type: integer
              discountPercentage:
                type: string
                description: Valor decimal como string (por ejemplo, `"5.00"`).
        countMode:
          type: string
          enum:
            - perRoute
            - perAccount
          description: (Solo volumen) Cómo se agrupan las transacciones.
        assetCode:
          type: string
          description: Código de moneda (ej., BRL).
        debitAccountAlias:
          type: string
          description: (Solo volumen) Cuenta a debitar.
        creditAccountAlias:
          type: string
          description: (Solo volumen) Cuenta a acreditar.
        feeAmount:
          type: string
          description: >-
            (Solo mantenimiento) Tarifa fija por cuenta activa. Valor decimal
            como string (por ejemplo, `"9.90"`).
        maintenanceCreditAccount:
          type: string
          description: (Solo mantenimiento) Cuenta que recibe la tarifa.
        accountTarget:
          type: object
          description: >-
            (Solo mantenimiento) Cuentas objetivo. Proporciona exactamente uno
            de `segmentId`, `portfolioId` o `aliases`.
          oneOf:
            - required:
                - segmentId
            - required:
                - portfolioId
            - required:
                - aliases
          properties:
            segmentId:
              type: string
              description: Segmento cuyas cuentas se cobran.
            portfolioId:
              type: string
              description: Portafolio cuyas cuentas se cobran.
            aliases:
              type: array
              description: Lista explícita de alias de cuentas a cobrar.
              minItems: 1
              items:
                type: string
      oneOf:
        - title: Paquete de billing por volumen
          description: Campos requeridos para `type = volume`.
          properties:
            type:
              const: volume
          required:
            - eventFilter
            - pricingModel
            - tiers
            - assetCode
            - debitAccountAlias
            - creditAccountAlias
        - title: Paquete de billing por mantenimiento
          description: Campos requeridos para `type = maintenance`.
          properties:
            type:
              const: maintenance
          required:
            - feeAmount
            - assetCode
            - maintenanceCreditAccount
            - accountTarget
    BillingPackageResponse:
      type: object
      properties:
        id:
          type: string
          description: Identificador único del paquete de billing.
        label:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
            - volume
            - maintenance
        enable:
          type: boolean
        organizationId:
          type: string
        ledgerId:
          type: string
        eventFilter:
          type: object
          properties:
            transactionRoute:
              type: string
            status:
              type: string
        pricingModel:
          type: string
          enum:
            - tiered
            - fixed
        tiers:
          type: array
          items:
            type: object
            properties:
              minQuantity:
                type: integer
              maxQuantity:
                type: integer
                nullable: true
              unitPrice:
                type: string
        freeQuota:
          type: integer
        discountTiers:
          type: array
          items:
            type: object
            properties:
              minQuantity:
                type: integer
              discountPercentage:
                type: string
        countMode:
          type: string
          enum:
            - perRoute
            - perAccount
        assetCode:
          type: string
        debitAccountAlias:
          type: string
        creditAccountAlias:
          type: string
        feeAmount:
          type: string
        maintenanceCreditAccount:
          type: string
        accountTarget:
          type: object
          properties:
            segmentId:
              type: string
            portfolioId:
              type: string
            aliases:
              type: array
              items:
                type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      properties:
        code:
          type: string
          description: Identificador único y estable del error.
        title:
          type: string
          description: Resumen breve del problema.
        message:
          type: string
          description: Orientación detallada para resolver el error.
      required:
        - code
        - title
        - message
      description: Mensaje de error devuelto en la respuesta.
  examples:
    Error0001:
      summary: Unexpected fields in the request
      value:
        code: FEE-0001
        title: Unexpected fields in the request
        message: >-
          The request body contains more fields than expected. Please send only
          the allowed fields as per the documentation. The unexpected fields are
          listed in the fields object.
    Error0002:
      summary: Missing fields in request
      value:
        code: FEE-0002
        title: Missing fields in request
        message: >-
          Your request is missing one or more required fields. Please refer to
          the documentation to ensure all necessary fields are included in your
          request.
    Error0019:
      summary: Invalid header parameter
      value:
        code: FEE-0019
        title: Invalid header parameter
        message: >-
          One or more headers parameters are in an incorrect format. Please
          check the following parameters and ensure they meet the required
          format before trying again.
    Error0020:
      summary: Missing header
      value:
        code: FEE-0020
        title: Missing header
        message: >-
          Headers parameters is required. Please check the following header
          parameters %v and ensure they are passing the values correctly.
    Error0041:
      summary: Unmarshalling error
      value:
        code: FEE-0041
        title: Unmarshalling error
        message: 'Invalid value for field ''%s'': expected type ''%s'', but got ''%s''.'
    Error0053:
      summary: Invalid billing type
      value:
        code: FEE-0053
        title: Invalid billing type
        message: The type field must be `volume` or `maintenance`.
    Error0054:
      summary: Missing volume fields
      value:
        code: FEE-0054
        title: Missing volume fields
        message: >-
          Volume billing packages require: eventFilter, pricingModel, tiers,
          assetCode, debitAccountAlias, and creditAccountAlias.
    Error0055:
      summary: Missing maintenance fields
      value:
        code: FEE-0055
        title: Missing maintenance fields
        message: >-
          Maintenance billing packages require: feeAmount, assetCode,
          maintenanceCreditAccount, and accountTarget.
    Error0056:
      summary: Invalid pricing model
      value:
        code: FEE-0056
        title: Invalid pricing model
        message: The pricingModel field must be `tiered` or `fixed`.
    Error0057:
      summary: Invalid pricing tier
      value:
        code: FEE-0057
        title: Invalid pricing tier
        message: >-
          Tiers must not overlap and must have valid minQuantity, maxQuantity,
          and positive unitPrice.
    Error0058:
      summary: Billing route overlap
      value:
        code: FEE-0058
        title: Billing route overlap
        message: >-
          Another active volume billing package already uses this
          transactionRoute for the same organization and ledger.
    Error0064:
      summary: Invalid free quota
      value:
        code: FEE-0064
        title: Invalid free quota
        message: The freeQuota field must be a non-negative integer.
    Error0065:
      summary: Invalid discount tier
      value:
        code: FEE-0065
        title: Invalid discount tier
        message: The discountPercentage must be between 0 and 100.
    Error0067:
      summary: Invalid count mode
      value:
        code: FEE-0067
        title: Invalid count mode
        message: The countMode field must be `perRoute` or `perAccount`.
    Error0069:
      summary: Invalid account target
      value:
        code: FEE-0069
        title: Invalid account target
        message: >-
          The accountTarget could not be resolved. Verify that segmentId,
          portfolioId, or the provided aliases exist in Midaz.
    Error0070:
      summary: Invalid fee amount
      value:
        code: FEE-0070
        title: Invalid fee amount
        message: The feeAmount must be a positive value greater than zero.
    Error0004:
      summary: Internal Server Error
      value:
        code: FEE-0004
        title: Internal Server Error
        message: >-
          The server encountered an unexpected error. Please try again later or
          contact support.

````