Skip to content
back to search

OCA/l10n-paraguay · 18.0

Paraguay - Electronic Invoicing Base

l10n_py_edi_base

LGPL-3Accounting/Localizations/EDIv18.0.1.0.02updated 9 days ago
search codeOCA runboatGitHubgithub

Odoo Community Association

Paraguay - Electronic Invoicing Base

Beta License: LGPL-3 OCA/l10n-paraguay Translate me on Weblate Try me on Runboat

Paraguay - Electronic Invoicing Base

This module provides the base functionality for electronic invoicing (facturación electrónica) in Paraguay, compliant with SET (Subsecretaría de Estado de Tributación) requirements.

Features

Document Types Support

  • Factura Electrónica: Electronic invoice
  • Nota de Crédito Electrónica: Electronic credit note
  • Nota de Débito Electrónica: Electronic debit note
  • Nota de Remisión Electrónica: Electronic delivery note
  • Autofactura Electrónica: Electronic self-invoice

Core Functionality

  • Data Models: Complete models for electronic documents
  • Field Extensions: Enhanced account.move, res.partner, and res.company
  • Fiscal Validation: RUC and DV validation
  • JSON Builder: Automatic generation of JSON for SIFEN
  • QR Code Generation: Ready for KUDE (Código Único de Documento Electrónico)
  • Log System: Complete audit trail of EDI operations

Compliance

  • SIFEN Compatible: Sistema Integrado de Facturación Electrónica Nacional
  • SET Requirements: Meets all SET regulatory requirements
  • Contingency Mode: Support for offline operation
  • KUDE Support: Ready for electronic document codes

Integration Ready

This is a base module that requires a connector:

  • l10n_py_edi_factpy: FactPy integration
  • l10n_py_edi_facturasend: FacturaSend integration

Technical Architecture

  • Provider-agnostic: Works with multiple EDI providers
  • Extensible: Easy to add new document types
  • Robust: Error handling and retry mechanisms
  • Auditable: Complete logging of all operations

Dependencies

  • account: Core accounting
  • l10n_py_base: Base Paraguayan localization
  • l10n_py_account: Accounting extensions (timbrado management)
  • product: Product management
  • sale: Sales management

Table of contents

Installation

Installation

Prerequisites

Required Modules

  • Odoo 16.0
  • account: Core accounting module
  • l10n_py_base: Paraguayan base localization
  • l10n_py_account: Accounting extensions with timbrado
  • product: Product management
  • sale: Sales management

Required Python Packages

The module requires these Python packages:

  • qrcode: QR code generation
  • requests: HTTP client for API calls
  • cryptography: Encryption and security

EDI Provider

You must choose and configure one provider:

  • FactPy (install l10n_py_edi_factpy)
  • FacturaSend (install l10n_py_edi_facturasend)

Installation Steps

Step 1: Install Dependencies

Install required Python packages:

pip install qrcode requests cryptography

Step 2: Install Base Modules

  1. Install prerequisites in order:
    • l10n_py_base
    • l10n_py_account

Step 3: Install EDI Base

  1. Go to Apps
  2. Click Update Apps List
  3. Search for "Paraguay - Electronic Invoicing Base"
  4. Click Install

Step 4: Install EDI Connector

Choose and install a connector:

Option A: FactPy
  1. Search for "Paraguay - FactPy EDI Connector"
  2. Click Install
Option B: FacturaSend
  1. Search for "Paraguay - FacturaSend EDI Connector"
  2. Click Install

Post-Installation Configuration

Step 1: Verify Installation

Check that new menus appear:

  • Facturación Electrónica main menu
  • EDI Logs submenu
  • Connectors submenu

Step 2: Configure Company

  1. Go to Settings > Companies
  2. Edit your company
  3. Configure Electronic Invoicing tab:
    • Enable EDI
    • Select environment (Test/Production)
    • Choose provider

Step 3: Configure EDI Provider

Follow provider-specific configuration:

  • See l10n_py_edi_factpy documentation, or
  • See l10n_py_edi_facturasend documentation

Step 4: Configure Security

  1. Go to Settings > Users & Companies > Groups
  2. Assign users to EDI groups:
    • Electronic Invoicing / User
    • Electronic Invoicing / Manager

Step 5: Initial Test

  1. Set environment to Test
  2. Create a test invoice
  3. Try sending to EDI
  4. Verify reception and approval
  5. Check logs for errors

Data Initialization

The module loads:

  • Electronic document type definitions
  • Cron job configurations
  • Email templates
  • Report templates

No manual data loading required.

System Parameters

Configure in Settings > Technical > Parameters > System Parameters:

ParameterDescriptionExample
l10n_py.edi_providerActive EDI providerfactpy or facturasend
l10n_py.edi_environmentEnvironmenttest or production
l10n_py.edi_auto_sendAuto-send on confirmTrue or False

Database Preparation

Existing Invoices

For existing invoices (pre-EDI):

  • They will NOT be sent to EDI automatically
  • You can migrate them manually if needed
  • New invoices will use EDI

Product Updates

Update products with:

  1. Tax configuration
  2. NCM codes (if applicable)
  3. GTIN/barcodes

Partner Updates

Ensure all partners have:

  1. Complete address
  2. Valid RUC (for taxpayers)
  3. Email address
  4. Taxpayer type

Testing Checklist

Before going to production:

  • Test environment configured
  • Test credentials working
  • Sample invoice sent successfully
  • PDF download works
  • XML download works
  • QR code generates correctly
  • Status updates work
  • Credit note flow tested
  • Cancellation tested
  • Error handling tested
  • Email sending tested
  • All users have correct permissions

Production Deployment

Pre-Production

  1. Backup database
  2. Complete all testing
  3. Train users
  4. Prepare support documentation

Go-Live

  1. Switch to production environment
  2. Update provider credentials
  3. Configure production parameters
  4. Send first real invoice
  5. Monitor logs closely

Post-Go-Live

  1. Monitor EDI logs daily
  2. Check success rate
  3. Respond to errors quickly
  4. Keep system updated

Troubleshooting Installation

Python Packages Not Found

If packages are missing:

pip install -r requirements.txt

Or install individually:

pip install qrcode requests cryptography

Module Not Installing

If installation fails:

  1. Check Odoo logs
  2. Verify all dependencies installed
  3. Check file permissions
  4. Restart Odoo server

If menus don't show:

  1. Check user permissions
  2. Refresh browser
  3. Clear browser cache
  4. Verify module is installed (not just downloaded)

Uninstallation

To uninstall (not recommended):

  1. First uninstall connector module
  2. Then uninstall base module
  3. Data will be preserved but EDI features disabled

Warning: Uninstalling will:

  • Disable EDI functionality
  • Remove EDI menus
  • Keep existing data but make it inaccessible

Upgrade Notes

When upgrading:

  1. Backup database first
  2. Test in staging environment
  3. Check changelog for breaking changes
  4. Update connectors to matching versions
  5. Test EDI functionality after upgrade

Configuration

Configuration

Initial Setup

Step 1: Company Configuration

  1. Go to Settings > General Settings > Companies
  2. Edit your company
  3. Navigate to Electronic Invoicing tab:
    • Enable Electronic Invoicing
    • Configure Environment (Test/Production)
    • Set EDI Provider (factpy/facturasend)

Step 2: Select EDI Provider

Choose and configure your provider:

Option A: FactPy
  1. Install l10n_py_edi_factpy module
  2. Configure credentials in connector settings
Option B: FacturaSend
  1. Install l10n_py_edi_facturasend module
  2. Configure credentials in connector settings

Step 3: Configure Products

For each product/service:

  1. Go to Products
  2. Edit product
  3. In Invoicing tab:
    • Set NCM Code (if applicable)
    • Configure GTIN (barcode for SET)
    • Set tax information

Step 4: Partner Configuration

Ensure customers have complete fiscal data:

  1. Valid RUC (if taxpayer)
  2. Correct Taxpayer Type
  3. Complete Address (required for electronic invoicing)
  4. Email (for sending electronic documents)

Document Type Configuration

Available Document Types

The module pre-configures these document types:

  • Factura Electrónica (1): Standard invoice
  • Nota de Crédito (4): Credit note
  • Nota de Débito (5): Debit note
  • Nota de Remisión (7): Delivery note
  • Autofactura (2): Self-invoice

Journal Configuration

  1. Go to Accounting > Configuration > Journals
  2. For each sales journal:
    • Enable Electronic Invoicing
    • Select Document Type
    • Ensure timbrado is configured

Security Groups

Configure user permissions:

  1. Go to Settings > Users & Companies > Users
  2. Edit user
  3. In Electronic Invoicing section:
    • User: Can create and send documents
    • Manager: Can configure and cancel documents

Automatic Operations

Cron Jobs

The module includes automatic jobs:

  1. Check Document Status: Polls provider for status updates
  2. Retry Failed Documents: Attempts to resend failed documents

Configure in Settings > Technical > Automation > Scheduled Actions:

  • Adjust frequency as needed
  • Enable/disable jobs

Automatic Sending

Configure automatic sending on invoice confirmation:

  1. Go to company settings
  2. In Electronic Invoicing tab:
    • Enable Auto Send on Confirm
    • Set Auto Download PDF/XML

Environment Configuration

Test Environment

For testing:

  1. Set Environment = "Test"
  2. Use test credentials from provider
  3. Documents won't be legally valid

Production Environment

For production:

  1. Set Environment = "Production"
  2. Use production credentials
  3. Ensure all fiscal data is accurate
  4. Test thoroughly before going live

KUDE Configuration

KUDE (Código Único de Documento Electrónico) settings:

  1. QR codes are generated automatically
  2. Configure QR size in report templates if needed
  3. KUDE appears on printed invoices

Contingency Mode

Configure fallback when EDI service is unavailable:

  1. Enable Contingency Mode in company settings
  2. Set Contingency Reason options
  3. Documents can be sent later when service recovers

Email Configuration

For automatic email sending:

  1. Configure Outgoing Mail Server in Odoo
  2. Set email template in Settings > Technical > Email Templates
  3. Customize "Electronic Invoice" template

Usage

Usage

Sending Electronic Invoices

Method 1: Automatic Sending

If auto-send is enabled:

  1. Create invoice as usual
  2. Click Confirm
  3. System automatically sends to EDI provider
  4. Status updates to "Sent" when successful

Method 2: Manual Sending

  1. Create and confirm invoice
  2. Click Send EDI button
  3. Wizard appears - review information
  4. Click Send
  5. Wait for confirmation

Document Status

Electronic invoices have these statuses:

  • Draft: Not yet confirmed
  • To Send: Confirmed, ready to send
  • Sending: Being sent to provider
  • Sent: Successfully sent
  • Approved: Approved by SET
  • Rejected: Rejected by SET
  • Cancelled: Cancelled document
  • Error: Error occurred

Checking Document Status

View Status

  1. Open invoice
  2. Check EDI Status field
  3. View EDI Information tab for details

Manual Status Update

To manually check status:

  1. Open invoice
  2. Click Update EDI Status button
  3. System queries provider
  4. Status and messages update

Cancelling Electronic Documents

Requirements

  • Document must be approved by SET
  • Within cancellation timeframe (per SET rules)
  • Valid cancellation reason

Process

  1. Open approved invoice
  2. Click Cancel EDI button
  3. Select Cancellation Reason
  4. Enter Reason Details
  5. Click Cancel Document
  6. System sends cancellation to SET

Downloading Documents

PDF Download

  1. Open invoice
  2. Click Download EDI PDF button
  3. PDF opens/downloads
  4. Contains KUDE QR code

XML Download

  1. Open invoice
  2. Click Download EDI XML button
  3. XML file downloads
  4. Valid SET-compliant XML

Credit and Debit Notes

Creating Credit Note

  1. From invoice, click Add Credit Note
  2. Select reason
  3. System creates note with EDI reference
  4. Send to EDI as usual

Creating Debit Note

  1. From invoice, click Add Debit Note
  2. Enter reason
  3. System creates note with EDI reference
  4. Send to EDI as usual

Monitoring EDI Operations

EDI Log

View all EDI operations:

  1. Go to Facturación Electrónica > EDI Logs
  2. Filter by:
    • Document
    • Status
    • Date
    • Error type

Error Handling

When errors occur:

  1. Check EDI Logs for details
  2. Review error message
  3. Fix issue (e.g., missing data)
  4. Click Retry button
  5. Document resends

Printing KUDE

Invoice with KUDE

When printing invoices:

  1. Click Print on invoice
  2. Select KUDE Report
  3. Report includes:
    • QR code
    • CDC (Código de Control)
    • All fiscal information
    • SET-compliant format

QR Code

The QR code contains:

  • Document number
  • RUC
  • CDC
  • Amounts
  • Validation URL

Customers can scan to verify authenticity.

Batch Operations

Sending Multiple Documents

  1. Go to invoice list view
  2. Select multiple invoices
  3. Click Action > Send EDI
  4. System sends all selected documents
  5. Check status individually

Updating Multiple Statuses

  1. Select documents
  2. Click Action > Update EDI Status
  3. System checks all selected documents

Customer Portal

Customers can:

  1. Access their invoices via portal
  2. Download PDF with KUDE
  3. Download XML if needed
  4. View EDI status

Reports and Analytics

EDI Dashboard

View EDI metrics:

  1. Go to Facturación Electrónica > Dashboard
  2. See:
    • Documents sent today/week/month
    • Success rate
    • Pending documents
    • Errors

Custom Reports

Create custom reports:

  1. Use invoice filters
  2. Filter by EDI Status
  3. Group by status, date, customer
  4. Export to Excel

Troubleshooting Common Issues

Issue: "Missing Customer Email"

Solution:

  1. Add email to customer record
  2. Retry sending

Issue: "Invalid RUC"

Solution:

  1. Verify customer RUC format
  2. Check verification digit
  3. Update customer record
  4. Retry

Issue: "Timbrado Expired"

Solution:

  1. Update timbrado in journal
  2. May need to cancel and recreate invoice

Issue: "Connection Error"

Solution:

  1. Check internet connection
  2. Verify provider credentials
  3. Check provider service status
  4. Try again or enable contingency mode

Best Practices

  1. Test First: Use test environment before production
  2. Monitor Logs: Regularly check EDI logs
  3. Keep Updated: Update status of pending documents
  4. Backup: Download and store PDF/XML copies
  5. Validate: Ensure all fiscal data is complete before sending

Known issues / Roadmap

Roadmap

Current Version: 16.0.1.0.0

This document outlines planned features and improvements for the Paraguay Electronic Invoicing module.

Short Term (Next Release)

Enhanced Validation

  • More comprehensive RUC validation
  • Automatic DV calculation for RUC
  • Product code validation against SET catalog
  • Real-time validation before sending

Improved User Experience

  • Better error messages with suggested fixes
  • Inline EDI status on invoice form
  • Dashboard with EDI statistics
  • Bulk operations improvement

Additional Reports

  • Monthly EDI summary report
  • Tax authority compliance report
  • Document tracking report
  • Error analysis report

Medium Term (2-3 Releases)

Additional Document Types

  • Comprobante de Retención (Retention receipt)
  • Factura de Exportación (Export invoice)
  • Factura de Importación (Import invoice)
  • Boleta de Venta (Sales receipt)

Integration Enhancements

  • Direct SIFEN integration (bypass third-party)
  • Webhook support for status updates
  • Batch sending optimization
  • Offline mode improvements

Advanced Features

  • Electronic credit management
  • Payment integration with electronic documents
  • Multi-currency support for EDI
  • Document routing rules

Compliance Updates

  • Support for SET regulation changes
  • Enhanced contingency mode
  • Document versioning
  • Legal archive management (7-year retention)

Long Term (Future Vision)

AI and Automation

  • Intelligent error detection and correction
  • Automatic document classification
  • Predictive timbrado expiration alerts
  • Smart retry strategies

Integration Ecosystem

  • Point of Sale (POS) integration
  • E-commerce integration
  • Accounting software exports
  • Bank reconciliation integration

Analytics and Intelligence

  • Advanced EDI analytics
  • Customer behavior insights
  • Tax optimization suggestions
  • Compliance scoring

Mobile Support

  • Mobile app for document approval
  • QR code scanning verification
  • Mobile notifications
  • Offline mobile capabilities

Additional Providers

  • Additional EDI provider integrations
  • Provider comparison tools
  • Automatic failover between providers
  • Cost optimization across providers

Technical Improvements

Performance

  • Asynchronous document sending
  • Caching layer for provider responses
  • Database query optimization
  • Bulk operation performance

Code Quality

  • Increase test coverage to 90%+
  • API documentation
  • Developer guide
  • Code refactoring for maintainability

Security

  • Enhanced credential encryption
  • Audit trail improvements
  • Role-based access control refinement
  • Security compliance certifications

Community Requests

We track community feature requests. Top requests:

  1. Multi-company enhancements - Better support for groups
  2. Import automation - Automatically import vendor electronic invoices
  3. API exposure - REST API for external systems
  4. Customs integration - Integration with customs systems
  5. Transportation documents - Support for e-transport documents

Contributing

Want to contribute to the roadmap?

  1. Submit feature requests via GitHub issues
  2. Vote on existing feature requests
  3. Contribute code via pull requests
  4. Join development discussions

Version Planning

v16.0.2.0.0 (Q2 2024)

  • Enhanced validation
  • Additional reports
  • UX improvements

v16.0.3.0.0 (Q3 2024)

  • New document types
  • Improved integrations
  • Performance optimizations

v17.0.1.0.0 (Q4 2024)

  • Odoo 17 migration
  • New features from roadmap
  • Architecture improvements

Deprecation Notices

Planned Deprecations

  • Legacy provider adapters will be deprecated in v17.0
  • Old XML format support ends in v16.0.5.0.0
  • Python 3.7 support ends with v16.0 series

Migration Paths

Documentation will be provided for all deprecations with clear migration paths and timelines.

Feedback

This roadmap is subject to change based on:

  • SET regulatory changes
  • Community feedback
  • Technical constraints
  • Resource availability

Submit feedback:

  • GitHub issues
  • Community forums
  • Direct contact with maintainers

Last updated: 2024

Bug Tracker

Bugs are tracked on GitHub Issues. In case of trouble, please check there if your issue has already been reported. If you spotted it first, help us to smash it by providing a detailed and welcomed feedback.

Do not contact contributors directly about support or help with technical issues.

Credits

Authors

  • KMEE

Maintainers

This module is maintained by the OCA.

Odoo Community Association

OCA, or the Odoo Community Association, is a nonprofit organization whose mission is to support the collaborative development of Odoo features and promote its widespread use.

This module is part of the OCA/l10n-paraguay project on GitHub.

You are welcome to contribute. To learn how please visit <https://odoo-community.org/page/Contribute>.