Consultar lista de cobranças com vencimento

get https://api.pix.voluti.com.br/cobv

Use este endpoint para consultar cobranças com vencimento através de parâmetros como início, fim, cpf, cnpj e status.

Query Params

inicio

date-time

required

Filtra os registros cuja data de criação seja maior ou igual que a data de início. Respeita RFC 3339.

fim

date-time

required

Filtra os registros cuja data de criação seja menor ou igual que a data de fim. Respeita RFC 3339.

cpf

string

Filtro pelo CPF do devedor. Não pode ser utilizado ao mesmo tempo que o CNPJ.

cnpj

string

Filtro pelo CNPJ do devedor. Não pode ser utilizado ao mesmo tempo que o CPF.

locationPresente

boolean

Filtra pela presença de uma localização associada.

status

string

Filtro pelo status da cobrança.

loteCobVId

int32

Id do lote de cobrança com vencimento.

paginacao.paginaAtual

int32

≥ 0

Defaults to 0

Página a ser retornada pela consulta. Se não for informada, o PSP assumirá que será 0.

paginacao.itensPorPagina

int32

1 to 1000

Defaults to 100

Quantidade máxima de registros retornados em cada página. Apenas a última página pode conter uma quantidade menor de registros.

Responses

Response body

object

parametros

object

required

[DEPRECIADO] Parâmetros utilizados para a realização de uma consulta de cobranças.

inicio

date-time

required

Data inicial utilizada na consulta. Respeita RFC 3339.

fim

date-time

required

Data de fim utilizada na consulta. Respeita RFC 3339.

cpf

string

Filtro pelo CPF do devedor. Não pode ser utilizado ao mesmo tempo que o CNPJ.

cnpj

string

Filtro pelo CNPJ do devedor. Não pode ser utilizado ao mesmo tempo que o CPF.

locationPresente

boolean

Filtra pela presença de uma localização associada.

status

string

Filtro pelo status das cobranças.

paginacao

object

required

cobs

array of objects

required

Lista de cobranças*

object

calendario

object

required

Os campos aninhados sob o identificador calendário organizam informações a respeito de controle de tempo da cobrança.

devedor

object

O objeto devedor organiza as informações sobre o devedor da cobrança.

loc

object

Identificador da localização do payload.

valor

object

required

Valores monetários.

chave

string

length ≤ 77

Formato da Chave Pix na qual a conta receberá o valor.

Conforme especificado na PACS.008. Os tipos de chave permitidos são:

Telefone
E-mail
CPF/CNPJ
O Endereço Virtual de Pagamento (EVP)

O formato detalhado das chaves está na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para Iniciação do Pix.
.

solicitacaoPagador

string

length ≤ 140

Permite que o pagador inclua um texto livre relacionado ao recebedor.

Preenchimento: O PSP do pagador insere esse texto no campo RemittanceInformation da pacs.008.

Limite de caracteres: Restrito a 140 caracteres.

infoAdicionais

array of objects

Apresentação das informações adicionais ao pagador:

Cada informação adicional contida nos campos nome e valor deve ser exibida ao pagador.

Informações adicionais

object

nome

string

required

length ≤ 50

Nome do pagador.

valor

string

required

length ≤ 200

Valor de cobrança.

txid

string

required

Identificador da transação (txid):

O campo txid determina o identificador da transação, sendo crucial para o processo de conciliação de pagamentos, pois determina a transação de forma única. Na pacs.008, é mencionado como TransactionIdentification <txId> ou idConciliacaoRecebedor.

Funcionalidade:

O txid é gerado pelo usuário recebedor e enviado ao PSP do pagador.
Após a confirmação do pagamento, é transmitido para o SPI via pacs.008 e também para o PSP do recebedor.
Ao detectar um pagamento com txid, o PSP do recebedor pode informar ao usuário recebedor sobre a liquidação específica desse pagamento.

Responsabilidades:

O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade.
Cada txid é único por CPF/CNPJ do usuário recebedor, com a validação dessa regra realizada pelo PSP recebedor na API Pix.

revisao

int32

required

Indica a revisão da cobrança, começando sempre em zero e aumentando em incrementos de 1.

Incremento: A revisão é incrementada sempre que um objeto da cobrança é alterado, exceto pelo campo loc.
Exceção: Se a única alteração em uma cobrança for no campo loc, a revisão não é incrementada, pois o loc não altera a cobrança em si.
Armazenamento: Não é necessário manter histórico das alterações do campo loc, mas é necessário para outros campos da cobrança.

recebedor

object

O objeto recebedor organiza as informações sobre o credor da cobrança.

status

string

required

Estado do registro da cobrança.

Os status:

ATIVA: Indica que o registro se refere a uma cobrança que foi gerada mas ainda não foi paga nem removida;
CONCLUIDA: Indica que o registro se refere a uma cobrança que já foi paga e, por conseguinte, não pode acolher outro pagamento;
REMOVIDO_PELO_USUARIO_RECEBEDOR: Indica que o usuário recebedor solicitou a remoção do registro da cobrança;
REMOVIDO_PELO_PSP: Indica que o PSP recebedor solicitou a remoção do registro da cobrança.

ATIVA CONCLUIDA REMOVIDA_PELO_USUARIO_RECEBEDOR REMOVIDA_PELO_PSP

pixCopiaECola

string

length ≤ 512

Este campo retorna o valor do Pix Copia e Cola correspondente à cobrança. Trata-se da sequência de caracteres que representa o BR Code.

pix

array of objects

Pix recebidos

object

endToEndId

string

required

length between 32 and 32

O identificador da transação ou End to End ID é utilizado para identificar um pagamento Pix realizado contemplando todo o mercado que transita na PACS002, PACS004 e PACS008.

PACS.002: Mensagem de status de pagamento. Utiliza o EndToEndIdentification para relacionar a resposta ao pagamento original.
PACS.004: Mensagem de devolução de pagamento. Garante que a devolução seja associada corretamente ao pagamento inicial.
PACS.008: Mensagem de crédito interbancário. Rastreia o pagamento da origem ao destino final.

txid

string

Identificador da transação (txid):

Funcionalidade:

O txid é gerado pelo usuário recebedor e enviado ao PSP do pagador.
Após a confirmação do pagamento, é transmitido para o SPI via pacs.008 e também para o PSP do recebedor.
Ao detectar um pagamento com txid, o PSP do recebedor pode informar ao usuário recebedor sobre a liquidação específica desse pagamento.

Responsabilidades:

O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade.
Cada txid é único por CPF/CNPJ do usuário recebedor, com a validação dessa regra realizada pelo PSP recebedor na API Pix.

valor

string

required

Valor do Pix.

componentesValor

object

O objetivo dessa estrutura é explicar os elementos de composição do valor do Pix, incluindo informações sobre as multas, juros, descontos e abatimentos quando o Pix for relativo a cobranças com vencimento.

Regras da estrutura:

O valor do Pix é igual a:
- (original.valor + saque.valor + troco.valor) + multa.valor + juros.valor – abatimento.valor – desconto.valor
  considerando-se apenas os campos que estiverem presentes para cada tipo de cobrança pago.
As estruturas saque e troco só serão retornadas quando o Pix for relativo a um Pix Saque ou Pix Troco, respectivamente, e
as demais estruturas (juros, multa, abatimento e desconto) só serão pertinentes aos Pix de pagamentos das cobranças com vencimento.
Não pode haver simultaneamente uma subsestrutura do tipo saque e outra do tipo troco;
Não há restrição na ordem das subestruturas.

Para o caso de um Pix Saque pode-se retornar original com valor=0.00 (zero) uma vez que a soma será respeitada, ou pode-se omitir a
subestrutura original. No caso de um Pix Troco ou de um pagamento de cobrança com vencimento a subsestrutura original vai sempre estar
presente.

Exemplos válidos:

Exemplo de preenchimentos válidos.

Pix para pagamento de cobrança imediata (sem saque ou troco).

...
"componentesValor": {
  "original": {
    "valor": "100.00"
  } 
}
...

Pix Saque.

...
"componentesValor": {
  "saque": {
    "valor": "100.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

Pix para pagamento de cobrança imediata com saque (pode vir original.valor=0.00).

...
"componentesValor": {
  "original": {
    "valor": "0.00"
  },
  "saque": {
    "valor": "100.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

Pix Troco.

...
"componentesValor": {
  "original": {
    "valor": "80.00"
  },
  "troco": {
    "valor": "20.00",
    "modalidadeAgente": "AGTEC",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

Pix para pagamento de cobrança imediata com troco (ordem não importa).

...
"componentesValor": {
  "troco": {
    "valor": "20.00",
    "modalidadeAgente": "AGTEC",
    "prestadorDeServicoDeSaque": "12345678"
  },
  "original": {
    "valor": "80.00"
  }
}
...

Pix para pagamento de cobrança com vencimento de R$100,00 considerando-se um atraso de 2 dias a uma multa de 3% e juros de 1% ao dia. O valor do Pix será R$105,00.
```
...
"componentesValor": {
  "original": {
    "valor": "100.00"
  },
  "multa": {
    "valor": "3.00"
  },
  "juros": {
    "valor": "2.00"
  }
}
...
```

Exemplos inválidos:

Exemplos, não exaustivos, de preenchimentos inválidos.

original.valor maior que 0.00 (zero) e saque juntos

...
"componentesValor": {
  "original": {
    "valor": "80.00"
  },
  "saque": {
    "valor": "20.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

dois elementos de saque

...
"componentesValor": [
  "saque": {
    "valor": "20.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  },
  "saque": {
    "valor": "10.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  } 
]
...

saque e troco simultaneamente

...
"componentesValor": {
  "original": {
    "valor": "60.00"
  },
  "saque": {
    "valor": "20.00",
    "modalidadeAgente": "AGPSS",
    "prestadorDeServicoDeSaque": "12345678"
  },
  "troco": {
    "valor": "20.00",
    "modalidadeAgente": "AGTEC",
    "prestadorDeServicoDeSaque": "12345678"
  } 
}
...

chave

string

length ≤ 77

Formato da Chave Pix.

O campo chave do recebedor é atribuído conforme especificado na PACS.008. Os tipos de chave permitidos são:

Telefone
E-mail
CPF/CNPJ
O Endereço Virtual de Pagamento (EVP)

O formato detalhado das chaves está na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para Iniciação do Pix.

horario

date-time

required

Horário em que o Pix foi processado no PSP.

infoPagador

string

length ≤ 140

Informação livre do pagador.

devolucoes

array of objects

Devoluções

object

string

required

Identificação gerada pelo cliente para representar uma devolução.

rtrId

string

required

length between 32 and 32

ReturnIdentification é utilizado para identificar de forma única uma transação de devolução na mensagem PACS.004. Ele assegura a correta associação entre a devolução e a transação original.

A utilização do ReturnIdentification garante a integridade e a rastreabilidade das devoluções no sistema de pagamentos.

valor

string

required

Valor da devolução.

natureza

string

Indica qual é a natureza da devolução. Uma devolução pode ser relacionada a um Pix comum (com códigos possíveis: MD06, BE08 e FR01 da pacs.004),
ou a um Pix de Saque ou Troco (com códigos possíveis: MD06 e SL02 da pacs.004). Na ausência deste campo a natureza deve ser interpretada como
sendo de um Pix comum (ORIGINAL).

As naturezas são assim definidas:

ORIGINAL: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum ou ao valor da compra em um Pix Troco (MD06);
RETIRADA: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix Saque ou ao valor do troco em um Pix Troco (SL02);
MED_OPERACIONAL: quando a devolução ocorre no âmbito do MED por motivo de falha operacional e se refere a um Pix comum (BE08);
MED_FRAUDE: quando a devolução ocorre no âmbito do MED por fundada suspeita de fraude e se refere a um Pix comum (FR01).

Os valores de devoluções são sempre limitados aos valores máximos a seguir:

Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso pode ser: ORIGINAL, MED_OPERACIONAL ou MED_FRAUDE);
Pix Saque: o valor da devolução é limitado ao valor da retirada (a natureza nesse caso deve ser: RETIRADA);
Pix Troco: o valor da devolução é limitado ao valor relativo à compra ou ao troco:
- Quando a devolução for referente à compra, o valor limita-se ao valor da compra (a natureza nesse caso deve ser ORIGINAL);
- Quando a devolução for referente ao troco, o valor limita-se ao valor do troco (a natureza nesse caso deve ser RETIRADA).

ORIGINAL RETIRADA MED_OPERACIONAL MED_FRAUDE

descricao

string

length ≤ 140

O campo descricao é opcional e permite que informações sobre a devolução sejam apresentadas ao pagador. Na mensagem PACS.004, este campo é preenchido pelo PSP do recebedor e inserido no campo RemittanceInformation.

horario

object

required

status

string

required

Status da devolução.

EM_PROCESSAMENTO DEVOLVIDO NAO_REALIZADO

motivo

string

length ≤ 140

Status da Devolução

Campo opcional que pode ser utilizado pelo PSP recebedor para detalhar os motivos
de a devolução ter atingido o status em questão.
Pode ser utilizado, por exemplo, para detalhar o motivo de a devolução não ter sido realizada.

Language

Credentials

OAuth2


xxxxxxxxxx
1
curl --request GET \
2
     --url 'https://api.pix.voluti.com.br/cobv?paginacao.paginaAtual=0&paginacao.itensPorPagina=100' \
3
     --header 'accept: application/json'


xxxxxxxxxx
54
}
1
{
2
  "parametros": {
3
    "inicio": "2020-04-01T00:00:00Z",
4
    "fim": "2020-04-01T23:59:59Z",
5
    "paginacao": {
6
      "paginaAtual": 0,
7
      "itensPorPagina": 100,
8
      "quantidadeDePaginas": 1,
9
      "quantidadeTotalDeItens": 1
10
    }
11
  },
12
  "cobs": [
13
    {
14
      "allOf": [
15
        {
16
          "calendario": {
17
            "criacao": "2020-09-09T20:15:00.358Z",
18
            "dataDeVencimento": "2020-12-31",
19
            "validadeAposVencimento": 30
20
          },
21
          "txid": "7978c0c97ea847e78e8849634473c1f1",
22
          "revisao": 0,
23
          "loc": {
24
            "id": 789,
25
            "location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",

200Lista de cobranças com vencimento.

Exemplos válidos:

Exemplos inválidos:

403Requisição de participante autenticado que viola alguma regra de autorização.

503Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.