> ## 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. # Planos de tarifas > Atribua um plano de tarifas a uma conta, com uma cota gratuita por tarifa e mês civil, e cobre as tarifas de serviço dele. Um **plano de tarifas** é um conjunto de tarifas que você atribui a uma conta. Cada tarifa tem uma cota gratuita: um número de unidades em cada mês civil que não custam nada. Um plano de tarifas tem dois tipos de tarifa: * **Tarifas de transação** se aplicam às transações `/v2` que a conta envia. * **Tarifas de serviço** se aplicam quando você cobra um serviço da conta, por exemplo um extrato em papel. Você as cobra com uma [cobrança de tarifas](#service-fees-and-fee-charges). Você cria planos de tarifas e os atribui pela API. Cada conta tem no máximo um plano de tarifas ativo. ## Planos de tarifas e pacotes de tarifas *** Um plano de tarifas e um [pacote de tarifas](https://docs.lerian.studio/pt/products/midaz/fees/fees-engine-overview.md#fee-packages) são entidades diferentes. * Uma conta com um plano de tarifas ativo paga as tarifas do plano dela nas transações `/v2` que envia. Nessas transações, um pacote de tarifas nunca cobra essa conta, também quando nenhuma tarifa do plano corresponde. Então a conta não paga tarifa. * Um pacote de tarifas não cobra os lançamentos de tarifa que um plano de tarifas adiciona. | | Pacotes de tarifas | Planos de tarifas | | - | - | - | | **Seleciona** | Transações, por rota, segmento, metadados e valor | As contas que você atribui ao plano | | **Cota gratuita** | Não | Sim, por tarifa e mês civil | | **Tarifas de serviço** | Não | Sim, por cobranças de tarifas | | **Tarifas dedutíveis** | Sim (`isDeductibleFrom`) | Não | | **Tarifas diferíveis** | Sim (`deferrable`) | Não | | **Arredondamento** | Sim (`rounding`) | Não | ## Crie um plano de tarifas *** Crie um plano com [Criar um plano de tarifas](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-an-account-plan.md). O plano tem estes campos: * `label`: o nome do plano. Dois planos de um ledger que não foram excluídos não podem ter o mesmo label (`0543`). * `description`: opcional. * `enable`: `true` permite atribuir o plano a contas. * `timezone`: o fuso horário IANA em que o plano conta os meses dele. O padrão é `America/Sao_Paulo`. * `fees`: pelo menos uma tarifa, por chave de tarifa. Uma chave de tarifa começa com uma letra minúscula, seguida apenas de letras e dígitos ASCII (`^[a-z][a-zA-Z0-9]*$`). Cada tarifa tem estes campos: * `feeLabel`: o nome da tarifa. * `trigger`: o que faz a tarifa se aplicar. Veja [Gatilhos](#triggers). * `calculationModel`: `flatFee`, `percentual` ou `maxBetweenTypes`, como em um [pacote de tarifas](https://docs.lerian.studio/pt/products/midaz/fees/fee-engine-calculation.md#fee-calculation-rules). Uma tarifa de serviço aceita apenas `flatFee` (`0555`). * `creditAccount`: o alias da conta do ledger que recebe a tarifa. O Midaz confere se a conta existe quando você cria ou atualiza o plano. * `accounting`: o `transactionRoute`, o `operationRouteFrom` e o `operationRouteTo` da tarifa. Veja [Rotas contábeis](#accounting-routes). * `freeQuota`: o número de unidades gratuitas por mês. O padrão é `0`. * `period`: apenas `monthly`, o padrão. * `referenceAmount`: apenas `originalAmount`, o padrão. ### Gatilhos Um gatilho com `type: transaction` aceita estes campos: * `direction`: obrigatório. O único valor é `sent`: a tarifa se aplica à conta que envia a transação. * `schemes`: os esquemas de transação que a tarifa corresponde, por exemplo `TED` ou `PIX`. * `metadata`: pares opcionais que os metadados da transação devem ter todos. Um par corresponde apenas a um valor de metadado do tipo string igual a ele. Um gatilho com `type: service` aceita apenas `serviceCode`, por exemplo `PAPER_STATEMENT`. O Midaz armazena esquemas e códigos de serviço sem espaços nas pontas e em maiúsculas. Cada um tem de 1 a 50 letras, dígitos, sublinhados ou hifens. Um código não pode ser o esquema de uma tarifa e o código de serviço de outra tarifa do plano (`0558`). ### Rotas contábeis As regras dependem de o ledger validar ou não as rotas contábeis (`accounting.validateRoutes` nas [configurações do ledger](https://docs.lerian.studio/pt/products/midaz/ledgers.md)): | Regra | Ledger sem validação de rotas | Ledger com validação de rotas | | - | - | - | | Tarifa de transação | Lista pelo menos um esquema (`0556`). | Uma tarifa sem esquemas corresponde a cada esquema da rota de transação dela. | | `accounting` | Opcional. | Obrigatório em cada tarifa, com um `transactionRoute` (`0547`) que existe (`0105`) e as duas rotas de operação (`0557`). | | Rotas de operação | Não são conferidas. | As duas estão vinculadas à rota de transação da tarifa. Em uma tarifa de transação, as duas são vínculos opcionais (`optionalOperationRoutes`) (`0557`). | Duas tarifas de transação de um plano com os mesmos `metadata` não podem selecionar as mesmas transações (`0544`). Em um ledger sem validação de rotas, elas não podem compartilhar um esquema. Em um ledger com validação de rotas, elas não podem compartilhar uma rota de transação e um esquema, e uma tarifa sem esquemas ocupa cada esquema da rota dela. Duas tarifas de serviço não podem compartilhar um código de serviço (`0544`). Se você ativar a validação de rotas depois de criar um plano, dê antes a cada tarifa uma rota de transação e as duas rotas de operação. Uma tarifa sem rota de transação recusa com `0547` cada transação a que ela corresponderia, e cada cobrança de tarifas que a nomeia. ## Versões *** As tarifas de um plano ficam em versões. Uma versão nunca muda. * A criação gera a versão 1, em vigor a partir do instante da criação. * Uma [atualização](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-an-account-plan.md) que envia `fees` gera uma nova versão com o conjunto completo de tarifas resultante. * `effectiveFrom` define o instante a partir do qual a nova versão se aplica, em RFC 3339. O padrão é o instante da requisição. Ele não pode ser anterior ao `effectiveFrom` da versão mais recente (`0553`). Envie-o apenas com `fees`. * `label`, `description`, `enable` e `timezone` mudam o plano, não uma versão. Nos `fees` de uma atualização: * Uma entrada com a chave de uma tarifa armazenada muda os campos que envia e mantém os outros. `trigger`, `calculationModel` e `accounting` mudam por inteiro. * Uma entrada vazia (`{}`) exclui essa tarifa. * Uma entrada com uma nova chave adiciona uma tarifa, com cada campo obrigatório. * A nova versão parte das tarifas da versão mais recente. Ela mantém pelo menos uma tarifa. Quando duas atualizações criam uma versão do mesmo plano ao mesmo tempo, uma delas recebe `0559` e não cria versão. Leia o plano de novo e envie a atualização de novo. [Consultar um plano de tarifas](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-an-account-plan.md) retorna a versão em vigor no instante da requisição. `currentVersion` é a maior versão criada, que pode começar depois. [Listar as versões de um plano de tarifas](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-the-versions-of-an-account-plan.md) retorna cada versão. ## Atribua um plano a uma conta *** [Atribuir um plano de tarifas a uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/assign-an-account-plan-to-an-account.md) envia o `accountPlanId` do plano. * O plano deve pertencer ao ledger, existir e estar habilitado (`0545`). * Se a conta tem uma atribuição ativa de outro plano, ela termina no instante em que a nova atribuição começa, em um único passo. * Se a conta já tem o mesmo plano, o Midaz retorna a atribuição ativa e não muda nada. * Quando outra atribuição da mesma conta acontece ao mesmo tempo, o Midaz pode responder `0560` e não mudar nada. Envie a requisição de novo. [Consultar a atribuição de plano de tarifas de uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-the-account-plan-assignment-of-an-account.md) retorna a atribuição ativa, ou `null`, e o histórico da conta. [Listar as contas atribuídas a um plano de tarifas](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-the-accounts-assigned-to-an-account-plan.md) retorna as atribuições ativas de um plano. [Terminar a atribuição de plano de tarifas de uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/end-the-account-plan-assignment-of-an-account.md) termina a atribuição ativa. Os pacotes de tarifas então voltam a se aplicar à conta. Uma conta sem atribuição ativa responde `0554`. ### Desabilite ou exclua um plano * Um plano desabilitado (`enable: false`) não pode ser atribuído. Ele continua cobrando as contas que já tem. * O Midaz recusa excluir um plano atribuído a uma conta (`0546`). Termine as atribuições dele antes. * Quando você exclui uma conta, o Midaz termina a atribuição ativa dela. O histórico da conta continua legível. ## Como um plano cobra uma transação *** O Midaz aplica planos de tarifas a estas transações `/v2`: direct, hold, block, unblock e cada item de um lote. Uma transação `/v1`, uma anotação, um estorno e uma transação que pula as tarifas com `skip.fees` não usam planos de tarifas. O Midaz toma uma decisão para cada conta de origem da transação que tem um plano ativo, exceto contas `@external`. Ele toma uma decisão por conta, também quando a conta envia de vários saldos. ### Correspondência As tarifas da versão em vigor são comparadas com a transação: * Em um ledger sem validação de rotas, uma tarifa de transação corresponde quando os `schemes` dela contêm o `scheme` da transação. Uma transação sem `scheme` não corresponde a nenhuma tarifa. * Em um ledger com validação de rotas, uma tarifa de transação corresponde quando o `transactionRoute` dela é o `routeId` da transação e os `schemes` dela estão vazios ou contêm o `scheme` da transação. * Nos dois casos, os metadados da transação devem ter cada par de `metadata` da tarifa. * Quando várias tarifas correspondem, se aplica a tarifa com mais pares de `metadata`. Quando duas ou mais tarifas têm esse número de pares, o Midaz recusa a transação com `0548`. ### Resultado A decisão tem um destes resultados: | Resultado | O que acontece | | - | - | | `quota` | Uma tarifa correspondeu, e a unidade está dentro da cota gratuita. A conta não paga tarifa. | | `charged` | Uma tarifa correspondeu, e a unidade passou da cota gratuita. O Midaz adiciona a tarifa por cima do que a conta envia e a credita em `creditAccount`. | | `no_match` | Nenhuma tarifa correspondeu. A conta não paga tarifa, e nenhuma unidade é contada. | O Midaz calcula uma tarifa cobrada sobre o valor que a conta envia na transação. Em um ledger com validação de rotas, os lançamentos de tarifa usam as rotas de operação da tarifa. A resposta da criação tem `accountPlanFees`, com um item para cada conta que tem um plano ativo: `accountId`, `accountAlias`, `accountPlanId`, `accountPlanVersion`, `feeKey`, `outcome`, `unit`, `freeQuota` e `amount`. Apenas as respostas de criação o retornam. Leituras, commits, cancelamentos e estornos não. As chaves de metadados da transação `packageAppliedID`, `feeApplied` e `feeExemption` descrevem apenas pacotes de tarifas. ### Holds, cancelamentos e estornos * Um hold conta a unidade quando você o cria. O commit não conta nada. * Um cancelamento ou um estorno devolve a unidade apenas no mesmo mês do plano. O estorno também reverte os lançamentos de tarifa. ## Cota gratuita *** Uma unidade é uma decisão com o resultado `quota` ou `charged`, ou um código de serviço de uma cobrança de tarifas com os mesmos resultados. * O Midaz conta unidades por conta, chave de tarifa e mês civil no fuso horário do plano. * A contagem pertence à conta e à chave de tarifa, não ao plano. Uma conta que passa para outro plano com a mesma chave de tarifa mantém a contagem dela no mês. * Uma tarifa de transação conta cada esquema separadamente. Em um ledger com validação de rotas, uma tarifa sem esquemas tem uma contagem para todos os esquemas da rota dela. Uma tarifa de serviço tem uma contagem. * Quando você muda uma tarifa, a contagem dela continua. Uma tarifa com uma nova chave começa do zero. * O mês é o mês em que o Midaz processa a transação, não o `transactionDate` dela. ## Tarifas de serviço e cobranças de tarifas *** [Cobrar tarifas de serviço de uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/charge-service-fees-to-an-account.md) envia `serviceCodes`, com 1 a 100 códigos, e `description` e `metadata` opcionais. A requisição precisa do header `X-Idempotency` (`0552`). Cada código da lista é uma unidade. O resultado dela é um destes: * `quota`: a unidade está dentro da cota gratuita da tarifa dela. Não custa nada. * `charged`: a unidade passou da cota gratuita. Custa o valor fixo da tarifa. * `not_covered`: o plano da conta não tem tarifa de serviço para o código, ou a conta não tem plano ativo. Não custa nada e não conta unidade. O Midaz recusa a requisição antes de cobrar qualquer coisa quando: * Nenhum plano de tarifas do ledger tem uma tarifa de serviço para um código (`0549`). * Um código pertence apenas a tarifas de transação (`0550`). * Em um ledger com validação de rotas, as tarifas dos códigos têm rotas de transação diferentes (`0551`), ou uma tarifa não tem rota de transação (`0547`). O Midaz lança as unidades cobradas como uma transação de tarifa no ativo da conta. Ele debita a conta e credita o `creditAccount` de cada tarifa. Em um ledger com validação de rotas, a transação usa a rota de transação e as rotas de operação das tarifas. A `description` e os `metadata` da cobrança vão para a transação de tarifa. Nenhum pacote de tarifas, plano de tarifas ou validação do Tracer se aplica à transação de tarifa. Quando o Midaz recusa a transação de tarifa, por exemplo por saldo insuficiente, ele recusa a cobrança com o mesmo erro e não conta unidade. Uma cobrança sem unidade cobrada não tem transação de tarifa, e o `feeTransactionIds` dela fica vazio. Nada desfaz essa cobrança, e as unidades dela continuam contadas. * Uma nova tentativa com a mesma chave e o mesmo corpo retorna a cobrança registrada com o header `X-Idempotency-Replayed`. Um corpo diferente com a mesma chave responde `0084`. As chaves são únicas por conta. * Para desfazer uma cobrança, estorne a transação de tarifa dela. Um estorno no mesmo mês devolve cada unidade da cobrança. * A transação de tarifa não tem referência à cobrança dela. O `feeTransactionIds` da cobrança liga as duas. [Listar as cobranças de tarifas de uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-the-fee-charges-of-an-account.md) retorna a cobrança mais nova primeiro, e `period` (`YYYY-MM`) filtra a lista. [Consultar uma cobrança de tarifas de uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-a-fee-charge-of-an-account.md) retorna uma cobrança. ## Uso *** [Consultar o uso do plano de tarifas de uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-the-account-plan-usage-of-an-account.md) retorna as unidades da conta em um mês. `period` (`YYYY-MM`, no fuso horário do plano) escolhe o mês. O padrão é o mês atual. Um `period` futuro ou malformado responde `0082`, e uma conta sem plano ativo responde `0554`. A resposta tem um item para cada contagem de cada tarifa: `feeKey`, `trigger`, `period`, `freeQuota`, `used`, `remaining` e `charged`. `trigger` é uma chave da contagem: leia `feeKey` em vez de interpretá-la. `remaining` nunca é negativo. O uso lista as tarifas e as cotas gratuitas da versão em vigor agora, também para um mês passado. Para conciliação, use o `accountPlanFees` das respostas de criação e as cobranças de tarifas. ## Estimativas e eventos *** * Uma [estimativa de tarifas](https://docs.lerian.studio/pt/reference/products/midaz/v2/estimate-fee-calculation.md) precifica o pacote de tarifas que você nomeia. Ela não lê as atribuições de planos de tarifas. * O evento `fee_charge.applied` cobre apenas pacotes de tarifas. Uma tarifa de plano de tarifas ou uma cobrança de tarifas não o emite. ## Permissões *** As rotas usam estes recursos de permissão do Midaz: | Recurso | Ação | Uso | | - | - | - | | `account-plans` | `get` | Ler planos, versões, contas atribuídas, atribuições e uso. | | `account-plans` | `post` | Criar um plano. | | `account-plans` | `patch` | Atualizar um plano. | | `account-plans` | `put` | Atribuir um plano a uma conta. | | `account-plans` | `delete` | Excluir um plano, ou terminar a atribuição de uma conta. | | `fee-charges` | `get` | Ler cobranças de tarifas. | | `fee-charges` | `post` | Cobrar tarifas de serviço. | ## Próximos passos *** > [card] [Usar planos de tarifas](https://docs.lerian.studio/pt/products/midaz/fees/using-account-plans.md) > > Crie um plano, atribua-o e cobre tarifas passo a passo. > [card] [Lista de erros do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/error-list.md) > > Veja os códigos de `0543` a `0560`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.