203 lines
2.3 KiB
Markdown
203 lines
2.3 KiB
Markdown
RUC Form Integration
|
|
1. Overview
|
|
|
|
This document defines the implementation of a RUC (Registro Único del Contribuyente) input form for the application.
|
|
|
|
The goal is to:
|
|
|
|
Collect valid Paraguayan RUC numbers
|
|
|
|
Reduce user input errors
|
|
|
|
Improve user experience
|
|
|
|
Ensure basic legal and invoicing compliance
|
|
|
|
The RUC field will be used for:
|
|
|
|
Invoicing
|
|
|
|
Payments
|
|
|
|
Registrations
|
|
|
|
Business verification
|
|
|
|
Tax-related records
|
|
|
|
2. RUC Format Specification
|
|
|
|
A valid RUC has the following structure:
|
|
|
|
6 to 8 digits + "-" + 1 check digit
|
|
|
|
|
|
Examples:
|
|
|
|
4521876-5
|
|
80012345-6
|
|
12345678-9
|
|
|
|
|
|
Rules:
|
|
|
|
Only numbers and one hyphen
|
|
|
|
The hyphen is always before the last digit
|
|
|
|
No spaces or letters allowed
|
|
|
|
Maximum length: 10 characters (including "-")
|
|
|
|
3. User Interface Requirements
|
|
3.1 Input Field
|
|
|
|
The RUC input field must:
|
|
|
|
Accept only numeric input
|
|
|
|
Auto-insert the hyphen
|
|
|
|
Show placeholder example
|
|
|
|
Display validation errors
|
|
|
|
Example UI:
|
|
|
|
[ RUC: 12345678-9 ]
|
|
|
|
|
|
Attributes:
|
|
|
|
Required field (when invoicing enabled)
|
|
|
|
Mobile-friendly
|
|
|
|
Copy-paste safe
|
|
|
|
Accessible (label + aria support)
|
|
|
|
3.2 Placeholder Text
|
|
|
|
Default placeholder:
|
|
|
|
12345678-9
|
|
|
|
|
|
Optional localized versions:
|
|
|
|
Spanish:
|
|
|
|
Ej: 12345678-9
|
|
|
|
|
|
English:
|
|
|
|
Example: 12345678-9
|
|
|
|
4. Client-Side Validation
|
|
4.1 Format Validation
|
|
|
|
The frontend must verify:
|
|
|
|
Pattern: /^[0-9]{6,8}-[0-9]{1}$/
|
|
|
|
Exactly one hyphen
|
|
|
|
Correct digit count
|
|
|
|
Invalid examples:
|
|
|
|
1234-5
|
|
123456789
|
|
ABC123-4
|
|
|
|
4.2 Check Digit Validation
|
|
|
|
The verification digit must be validated using modulo 11.
|
|
|
|
Purpose:
|
|
|
|
Detect mistyped RUC numbers
|
|
|
|
Prevent fake entries
|
|
|
|
Improve data quality
|
|
|
|
Validation occurs:
|
|
|
|
On input blur
|
|
|
|
On form submit
|
|
|
|
Before backend submission
|
|
|
|
4.3 Auto-Formatting
|
|
|
|
The system must:
|
|
|
|
Remove non-numeric characters
|
|
|
|
Automatically insert "-"
|
|
|
|
Limit input to 9 digits
|
|
|
|
Behavior:
|
|
|
|
User types:
|
|
|
|
45218765
|
|
|
|
|
|
System shows:
|
|
|
|
4521876-5
|
|
|
|
|
|
This improves usability and reduces errors.
|
|
|
|
5. Error Handling
|
|
5.1 Error Messages
|
|
|
|
When validation fails, show:
|
|
|
|
Format error:
|
|
|
|
Formato inválido. Ej: 12345678-9
|
|
|
|
|
|
Check digit error:
|
|
|
|
RUC inválido. Verifique el número.
|
|
|
|
|
|
Empty field:
|
|
|
|
Este campo es obligatorio.
|
|
|
|
|
|
Messages should be:
|
|
|
|
Clear
|
|
|
|
Short
|
|
|
|
Non-technical
|
|
|
|
Localized
|
|
|
|
5.2 Visual Feedback
|
|
|
|
Invalid input must:
|
|
|
|
Highlight input in red
|
|
|
|
Show error text below field
|
|
|
|
Disable submit if blocking
|
|
|
|
Valid input must:
|
|
|
|
Show neutral or success state
|
|
|
|
Remove error messages |