Faturamentos

Com a API Faturamento é possível visualizar o saldo detalhado da fatura, consultar e parcelar faturas, simular e antecipar parcelamentos, e aderir ou cancelar o recebimento de fatura digital ou via SMS. A API faz cobranças em contas ativas, extratadas ou com status creliq, independente do tipo de transação (on-us e off-us).

Figura 1. Diagrama do funcionamento da API Faturamentos

Contas ativas:
Contas que possuíram vendas, lançamentos de ajustes (exceto crédito de pagamento e crédito acumulado), pagamentos e pagamentos de acordos, e lançamentos de rolagem.

Contas com status creliq:
Contas inadimplentes que possuíram pagamentos de acordo.

Contas extratadas:
Faturas geradas, com lançamentos de ajustes (exceto crédito de pagamento e crédito acumulado), com lançamento de renegociação, com lançamento de rolagem, com valor total superior a zero reais. Também são contas com emissão de carnê, contas canceladas que tiveram lançamentos de vendas não faturados e contas com lançamento de ajuste não faturados.

Transações on-us e off-us:
Transações com cartões private label, chamadas on-us, e transações com cartões bandeirados, chamadas off-us.

Autenticação e segurança

A API Portadores utiliza OAuth 2 como protocolo de segurança junto de um Json Web Token (JWT). Para saber mais detalhes, confira a documentação de autenticação.

Endpoints

Todos os endpoints da API Faturamentos utilizam URL base /api/v1/faturamentos/.

Ciclos de fatura

Consulta de fatura

Faturas digitais

Parcelamentos de fatura

Ciclos de fatura

Endpoints para visualização e alteração dos ciclos de fatura de um portador através do seu identificador.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/faturamentos/ciclos`	Visualiza ciclos de fatura
`PUT`	`/api/v1/faturamentos/ciclos`	Altera ciclos de fatura

Casos de uso

Abaixo, alguns casos de uso da API Faturamentos para o seu negócio.

Buscando parcelamentos pendentes

Utilize o endpoint para busca de parcelamentos pendentes para visualizar os parcelamentos que ainda não foram ativados para um portador.

Exemplo de response body utilizando o idPortador:

{
  "parcelamentos": [
    {
      "quantidadeParcelas": 3,
      "status": "P",
      "idFatura": 58613135,
      "processamento": "MANUAL",
      "valorEntrada": 102.43,
      "valorParcela": 102.43,
      "valorTotal": 308.87,
      "valorFinanciado": 278.08,
      "taxaJuros": 10.9,
      "valorJuros": 29.21,
      "taxaIof": 0.0111,
      "taxaIofAdicional": 0.38,
      "valorIof": 1.58,
      "cet": 273.75,
      "valorDesconto": 1,
      "dataSimulacao": "2023-03-21T01:44:37",
      "dataAtivacao": "2023-03-21T01:44:37",
      "nomeUsuario": "SISTEMA",
      "idPagamentoAtivacao": 1234,
      "idLancamentoAtivacao": 1234,
      "devedorTotal": "S",
      "valorJurosDevedor": 13.98,
      "dataRecomendavelAtivacao": "2023-04-19T19:32:54.295+0000",
      "parcelas": [
        {
          "posicao": 1,
          "valor": 102.43,
          "principal": 102.43,
          "juros": 0,
          "iof": 0,
          "dataFaturamento": "2023-04-19T19:32:54.295+0000"
        },
        {
          "posicao": 2,
          "valor": 102.43,
          "principal": 83.28,
          "juros": 19.15,
          "iof": 0.6,
          "dataFaturamento": "2023-03-21T00:00:00.000+0000"
        },
        {
          "posicao": 3,
          "valor": 102.43,
          "principal": 92.37,
          "juros": 10.06,
          "iof": 0.98,
          "dataFaturamento": "2023-04-21T00:00:00.000+0000"
        }
      ]
    }
  ]
}

Consultando ciclos de vencimento

Utilize o endpoint para consulta de ciclos de vencimento para visualizar os ciclos de vencimento da(s) fatura(s) de um portador:

O response body do endpoint com a lista de informações da(s) fatura(s):

[
 {
   "id": 1,
   "diaCorte": 2,
   "diaVencimento": 17,
   "descricao": "VENCIMENTO 17",
   "ativo": "S",
   "corteUltimoDiaMes": "N",
   "diasCarencia": 0,
   "descricaoContaBancariaCicloAtual": "BANCO CNAB NOVO",
   "descricaoContaBancariaProximoCiclo": "BANCO CNAB NOVO"
 },
 {
   "id": 2,
   "diaCorte": 27,
   "diaVencimento": 16,
   "descricao": "VENCIMENTO 16",
   "ativo": "S",
   "corteUltimoDiaMes": "N",
   "diasCarencia": 0,
   "descricaoContaBancariaCicloAtual": "BANCO CNAB NOVO",
   "descricaoContaBancariaProximoCiclo": "BANCO CNAB NOVO"
 },
 {
   "id": 3,
   "diaCorte": 12,
   "diaVencimento": 22,
   "descricao": "VENCIMENTO 22",
   "ativo": "N",
   "corteUltimoDiaMes": "N",
   "diasCarencia": 0,
   "descricaoContaBancariaCicloAtual": "BANCO NOVO",
   "descricaoContaBancariaProximoCiclo": "BANCO NOVO"
 },
 {
   "id": 1,
   "diaCorte": 20,
   "diaVencimento": 1,
   "descricao": "VENCIMENTO 01",
   "ativo": "S",
   "corteUltimoDiaMes": "N",
   "diasCarencia": 0,
   "descricaoContaBancariaCicloAtual": "BANCO NOVO",
   "descricaoContaBancariaProximoCiclo": "BANCO NOVO"
 },
 {
   "id": 3,
   "diaCorte": 18,
   "diaVencimento": 3,
   "descricao": "VENCIMENTO 3",
   "ativo": "N",
   "corteUltimoDiaMes": "N",
   "diasCarencia": 0,
   "descricaoContaBancariaCicloAtual": "BANCO NOVO",
   "descricaoContaBancariaProximoCiclo": "BANCO NOVO"
 },
 {
   "id": 5,
   "diaCorte": 20,
   "diaVencimento": 5,
   "descricao": "VENCIMENTO 05",
   "ativo": "S",
   "corteUltimoDiaMes": "N",
   "diasCarencia": 0,
   "descricaoContaBancariaCicloAtual": "BANCO NOVO",
   "descricaoContaBancariaProximoCiclo": "BANCO NOVO"
 },
 {
   "id": 6,
   "diaCorte": 26,
   "diaVencimento": 6,
   "descricao": "VENCIMENTO 6",
   "ativo": "N",
   "corteUltimoDiaMes": "N",
   "diasCarencia": 0,
   "descricaoContaBancariaCicloAtual": "BANCO NOVO",
   "descricaoContaBancariaProximoCiclo": "BANCO NOVO"
 }
]

Consultando a última fatura fechada

Utilize o endpoint para consulta da última fatura fechada para visualizar as informações de lançamento na(s) última(s) fatura(s) fechada(s) de um portador:

O response body com as informações consultadas através do idPortador:

{
 "dataVencimento": "2024-03-01T00:00:00.000-0300",
 "valorMinimo": 101.11,
 "linhaDigitavel": "62010144964200000481610339989469574001010698035",
 "codigoDeBarras": "46574001010680356201010339496420000048161989",
 "possuiPagamentoMinimo": true,
 "hashFatura": "b60bd300c97cf339d87af8937516228443f86b68d007b2418ef3ccf80802ce53",
 "lancamentos": [
   {
     "dataLancamento": "2024-02-01T01:00:00.000-0200",
     "descricaoLancamento": "TOTAL DA FATURA ANTERIOR",
     "valor": 537.29,
     "tipo": "FATURA_ANTERIOR",
     "dataTransacao": "2024-01-16T01:00:00.000-0200",
     "tipoProprietario": "TITULAR"
   },
   {
     "dataLancamento": "2024-02-02T20:49:13.000-0200",
     "descricaoLancamento": "PAGAMENTO EFETIVADO",
     "valor": -525.29,
     "tipo": "PAGAMENTO",
     "dataTransacao": "2024-02-02T20:49:13.000-0200",
     "tipoProprietario": "TITULAR"
   },
   {
     "dataLancamento": "2024-02-04T01:00:00.000-0200",
     "descricaoLancamento": "REDE 1 / 2 - Venda",
     "valor": 69.99,
     "tipo": "ELO",
     "valorMoedaOrigem": 139.99,
     "dataTransacao": "2024-02-04T01:00:00.000-0200",
     "valorDolar": 0,
     "cotacaoDolar": 0,
     "tipoProprietario": "TITULAR",
     "codigoISO": 5977,
     "numeroCartaoTruncado": "123456XXXXXX1234",
     "nsu": "123456789000",
     "idVenda": 1234567,
     "idVendaBandeira": 1234567
   },
   {
     "dataLancamento": "2024-02-04T01:00:00.000-0200",
     "descricaoLancamento": "Restaurante 1 / 1 - Venda",
     "valor": 19.75,
     "tipo": "ELO",
     "valorMoedaOrigem": 19.75,
     "dataTransacao": "2024-02-04T01:00:00.000-0200",
     "valorDolar": 0,
     "cotacaoDolar": 0,
     "tipoProprietario": "TITULAR",
     "codigoISO": 5812,
     "numeroCartaoTruncado": "123456XXXXXX1234",
     "nsu": "071641302913",
     "idVendaBandeira": 9134819
   },
   {
     "dataLancamento": "2024-02-06T01:00:00.000-0200",
     "descricaoLancamento": "REDE 1 / 1 - Venda",
     "valor": 21,
     "tipo": "ELO",
     "valorMoedaOrigem": 21,
     "dataTransacao": "2024-02-06T01:00:00.000-0200",
     "codigoISO": 5812,
     "numeroCartaoTruncado": "123456XXXXXX1234",
     "nsu": "009886646066",
     "idVendaBandeira": 9160712
   },
   {
     "dataLancamento": "2024-02-09T01:00:00.000-0200",
     "descricaoLancamento": "LANCHONETE 1 / 1 - Venda",
     "valor": 28.8,
     "tipo": "ELO",
     "valorMoedaOrigem": 28.8,
     "dataTransacao": "2024-02-09T01:00:00.000-0200",
     "codigoISO": 5814,
     "numeroCartaoTruncado": "123456XXXXXX1234",
     "nsu": "207987793446",
     "idVendaBandeira": 9219757
   },
   {
     "dataLancamento": "2024-02-09T18:28:06.000-0200",
     "descricaoLancamento": "Taxa por uso de overlimit",
     "valor": 21.1,
     "tipo": "AJUSTE",
     "dataTransacao": "2024-02-09T18:28:06.000-0200",
     "tipoProprietario": "TITULAR",
     "tipoLancamentoAjuste": "TAXA POR USO DE OVERLIMIT"
   },
   {
     "dataLancamento": "2024-02-10T01:00:00.000-0200",
     "descricaoLancamento": "REDE 1 / 1 - Venda",
     "valor": 10,
     "tipo": "ELO",
     "valorMoedaOrigem": 10,
     "dataTransacao": "2024-02-10T01:00:00.000-0200",
     "codigoISO": 5995,
     "numeroCartaoTruncado": "123456XXXXXX1234",
     "nsu": "208011346344",
     "idVendaBandeira": 9232794
   },
   {
     "dataLancamento": "2024-02-10T01:00:00.000-0200",
     "descricaoLancamento": "SUPERMERCADO 1 / 1 - Venda",
     "valor": 250,
     "tipo": "ELO",
     "valorMoedaOrigem": 250,
     "dataTransacao": "2024-02-10T01:00:00.000-0200",
     "codigoISO": 5411,
     "numeroCartaoTruncado": "123456XXXXXX1234",
     "nsu": "000366939792",
     "idVendaBandeira": 9233625
   },
 ]
}

Consultando faturas entre um período

Utilize o endpoint para consulta de faturas num determinado período de tempo para visualizar as informações e lançamentos das faturas:

Exemplo de request body:

{
  "idPortador": 2001
  "dataFinal": "2024-01-01"
  "dataInicial": "2024-01-01"
}

O response body do endpoint com as informações das faturas:

{
 [
    {
      "idFatura": "1245678",
      "dataVencimento": "2024-01-15T03:00:00.000+0000",
      "valorTotal": 1541.91,
      "valorMinimo": 242.96,
      "valorPagamentosEfetuados": 1541.21,
      "devedor": 0,
      "status": "PASSADA",
      "faturaDisponivel": true,
      "statusPagamento": "INTEGRAL"
    }
  ],
  "limitePrincipal": 2332,
  "limiteParcelado": 0,
  "saldoDisponivel": 992.88,
  "saldoReservado": 0,
  "saldoDisponivelParcelado": 0,
  "devedorTotal": 1339.12,
  "devedorParcelado": 0
}

Visualizando detalhes de uma fatura

Utilize o endpoint para consulta detalhada de fatura para visualizar, de forma detalhada, as informações e lançamentos de uma determinada fatura fechada:

Exemplo de request body utilizando o idPortador e idFatura:

O response body com os detalhes da fatura:

{
 "idFatura": "[FUTURA]",
 "nomeCartao": "JOSÉ DA SILVA",
 "numeroCartaoTruncado": "6087XXXXXXXX0374",
 "diaDeCorte": 2,
 "status": "FUTURA",
 "dataVencimento": "2023-03-17T03:00:00.000+0000",
 "lancamentos": {
   "dataLancamento": "2023-02-21T01:00:00.000-0200",
   "descricaoLancamento": "Estorno Juros Parcelamento Fatura na antecipação.",
   "valor": -2.89,
   "tipo": "AJUSTE",
   "dataTransacao": "2023-02-21T11:58:49.000-0200",
   "tipoProprietario": "TITULAR",
   "numeroCartaoTruncado": "6087XXXXXXXX0374",
   "idVenda": 18849588
 },
 "valorTotalFaturaAnterior": 0,
 "valorPagoFaturaAnterior": 0,
 "valorLancamentosFaturaAtual": 921.18,
 "valorTotalFaturaAtual": 154.69,
 "valorPagamentoMinimoFaturaAtual": 48.44,
 "limiteRotativo": 3000,
 "limiteParcelado": 0,
 "devedorRotativo": 1043.65,
 "devedorParcelado": 0,
 "saldoDisponivelRotativo": 1956.35,
 "saldoReservado": 0,
 "saldoDisponivelParcelado": 0,
 "totalPrincipalFatura": 125,
 "totalTaxasFatura": 29.69,
 "totalEncargosFatura": 0,
 "melhorDiaCompra": 3,
 "tarifaJurosRotativo": 9,
 "itemArquivoCobranca": {
   "moeda": "R$",
   "localPagamento": "Consulte o horário limite de compensação com sua instituição financeira.",
   "nossoNumero": "33185321008607058",
   "nossoNumeroDV": "5",
   "dataVencimento": "2023-03-17T00:00:00.000-03:00",
   "dataEmissao": "2023-03-02T00:00:00.000-03:00",
   "dataProcessamento": "2023-03-02T00:00:00.000-03:00",
   "valorTitulo": 154.69,
   "mensagem": "Sr. Caixa preencher o valor a ser pago no campo Valor Cobrado, respeitando o pagamento mínimo. O pagamento pode ser efetuado em  qualquer loja do Tenda Atacado, através de rede bancaria, caixas eletrônicos, internet ou casas lotéricas, até 28 dias após o vencimento.  Encargos pelo atraso serão incluídos na próxima fatura.",
   "linhaDigitavel": "00190000090331853210208607058172200000000000000",
   "codigoBarras": "00192000000000000000000003318532100860705817",
   "especieTitulo": "31",
   "aceite": "N",
   "numeroDocumento": "string",
   "beneficiarioResponse": {
     "nome": "VOXCRED ADMINISTRADORA DE CARTOES",
     "enderecoResponse": {
       "logradouro": "RUA DOS ALFENEIROS",
       "complemento": "BLOCO B",
       "numero": "12",
       "bairro": "CENTRO",
       "cep": "58000000",
       "uf": "PB",
       "cidade": "JOAO PESSOA"
     }
   },
   "sacadoResponse": {
     "nome": "JOSÉ DA SILVA",
     "cpfSacado": "07914842036",
     "enderecoResponse": {
       "logradouro": "RUA ESTUDANTE OLIVEIROS FERNANDE FILHO",
       "complemento": "BL B APTO 666",
       "numero": "56",
       "bairro": "BANCARIOS",
       "cep": "58000000",
       "uf": "PB",
       "cidade": "JOAO PESSOA"
     }
   }
 },
 "encargosMaximos": 15.36,
 "hashFatura": "662ab306bdc888394ea3ea71e6acead29fff8d7040bb506ebc9a03976ff3abbb"
}