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