2.3 KiB
RUC Form Integration
- 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
- 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 "-")
- 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
- 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.
- 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