Atualização de recorrência

Este endpoint possibilita que o parceiro Bankly realize a atualização de uma cobrança recorrente previamente agendada.

🚧
Importante
A quantidade (quantity) de cobranças e a frequência (frequency) em que elas ocorrem não poderão ser atualizadas.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que o cliente do parceiro Bankly:

Possua uma cobrança recorrente ativa.

Requisição (Request)

Requisição HTTP

HTTP

PATCH 'https://api-mtls.sandbox.bankly.com.br/cards/invoices/recurrencies/{recurrencyId}'

--request PATCH \
     --location --url 'https://api-mtls.sandbox.bankly.com.br/cards/invoices/recurrencies/{recurrencyId}' 
     --header 'Content-Type: application/json' \ 
     --header 'Authorization: Bearer {Token}'
     --header 'api-version: 1.0'\
     --header 'x-correlation-id: {Guid}'
     --data '{ 
        "recurrencyId": "string", 
        "billingType": "", 
        "recurrency": { 
          "postDate": 4, 
          "amount": { 
            "value": 101.5, 
            "currency": "BRL" 
          }, 
          "discount": { 
            "value": 2.00, 
            "currency": "BRL" 
          }, 
          "chargeOptions": { 
            "forceLimit": false, 
            "blockedAccount": false
          } 
        }, 
        "user": { 
          "documentNumber": { 
            "value": "47742663023", 
            "type": "CPF" 
          }, 
          "contract": { 
            "id": "12345678", 
            "type": "Credit" 
          } 
        } 
      }'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.

Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`recurrency.update`	Concede acesso para atualizar uma recorrência de cobrança.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.
`x-correlation-id`	Informe um GUID, sendo um novo cada requisição.

Parâmetros da rota (Path)

No path desta requisição, envie o seguinte campo:

Nome	Tipo	Descrição	Especificação
`recurrencyId`	`path`	Obrigatório. Identificador único da recorrência que deverá ser atualizada. Informe o valor do campo `recurrencyId` retornado no endpoint Agendamento de recorrência.	—

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	**Descrição	Especificação
`billingType`	`string`	Obrigatório. Tipo de cobrança.	Preencha este campo com "" ou com null.
`recurrency`	`object`	Obrigatório. Objeto que deverá conter informações sobre a recorrência.	—
`recurrency.postDate`	`int`	Dia em que deverá ser realizada a postagem de recorrência na fatura.	—
`recurrency.amount`	`object`	Objeto que deverá conter informações sobre o valor da cobrança recorrente. Importante: caso este objeto seja enviado, seus subcampos devem ser preenchidos obrigatoriamente.	—
`recurrency.amount.currency`	`string`	Código da moeda com base na ISO 3361.	—
`recurrency.amount.value`	`number`	Valor da cobrança recorrente.	—
`recurrency.discount`	`object`	Objeto que deverá conter informações sobre o desconto aplicado na cobrança, caso exista. Importante: caso este objeto seja enviado, seus subcampos devem ser preenchidos obrigatoriamente.	—
`recurrency.discount.currency`	`string`	Código da moeda com base na ISO 3361.	—
`recurrency.discount.value`	`number`	Valor do desconto.	—
`recurrency.chargeOptions`	`object`	Objeto que deverá conter informações sobre o formato de cobrança.	—
`recurrency.chargeOptions.forceLimit`	`boolean`	Indica se a cobrança recorrente deverá ocorrer para cartão sem limite (true) ou não (false).	—
`recurrency.chargeOptions.blockedAccount`	`boolean`	Indica se a cobrança recorrente deverá ocorrer para contas bloqueadas (true) ou não (false).	—
`user`	`object`	Obrigatório. Objeto que deverá conter informações sobre o titular do cartão.	—
`user.documentNumber`	`object`	Obrigatório. Objeto que deverá conter informações sobre o documento do titular.	—
`user.documentNumber.value`	`string`	Obrigatório. Número do documento.	Informe somente números.
`user.documentNumber.type`	`string`	Obrigatório. Tipo de documento, que pode ser "CPF" ou "CNPJ".	—
`user.contract`	`object`	Obrigatório. Objeto que deverá conter informações sobre o contrato de crédito do titular do cartão.	—
`user.contract.id`	`string`	Obrigatório. Identificador único do contrato.	—
`user.contract.type`	`string`	Obrigatório. Tipo de contrato, que pode ser "Credit" ou "Debit".	—

{ 
        "recurrencyId": "string", 
        "billingType": "", 
        "recurrency": { 
          "postDate": 4, 
          "amount": { 
            "value": 101.5, 
            "currency": "BRL" 
          }, 
          "discount": { 
            "value": 2.00, 
            "currency": "BRL" 
          }, 
          "chargeOptions": { 
            "forceLimit": false, 
            "blockedAccount": false
          } 
        }, 
        "user": { 
          "documentNumber": { 
            "value": "47742663023", 
            "type": "CPF" 
          }, 
          "contract": { 
            "id": "12345678", 
            "type": "Credit" 
          } 
        } 
      }

Resposta (Response)

O status code 201 indicará que a solicitação foi aceita e a atualização de recorrência da cobrança foi criada.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Número máximo de caracteres
`value`	`object`	Objeto que contém informações sobre a recorrência agendada.	—
`value.code`	`string`	Código personalizado da mensagem de sucesso.	—
`value.message`	`string`	Descrição do código de sucesso.	—
`value.recurrencyId`	`string`	Identificador único da recorrência atualizada.	—
`value.productType`	`string`	Descrição do produto enviado na requisição.	—

{ 
  "value": { 
    "code": "RECURRENCY_UPDATED", 
    "message": "Recurrency updated successfully.", 
    "recurrencyId": "COMPANY_KEY-edd874f6-6f00-4984-aa76-e50dabdba8a5", 
    "productType": "Seguros"
  } 
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
400	NOT_NEW_VALUES	There is no new value to apply to the requested Recurrency	Não existem dados a serem atualizados.
400	NOT_NEW_VALUES	'recurrencyId' must not be empty	Insira um valor válido de ID da recorrência.
406	NOT_SAME_RECURRENCY_ID	RecurrencyId from path doesn't match with RecurrencyId on body	O Id da recorrência enviado no path não é o mesmo que foi enviado na requisição.

Válido lembrar que a API também poderá retornar erros comuns entre todos os endpoints.

Eventos

Este endpoint não possui eventos relacionados a ele.