Consulta de fatura por ID

Este endpoint permite que o cliente do parceiro Bankly consulte os dados de uma fatura específica, independentemente do seu status, por meio do seu identificador único (id).

Pré-requisitos

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

Tenha sido aprovado na análise de crédito;
Tenha pelo menos um cartão de crédito emitido;
Tenha pelo menos uma fatura emitida.

Requisição

Requisição HTTP

GET 'https://api-mtls.sandbox.bankly.com.br/cards/invoices/{statementId}'

--request GET \ 
--url 'https://api-mtls.sandbox.bankly.com.br/cards/invoices/{statementId}' \ 
--header 'Authorization:  Bearer {Token}' \ 
--header 'accept: application/json' \ 
--header 'api-version: 2.0'

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.read`	Concede acesso para realizar consultas referentes à gestão de faturas.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. Versão da API, que, neste caso, é 2.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

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

Nome	Tipo	Descrição
`statementId`	`path`	Obrigatório. Identificador único da fatura, retornado na consulta de todas as faturas.

Corpo da requisição (Body)

Não é necessário enviar campos no body desta requisição.

Resposta (Response)

O status code 200 indicará que a solicitação foi aceita com sucesso.

O retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Número máximo de caracteres
`programId`	`integer`	Identificador único do porgrama.	—
`companyKey`	`string`	Chave que identifica o parceiro dentro do Bankly.	—
`statementId`	`integer`	Identificador único da fatura.	—
`month`	`integer`	Mês de vencimento da fatura.	—
`year`	`integer`	Ano de vencimento da fatura.	—
`cycle`	`integer`	Indicador do ciclo da fatura (por contrato de crédito).	—
`cycleCloseDate`	`string`	Data de fechamento da fatura, no formato ISO 8601 - UTC.	25
`dueDateStart`	`string`	Data inicial do período da fatura, no formato ISO 8601 - UTC.	25
`dueDateEnd`	`string`	Data final do período da fatura, no formato ISO 8601 - UTC.	25
`dueDate`	`string`	Data de vencimento da fatura, no formato ISO 8601 - UTC.	25
`amountMinimal`	`number`	Valor mínimo a ser pago da fatura. Somente é calculado após o fechamento da fatura.	—
`balance`	`number`	Valor total da fatura.	—
`cycleType`	`string`	Situação da fatura, a qual pode ser “Open” (fatura aberta), “Future” (fatura futura), “Closed” (fatura fechada) e “DueDate” (fatura atrasada).	—
`documentNumber`	`string`	Número do documento de CPF ou CNPJ do titular do cartão.	50
`paymentStatus`	`string`	Situação do pagamento da fatura, a qual pode ser “Pending” (pendente), “Paid” (paga) e “PartialPaid” (parcialmente paga).	—
`canBePaid`	`boolean`	Indica se a fatura pode ser paga (true) ou não (false).	—
`previousBalance`	`object`	Objeto que contém informações referentes ao valor total da fatura anterior.	—
`previousBalance.value`	`number`	Valor total da fatura anterior.	decimal(18,2)
`previousBalance.currency`	`string`	Código da moeda com base na ISO-4217.	3
`residualBalance`	`object`	Objeto que contém informações sobre o saldo residual da fatura.	—
`residualBalance.value`	`number`	Saldo residual da fatura.	decimal(18,2)
`residualBalance.currency`	`string`	Código da moeda com base na ISO-4217.	3
`statementItens[]`	`array of objects`	Lista de objetos contendo informações sobre os itens da fatura.	—
`statementItens[].statementNumber`	`integer`	Número da parcela.	—
`statementItens[].statementTotal`	`integer`	Total de parcelas.	—
`statementItens[].isCredit`	`boolean`	Indica se é uma operação de crédito (true) ou débito (false).	—
`statementItens[].transactionDate`	`string`	Data em que ocorreu a transação, no formato ISO 8601 - UTC.	25
`statementItens[].createdAt`	`string`	Data em que o item foi adicionado na fatura, no formato ISO 8601 - UTC.	25
`statementItens[].transactionType`	`string`	Tipo da transação.	—
`statementItens[].transaction`	`object`	Objeto que contém informações sobre a transação do item de fatura. Os subcampos deste objeto somente serão retornados caso o item seja de uma transação bandeirada (compra, estorno ou outra ação realizada com o cartão). Caso se trate de encargos, pagamentos, anuidade etc., ele não será preenchido.	—
`statementItens[].transaction.merchant`	`string`	Nome do estabelecimento/comerciante que aceitou a transação.	—
`statementItens[].transaction.mcc`	`string`	Código MCC da transação.	—
`statementItens[].transaction.entrymode`	`string`	Código do modo de entrada utilizado na transação.	—
`statementItens[].transaction.mcg`	`string`	Descrição do tipo do MCC.	—
`statementItens[].transaction.card`	`object`	Objeto que contém informações sobre o cartão utilizado na transação.	—
`statementItens[].transaction.card.proxy`	`string`	Identificador do cartão utilizado na transação.	30
`statementItens[].transaction.card.lastFourDigits`	`string`	Quatro últimos dígitos do cartão.	—
`statementItens[].transaction.card.alias`	`string`	Apelido dado ao cartão.	—
`statementItens[].transaction.card.cardType`	`string`	Tipo do cartão, o qual pode ser “Physical” (físico) ou “Virtual” (virtual).	—
`statementItens[].amounts[]`	`array of objects`	Lista de objetos contendo os valores de cada item de fatura.	—
`statementItens[].amounts[].amountType`	`string`	Indicador do item de fatura, o qual pode ser “NotMapper” (não informado), “Local” (valor da moeda local), “Exchange” (valor em dólar da transação, no caso de compra internacional) ou “Billet” (valor cobrado, em real, ao cliente).	—
`statementItens[].amounts[].value`	`number`	Valor do item da fatura.	decimal(18,2)
`statementItens[].amounts[].currency`	`string`	Código da moeda com base na ISO-4217. Exemplo: BRL.	3
`statementItens[].fees[]`	`array of objects`	Lista de objetos contendo informações sobre as taxas cobradas em saques e transações internacionais.	—
`statementItens[].fees[].feeType`	`string`	Tipo da taxa, o qual pode ser: “NotMapper” (não informado), “IOF” (Imposto de Operações Financeiras fixo da transação), “Markup” (taxa de conversão para proteção de mudanças de câmbio), “DailyIOF” (IOF diário em cima da fatura) e “Interest” (juros de transação cobrado pelo emissor).	—
`statementItens[].fees[].value`	`number`	Valor da taxa.	decimal(18,2)
`statementItens[].statementItemId`	`integer`	Indicador do item da fatura.	—
`statementItens[].transactionDescription`	`string`	Descritivo do item da fatura.	—
`statementItens[].isAnticipation`	`boolean`	Indica se o item da fatura foi antecipado (true) ou não (false).	—
`transactionsSummary`	`object`	Objeto que contém os valores totalizadores das transações da fatura.	—
`transactionsSummary.nationalPurchasing`	`object`	Objeto que contém os valores totalizadores das transações nacionais da fatura.	—
`transactionsSummary.nationalPurchasing.value`	`number`	Valor total das transações nacionais da fatura.	decimal(18,2)
`transactionsSummary. nationalPurchasing.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.internationalPurchasing`	`object`	Objeto que contém os valores totalizadores das transações internacionais da fatura.	—
`transactionsSummary.internationalPurchasing[].value`	`number`	Valor total das transações internacionais da fatura.	decimal(18,2)
`transactionsSummary.internationalPurchasing[].currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.fees`	`object`	Objeto que contém os valores totalizadores dos encargos.	—
`transactionsSummary.fees.value`	`number`	Valor total dos encargos.	decimal(18,2)
`transactionsSummary.fees.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.debitAdjustments`	`object`	Objeto que contém os valores totalizadores dos ajustes a débito.	—
`transactionsSummary.debitAdjustments.valu`	`number`	Valor total dos ajustes a débito.	decimal(18,2)
`transactionsSummary.debitAdjustments.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.creditAdjustments`	`object`	Objeto que contém os valores totalizadores dos ajustes a crédito.	—
`transactionsSummary.creditAdjustments.value`	`number`	Valor total dos ajustes a crédito.	decimal(18,2)
`transactionsSummary.creditAdjustments.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.payments`	`object`	Objeto que contém os valores totalizadores de pagamentos.	—
`transactionsSummary.payments.value`	`number`	Valor total das transações de pagamentos.	decimal(18,2)
`transactionsSummary.payments.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.insurance`	`object`	Objeto que contém os valores totalizadores de seguro.	—
`transactionsSummary.insurance.value`	`number`	Valor total de seguro.	decimal(18,2)
`transactionsSummary.insurance.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.annuity`	`object`	Objeto que contém os valores totalizadores de anuidade.	—
`transactionsSummary.annuity.value`	`number`	Valor total de anuidade.	decimal(18,2)
`transactionsSummary.annuity.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.withdraw`	`object`	Objeto que contém os valores totalizadores de saque.	—
`transactionsSummary.withdraw.value`	`number`	Valor total de saque.	decimal(18,2)
`transactionsSummary.withdraw.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.internationalWithdraw`	`object`	Objeto que contém os valores totalizadores de saques internacionais.	—
`transactionsSummary.internationalWithdraw.value`	`number`	Valor total de saque.	decimal(18,2)
`transactionsSummary.internationalWithdraw.currency`	`string`	Código da moeda com base na ISO-4217.	3
`transactionsSummary.installment`	`object`	Objeto que contém os valores totalizadores das parcelas da fatura atual.	—
`transactionsSummary.installment.value`	`number`	Valor total das parcelas da fatura atual.	decimal(18,2)
`transactionsSummary.installment.currency`	`string`	Código da moeda com base na ISO-4217.	3

{
 "programId": 0,
 "companyKey": "string",
 "statementId": 0,
 "month": 0,
 "year": 0,
 "cycle": 0,
 "cycleCloseDate": "2024-09-10T20:23:29.257Z",
 "dueDateStart": "2024-09-10T20:23:29.257Z",
 "dueDateEnd": "2024-09-10T20:23:29.257Z",
 "dueDate": "2024-09-10T20:23:29.257Z",
 "amountMinimal": 0,
 "balance": 0,
 "cycleType": 1,
 "documentNumber": "string",
 "paymentStatus": 1,
 "canBePaid": true,
 "previousBalance": {
   "value": 0,
   "currency": "string"
 },
 "residualBalance": {
   "value": 0,
   "currency": "string"
 },
 "statementItens": [
   {
     "statementNumber": 0,
     "statementTotal": 0,
     "isCredit": true,
     "transactionDate": "2024-09-10T20:23:29.257Z",
     "createdAt": "2024-09-10T20:23:29.257Z",
     "transactionType": "string",
     "transaction": {
       "merchant": "string",
       "mcc": "string",
       "entrymode": "string",
       "mcg": "string",
       "card": {
         "proxy": "string",
         "lastFourDigits": "string",
         "alias": "string",
         "cardType": "string"
       }
     },
     "amounts": [
       {
         "value": 0,
         "currency": "string"
       }
     ],
     "fees": [
       {
         "feeType": 0,
         "value": 0
       }
     ],
     "statementItemId": 0,
     "transactionDescription": "string",
     "isAnticipation": false
   }
 ],
 "transactionsSummary": {
   "nationalPurchasing": {
     "value": 0,
     "currency": "string"
   },
   "internationalPurchasing": [
     {
       "value": 0,
       "currency": "string"
     }
   ],
   "fees": {
     "value": 0,
     "currency": "string"
   },
   "debtAdjustments": {
     "value": 0,
     "currency": "string"
   },
   "creditAdjustments": {
     "value": 0,
     "currency": "string"
   },
   "payments": {
     "value": 0,
     "currency": "string"
   },
   "insurance": {
     "value": 0,
     "currency": "string"
   },
   "annuity": {
     "value": 0,
     "currency": "string"
   },
   "withdraw": {
     "value": 0,
     "currency": "string"
   },
   "internationalWithdraw": {
     "value": 0,
     "currency": "string"
   },
   "installment": {
     "value": 0,
     "currency": "string"
   }
 }
}

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 parcelado com 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

Código do modo de entrada (`entryMode`)

Código	Descrição
00	Modo de entrada do PAN desconhecido.
01	Entrada do PAN manual.
02	Entrada automática do PAN via leitura da tarja magnética. Para transações Plus, este código também significa que o conteúdo exato da faixa 2 está incluído e a verificação de CVV é possível.
03	Entrada automática via leitor de código de barras.
04	Entrada automática de PAN via leitor óptico de caracteres (OCR).
05	Entrada automática de PAN via chip.
06	Contactless obsoleto.
07	Entrada automática de PAN via M/Chip sem contato.
08	Contactless MChip obsoleto.
09	Entrada de PAN/Token via comércio eletrônico contendo criptograma DSRP em DE 55 (Integrated Circuit Card [ICC] System-Related Data).
10	Credencial em arquivo.
79	Um terminal híbrido com conexão online com o adquirente falhou no envio de uma transação de chip fallback (em que DE 22, subcampo 1 = 80) ao emissor.
80	O cartão com chip não foi capaz de processar/leitura da tarja magnética padrão.
81	Entrada de PAN/Token via comércio eletrônico com opcional Identity Check-AAV ou criptograma DSRP em UCAF.
82	Entrada automática de PAN via servidor (sistema emissor, adquirente ou fornecedor terceirizado).
90	A tarja magnética lê e extrai o conteúdo da Faixa 1 ou Faixa 2 incluída (a verificação CVV é possível).
91	Entrada automática do número da conta via tarja magnética sem contato.
95	Apenas Visa – Chip com CVV não confiável.

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

Erros

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

Status Code	Código	Mensagem	Descrição
404	INVOICE_DATA_NOT_FOUND	Invoice Data not found!	Fatura não encontrada.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.

Pré-requisitos

Requisição

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

Resposta (Response)

Tipos de transação

Código do modo de entrada (entryMode)

👍Dica

Erros

Eventos

Código do modo de entrada (`entryMode`)

👍
Dica