🇧🇷 Directus Brazilian Standards

Complete Brazilian formatting extensions for Directus - Currency (BRL), Postal Codes (CEP), and Tax IDs (CPF) with interfaces and displays.

✨ Features

🇧🇷 Brazilian Currency (BRL)

• Live formatting while typing (e.g., 215 → R$ 2,15)
• Smart input handling for different amounts
• Validation with min/max value support
• API returns numbers, not strings
• Examples:
  • Type 215 → shows R$ 2,15
  • Type 21578 → shows R$ 215,78
  • Type 2156789 → shows R$ 21.567,89

📮 Brazilian CEP (Postal Code)

• Automatic formatting (12345678 → 12.345-678)
• Real-time validation (8 digits required)
• Visual feedback with success/error indicators
• Stores clean numbers in database

👤 Brazilian CPF (Tax ID)

• Live formatting (12345678901 → 123.456.789-01)
• Full CPF validation using official algorithm
• Prevents invalid patterns (like 111.111.111-11)
• Visual validation feedback
• Privacy masking option for displays

🆔 CNPJ (Brazilian Company Tax ID)

• Interface: brazilian-cnpj
• Display: brazilian-cnpj
• Features:
  • Automatic formatting (XX.XXX.XXX/XXXX-XX)
  • Real-time validation using official algorithm
  • 🆕 Smart paste: Automatically cleans formatted CNPJs when pasted
  • 🆕 API Lookup: Automatic company data lookup via CNPJ.ws API
  • 🆕 Auto-fill mapping: Automatically populate other form fields
  • 🆕 Manual search trigger: Search button for user-controlled API calls

CNPJ API Lookup Configuration

The CNPJ interface now supports automatic company data lookup using the publica.cnpj.ws API:

1. Enable API Lookup: Toggle to enable CNPJ.ws API integration
2. API Token (Optional): For future commercial features (not required for public API)
3. Auto-fill Field Mapping: JSON mapping of API fields to form fields
4. Search Button: Manual trigger for API lookup (appears when API lookup is enabled)

How it works:

• User types CNPJ with automatic formatting and validation
• Smart paste: Copy formatted CNPJs (e.g., "33.000.167/0001-01") and paste directly - formatting is automatically cleaned and reapplied
• When API lookup is enabled, a search button (🔍) appears next to the input
• User clicks the search button to trigger company data lookup
• Mapped fields are automatically populated with company information

Example mapping:

{
  "company_name": "razao_social",
  "trade_name": "estabelecimento.nome_fantasia", 
  "complete_address": "estabelecimento.tipo_logradouro + ' ' + estabelecimento.logradouro + ', ' + estabelecimento.numero + ' - ' + estabelecimento.complemento",
  "city": "estabelecimento.cidade.nome",
  "state": "estabelecimento.estado.sigla",
  "phone": "estabelecimento.telefone1",
  "email": "estabelecimento.email"
}

Mapping Format:

• Simple mapping: "form_field": "api_field"
• Concatenation: "form_field": "api_field1 + ' separator ' + api_field2"
• String literals: Use single or double quotes for static text
• Multiple fields: Combine any number of API fields with separators

Concatenation Examples:

{
  "full_address": "estabelecimento.tipo_logradouro + ' ' + estabelecimento.logradouro + ', ' + estabelecimento.numero",
  "contact_info": "estabelecimento.telefone1 + ' - ' + estabelecimento.email",
  "company_info": "razao_social + ' (' + estabelecimento.nome_fantasia + ')'"
}

Available API fields:

• razao_social - Company legal name
• capital_social - Share capital
• natureza_juridica.descricao - Legal nature description
• porte.descricao - Company size description
• estabelecimento.nome_fantasia - Trade name
• estabelecimento.email - Email address
• estabelecimento.telefone1 - Primary phone
• estabelecimento.telefone2 - Secondary phone
• estabelecimento.logradouro - Street address
• estabelecimento.numero - Street number
• estabelecimento.complemento - Address complement
• estabelecimento.bairro - Neighborhood
• estabelecimento.cidade.nome - City name
• estabelecimento.estado.nome - State name
• estabelecimento.estado.sigla - State abbreviation
• estabelecimento.cep - ZIP code
• estabelecimento.situacao_cadastral - Registration status
• estabelecimento.data_inicio_atividade - Activity start date
• estabelecimento.atividade_principal.descricao - Main activity description

📦 Installation

Via NPM

npm install directus-brazilian-standards

🐛 v1.4.1 Bug Fix: Fixed critical currency formatting issue where typing 10000 displayed as R$ 100,00 instead of R$ 10.000,00

Via Directus Marketplace

1. Go to Settings → Extensions → Marketplace
2. Search for "Brazilian Standards"
3. Click Install

🚀 Usage

Currency Fields

1. Create field → Type: Decimal → Precision: 12,2
2. Interface: Brazilian Currency (BRL)
3. Display: Brazilian Currency (BRL)
4. Configure options as needed

CEP Fields

1. Create field → Type: String → Max Length: 8
2. Interface: Brazilian CEP
3. Display: Brazilian CEP
4. Enable validation as needed

CPF Fields

1. Create field → Type: String → Max Length: 11
2. Interface: Brazilian CPF
3. Display: Brazilian CPF  
4. Enable CPF validation as needed

CNPJ with API Lookup

1. Configure the field with Brazilian CNPJ interface
2. Enable "Enable API Lookup" option
3. (Optional) Add CNPJ.ws API token for commercial features
4. Configure "Auto-fill Field Mapping" with your desired field mappings
5. When users type a valid CNPJ, the extension will:
   • Validate the CNPJ format
   • Query CNPJ.ws API for company data
   • Automatically fill mapped fields with company information

📊 API Response Examples

Currency Field

{
  "price": 1299.99,           // Number, perfect for calculations
  "total": 25000.50          // No string conversion needed
}

CEP Field

{
  "postal_code": "77360016"   // Clean numbers for integrations
}

CPF Field

{
  "tax_id": "01958284106"     // Clean numbers for validation
}

⚙️ Configuration Options

Currency Interface

• Placeholder: Custom placeholder text (default: "R$ 0,00")
• Min Value: Minimum allowed value in BRL
• Max Value: Maximum allowed value in BRL
• Disabled: Disable input

Currency Display

• Show Currency Symbol: Toggle R$ symbol display
• Decimal Places: Number of decimal places (default: 2)

CEP Interface

• Placeholder: Custom placeholder text (default: "12.345-678")
• Required: Make field required
• Validate CEP: Enable format validation (8 digits)
• Disabled: Disable input

CEP Display

• Show Placeholder for Empty: Show placeholder for empty values

CPF Interface

• Placeholder: Custom placeholder text (default: "123.456.789-01")
• Required: Make field required
• Validate CPF: Enable full CPF validation with algorithm
• Disabled: Disable input

CPF Display

• Show Placeholder for Empty: Show placeholder for empty values
• Mask Digits for Privacy: Show as ..*- for privacy

🛠️ Development

This package includes both interfaces (for input/editing) and displays (for read-only views).

Interfaces Included:

• brazilian-currency - Currency input with live formatting
• brazilian-cep - CEP input with validation
• brazilian-cpf - CPF input with validation
• brazilian-cnpj - CNPJ input with validation and API lookup

Displays Included:

• brazilian-currency-display - Currency display with Brazilian formatting
• brazilian-cep-display - CEP display with formatting
• brazilian-cpf-display - CPF display with formatting and privacy options
• brazilian-cnpj-display - CNPJ display with formatting and API lookup

🌟 Why Use This Extension?

✅ Professional UX

Brazilian users see familiar formatting they expect

✅ Data Integrity

Proper validation prevents invalid entries

✅ API Efficiency

Clean data storage, no string parsing needed

✅ Developer Friendly

Easy to use, well-documented, TypeScript support

✅ Production Ready

Thoroughly tested, used in production systems

🔧 Requirements

• Directus: ^10.10.0
• Node.js: >=18.0.0

📝 Examples in Action

Currency Input

User types: 1000
Display shows: R$ 10,00
Database stores: 10.00

CEP Input

User types: 77360016
Display shows: 77.360-016
Database stores: "77360016"

CPF Input

User types: 01958284106
Display shows: 019.582.841-06
Database stores: "01958284106"

CNPJ Input

User types: 33.000.167/0001-01
Display shows: 33.000.167/0001-01
Database stores: "33.000.167/0001-01"

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

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

👨‍💻 Author

Bruno Ribeiro

• GitHub: @brunribeiro
• Project: Directus Renovando

🙏 Acknowledgments

• Built for the Brazilian Directus community
• Follows official Brazilian formatting standards
• Uses proper pt-BR locale formatting
• Implements official CPF validation algorithm

Made with ❤️ for the Brazilian developer community 🇧🇷

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.5.0] - 2024-12-18

Added

• CNPJ API Lookup Integration: Complete integration with CNPJ.ws API for automatic company data lookup
• Smart Paste Feature: Automatically cleans formatted CNPJs when pasted (e.g., "33.000.167/0001-01" → cleaned and reformatted)
• Auto-fill Field Mapping: JSON-based field mapping system for automatic form population
• Manual Search Trigger: Search button (🔍) for user-controlled API calls
• Text Formatting: Automatic Title Case conversion for ALL CAPS API responses
• Advanced Field Mapping: Support for concatenation expressions with string literals
• DOM-based Field Updates: Robust field updating that simulates user interaction for proper Directus integration

Enhanced

• CNPJ Interface: Now includes API lookup toggle, token field, and mapping configuration
• CNPJ Display: Improved formatting and validation feedback
• Field Validation: Better integration with Directus form validation system
• Error Handling: Comprehensive error handling for API calls and field updates

Technical Improvements

• Vue 3 Composition API: Full migration to modern Vue patterns
• TypeScript Support: Enhanced type safety and development experience
• Event Simulation: Proper field update events for Directus compatibility
• Reactive Updates: Improved reactivity and UI responsiveness

API Integration Details

• CNPJ.ws API: Free public API integration for company data lookup
• Field Mapping Examples:
  • Simple: "company_name": "razao_social"
  • Concatenation: "full_address": "estabelecimento.tipo_logradouro + ' ' + estabelecimento.logradouro + ', ' + estabelecimento.numero"
• Available API Fields: Complete company information including address, contact, and legal details

[1.4.1] - 2024-12-15

Fixed

• Currency Bug: Fixed critical issue where typing 10000 displayed as R$ 100,00 instead of R$ 10.000,00

[1.4.0] - 2024-12-10

Added

• Phone Number Interface: Brazilian phone number formatting and validation
• Phone Number Display: Formatted phone number display with proper Brazilian formatting

Enhanced

• Currency Interface: Improved decimal handling and validation
• CEP Interface: Better postal code validation and formatting
• CPF Interface: Enhanced tax ID validation with algorithm checking

[1.3.0] - 2024-12-05

Added

• Currency Interface: Brazilian Real (BRL) currency formatting with live input
• Currency Display: Formatted currency display with customizable decimal places
• CNPJ Interface: Brazilian company tax ID formatting and validation
• CNPJ Display: Formatted CNPJ display with validation indicators

Enhanced

• CPF Validation: Improved algorithm validation for Brazilian tax IDs
• CEP Formatting: Better postal code formatting and validation

[1.2.0] - 2024-11-28

Added

• Bundle Extension: Converted to bundle extension for better performance
• Display Components: Added display components for all interfaces

Enhanced

• Code Organization: Improved project structure and maintainability
• Build Process: Optimized build configuration

[1.1.0] - 2024-11-20

Added

• CEP Interface: Brazilian postal code formatting and validation
• CPF Interface: Brazilian tax ID formatting and validation

Enhanced

• TypeScript Support: Full TypeScript implementation
• Validation System: Comprehensive validation for Brazilian standards

[1.0.0] - 2024-11-15

Added

• Initial release with basic Brazilian formatting support
• Project setup and configuration
• Basic interface structure

Release Notes

Version 1.5.0 Highlights

This major release introduces CNPJ API Integration, making it the most comprehensive Brazilian business data extension for Directus:

🆕 CNPJ API Lookup: Automatically fetch company data from CNPJ.ws API 🆕 Smart Paste: Clean formatted CNPJs automatically when pasting 🆕 Auto-fill Mapping: Configure which fields get populated with company data 🆕 Manual Search: User-controlled API calls with search button 🆕 Text Formatting: Convert ALL CAPS responses to proper Title Case

Perfect for: Business directories, CRM systems, invoice management, customer databases, and any application dealing with Brazilian companies.

Compatibility: Directus 10+ with Vue 3 and modern TypeScript support.