Realização de ajuste financeiro

Este endpoint permite ao parceiro executar um ajuste forçado de débito ou crédito em uma fatura em aberto.

Pré-requisitos

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

Possua uma conta ativa;
Possua um cartão válido, ativo e pós-pago;
Tenha uma fatura criada.

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/cards/invoices/adjustments \

--request POST/
--url 'https://api-mtls.sandbox.bankly.com.br/cards/invoices/adjustments' \ 
--header 'api-version: 1.0' \ 
--header 'x-bkly-version: 01-04-2023' \ 
--header 'authorization: Bearer {{token}}' \ 
--header 'idempotency-key: b1409d1e-5b3d-4bbb-99a2-226f7eff5924' \ 
--header 'x-bkly-correlation-id: 9d15fdb6-592f-4cbd-9403-e3f28694be49' \
--header 'x-user-id: 35268974710' \
--header 'Content-Type: application/json' \ 
--data '{ 
  "client": { 
    "contractNumber": "ACESSO123456", 
  }, 
  "transaction": { 
    "amount": {
      "value": 78458.7,
      "currency": "BRL",
    },
    "transactionType": "090907", 
    "descriptor": "string",
    "metadata": { 
        "parametro1": "info1", 
        "parametro2": "info2", 
        "parametro3": "info3" 
    } 
  } 
}'

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
`invoice.adjustment`	Concede acesso para a realização de lançamentos de ajustes de crédito ou débito, assim como de seu cancelamento.

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-bkly-correlation-id`	Informe um GUID, sendo um novo cada requisição.
`x-bkly-version`	Indica a versão do contrato. É alterada somente quando há quebra de contrato. O padrão definido é: yyyy-mm-dd , que se refere à data da quebra de contrato. No caso deste endpoint será sempre 01-04-2023.
`idempotency-key`	Informe um UUID, sendo um novo a cada requisição.
`x-user-id`	Documento associado à conta do usuário.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Especificação
`client`	`object`	Obrigatório*. Objeto que deverá conter informações sobre o titular do cartão de crédito.	—
`client.contractNumber`	`string`	Obrigatório*. Número do contrato vigente.	—
`transaction`	`object`	Obrigatório*. Objeto que deverá conter informações sobre a operação que será forçosamente lançada na fatura em aberto.	—
`transaction.amount`	`object`	Obrigatório*. Objeto que deverá conter informações sobre o valor monetário do ajuste.	—
`transaction.amount.value`	`number`	Obrigatório*. Valor monetário do ajuste.	Informe somente os números.
`transaction.amount.currency`	`string`	Obrigatório*. Código da moeda com base na ISO - 4217.	—
`transaction.transactionType`	`string`	Obrigatório*. Código que identifica a transação de crédito ou débito. Confira a tabela dos possíveis códigos de transação.	—
`transaction.descriptor`	`string`	Obrigatório*. Descrição do ajuste financeiro realizado. O valor inserido neste campo será retornado no campo `transactionDescription` do evento TRANSACTION_CREATED.	Máximo de 256 caracteres. Este campo não aceita caracteres especiais.
`transaction.metadata`	`object`	Dados adicionais que podem ser informados na operação.	Máximo de 256 caracteres.

{ 
  "client": { 
    "contractNumber": "ACESSO123456", 
  }, 
  "transaction": { 
    "amount": {
      "value": 78458.7,
      "currency": "BRL",
    },
    "transactionType": "090907", 
    "descriptor": "string",
    "metadata": { 
        "parametro1": "info1", 
        "parametro2": "info2", 
        "parametro3": "info3" 
    } 
  } 
}

Códigos dos tipos de transação

Código	Descrição
REFINANCE_CHARGES	Encargos de refinanciamento
INTEREST_ON_ARREST	Juros de mora
TRAFFIC_TICKET	Multa
PURCHASE_BY_SIGHT	Compra à vista
INSTALLMENT_WITHOUT_INTEREST	Parcela sem juros
DEBIT_ADJUSTMENT	Ajuste a débito
INSTALLMENTS_WITHOUT_INTEREST	Parcelado sem juros
INSTALLED_WITH_INTEREST	Parcelado com juros
PAYMENT	Pagamento
CREDIT_ADJUSTMENT	Ajuste a crédito
PARTIAL_CANCELLATION_OF_PURCHASE	Cancelamento parcial de compra
WITHDRAW	Saque
INTERNATIONAL_PURCHASE	Compra internacional
INTERNATIONAL_IOF	IOF internacional
IOF	Imposto sobre Operações Financeiras
IOF_WITHDRAWAL	IOF sobre o saque
WITHDRAWAL_CHARGES	Encargos de saque
ANNUITY	Anuidade
WITHDRAWAL_RATE	Tarifa de saque
RATE_CARD_ISSUANCE	Tarifa de emissão de cartão
REFINANCE_INSTALLMENT	Parcela de refinanciamento
CANC_CREDIT_INSTALLMENTS	Cancelamento de crédito parcelamento
PREPAID_CHARGE	Carga de pré-pago
MEMBERSHIP_PAYMENT	Pagamento de adesão
PURCHASE_CANCELLATION	Cancelamento de compra
CANC_INSTALLMENT_WITHOUT_INTEREST	Cancelamento de parcela sem juros
ANNUAL_REVERSAL	Estorno da anuidade
CREDIT_BY_INSTALLMENT	Crédito por parcelamento
REFINANCE_CONTRACT	Contrato de refinanciamento
CANC_PARC_DE_REF	Cancelamento de parcela de refinanciamento
EXCHANGE_DIF_DEBIT	Débito de DIF cambial
DIF_EXCHANGE_CREDIT	Crédito de DIF cambial
REVERSAL_REFINING_CHARGES	Estorno de encargos de refinanciamento
REVERSAL_INTEREST	Estorno de juros de mora
FINE_REVERSAL	Estorno de multa
REVERSAL_IOF	Estorno de IOF
CANCELLATION_AGREEMENT_REFINANC	Cancelamento do contrato de refinanciamento
CREDIT_BY_AGREEMENT	Crédito por acordo
INSTALLMENT_OF_AGREEMENT	Parcela de acordo
AGREEMENT_CONTRACT	Contrato de acordo
CANCELLATION_OF_INSTALLMENT_AGREEMENT	Cancelamento de parcela de acordo
CANC_CREDIT_AGREEMENT	Cancelamento de crédito de acordo
CANCELLATION_CONTRACT_AGREEMENT	Cancelamento de contrato de acordo
CREDIT_BY_INSTALLMENT_CP	Crédito por parcelamento compulsório
CP_REFINANCING_INSTALLMENT	Parcelamento de refinanciamento compulsório
CP_REFINANCE_CONTRACT	Contrato de refinanciamento compulsório
CANC_PARC_DE_REF_CP	Cancelamento do parcelamento de refinanciamento compulsório
CANC_CREDIT_INSTALLMENT_CP	Cancelamento de crédito do parcelamento compulsório
CANCELLATION_CONTRACT_REF_CP	Cancelamento do contrato de refinanciamento compulsório
DEBIT_PAYMENT	Pagamento com débito
CREDIT_VOUCHER	Voucher de crédito
CANC_INSTALLMENTS_WITHOUT_INTEREST	Cancelamento de parcelas sem juros
CANC_IN_INSTALLMENTS_WITH_INTEREST	Cancelamento de parcelado com juros
CANC_INSTALLMENT_WITH_INTEREST	Cancelamento de parcelamento com juros
CANC_INTERNATIONAL_PURCHASE	Cancelamento de compra internacional
CANC_IOF_INTERNATIONAL	Cancelamento de IOF internacional
REVERSAL_INTERNATIONAL_WITHDRAWAL	Estorno de saque internacional
REVERSAL_DEBIT_PAYMENT	Estorno de pagamento com débito
REVERSED_WITHDRAWAL	Estorno de saque
REVERSAL_RATE_WITHOUT_WITHDRAWAL	Estorno de tarifa de saque internacional
INTERNATIONAL_WITHDRAWAL	Saque internacional
FLAG_PAYMENT	Pagamento da bandeira
TED_CASH_OUT	TED cash-out
TEF_CASH_OUT	TEF cash-out
TED_CASH_IN	TED cash-in
DEBIT_REVERSAL	Reversão de débito
REVERSAL_PAYMENT	Estorno de pagamento de adesão
REVERSED_WITHDRAWAL_CHARGES	Estorno de encargos de saque
PRE_PAID_RECHARGE_RATE	Tarifa de recarga de pré-pago
PREPAID_RECHARGE_PERCENTAGE	Percentual de recarga de pré-pago
MDR	Merchant Discount Rate ou taxa de desconto do comerciante
REVERSAL_RATE_WITHDRAWAL	Estorno de tarifa de saque
REVERSAL_IOF_WITHDRAWAL	Estorno de IOF de saque

Resposta (Response)

O status code 201 indicará que a operação de ajuste foi criada com sucesso.

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

Nome	Tipo	Descrição	Número máximo de caracteres
`forceOperationId`	`string`	Identificador único do ajuste financeiro. Guarde-o, pois ele deverá ser enviado no path do endpoint de consulta e de cancelamento do ajuste realizado.	32

{ 
  "forceOperationId": "ec35f747-0f07-17dd-81ec-4f0a21cf769d"
}

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

Erros

Este endpoint não retorna erros específicos. Porém, ele poderá retornar alguns erros comuns entre todos os endpoints.

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. O evento é:

Nome do evento	Descrição
TRANSACTION_CREATED	Uma transação foi criada.