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

# Criar um pacote de cobrança

> Cria um pacote de billing para cobranças baseadas em períodos. Suporta dois tipos — `volume` (baseado em contagem de transações) e `maintenance` (taxa fixa por conta).



## OpenAPI

````yaml pt/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: Criar um pacote de billing
      description: >-
        Cria um pacote de billing para cobranças baseadas em períodos. Suporta
        dois tipos — `volume` (baseado em contagem de transações) e
        `maintenance` (taxa fixa por conta).
      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: Pacote de billing por volume
                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: Pacote de billing de manutenção
                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: Pacote de billing criado com sucesso.
          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: Conflito — já existe um pacote de billing com a mesma chave.
          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: O identificador único da Organização associada à requisição.
      required: true
      schema:
        type: string
        example: 019c96a0-0a98-7287-9a31-786e0809c769
    Authorization:
      name: Authorization
      in: header
      description: >-
        O token de autorização no formato 'Bearer <token>'.


        **Importante:** Este header é obrigatório se o seu ambiente possui o
        Access Manager habilitado. Para mais informações, consulte a
        documentação do [Access Manager](/pt/access-manager).
      required: false
      schema:
        type: string
    ContentType:
      name: Content-Type
      in: header
      description: O tipo de mídia do recurso. Deve ser `application/json`.
      required: true
      schema:
        type: string
        example: application/json
  schemas:
    CreateBillingPackageRequest:
      description: >
        Corpo da requisição para criar um pacote de billing. O conjunto de
        campos obrigatórios depende de `type`.

        - Pacotes `volume` exigem `eventFilter`, `pricingModel`, ao menos uma
        entrada em `tiers`, `assetCode`, `debitAccountAlias` e
        `creditAccountAlias`.

        - Pacotes `maintenance` exigem `feeAmount`, `assetCode`,
        `maintenanceCreditAccount` e `accountTarget`.

        `enable` é opcional; quando omitido, o serviço assume `true` por padrão.
      type: object
      required:
        - label
        - ledgerId
        - type
      properties:
        label:
          type: string
          description: Nome do pacote de billing.
        description:
          type: string
          description: Descrição opcional.
        ledgerId:
          type: string
          description: Ledger que registra as transações de billing.
        type:
          type: string
          enum:
            - volume
            - maintenance
          description: 'Tipo de billing: `volume` ou `maintenance`.'
        enable:
          type: boolean
          description: >-
            Se o pacote está ativo. Opcional. Se omitido, o valor padrão é
            `true`.
        eventFilter:
          type: object
          description: (Apenas volume) Filtro para determinar quais transações contar.
          required:
            - transactionRoute
            - status
          properties:
            transactionRoute:
              type: string
              description: Rota de transação associada ao pacote.
            status:
              type: string
              description: Status de transação a contabilizar (por exemplo, `APPROVED`).
        pricingModel:
          type: string
          enum:
            - tiered
            - fixed
          description: (Apenas volume) Modelo de preços.
        tiers:
          type: array
          minItems: 1
          description: >-
            (Apenas volume) Faixas de quantidade e preços unitários. É
            obrigatório informar pelo menos uma faixa.
          items:
            type: object
            required:
              - minQuantity
              - unitPrice
            properties:
              minQuantity:
                type: integer
                description: Quantidade mínima (inclusiva) à qual a faixa se aplica.
              maxQuantity:
                type: integer
                nullable: true
                description: >-
                  Quantidade máxima (inclusiva) da faixa, ou `null` para um
                  limite superior aberto.
              unitPrice:
                type: string
                description: >-
                  Preço unitário aplicado às transações dentro da faixa. Valor
                  decimal como string (por exemplo, `"0.50"`).
        freeQuota:
          type: integer
          description: (Apenas volume) Transações isentas antes da cobrança.
        discountTiers:
          type: array
          description: (Apenas volume) Limites de desconto progressivo.
          items:
            type: object
            properties:
              minQuantity:
                type: integer
              discountPercentage:
                type: string
                description: Valor decimal como string (por exemplo, `"5.00"`).
        countMode:
          type: string
          enum:
            - perRoute
            - perAccount
          description: (Apenas volume) Como as transações são agrupadas.
        assetCode:
          type: string
          description: Código da moeda (ex., BRL).
        debitAccountAlias:
          type: string
          description: (Apenas volume) Conta a debitar.
        creditAccountAlias:
          type: string
          description: (Apenas volume) Conta a creditar.
        feeAmount:
          type: string
          description: >-
            (Apenas manutenção) Taxa fixa por conta ativa. Valor decimal como
            string (por exemplo, `"9.90"`).
        maintenanceCreditAccount:
          type: string
          description: (Apenas manutenção) Conta que recebe a taxa.
        accountTarget:
          type: object
          description: >-
            (Apenas manutenção) Contas alvo. Informe exatamente um entre
            `segmentId`, `portfolioId` ou `aliases`.
          oneOf:
            - required:
                - segmentId
            - required:
                - portfolioId
            - required:
                - aliases
          properties:
            segmentId:
              type: string
              description: Segmento cujas contas serão cobradas.
            portfolioId:
              type: string
              description: Portfólio cujas contas serão cobradas.
            aliases:
              type: array
              description: Lista explícita de aliases de contas a cobrar.
              minItems: 1
              items:
                type: string
      oneOf:
        - title: Pacote de billing por volume
          description: Campos obrigatórios para `type = volume`.
          properties:
            type:
              const: volume
          required:
            - eventFilter
            - pricingModel
            - tiers
            - assetCode
            - debitAccountAlias
            - creditAccountAlias
        - title: Pacote de billing por manutenção
          description: Campos obrigatórios para `type = maintenance`.
          properties:
            type:
              const: maintenance
          required:
            - feeAmount
            - assetCode
            - maintenanceCreditAccount
            - accountTarget
    BillingPackageResponse:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do pacote 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: Um identificador único e estável para o erro.
        title:
          type: string
          description: Um resumo breve do problema.
        message:
          type: string
          description: Orientação detalhada para resolver o erro.
      required:
        - code
        - title
        - message
      description: A mensagem de erro da resposta.
  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.

````