Brazilian PIX Key Extension for Directus

A comprehensive Directus extension bundle for handling Brazilian PIX keys with validation, formatting, and beautiful displays.

🚀 Features

PIX Key Interface

  • Multi-type Support: CPF, CNPJ, Phone numbers, and Email addresses
  • Auto-detection: Automatically detects PIX key type based on input format
  • Real-time Validation: Validates keys using official Brazilian algorithms
  • Smart Formatting: Applies proper formatting as you type
  • Type Selection: Dropdown to manually select PIX key type
  • Configurable: Extensive configuration options for different use cases

PIX Key Display

  • Type Badges: Visual indicators showing the PIX key type
  • Copy to Clipboard: One-click copying with visual feedback
  • Privacy Mode: Option to mask sensitive information (CPF/CNPJ)
  • QR Code Generation: Generate QR codes for PIX keys (placeholder)
  • Responsive Design: Works on all screen sizes

📦 Installation

npm install directus-brazilian-pix

Manual Installation

  1. Download the latest release
  2. Extract to your Directus extensions folder
  3. Restart your Directus instance

🔧 Usage

Interface Configuration

Add the Brazilian PIX Key interface to any string field:

  1. Go to Settings > Data Model
  2. Select your collection and field
  3. Choose “Brazilian PIX Key” as the interface
  4. Configure the options as needed

Interface Options

Option Type Default Description
Auto-detect Type Boolean true Automatically detect PIX key type based on input
Allowed Types Array All types Restrict which PIX key types are allowed
Default Type String cpf Default type when creating new items
Validate Key Boolean true Enable validation using official algorithms
Required Boolean false Make the field required

Display Configuration

Configure the display to show PIX keys with type badges:

  1. Go to your collection layout
  2. Select the PIX key field
  3. Choose “Brazilian PIX Key Display” as the display
  4. Configure the display options

Display Options

Option Type Default Description
Show Type Badge Boolean true Display type badge (CPF, CNPJ, etc.)
Format Key Boolean true Apply formatting to displayed keys
Hide Partial Key Boolean false Mask part of the key for privacy
Copy to Clipboard Boolean true Enable copy functionality
Show QR Code Boolean false Show QR code generation button

📋 PIX Key Types

Supported Types

Type Description Format Example
CPF Individual taxpayer ID XXX.XXX.XXX-XX 123.456.789-01
CNPJ Company taxpayer ID XX.XXX.XXX/XXXX-XX 12.345.678/0001-90
Phone Mobile/landline number (XX) XXXXX-XXXX (11) 99999-9999
Email Email address user@domain.com usuario@email.com

Validation Rules

  • CPF: Validates using the official Brazilian CPF algorithm
  • CNPJ: Validates using the official Brazilian CNPJ algorithm
  • Phone: Validates area codes and mobile number formats
  • Email: Standard email format validation

🎨 Styling

The extension uses Directus design tokens and follows the system theme automatically.

Type Badge Colors

  • CPF: Blue (--blue)
  • CNPJ: Purple (--purple)
  • Phone: Green (--green)
  • Email: Orange (--orange)

📊 Data Storage

PIX keys are stored as JSON strings containing both the key and its type:

{
  "key": "12345678901",
  "type": "cpf"
}

This allows for:

  • Proper validation based on type
  • Correct formatting in displays
  • Type-aware functionality

🔧 Development

Prerequisites

  • Node.js 18+
  • Directus 10+

Local Development

# Clone the repository
git clone https://github.com/brunribeiro/directus-brazilian-pix.git

# Install dependencies
cd directus-brazilian-pix
npm install

# Build the extension
npm run build

# Link for development
npm run link

Building

npm run build

Validation

npm run validate

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

  • Follow the existing code style
  • Add tests for new features
  • Update documentation
  • Ensure all validations pass

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Issues & Support

Found a bug or need help? Please open an issue on GitHub.

🙏 Acknowledgments

  • Brazilian Central Bank for PIX key specifications
  • Directus team for the amazing extension SDK
  • The Brazilian development community

📈 Roadmap

  • Real QR Code generation
  • PIX key validation API integration
  • Bulk PIX key operations
  • Additional PIX key types (EVP - Random keys)
  • Export/import functionality