Referência de operações e erros

Esta página descreve as operações da biblioteca Client Conecta e os códigos de retorno da função RequestDispatcher.

Para o contrato geral, o formato do JSON e o primeiro exemplo de venda, consulte o Guia de integração.

Toda integração está sujeita ao PCI DSS. Antes de registrar, exibir ou gravar qualquer campo de resposta, leia Segurança e PCI DSS.

Operações

Operação 001: inicialização (INITIALIZE)

Abre a sessão da biblioteca. Dispare-a por ação explícita da pessoa usuária, nunca de forma automática. Todos os campos são enviados como string.

Parâmetro	Descrição	Tipo	Obrigatório?
`Cnpj`	CNPJ válido do estabelecimento.	string	Sim
`ClientId`	Credencial de API. Trate como segredo e nunca a escreva no código-fonte.	string	Sim
`ClientSecret`	Credencial de API. Trate como segredo e nunca a escreva no código-fonte.	string	Sim
`TerminalId`	Identificador do terminal. Obrigatório na primeira inicialização e também após a desassociação do terminal.	string	Condicional
`Environment`	Ambiente de execução: `"0"` Produção (padrão) ou `"1"` Homologação. Se o campo for omitido ou inválido, a biblioteca assume Produção. Envie `"1"` explicitamente nos testes.	string	Não
`ConfirmationStatusSetup`	Modo de confirmação: `"1"` automática (padrão) ou `"0"` manual. Consulte a seção Confirmação automática e manual do Guia de Integração.	string	Não
`TableParamsUpdate`	Atualização de tabelas: `"0"` desabilita; `"1"` normal (padrão); `"2"` força parâmetros; `"3"` força parâmetros e pin pad.	string	Não
`PortPinpad`	Porta do pin pad. Vazio significa automático. No Linux, deixe sempre vazio.	string	Não

Operação 005: venda (TRANSACTION)

A tabela a seguir descreve os campos principais de uma venda.

Parâmetro	Descrição
`TransactionType`	Tipo da transação: `"01"` crédito à vista; `"02"` débito; `"03"` parcelado sem juros; `"30"` voucher.
`Amount`	Valor em centavos, como string e inteiro (por exemplo, R$ 10,00 é `"1000"`). Nunca use ponto flutuante.
`MerchantOrderId`	Somente números, com 15 posições fixas, e único por transação.
`Installments`	Número de parcelas. Obrigatório e maior que 1 para `"03"`. O débito só aceita `"1"`. Nos demais tipos, o padrão é `"1"`.
`Tokenize`	Opcional. Com `"1"`, a biblioteca tokeniza o cartão, e a resposta traz `CardToken`.

Nunca envie dado de cartão (PAN, validade, CVV ou trilha) no JSON. A biblioteca lê tudo pelo Pin pad.

Estorno e cancelamento (também pela operação 005)

Use TransactionType "50" para crédito, "51" para débito e "52" para voucher. Identifique a transação original por um destes dois modos:

Modo A: RefundPaymentId;
Modo B: RefundDatetime, RefundMerchantOrderId, RefundNSU e RefundAuthorizationCode.

O cancelamento parcial não é suportado: o Amount do estorno precisa ser igual ao da transação original.

Outras operações

A tabela a seguir resume as demais operações.

Oper	Nome	Resumo
`002`	MERCHANT	Cadastro e atualização do estabelecimento subordinado.
`003`	UNINSTALL	Encerra a sessão, fechando e apagando o banco local. Resposta: `{"Oper":"003","Code":"XX"}`.
`004`	STATUS	Devolve o estado da sessão a partir da memória local, sem comunicação externa.
`006`	TRANSREPRINT	Reimprime o recibo (texto e PNG em base64), por `PaymentId`, por `MerchantOrderId` ou pela última transação.
`007`	CONFIRMATION	Confirma (`"1"`) ou desfaz (`"2"`) a transação. Funciona só no modo manual.
`008`	TRANSQUERY	Consulta por `PaymentId`, por `MerchantOrderId` e data, ou por filtros no banco local. A resposta é paginada.
`009`	PPRECEIVE	Captura dado no PINPAD (menu ou campo predefinido), selecionada por `PPOper`.
`010`	PPSEND	Envia comando ao PINPAD (Pix, imagem, texto), selecionado por `PPOper`.

Nas operações com subcomando (009 e 010, pelo PPOper), envie no pacote apenas os campos que o comando escolhido usa. O PPOper sempre vai. Se a AC tiver um único formulário com todos os campos, descarte os demais antes do envio.

Na operação 009, o código de segurança (CVV) e o número do cartão (PAN) capturados pelo teclado do PINPAD voltam em claro. Mascare esses dados antes de registrar, exibir ou gravar.

Tratamento de erros e reconciliação

Trate os códigos de retorno da função RequestDispatcher conforme a tabela a seguir.

Código	Significado e orientação
`0`	Sucesso imediato da chamada. Os dados da operação chegam pelo callback.
`CFL_ERROR_INVPARAM (2)`	Campo obrigatório vazio, campo acima do tamanho máximo ou `PPOper` fora do formato de dois dígitos.
`CFL_ERROR_MANDAT (3)`	Campo obrigatório ausente.
`CFL_ERROR_CANCEL (5)`	Ação da pessoa operadora no pin pad.
`CFL_ERROR_TIMEOUT (6)`	Tempo esgotado no pin pad.
`CFL_ERROR_NOT_INIT (62)`	A sessão não foi inicializada. Faça o INITIALIZE (001) antes.
`CFL_ERROR_PENDING_TRANSACTION (66)`	Há confirmação ou desfazimento pendente de uma chamada anterior. A biblioteca tenta resolver na próxima transação.

Siga também estas orientações:

Em falha de rede ou timeout em uma venda: use o TRANSQUERY (008) para descobrir o estado real antes de reapresentar ou estornar. Nunca assuma sucesso sem confirmação;
Serialize as chamadas: não chame RequestDispatcher de forma concorrente.

Um erro "sem causa aparente" pode vir de uma pendência anterior. Antes de processar um novo pagamento ou estorno, a biblioteca tenta resolver sozinha uma transação pendente de uma chamada anterior (por exemplo, quando o processo foi encerrado entre a aprovação e a confirmação). Se essa resolução automática falhar por rede, o novo pagamento também não é processado, e o erro devolvido é o da resolução da pendência. Esse erro pode parecer, à primeira vista, não relacionado ao cartão que está sendo lido. O cenário típico é o reinício do aplicativo logo após uma falha. Nesse caso, consulte o estado pelo TRANSQUERY (008).