Pular para conteúdo

1. Início Rápido

Bem-vindo ao guia de início rápido do PixCore! Este tutorial mostrará os passos essenciais para você gerar seu primeiro payload e QR Code Pix de forma simples e direta.

Passo 1: Instalação

Primeiro, certifique-se de que a biblioteca esteja instalada. Se ainda não a instalou, utilize o pip:

pip install pixcore

Isso instalará o pixcore e suas dependências necessárias, como qrcode e Pillow.

Passo 2: Importando as Classes Principais

Para começar, você precisará importar duas classes centrais do projeto:

  • PixData: Uma classe de dados para armazenar e validar todas as informações da sua cobrança.
  • Pix: A classe principal que utiliza os dados do PixData para gerar o payload e o QR Code.
from pixcore.models import PixData
from pixcore.brcode import Pix

Passo 3: Reunindo e Validando os Dados

Agora, crie uma instância de PixData com as informações do recebedor e da transação. A grande vantagem é que esta classe valida os dados automaticamente, garantindo que o nome não é muito longo, que o valor é positivo, etc., prevenindo erros antes mesmo da geração do código.

# Crie um objeto com os dados da cobrança
# Se houver algum dado inválido, um erro (ValueError) será levantado aqui.
try:
    dados_pix = PixData(
        recebedor_nome="EMPRESA MODELO LTDA",
        recebedor_cidade="CIDADE EXEMPLO",
        pix_key="123e4567-e89b-12d3-a456-426655440000", # Use uma chave pix válida aqui
        valor=25.50,
        transacao_id="ID.DA.SUA.TRANSACAO.123"
    )
except ValueError as e:
    print(f"Erro nos dados fornecidos: {e}")

Passo 4: Gerando o Payload e o QR Code

Com os dados validados, passe o objeto dados_pix para a classe Pix. A partir daí, você pode gerar o payload (Pix Copia e Cola) ou salvar o QR Code diretamente em um arquivo.

# Instancie a classe principal com os dados validados
gerador_pix = Pix(dados_pix)

# Para obter o payload (Copia e Cola)
payload = gerador_pix.payload()
print("Payload (Copia e Cola):")
print(payload)

# Para gerar e salvar o QR Code em um arquivo
print("\nSalvando QR Code...")
gerador_pix.save_qrcode("meu_primeiro_pix.png")

Código Completo (Exemplo Funcional)

Para facilitar, aqui está o script completo que você pode copiar, colar e executar para ver a mágica acontecer.

from pixcore.models import PixData
from pixcore.brcode import Pix

def gerar_cobranca_pix_exemplo():
    """
    Função de exemplo que encapsula todos os passos para gerar um Pix.
    """
    print("Iniciando a geração de uma cobrança Pix...")

    try:
        # 1. Defina e valide os dados da cobrança
        dados_pix = PixData(
            recebedor_nome="EMPRESA MODELO LTDA",
            recebedor_cidade="CIDADE EXEMPLO",
            pix_key="123e4567-e89b-12d3-a456-426655440000", # Chave aleatória (UUID)
            valor=25.50,
            transacao_id="TXID.12345"
        )
        print("Dados validados com sucesso!")

        # 2. Crie a instância principal do gerador
        gerador_pix = Pix(dados_pix)

        # 3. Obtenha o payload (Copia e Cola) e exiba
        payload = gerador_pix.payload()
        print("\n--- Payload (Copia e Cola) Gerado ---")
        print(payload)
        print("------------------------------------")

        # 4. Salve o QR Code em um arquivo
        caminho_arquivo = "pix_exemplo.png"
        gerador_pix.save_qrcode(caminho_arquivo)

        print(f"\nQR Code foi salvo com sucesso em: '{caminho_arquivo}'")

    except ValueError as e:
        # Captura erros de validação da classe PixData
        print(f"\nERRO: Não foi possível gerar o Pix. Motivo: {e}")

if __name__ == "__main__":
    gerar_cobranca_pix_exemplo()

Ao executar este script, ele imprimirá o payload no seu terminal e criará um arquivo de imagem pix_exemplo.png no mesmo diretório.

Pronto! Agora você já sabe o básico para criar cobranças Pix com a biblioteca.