3. Guia CLI

Bem-vindo ao guia da CLI do PixCore! Além de ser uma biblioteca Python, o PixCore oferece uma poderosa ferramenta de linha de comando para gerar cobranças Pix diretamente do seu terminal.

A CLI é ideal para automação, scripts, testes rápidos ou simplesmente para quando você precisa de um QR Code sem escrever nenhum código Python.

1. Instalação e Uso Básico

Ao instalar a biblioteca com pip install pixcore, a ferramenta de linha de comando pixcore é automaticamente adicionada ao seu ambiente.

O uso mais simples é gerar um QR Code e exibi-lo na tela. A CLI irá solicitar interativamente qualquer informação obrigatória que não for fornecida.

# A CLI pedirá a chave, nome e cidade
pixcore qrcode --amount 10.50

2. Estrutura dos Comandos

A CLI segue uma estrutura simples e intuitiva:

pixcore [COMANDO] [ARGUMENTOS] [OPÇÕES]

- [COMANDO]: A ação que você deseja executar (ex: qrcode, payload).

[ARGUMENTOS]: Valores necessários para um comando (ex: o payload para o comando decode).
[OPÇÕES]: Parâmetros para customizar a execução (ex: --key, --output).

Você pode obter ajuda a qualquer momento com a opção --help.

# Ajuda geral com a lista de comandos
pixcore --help

# Ajuda específica para o comando qrcode
pixcore qrcode --help

3. Comandos Principais

3.1. qrcode

Gera a imagem de um QR Code Pix. Este é o comando mais comum. Por padrão, ele abre a imagem no visualizador padrão do seu sistema. Usando a opção --output, ele salva a imagem em um arquivo.

Opção	Atalho	Descrição
`--key`	`-k`	Chave PIX (CPF/CNPJ, e-mail, celular ou aleatória).
`--name`	`-n`	Nome do beneficiário.
`--city`	`-c`	Cidade do beneficiário (maiúsculas, sem acentos).
`--amount`	`-a`	Valor da transação. Ex: 10.50.
`--output`	`-o`	Caminho e nome do arquivo de saída (ex: 'output/pix.png').
`--logo`	`-l`	Caminho para um arquivo de imagem (ex: pasta/logo.png).
`--txid`	`-t`	ID da transação (Transaction ID).
`--info`	`-i`	Informações adicionais para o pagador.
`--cep`		CEP do beneficiário (formato XXXXXXXX).
`--mcc`		Merchant Category Code (Código da Categoria do Comerciante).
`--initiation-method`		Método de iniciação (ex: '11' para estático, '12' para dinâmico).
`--lang`		Idioma de preferência para dados alternativos (ex: pt_BR, en_US).
`--alt-name`		Nome alternativo do beneficiário (em outro idioma).
`--alt-city`		Cidade alternativa do beneficiário (em outro idioma).

Exemplos:

# Gerar QR Code de R$ 25,00 e exibir na tela
pixcore qrcode -k "chave-aleatoria-aqui" -n "NOME DO RECEBEDOR" -c "SAO PAULO" -a 25.00

# Gerar QR Code de R$ 99,90 com logo e salvar em um arquivo
pixcore qrcode -k "vendas@minhaloja.com" -n "MINHA LOJA" -c "CURITIBA" -a 99.90 --logo "logo.png" -o "cobrança.png"

3.2. payload

Gera a string "Pix Copia e Cola" (BR Code). Este comando exibe no terminal o payload completo, que pode ser usado em qualquer app de banco. Ele aceita as mesmas opções de dados do comando qrcode (chave, nome, valor, etc.), exceto as de customização visual.

Opção	Atalho	Descrição
`--key`	`-k`	Chave PIX (CPF/CNPJ, e-mail, celular ou aleatória).
`--name`	`-n`	Nome do beneficiário.
`--city`	`-c`	Cidade do beneficiário (maiúsculas, sem acentos).
`--amount`	`-a`	Valor da transação. Ex: 10.50.
`--txid`	`-t`	ID da transação (Transaction ID).
`--info`	`-i`	Informações adicionais para o pagador.
`--cep`		CEP do beneficiário (formato XXXXXXXX).
`--mcc`		Merchant Category Code (Código da Categoria do Comerciante).
`--initiation-method`		Método de iniciação (ex: '11' para estático, '12' para dinâmico).
`--lang`		Idioma de preferência para dados alternativos (ex: pt_BR, en_US).
`--alt-name`		Nome alternativo do beneficiário (em outro idioma).
`--alt-city`		Cidade alternativa do beneficiário (em outro idioma).

Exemplo:

# Gerar um payload para uma doação de valor livre
pixcore payload -k "doacoes@causa.org" -n "ONG CAUSA NOBRE" -c "BRASILIA" --txid "DOACAO-ABERTA"

3.3. decode

Decodifica um payload "Copia e Cola" e exibe seus dados. Útil para verificar o conteúdo de um código Pix antes de pagar ou para depuração.

Argumento	Descrição
`payload`	A string do payload BR Code a ser decodificada.

Exemplo:

# Cole o payload completo como argumento
pixcore decode "00020126580014br.gov.bcb.pix0136..."

3.4. lote

Gera múltiplos QR Codes a partir de um arquivo CSV. Ideal para cobranças em massa. Você precisa fornecer um arquivo de entrada (.csv) e um diretório de saída. O arquivo CSV deve conter as colunas valor e txid. Outras colunas como chave, nome e cidade podem ser usadas para sobrescrever os valores padrão.

Argumentos:

Argumento	Descrição
`arquivo_csv`	Caminho para o arquivo CSV com os dados.
`diretorio_saida`	Diretório onde os QR Codes serão salvos.

Opções:

Opção	Atalho	Descrição
`--key`	`-k`	Chave PIX padrão (usada se não especificada no CSV).
`--name`	`-n`	Nome do beneficiário padrão (usado se não especificado no CSV).
`--city`	`-c`	Cidade padrão do beneficiário (usada se não especificada no CSV).

Exemplo:

# Processar o arquivo 'cobrancas.csv' e salvar os QR Codes na pasta 'saida/'
pixcore lote cobrancas.csv saida/ --name "MINHA EMPRESA" -k "meu-cnpj-aqui" -c "SAO PAULO"

3.5. config

Gerencia configurações padrão para evitar repetição.

config set [CHAVE] [VALOR]: Salva um valor padrão (chaves válidas: key, name, city).
config show: Mostra as configurações salvas.

Argumento	Descrição
`key`	A chave de configuração (ex: `name`, `city`, `key`).
`value`	O valor a ser salvo.

Exemplo:

# Salve seu nome e chave PIX para não precisar digitá-los sempre
pixcore config set name "MEU NOME COMPLETO"
pixcore config set key "meu-email@exemplo.com"

# Agora você pode gerar um QR Code de forma mais simples
pixcore qrcode --city "SAO PAULO" --amount 50