Add ASCII QR output and dynamic Pix improvements

- Add GenQRCodeASCII and qrcode.NewASCII (uses github.com/mdp/qrterminal) plus CLI flags: --ascii-scale, --ascii-quiet, --ascii-black/--ascii-white; also add --qr-size.
- Improve payload generation: sanitize/normalize characters, MAI/url handling per BACEN Pix manual v2.9.0, and enforce TXID rules (static up to 25 alnum or "***"; dynamic requires txid and payload carries "***").
- Harden validations: stricter amount/txid patterns, increased additional info limit, and return errors from New/GenPayload when constraints fail.
- Update QR code PNG sizing, replace CRC handling, adjust options getters/setters, and add tests, README updates, go.mod/go.sum changes and docs/.gitkeep.

Author: thiagozs

.gitignore

@@ -1,4 +1,7 @@
 .gocache
 
 bin/*
-!bin/.gitkeep
+!bin/.gitkeep
+
+docs/*
+!docs/.gitkeep

README.md

@@ -2,6 +2,10 @@
 
 <p align="center"><img alt="pix-utils" src="https://raw.githubusercontent.com/thiagozs/go-pixgen/main/assets/logo-pix.png" width="128px" /></p>
 
+***release: Ultima versão do manual v2.9.0***
+
+---
+
 Gere e valide pagamentos do Sistema de Pagamentos Instantâneo (Pix) do Banco Central de forma simples. Além da biblioteca, este repositório inclui um CLI e um serviço REST para gerar payloads Pix estáticos ou dinâmicos, bem como seus códigos QR.
 
 ## Funcionalidades
@@ -24,7 +28,7 @@ Requer Go 1.17 ou superior.
 
 ## Guia rápido
 
-### CLI – gerar payload no terminal
+### CLI - gerar payload no terminal
 
 ```bash
 make cli
@@ -36,10 +40,13 @@ bin/pixgen generate \
   --merchant-city ARARANGUA \
   --amount 10.00 \
   --description "Pedido 123" \
-  --txid PEDIDO-123
+  --txid PEDIDO-123 \
+  --ascii-scale 1
 ```
 
-A saída inclui o código copia-e-cola, campos relevantes e o QR Code em base64.
+A saída inclui o código copia-e-cola, campos relevantes, o QR Code em base64 e a versão em ASCII. Use `--ascii-scale` (>=1), `--ascii-quiet=true` para recolocar a borda de silêncio e `--ascii-black/--ascii-white` para personalizar o render em terminal.
+
+Para QR Codes dinâmicos, lembre-se de informar `--url https://...` e um `--txid` alfanumérico (até 25 caracteres); o payload emitido trará a URL (tag `25`) e `***` no campo TxID conforme o manual.
 
 ### Serviço REST
 
@@ -106,7 +113,11 @@ if err != nil {
 	return
 }
 
-cpy := p.GenPayload()
+cpy, err := p.GenPayload()
+if err != nil {
+	fmt.Println(err.Error())
+	return
+}
 fmt.Printf("Copy and Paste: %s\n", cpy)
 
 qrPNG, err := p.GenQRCode()
@@ -117,6 +128,13 @@ if err != nil {
 
 fmt.Printf("QRCode bytes: %d\n", len(qrPNG))
 
+asciiQR, err := p.GenQRCodeASCII()
+if err != nil {
+	fmt.Println(err.Error())
+	return
+}
+fmt.Println(asciiQR)
+
 parsed, err := pix.ParsePayload(cpy)
 if err != nil {
 	fmt.Println(err.Error())
@@ -156,23 +174,25 @@ fmt.Printf("Remote Pix expires at: %v\n", payload.ExpiresAt)
 
 ## Destaques da API
 
-- `pix.New(opts...) (*pix.Pix, error)` – cria um gerador Pix configurável.
-- `(*Pix).GenPayload()` – retorna o payload EMV e o mantém em cache para `GenQRCode()`.
-- `pix.ParsePayload(string) (*ParsedPayload, error)` – faz o parsing do payload e valida o CRC.
-- `(*Pix).FetchDynamicPayload(ctx, client)` – baixa, valida e parseia payloads dinâmicos remotos.
-- `(*Pix).Validates()` – valida os parâmetros (chaves, tamanho de campos, etc.).
+- `pix.New(opts...) (*pix.Pix, error)` - cria um gerador Pix configurável.
+- `(*Pix).GenPayload() (string, error)` - retorna o payload EMV e o mantém em cache para `GenQRCode()`.
+- `pix.ParsePayload(string) (*ParsedPayload, error)` - faz o parsing do payload e valida o CRC.
+- `(*Pix).FetchDynamicPayload(ctx, client)` - baixa, valida e parseia payloads dinâmicos remotos.
+- `(*Pix).Validates()` - valida os parâmetros (chaves, tamanho de campos, etc.).
+- `(*Pix).GenQRCodeASCII() (string, error)` - renderiza o QR Code em ASCII para uso direto no terminal.
+- `pix.OptQRCodeScale`, `pix.OptASCIIQuietZone`, `pix.OptASCIICharset` - controlam escala, borda e caracteres usados no QR ASCII.
 
 ### Formatos aceitos de chave Pix
 
-- EVP (UUID) – normalizado para minúsculo.
-- Telefone (`+55DDDNÚMERO`) – aceita apenas dígitos com ou sem `+55`.
-- CPF/CNPJ – somente dígitos, com validação dos dígitos verificadores.
-- E-mail – validado via `net/mail`.
+- EVP (UUID) - normalizado para minúsculo.
+- Telefone (`+55DDDNÚMERO`) - aceita apenas dígitos com ou sem `+55`.
+- CPF/CNPJ - somente dígitos, com validação dos dígitos verificadores.
+- E-mail - validado via `net/mail`.
 
 ### Valor e TxID
 
 - Valor suporta até 13 dígitos antes da vírgula e 2 casas decimais (`9999999999999.99` limite).
-- TxID permite letras, números, `.` e `-` até 35 caracteres e é armazenado em maiúsculas.
+- TxID (estático ou dinâmico) deve ser alfanumérico (A-Z, 0-9) e ter no máximo 25 caracteres. No caso estático, deixe em branco para que o payload utilize `***`; no dinâmico, o QR Code continua transportando `***` enquanto a URL carrega os dados da cobrança.
 
 ### Busca de payload dinâmico
 

cmd/pixgen/main.go

@@ -8,6 +8,7 @@ import (
 	"log"
 	"net/http"
 	"os"
+	"strconv"
 	"strings"
 	"time"
 
@@ -48,7 +49,7 @@ func newGenerateCmd() *cobra.Command {
 				return err
 			}
 
-			payload, qr, parsed, err := buildPix(params)
+			payload, qr, asciiQR, parsed, err := buildPix(params)
 			if err != nil {
 				return err
 			}
@@ -60,6 +61,10 @@ func newGenerateCmd() *cobra.Command {
 				fmt.Printf("TxID: %s\n", parsed.AdditionalDataField.TxID)
 			}
 			fmt.Printf("QR Code (base64): %s\n", base64.StdEncoding.EncodeToString(qr))
+			if asciiQR != "" {
+				fmt.Println("QR Code (ASCII):")
+				fmt.Println(asciiQR)
+			}
 
 			return nil
 		},
@@ -75,6 +80,11 @@ func newGenerateCmd() *cobra.Command {
 	flags.String("description", "", "Transaction description (optional)")
 	flags.String("additional-info", "", "Additional info (static only)")
 	flags.String("txid", "", "Transaction identifier (optional)")
+	flags.Int("qr-size", 0, "PNG QR code size in pixels (default 256 when omitted)")
+	flags.Int("ascii-scale", 1, "Scale factor (>=1) for ASCII QR output")
+	flags.Bool("ascii-quiet", false, "Include quiet zone border in ASCII QR output")
+	flags.String("ascii-black", "", "Character(s) used for dark modules in ASCII QR output")
+	flags.String("ascii-white", "", "Character(s) used for light modules in ASCII QR output")
 
 	return cmd
 }
@@ -151,7 +161,7 @@ func pixHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	payload, qr, parsed, err := buildPix(params)
+	payload, qr, _, parsed, err := buildPix(params)
 	if err != nil {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
@@ -182,11 +192,21 @@ type pixParams struct {
 	Description    string
 	AdditionalInfo string
 	TxID           string
+	QRCodeSize     int
+	ASCII          asciiParams
+}
+
+type asciiParams struct {
+	Scale     int
+	Quiet     bool
+	QuietSet  bool
+	BlackChar string
+	WhiteChar string
 }
 
 func collectPixParams(cmd *cobra.Command) (pixParams, error) {
 	flags := cmd.Flags()
-	return parseParams(
+	params, err := parseParams(
 		flags.Lookup("kind").Value.String(),
 		flags.Lookup("key").Value.String(),
 		flags.Lookup("url").Value.String(),
@@ -197,6 +217,50 @@ func collectPixParams(cmd *cobra.Command) (pixParams, error) {
 		flags.Lookup("additional-info").Value.String(),
 		flags.Lookup("txid").Value.String(),
 	)
+	if err != nil {
+		return pixParams{}, err
+	}
+
+	if fl := flags.Lookup("qr-size"); fl != nil && fl.Value.String() != fl.DefValue {
+		size, err := strconv.Atoi(fl.Value.String())
+		if err != nil {
+			return pixParams{}, fmt.Errorf("invalid qr-size: %w", err)
+		}
+		if size <= 0 {
+			return pixParams{}, fmt.Errorf("qr-size must be greater than zero")
+		}
+		params.QRCodeSize = size
+	}
+
+	if fl := flags.Lookup("ascii-scale"); fl != nil && fl.Value.String() != fl.DefValue {
+		scale, err := strconv.Atoi(fl.Value.String())
+		if err != nil {
+			return pixParams{}, fmt.Errorf("invalid ascii-scale: %w", err)
+		}
+		if scale < 1 {
+			return pixParams{}, fmt.Errorf("ascii-scale must be at least 1")
+		}
+		params.ASCII.Scale = scale
+	}
+
+	if fl := flags.Lookup("ascii-quiet"); fl != nil && fl.Value.String() != fl.DefValue {
+		quiet, err := strconv.ParseBool(fl.Value.String())
+		if err != nil {
+			return pixParams{}, fmt.Errorf("invalid ascii-quiet: %w", err)
+		}
+		params.ASCII.Quiet = quiet
+		params.ASCII.QuietSet = true
+	}
+
+	if fl := flags.Lookup("ascii-black"); fl != nil && fl.Value.String() != fl.DefValue {
+		params.ASCII.BlackChar = fl.Value.String()
+	}
+
+	if fl := flags.Lookup("ascii-white"); fl != nil && fl.Value.String() != fl.DefValue {
+		params.ASCII.WhiteChar = fl.Value.String()
+	}
+
+	return params, nil
 }
 
 func requestToParams(req pixRequest) (pixParams, error) {
@@ -259,7 +323,7 @@ func parseKind(kind string) (pix.PixKind, error) {
 	}
 }
 
-func buildPix(params pixParams) (string, []byte, *pix.ParsedPayload, error) {
+func buildPix(params pixParams) (string, []byte, string, *pix.ParsedPayload, error) {
 	opts := []pix.Options{
 		pix.OptKind(params.Kind),
 		pix.OptMerchantName(params.MerchantName),
@@ -284,22 +348,42 @@ func buildPix(params pixParams) (string, []byte, *pix.ParsedPayload, error) {
 	if params.URL != "" {
 		opts = append(opts, pix.OptUrl(params.URL))
 	}
+	if params.QRCodeSize > 0 {
+		opts = append(opts, pix.OptQRCodeSize(params.QRCodeSize))
+	}
+	if params.ASCII.Scale > 0 {
+		opts = append(opts, pix.OptQRCodeScale(params.ASCII.Scale))
+	}
+	if params.ASCII.BlackChar != "" || params.ASCII.WhiteChar != "" {
+		opts = append(opts, pix.OptASCIICharset(params.ASCII.BlackChar, params.ASCII.WhiteChar))
+	}
+	if params.ASCII.QuietSet {
+		opts = append(opts, pix.OptASCIIQuietZone(params.ASCII.Quiet))
+	}
 
 	p, err := pix.New(opts...)
 	if err != nil {
-		return "", nil, nil, err
+		return "", nil, "", nil, err
 	}
 
-	payload := p.GenPayload()
+	payload, err := p.GenPayload()
+	if err != nil {
+		return "", nil, "", nil, err
+	}
 	qr, err := p.GenQRCode()
 	if err != nil {
-		return "", nil, nil, err
+		return "", nil, "", nil, err
+	}
+
+	asciiQR, err := p.GenQRCodeASCII()
+	if err != nil {
+		return "", nil, "", nil, err
 	}
 
 	parsed, err := pix.ParsePayload(payload)
 	if err != nil {
-		return "", nil, nil, err
+		return "", nil, "", nil, err
 	}
 
-	return payload, qr, parsed, nil
+	return payload, qr, asciiQR, parsed, nil
 }

docs/.gitkeep

@@ -42,7 +42,10 @@ func runStaticExample() error {
 		return fmt.Errorf("create pix: %w", err)
 	}
 
-	payload := p.GenPayload()
+	payload, err := p.GenPayload()
+	if err != nil {
+		return fmt.Errorf("generate payload: %w", err)
+	}
 	fmt.Printf("Copy & Paste payload: %s\n", payload)
 
 	qrBytes, err := p.GenQRCode()
@@ -73,6 +76,7 @@ func runDynamicExample() error {
 		pix.OptUrl(server.URL),
 		pix.OptMerchantName("Fulano de Tal"),
 		pix.OptMerchantCity("CURITIBA"),
+		pix.OptTxId("DYNAMICPIXTXIDEXAMPLE01"),
 	}
 
 	p, err := pix.New(opts...)
@@ -108,7 +112,7 @@ func newMockDynamicServer() *httptest.Server {
 			pix.OptMerchantName("Fulano de Tal"),
 			pix.OptMerchantCity("CURITIBA"),
 			pix.OptAmount("50.00"),
-			pix.OptTxId("ABC123"),
+			pix.OptTxId("SERVERPAYLOADTXIDEX1"),
 		}
 
 		payloadPix, err := pix.New(opts...)
@@ -117,7 +121,11 @@ func newMockDynamicServer() *httptest.Server {
 			return
 		}
 
-		payload := payloadPix.GenPayload()
+		payload, err := payloadPix.GenPayload()
+		if err != nil {
+			http.Error(w, fmt.Sprintf("generate payload: %v", err), http.StatusInternalServerError)
+			return
+		}
 		resp := map[string]string{
 			"pixCopyPaste": payload,
 			"expiresAt":    time.Now().Add(5 * time.Minute).Format(time.RFC3339),

examples/main.go

@@ -8,4 +8,9 @@ require (
 	github.com/spf13/cobra v1.7.0
 )
 
+require (
+	github.com/mdp/qrterminal v1.0.1 // indirect
+	rsc.io/qr v0.2.0 // indirect
+)
+
 replace github.com/spf13/cobra => ./internal/cobra

go.mod

@@ -1,4 +1,8 @@
+github.com/mdp/qrterminal v1.0.1 h1:07+fzVDlPuBlXS8tB0ktTAyf+Lp1j2+2zK3fBOL5b7c=
+github.com/mdp/qrterminal v1.0.1/go.mod h1:Z33WhxQe9B6CdW37HaVqcRKzP+kByF3q/qLxOGe12xQ=
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e h1:MRM5ITcdelLK2j1vwZ3Je0FKVCfqOLp5zO6trqMLYs0=
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e/go.mod h1:XV66xRDqSt+GTGFMVlhk3ULuV0y9ZmzeVGR4mloJI3M=
 github.com/snksoft/crc v1.1.0 h1:HkLdI4taFlgGGG1KvsWMpz78PkOC9TkPVpTV/cuWn48=
 github.com/snksoft/crc v1.1.0/go.mod h1:5/gUOsgAm7OmIhb6WJzw7w5g2zfJi4FrHYgGPdshE+A=
+rsc.io/qr v0.2.0 h1:6vBLea5/NRMVTz8V66gipeLycZMl/+UlFmk8DvqQ6WY=
+rsc.io/qr v0.2.0/go.mod h1:IF+uZjkb9fqyeF/4tlBoynqmQxUoPfWEKh921coOuXs=