Consulta de transações
Operação responsável por consultar transações já realizadas no Cielo Conecta por meio da biblioteca Client Conecta.
Esta operação foi projetada para atender dois cenários de uso distintos:
-
Consulta de pagamento específico: usada para recuperar uma única transação de forma determinística, por meio de um identificador exclusivo ou combinação de parâmetros. Nesse caso, a consulta é realizada diretamente no Cielo Conecta.
-
Listagem de pagamentos com filtros: usada para consultar múltiplas transações, aplicando filtros como período, tipo, status e confirmação. Nessa modalidade, a consulta é realizada localmente no ponto de venda (PDV), com base nos registros mantidos pela biblioteca Client Conecta.
ImportanteEm ambas as modalidades, é obrigatório informar pelo menos um parâmetro válido para que a consulta seja realizada.
Modalidades de consulta
Consulta de pagamento específico
Permite recuperar uma única transação de forma determinística, utilizando um identificador exclusivo ou combinação de parâmetros.
Parâmetros suportados
Utilize apenas um dos conjuntos abaixo:
-
PaymentId: identificador exclusivo da transação no Cielo Conecta;ou
-
StartDatetime: data/hora da transação; -
MerchantOrderId: chave de controle gerada pela automação comercial
Comportamento de execução
A biblioteca sempre realiza a consulta diretamente no Cielo Conecta, independentemente do terminal onde a transação foi originada.
Validações recomendadas
- Garantir o formato correto do
PaymentId(se aplicável); - Validar que
StartDatetimeeMerchantOrderIdcorrespondem à mesma transação.
Listagem de pagamentos com filtros
Retorna múltiplas transações armazenadas localmente pela biblioteca no terminal, com base nos filtros informados.
Essa listagem considera apenas transações processadas pelo próprio terminal.
Filtros suportados
É necessário informar pelo menos um dos filtros:
TransactionType: tipo de transação;StartDatetimeeEndDatetime: período de realização;PhysicalTransactionStatus: status da transação.
Comportamento de execução
A listagem é realizada exclusivamente sobre a base local do terminal, sem consulta ao Cielo Conecta.
AtençãoA origem dos dados varia conforme o tipo de consulta:
- consulta específica utiliza dados do Cielo Conecta;
- listagem de pagamentos utiliza dados locais do terminal.
Esse comportamento deve ser considerado na implementação para garantir consistência nos resultados.
Parâmetros de entrada
| Campo | Tipo | Formato | Obrigatório | Descrição |
|---|---|---|---|---|
Oper | string | N..3 | M | Código da operação: fixo "8" (CFL_OPER_TRANSQUERY) |
TransactionType | string | N2 | O | Tipo das transações a serem consultadas: “01” = “Crédito a vista”; “02” = “Débito”; “03” = “Crédito parcelado sem juros”; “04” = “Crédito parcelado com juros”; “30” = “Voucher”; “50” = “Cancelamento de crédito”; “51” = “Cancelamento de débito” |
StartDatetime | string | N14 | O | Data inicial no formato "AAAAMMDDhhmmss" |
EndDatetime | string | N14 | O | Data final no formato "AAAAMMDDhhmmss" |
MerchantOrderId | string | N15 | O | Chave de identificação da Automação Comercial para a transação a ser consultada. |
PaymentId | string | A36 | O | Chave de identificação Cielo Conecta para a transação a ser consultada. |
PhysicalTransactionStatus | string | N..2 | O | Status das transações a serem consultadas: “0” = não processada; “2” = aprovada, pendente de confirmação; “3” = não aprovada/negada; “10” = cancelada; “13” = abortada e/ou desfeita; “20” = confirmada. |
Regra de obrigatoriedade
Pelo menos um parâmetro válido deve ser informado para que a consulta seja executada.
Mensagem de notificação recebida na callback da operação
Não há.
Dados de resposta recebido na callback da operação
Os dados são retornados via callback no formato JSON.
Campos principais
| Campo | Tipo | Formato | Obrigatório | Descrição |
|---|---|---|---|---|
Oper | string | N..3 | ME | Código da operação: fixo "8" (CFL_OPER_TRANSQUERY) |
Code | string | N..2 | M | Código da resposta. Valor "0" indica retorno válido |
TotalPayments | string | N..3 | M | Total de transações encontradas |
TotalPages | string | N..3 | M | Total de páginas disponíveis |
Page | string | N..3 | M | Página retornada |
Payments | string array | M | Lista de transações |
Estrutura de cada item em Payments
PaymentsCada item em Payments contém os seguintes dados:
| Campo | Tipo | Formato | Obrigatório | Descrição |
|---|---|---|---|---|
TransactionType | string | N2 | M | Tipo da transação consultada: “01” = “Crédito a vista”; “02” = “Débito”; “03” = “Crédito parcelado sem juros”; “04” = “Crédito parcelado com juros”; “30” = “Voucher”; “50” = “Cancelamento de crédito”; “51” = “Cancelamento de débito” |
Amount | string | N..12 | M | Valor da transação |
MerchantOrderId | string | N15 | M | Chave única de identificação da transação, de controle da Automação Comercial. |
Datetime | string | N14 | M | Data e hora da transação no formato “AAAAMMDDhhmmss” |
PaymentId | string | A36 | M | Chave única de identificação da transação no Cielo Conecta |
PhysicalTransactionStatus | string | N..2 | M | Status das transações a serem consultadas: “0” = não processada; “2” = aprovada, pendente de confirmação; “3” = não aprovada/negada; “10” = cancelada; “13” = abortada e/ou desfeita; “20” = confirmada. |
ReturnCode | string | A3 | M | Código de resposta |
ReturnMessage | string | A..99 | M | Mensagem de resposta |
Installments | string | N2 | M | Número de parcelas de “01” a “99” |
TerminalId | string | A8 | M | Identificador do terminal |
isLocalStore | string | N1 | M | Indica origem da transação:0 = outra loja com outro CNPJ;1 = mesma loja. |
Retornos
| Código | Descrição |
|---|---|
CFL_OK | Operação realizada com sucesso |
CFL_ERROR_INVCALL | Operação não permitida no momento |
CFL_ERROR_INVPARAM | Parâmetros inválidos |
CFL_ERROR_NETWORK | Erro na comunicação com Cielo Conecta |
Updated about 2 months ago