Complete Brazilian formatting extensions for Directus - Currency (BRL), Postal Codes (CEP), Tax IDs (CPF/CNPJ), and Phone Numbers with interfaces and displays
npm install directus-brazilian-standardsComplete Brazilian formatting extensions for Directus - Currency (BRL), Postal Codes (CEP), and Tax IDs (CPF) with interfaces and displays.


215 → shows R$ 2,1521578 → shows R$ 215,782156789 → shows R$ 21.567,89brazilian-cnpjbrazilian-cnpj#### 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:
``json`
{
"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""form_field": "api_field1 + ' separator ' + api_field2"
- Concatenation:
- String literals: Use single or double quotes for static text
- Multiple fields: Combine any number of API fields with separators
Concatenation Examples:
`json`
{
"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 namecapital_social
- - Share capitalnatureza_juridica.descricao
- - Legal nature descriptionporte.descricao
- - Company size descriptionestabelecimento.nome_fantasia
- - Trade nameestabelecimento.email
- - Email addressestabelecimento.telefone1
- - Primary phoneestabelecimento.telefone2
- - Secondary phoneestabelecimento.logradouro
- - Street addressestabelecimento.numero
- - Street numberestabelecimento.complemento
- - Address complementestabelecimento.bairro
- - Neighborhoodestabelecimento.cidade.nome
- - City nameestabelecimento.estado.nome
- - State nameestabelecimento.estado.sigla
- - State abbreviationestabelecimento.cep
- - ZIP codeestabelecimento.situacao_cadastral
- - Registration statusestabelecimento.data_inicio_atividade
- - Activity start dateestabelecimento.atividade_principal.descricao
- - Main activity description
bash
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$3
1. Go to Settings → Extensions → Marketplace
2. Search for "Brazilian Standards"
3. Click Install🚀 Usage
$3
`
1. Create field → Type: Decimal → Precision: 12,2
2. Interface: Brazilian Currency (BRL)
3. Display: Brazilian Currency (BRL)
4. Configure options as needed
`$3
`
1. Create field → Type: String → Max Length: 8
2. Interface: Brazilian CEP
3. Display: Brazilian CEP
4. Enable validation as needed
`$3
`
1. Create field → Type: String → Max Length: 11
2. Interface: Brazilian CPF
3. Display: Brazilian CPF
4. Enable CPF validation as needed
`$3
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
$3
`json
{
"price": 1299.99, // Number, perfect for calculations
"total": 25000.50 // No string conversion needed
}
`$3
`json
{
"postal_code": "77360016" // Clean numbers for integrations
}
`$3
`json
{
"tax_id": "01958284106" // Clean numbers for validation
}
`⚙️ Configuration Options
$3
- 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$3
- Show Currency Symbol: Toggle R$ symbol display
- Decimal Places: Number of decimal places (default: 2)$3
- Placeholder: Custom placeholder text (default: "12.345-678")
- Required: Make field required
- Validate CEP: Enable format validation (8 digits)
- Disabled: Disable input$3
- Show Placeholder for Empty: Show placeholder for empty values$3
- Placeholder: Custom placeholder text (default: "123.456.789-01")
- Required: Make field required
- Validate CPF: Enable full CPF validation with algorithm
- Disabled: Disable input$3
- 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).
$3
- 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$3
- 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?
$3
Brazilian users see familiar formatting they expect$3
Proper validation prevents invalid entries$3
Clean data storage, no string parsing needed$3
Easy to use, well-documented, TypeScript support$3
Thoroughly tested, used in production systems🔧 Requirements
- Directus: ^10.10.0
- Node.js: >=18.0.0
📝 Examples in Action
$3
`
User types: 1000
Display shows: R$ 10,00
Database stores: 10.00
`$3
`
User types: 77360016
Display shows: 77.360-016
Database stores: "77360016"
`$3
`
User types: 01958284106
Display shows: 019.582.841-06
Database stores: "01958284106"
`$3
`
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 🇧🇷
🎯 Funcionalidades
$3
- Interface: Campo de entrada com formatação automática (XXXXX-XXX)
- Display: Visualização formatada do CEP
- Validação: Estrutura e dígitos válidos
- API Lookup: Busca automática de endereço via ViaCEP
- Preenchimento automático: Campos de endereço baseados na API
- Title Case: Conversão automática de texto em MAIÚSCULAS$3
#### Mapeamento de Campos
`json
{
"logradouro": "logradouro",
"bairro": "bairro",
"cidade": "localidade",
"estado": "uf"
}
`#### Concatenação de Campos
`json
{
"address": "logradouro + ', ' + bairro",
"estado": "uf",
"cidade": "localidade"
}
`$3
- Interface: Campo de entrada com formatação (XX.XXX.XXX/XXXX-XX)
- Display: Visualização formatada do CNPJ
- Validação: Algoritmo oficial de validação de CNPJ
- API Lookup: Busca dados da empresa via CNPJ.ws
- Preenchimento automático: Razão social, endereço, telefone, etc.$3
- Interface: Campo de entrada com formatação (XXX.XXX.XXX-XX)
- Display: Visualização formatada do CPF
- Validação: Algoritmo oficial de validação de CPF$3
- Interface: Campo de entrada com formatação brasileira ((XX) XXXXX-XXXX)
- Display: Visualização formatada do telefone
- Validação: Códigos de área e números válidos$3
- Interface: Campo de entrada com formatação monetária (R$ 0,00)
- Display: Visualização formatada em reais🛠️ Instalação
1. Baixe a extensão compilada ou compile do código fonte
2. Coloque no diretório extensions do seu Directus
3. Reinicie o Directus para carregar as extensões
🔧 Compilação
`bash
npm install
npm run build
`📋 Requisitos
- Directus 10+
- Node.js 16+
- TypeScript (para desenvolvimento)
🎨 Interface de Configuração
Todas as interfaces possuem configurações simples e intuitivas:
- Habilitação de validação
- Configuração de API lookup
- Mapeamento de campos
- Placeholder personalizado
🔍 Debug e Troubleshooting
$3
O sistema inclui logs detalhados no console do navegador:`
🔗 Processing relational field: state
🔍 Looking up states where uf = "SP"
✅ Found states ID: 25
✅ Mapped field: state = 25 (relational)
`$3
Erro de Autenticação:
- Verifique se o usuário tem permissão de leitura nas collections relacionais
- Token de autenticação deve estar válido
Campo não encontrado:
- Confirme se o nome da collection está correto
- Verifique se o campo de busca existe na collection
- Teste com um filtro manual no Directus
📚 Documentação das APIs
$3
- URL: https://viacep.com.br/
- Formato: https://viacep.com.br/ws/{cep}/json/
- Campos retornados: cep, logradouro, bairro, localidade, uf, etc.$3
- URL: https://cnpj.ws/
- Formato: https://cnpj.ws/{cnpj}`MIT License - veja LICENSE para detalhes.
Contribuições são bem-vindas! Por favor:
1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request
Use as Issues do GitHub para reportar bugs, incluindo:
- Versão do Directus
- Versão da extensão
- Passos para reproduzir
- Logs do console (se aplicável)
---
Desenvolvido com ❤️ para a comunidade brasileira do Directus