Endpoint

Utilize o endpoint abaixo para criar uma fatura recorrente estilo carnê.

Método POST

URL: /v2/invoices/booklet

Request

Exemplo de requisição para ser enviada no body.

{
   "customerId":1,
   "daysUntilDue":7,
   "billingFrequency":"MONTHLY",
   "collectionMethod":"AUTOMATIC_CHARGE",
   "chargesByBooklet":"5",
   "recurringItem":{
      "quantity":1,
      "productId":1,
      "maxBillingCycles":10,
      "unitPriceInCents":1027
   },
   "acceptedPaymentMethods":[
      {
         "method":"BANK_SLIP",
         "amountOff":1000
      }
   ],
   "splits":[
      {
         "sellerId":2,
         "percentage":5.50,
         "cyclesToParticipate":1,
         "absorbBalance":false
      },
      {
         "sellerId":1,
         "percentage":94.50,
         "cyclesToParticipate":10,
         "absorbBalance":true
      }
   ]
}

📄 Parâmetros do corpo da requisição

Campo	Tipo	Obrigatório	Descrição
customerId	integer	Sim	ID do cliente que está sendo faturado.
daysUntilDue	integer	Sim	Número de dias até a fatura vencer.
billingFrequency	string	Sim	Frequência de cobrança. Valores possíveis: WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMESTRAL, YEARLY.
collectionMethod	string	Sim	Método de cobrança. Valores possíveis: AUTOMATIC_CHARGE ou SEND_INVOICE.
chargesByBooklet	integer	Sim	Quantidade de cobranças no carnê (número de faturas geradas).
recurringItem	object	Sim	Dados do item recorrente. Veja abaixo os campos aninhados.
acceptedPaymentMethods	array	Sim	Lista de métodos de pagamento aceitos. Cada item pode conter configurações específicas por método. Veja abaixo.
splits	array	Não	Regras de divisão de receita entre os sellers. A soma dos percentage deve ser 100%. Veja estrutura abaixo.

🧾 Objeto: recurringItem

Campo	Tipo	Obrigatório	Descrição
productId	integer	Sim	ID do produto a ser faturado.
quantity	integer	Sim	Quantidade do produto.
unitPriceInCents	integer	integer	Preço unitário do produto, em centavos. Ex: 1027 = R$ 10,27.
maxBillingCycles	integer	Sim	Máximo de ciclos de cobrança de acordo com a frequência informada no campo `billingFrequency`. (Ex: 10 faturas mensais). Máximo: 9999.

💳 acceptedPaymentMethods

Campo	Tipo	Obrigatório	Descrição
method	string	Sim	Método de pagamento aceito. Valores: BANK_SLIP.
amountOff	integer	Não	Valor do desconto para esse método (em centavos). Ex: 1500 = R$ 15,00.

🤝 splits

Campo	Tipo	Obrigatório	Descrição
sellerId	integer	Sim	ID do seller que participará da divisão.
percentage	decimal	Sim	Percentual da receita destinado ao seller. A soma de todos os percentage deve ser 100%.
cyclesToParticipate	integer	Sim	Quantidade de ciclos (faturas) que o seller participará.
absorbBalance	boolean	Sim	Define se esse seller absorverá qualquer saldo residual.

Response

Retornamos o URL do recurso criado no response header

✅ 201 - Created

Header	Exemplo	Descrição
Location	/api/v2/recurring-invoices/1	URL do recurso criado.