Sopague Documentação

Para integrar seu PDV, ERP ou qualquer outro sistema de automação comercial com o Simple TEF, utilize o executável CLI PdvCliSitef.exe.

A cada operação realizada, seu sistema executa a CLI passando um comando e parâmetros. O resultado da transação é retornado em formato JSON no stdout acompanhado de um código de saída numérico.

1. Caminhos dos arquivos e executáveis

Item	Caminho padrão
CLI de Integração	`C:\Program Files (x86)\SimpleTEF\PdvCliSitef.exe`
PDV CliSiTef	`C:\PDVCliSiTef\PDVSiTef.exe`
Pasta de Requisições	`C:\Client\Req`
Pasta de Respostas	`C:\Client\Resp`
Pasta de Comprovantes	`C:\Client\Comprovantes`

Caminho da CLI

Se o caminho de instalação foi alterado durante a instalação, utilize o diretório escolhido. No ambiente de homologação (HMG), o caminho padrão é C:\Program Files (x86)\SimpleTEF-HMG. Não fixe o caminho de forma estática no seu código sem permitir parametrização.

2. Formato da chamada

A sintaxe de invocação da CLI segue a estrutura abaixo:

PdvCliSitef.exe <comando> [parâmetros]

Formatação de valores monetários

O parâmetro --valor deve sempre receber centavos inteiros.

R$ 15,00 deve ser passado como --valor 1500.
R$ 300,00 deve ser passado como --valor 30000.
R$ 50,00 deve ser passado como --valor 5000.

Ativação via CLI (Entrada Padrão - stdin)

Ao executar o comando de ativação via CLI, o token deve ser enviado obrigatoriamente pela entrada padrão (stdin), acompanhado do parâmetro --activation-code-stdin. Não informe o token diretamente na linha de comando.

Exemplo em PowerShell:

"TOKEN_RECEBIDO" | PdvCliSitef.exe ativacao --serial-number 7500032412001566 --activation-code-stdin

3. Comandos disponíveis

Comando	Parâmetros principais	Finalidade
`venda`	`--valor`; `--tipo`; `--parcelas`; `--output`	Realiza pagamento em débito ou crédito
`pix`	`--valor`; `--output`	Processa pagamento via PIX no PIN pad
`cancelamento`	`--valor`; `--tipo`; `--nsu-sitef`; `--output`	Cancela uma venda realizada com cartão
`reimpressao`	`--nsu-sitef`; `--output`	Reimprime a última transação ou um NSU específico
`ativacao`	`--serial-number`; `--output`	Ativa o terminal no Simple TEF
`desativacao`	Sem parâmetros obrigatórios; `--output` opcional	Revoga a licença e desvincula a instalação atual do terminal
`health`	Sem parâmetros obrigatórios	Verifica o status da ativação e do PDV CliSiTef

4. Exemplos de requisição

Venda no débito (R$ 15,00)

PdvCliSitef.exe venda --valor 1500 --tipo debito

Venda no crédito parcelado (R$ 300,00 em 3x)

PdvCliSitef.exe venda --valor 30000 --tipo credito --parcelas 3

Pagamento via PIX (R$ 50,00)

PdvCliSitef.exe pix --valor 5000

Cancelamento de venda

PdvCliSitef.exe cancelamento --valor 1500 --nsu-sitef 123456789

Desativar instalação

PdvCliSitef.exe desativacao

Health Check do terminal

PdvCliSitef.exe health

5. Resposta da CLI e interpretação

A CLI escreve o resultado final em JSON no fluxo de saída padrão (stdout). Mensagens de acompanhamento e logs operacionais são escritos no stderr.

O sistema integrador deve avaliar conjuntamente o código de saída do processo (exit code) e os campos do JSON devolvido.

Exemplo de resposta JSON (Sucesso)

{
  "status": "aprovada",
  "codigoSaida": 0,
  "valorCentavos": 1500,
  "mensagemOperador": "TRANSAÇÃO APROVADA",
  "nsuSitef": "123456789",
  "nsuHost": "987654321",
  "linhasCupom": ["VIA ESTABELECIMENTO"],
  "codigoQrCode": null,
  "caminhoPdfComprovante": null,
  "erro": null
}

Dicionário de campos da resposta

Campo	Tipo	Descrição
`status`	`string`	Status da transação: `aprovada`, `negada`, `cancelada` ou `erro`
`codigoSaida`	`integer`	Código numérico de retorno do processo
`valorCentavos`	`integer`	Valor processado na transação em centavos
`mensagemOperador`	`string`	Mensagem descritiva a ser exibida na tela do operador
`nsuSitef`	`string`	Número de Sequência Único gerado pelo SiTef
`nsuHost`	`string`	Número de autorização retornado pela adquirente/autorizadora
`linhasCupom`	`array[string]`	Linhas do comprovante formatadas para impressão em bobina
`codigoQrCode`	`string`	Conteúdo do QR Code em operações PIX, quando aplicável
`caminhoPdfComprovante`	`string`	Caminho absoluto do arquivo PDF do comprovante, se habilitado
`ativo` / `tokenAtivo` / `pdvSitefAberto`	`boolean`	Status retornado exclusivamente pelo comando `health`
`erro`	`string`	Detalhamento técnico da falha quando o status for `erro`

Códigos de saída do processo (Exit Codes)

Código	Significado
`0`	Operação aprovada ou concluída com sucesso
`1`	Transação negada pela autorizadora/emissora
`2`	Operação cancelada pelo operador ou cliente no PIN pad
`3`	Erro de comunicação, parâmetro inválido ou falha de configuração

6. Gravar resposta diretamente em arquivo

Quando o integrador preferir ler o resultado diretamente de um arquivo no disco em vez do stdout, utilize o parâmetro --output:

PdvCliSitef.exe venda --valor 1500 --output C:\PDV\resultado.json