Pular para o conteúdo principal
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.
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 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.

​
Crie um plano de tarifas

Crie um plano com Criar um plano de tarifas. 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.
  • calculationModel: flatFee, percentual ou maxBetweenTypes, como em um pacote de tarifas. 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.
  • 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): 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 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 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 retorna cada versão.

​
Atribua um plano a uma conta

Atribuir um plano de tarifas a uma conta 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 retorna a atribuição ativa, ou null, e o histórico da conta. Listar as contas atribuídas a um plano de tarifas retorna as atribuições ativas de um plano. Terminar a atribuição de plano de tarifas de uma conta 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: 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 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 retorna a cobrança mais nova primeiro, e period (YYYY-MM) filtra a lista. Consultar uma cobrança de tarifas de uma conta retorna uma cobrança.

​
Uso

Consultar o uso do plano de tarifas de uma conta 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 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:

​
Próximos passos

Usar planos de tarifas

Crie um plano, atribua-o e cobre tarifas passo a passo.

Lista de erros do Midaz

Veja os códigos de 0543 a 0560.