PTS Alegra
Complete documentation to install, configure, and use the PTS Alegra module in your PrestaShop store.
What is PTS Alegra?
PTS Alegra connects your PrestaShop store with Alegra so you can issue electronic invoices and credit notes straight from the order, keeping customers, products, carriers, bank accounts, numberings and withholdings in sync.
What each side does. The module is the bridge: the one that issues the documents and gives them fiscal validity is Alegra. That is why you need an Alegra account that is already up and running — with its user, its API token and its numberings registered — before you start. What the module adds is that all of it is used from the order page, without leaving PrestaShop.
Main Features
Billing from the order
The Alegra invoice is issued from the PrestaShop order page itself, and credit notes are created from there too.
Data matching
Products, carriers, customers, bank accounts and withholdings are matched with their Alegra counterparts so the invoice goes out with the right information.
Numberings per country
Each country can have its own Alegra numbering assigned, on top of the module's default numbering.
Ticket POS
Produces a point-of-sale ticket with the establishment details you configure in the module itself.
System Requirements
| Requirement |
Minimum |
Recommended |
| PrestaShop |
1.7.6 |
9.x |
| PHP |
7.2.5 |
8.1+ |
| PHP extensions |
curl, mbstring, openssl |
The same |
| Alegra account |
Active, with user and API token |
A sandbox account as well, for testing |
Installation
There are two methods to install the module in your PrestaShop store, depending on your server characteristics.
Method 1: Installation from Back Office
1
Access the Back Office
Log in to your PrestaShop store administration panel.
2
Navigate to Modules
Go to Modules → Module Manager in the side menu.
3
Upload the module
Click "Upload a module" and select the downloaded ZIP file.
4
Install and activate
Once uploaded, the module will install automatically. Click "Configure" to get started.
Method 2: FTP Installation
Use this method if the ZIP file is too large and your server doesn't allow uploading it from the Back Office due to upload size limitations.
1
Extract the ZIP file
Extract the contents of the ZIP file on your local computer.
2
Connect via FTP
Use an FTP client (like FileZilla) to connect to your server.
3
Upload the module folder
Upload the module folder to /modules/ in your PrestaShop installation.
4
Install from Back Office
Go to Modules → Module Manager, search for the module and click "Install".
Possible Installation Issues
Override Conflicts: During module installation or activation, issues related to override files may arise. This happens when another module has already modified the same PrestaShop core files.
If you experience override errors when installing or activating the module, don't try to resolve it yourself if you don't have technical experience. Contact our support team to receive personalized help and resolve the conflict safely.
Contact Support
Accounts
This is the module's first tab and the only one that shows while there is no connection to Alegra. It is where you register the Alegra accounts the store is going to work with. The module supports several, and one of them is later marked as the default account.
Note: It is necessary to configure the connection with Alegra to start using the module. Until there is a connected account, the remaining tabs are not shown.
The tab lists the accounts already connected and offers a Synchronize accounts button, which updates the status (active or inactive) of the accounts that already exist in Alegra.
Connection details
These are the four fields of the form that opens when you add an account. The last three are mandatory: without them the save button stays disabled.
Sandbox account
Marks the account as a test account. Use it to check how the module behaves without issuing documents in your real Alegra account.
User
The user of the Alegra account the store connects with.
User token
The API token Alegra generates for that user. It is what authorises the module to operate on the account.
Account country
The country the Alegra account belongs to. It conditions the fiscal behaviour of the documents issued with it.
General
Brings together the settings that govern how the module invoices. You reach them from Modules → PTS Alegra → Configure, in the General tab.
Important: except for Debug mode and Integration with Sales Commissions, every option in this tab stays disabled until you choose an Alegra account by default.
Debugging
Debug mode
Enables the module's debug log so you can diagnose its behaviour. Turning it on reveals the IP field.
IP
Restricts debugging to one IP address, so only that one sees the behaviour under test. The module includes a button that fills the field with the IP you are connected from.
Note: It is recommended that you enable this option to test the module in your store before enabling it for clients.
Integrations
Integration with Sales Commissions
Connects the module with PTS Sales Commissions. For the integration to work, that module has to be installed and active in the store: if it is not, switching this on here adds nothing to the billing screen.
Note: When enabled, you can select a seller during invoice creation to automatically assign them to the order for commission calculation.
Account and default values
Alegra account by default
Chooses which of the connected accounts the module uses to invoice. It is the option that unlocks the rest of the tab and the association tabs.
Note: Default account for billing and the first option to choose to associate information.
It is not always the one that invoices. It is the starting point, but a rule in Invoices → Restrictions can replace it for a specific customer or group. If you work with several accounts, look there before taking for granted which one an invoice will go out with.
Default ISO currency
Declares which is the base currency of your Alegra account. The options are Colombian Peso (COP) and Euro (EUR). It does not limit which currencies the store can sell in: it is the reference the module uses to decide whether an order is in its own currency or in a foreign one.
What changes depending on whether it matches. If the order is in this same currency, the invoice goes out directly. If it is in another one, the module checks that the currency exists in your Alegra account and that you have multi-currency enabled there, and it will ask you for the conversion rate when billing. If either of those two is missing, it tells you before creating the draft.
Default language for sending information
Determines which language the data the module sends to Alegra travels in.
Note: The selected language is for sending information, it is not for changing the language of the module.
Default numeration for invoices
The Alegra numbering applied to invoices when the order's country has no numbering of its own assigned in the Numerations tab.
Note: The numbering list will only show those that are of the type: automatic numbering.
Default ledger account for products
The Alegra ledger account assigned to the products the module creates or invoices when they do not have one of their own.
Delivery terms
The incoterm that accompanies the invoice. The list includes, among others, Cost and freight (CFR), Cost, freight and insurance (CIF), In factory (EXW) and Franco on board (FOB).
When it applies: the module marks the invoice as export when the billing address country is not Colombia; otherwise it marks it as national and this value does not come into play. It is optional.
Customer groups that cannot invoice
Select one or more PrestaShop customer groups whose orders cannot be invoiced with the module. It accepts several groups at once.
It looks at the customer's default group, not all of theirs. A customer who belongs to several groups is only excluded if the group listed here is the one set as their default group in their PrestaShop record.
Cost center
The Alegra cost center the invoices issued by the module are charged to.
Behaviour when billing
Show Ticket POS after billing
Once the invoice has been issued, it opens the point-of-sale ticket automatically.
Show the invoice created on another page
After creating the invoice, it opens it on a separate page instead of staying on the order page.
Issue invoice with automatic payment
The invoice is issued with the payment taken as recorded, without having to mark it in a later step.
Hide issue invoice button
Removes the issue invoice button from the order page. It is useful in stores where billing is not done by whoever manages the orders.
Customers and records
Save clients with second name and second surname
When creating the customer in Alegra, it spreads the PrestaShop first name and surnames across Alegra's four fields instead of two. It only applies to customers who are a natural person; companies are saved under their business name.
How it is split: the cut is made at the first space of each field. "Maria Fernanda" gives first name "Maria" and second name "Fernanda", but "Juan Carlos de la Vega" in the first name field would give second name "Carlos de la Vega". If your customers write compound names, check how they end up in Alegra before taking the setting as good.
Ignoring repeated customers
What is ignored is the duplicate check, not the customers: when enabled, Alegra accepts creating a new record even if another one already exists with the same identification number, instead of rejecting the request. Leave it off if you prefer a repeated identification to stop billing so you can review it.
Keep records of requests to Alegra
Lets you keep records of the requests made to Alegra that return an error. They are the ones that help diagnose an invoice that never got issued.
Associate
Groups the five screens that match PrestaShop data with Alegra data. They all follow the same pattern: a table with the existing associations and a form to add a new one. They only appear once an Alegra account by default has been chosen.
Products
Matches a store product with its equivalent product in Alegra, so the invoice line goes out with the right item.
Note: if the default Alegra account has no products created, the module says so: "No products were found created in the default Alegra account for the association."
Alegra product
The product from the Alegra account it is matched with.
Product
The PrestaShop store product to be matched.
Carriers
Matches each store carrier with an Alegra product, which is how Alegra represents the shipping charge inside the invoice.
Alegra product
The Alegra product that represents that carrier's shipping.
Carrier
The PrestaShop carrier to be matched.
Customers
Matches a store customer with their record in Alegra, so they are not duplicated when billing.
Alegra customer
The customer that already exists in Alegra.
Customer
The PrestaShop store customer.
Bank accounts
Relates a store payment method with the Alegra bank account the payment is recorded in.
Alegra bank account
The Alegra bank account where the payment is booked.
Currency
The bank account's currency.
Payment method
The PrestaShop payment method associated with that account.
Payment names
Lets you cover the variants under which the same method appears named in the orders.
Note: Exact payment names, separated by commas and spaces. Example: Card, PSE, Cash.
Retentions
Defines which Alegra withholding applies according to the order's country and payment method.
Country
The country the withholding applies to.
Payment method
The payment method the withholding applies to.
Retention
The Alegra withholding applied when both conditions above are met.
Invoices
Groups the list of issued invoices and the settings around it: who is allowed to invoice, what data the ticket carries, and how to bring back changes made in Alegra.
List of invoices
Shows the invoices the module has issued. Each row carries a colour according to its status, and the screen itself includes the legend:
- Invoice colour in Draft status.
- Invoice colour in Opened status.
- Invoice colour in Closed status.
- Colour of the orders that cannot be invoiced.
The actions of each row do the same as the order block, including Link existing Alegra invoice and Unlink invoice. The order block is a shortcut: there is no need to open each order.
Restrictions
Assigns a specific Alegra account to a customer or to a group of customers. It is useful when the store works with several accounts and each one serves a different audience.
It routes, it does not block. A rule on this screen does not prevent billing: it changes which account is billed with. When preparing the invoice, the module starts from the Alegra account by default and replaces it if it finds a rule for that customer. The one that does prevent billing is General → Customer groups that cannot invoice.
Which one wins if there are several. A rule set on the customer takes priority over any group rule. Among group rules, if the customer belongs to several, the one for their default group wins.
Alegra account
The Alegra account the restriction applies to.
Groups
The PrestaShop customer groups affected.
Customer
A specific customer, when the restriction is not by group but individual.
Ticket configuration
The establishment details printed on the Ticket POS. Unlike the other tabs, here changes are saved on their own as you leave each field.
Store name
The establishment name as it should appear on the ticket.
Address of the establishment
The address printed on the ticket.
Phone
The establishment's contact phone number.
Email
The establishment's contact email.
Website domain
The store's web address.
Free text
A text of your own added to the ticket.
Note: This text will be reflected on the invoice in the taxpayer information section.
Synchronize invoices
Brings the current status of the Alegra invoices back into PrestaShop, for when changes have been made directly there.
1
Choose the date range
On the calendar, mark the start and end dates of the invoices you want to update.
2
Press "Synchronize invoices"
The button stays disabled until you have selected a range.
Numerations
Assigns to each country the Alegra numbering its invoices must use. Anything without a numbering of its own here uses the Default numeration for invoices from the General tab.
Note: The list will only show the countries that are active.
Assigning a numbering to a country
Country list
The country the numbering is assigned to.
Numerations
The Alegra numbering that will be applied to that country.
Billing an order
Billing does not live in the module configuration, but on the PrestaShop order page, in a block called Alegra Invoicing that the module adds. Everything that follows happens there.
The buttons change according to the invoice status, they are not all there at once. An order that has not been invoiced shows some, a draft shows others and an invoice already issued shows different ones again. That is why this section is organised by status and not by button.
Before you start: what the module will ask you for
An Alegra invoice needs everything that goes in it to exist in Alegra too. If something is missing, the module does not fail silently: it opens a screen listing what it is missing and lets you resolve it without leaving the order, with an Associate button (link it with something that already exists in Alegra) or Create in Alegra (register it there and then).
The messages you may run into, and what each one means:
| What it says |
What to do |
| The following products are not associated in Alegra… |
Associate or create them. Prevented beforehand from Associate → Products. |
| The following carrier is not associated in Alegra… |
Same, from Associate → Carriers. |
| The following customer is not associated in Alegra… |
Create or associate them. If it is a natural person, the identification number is mandatory and billing stops without it. |
| The following payment method is not associated in Alegra… |
Associate it from Associate → Bank accounts. |
| The following taxes were not created in Alegra… |
Create them in Alegra. These are not registered from the module. |
| No default numbering has been associated for invoices. |
Choose it in General → Default numeration for invoices. |
| The order currency is not created in Alegra… |
Create it in Alegra. |
| You do not have the multi-currency option activated in Alegra… |
It is a setting of your Alegra account, not of the module. |
Depending on the order and the account's country, the module may also ask you for two more things before going on: the missing Customer data (document type and number, country of origin of the document) and the Information required for the invoice, which is where the conversion rate and the billing date are filled in when they are needed.
The life of an invoice, step by step
An Alegra invoice goes through three statuses, and in each one the module only shows what makes sense to do:
| Status |
What it is |
Available buttons |
| Not invoiced |
The order has nothing in Alegra yet. |
Bill · Modify client and invoice · Link existing Alegra invoice |
| Draft |
It exists in Alegra but it is not a final document: it can be reviewed and redone. |
Bill · Modify client and invoice · Draft preview · Convert draft to invoice · Convert draft to invoice and issue it |
| Opened |
Final invoice, awaiting payment. |
Download invoice · Ticket POS · Pay Invoice · Delete payment · Create credit note · Unlink invoice |
| Closed |
Final invoice, already paid. |
Download invoice · Ticket POS · Create credit note · Unlink invoice |
1
Bill
Creates the draft in Alegra with the order data. This is where the warnings from the previous section appear if something is still unassociated. It does not issue anything yet.
2
Draft preview
Opens the draft so you can check it before converting it. It is the last cheap moment to catch a mistake.
3
Convert draft to invoice
Turns the draft into a final invoice inside Alegra, without sending it to the tax authority.
4
Convert draft to invoice and issue it
The same as the previous one and, in addition, issues it, which is the electronic invoicing step. This is the option normally used.
5
Pay Invoice
Records the payment in Alegra and moves the invoice from Opened to Closed. The payment is booked in the bank account you have associated with that payment method.
Shortcut: with General → Issue invoice with automatic payment enabled, step 5 is taken as done when issuing and there is no need to record the payment by hand.
The other actions in the block
Modify client and invoice
Opens the customer data so you can correct it before creating the draft. This is what you use when the customer entered their document wrongly or a fiscal detail is missing: changing it here saves you from having to void the invoice later.
Download invoice
Downloads the PDF of the invoice once it is final. It is the file the scheduled task deletes after 30 days; the invoice itself stays in Alegra.
Ticket POS
Opens the point-of-sale ticket with the data you set in Invoices → Ticket configuration. If you have Show Ticket POS after billing enabled, it opens on its own once billing is done.
Delete payment
Deletes the payments booked against that invoice in Alegra. It appears next to Pay Invoice while the invoice is still Opened, which is when a wrongly recorded payment can still be put right. If no payment is booked, there is nothing to delete.
Create credit note
This is the way to correct or void an invoice that has already been issued, and it only appears once the invoice is final (opened or closed). It opens a form with the number, contact, reason, notes, operation type and description, concept, rectifying invoice type, issue date, currency, price list, cost center and delivery order.
An issued invoice is not deleted. If it has to be reversed, the way is the credit note: a new document that corrects the previous one and is recorded as such. That is why it is worth reviewing the draft with Draft preview before issuing.
When the credit note is created, the voided invoice is no longer linked to the order, which is free to have the replacing invoice linked to it.
Link existing Alegra invoice
Links to the order an invoice that already exists in Alegra, for example one created manually there. It appears when the order has no invoice and opens the list of the latest invoices of that customer in Alegra, with their number, date, total and status. If the total does not match the order's it is highlighted in red, but it can still be linked.
Only open or closed invoices can be linked, from the same Alegra contact as the order's customer and not already linked to another order.
Unlink invoice
Removes the link between the order and its invoice, after asking for confirmation. It appears when the invoice is final (open or closed).
Unlinking changes nothing in Alegra. The invoice still exists there as it is; if it has to be voided, it is done with a credit note.
On the customer page and the product page
The module also adds a block of its own on the back-office customer page and product page, so you can see and manage their counterpart in Alegra from there without going to the Associate screens.
If the block does not appear or will not let you bill: check that an Alegra account by default has been chosen — without one the block only shows a notice —, that the customer's default group is not in Customer groups that cannot invoice, and that you have not enabled Hide issue invoice button.
Scheduled task
The module exposes a scheduled-task URL that deletes old invoice PDF files so they do not pile up on the server. The screen shows the URL with buttons to copy or open it.
The module gives you the URL, but it does not run it by itself. Until someone schedules it, the cleanup never happens. You have to register it as a recurring task in your hosting panel (cron) or with PrestaShop's scheduled-tasks module. Once a day is enough. Opening it from the button runs it once, as a test.
Note: The URL is set by default to delete PDF files of invoices that are 30 days old or older. If you want to change the number you must modify the URL and change the value of the days parameter. What is deleted is the PDF stored on the server: the invoice stays in Alegra and can be downloaded again from there.
Translations
Edit Translations
The module includes a translation editor that allows you to customize all texts in any language installed in your store.
- Access the "Translations" section in the module configuration
- Select the language you want to edit
- Modify the text strings as needed
- Click "Save" to apply the changes
Available Actions
The translation editor includes several actions to manage your translations:
- Save: Saves the changes made to the translations.
- Save and download: Saves the changes and downloads the translation file for backup.
- Share with us: Sends your translations to our PresTeamShop team to include them in future module versions.
- Expand all: Shows all translation sections expanded.
- Collapse all: Hides the content of all sections.
Backups
The backup system allows you to protect your module configuration and restore it if needed.
Generate Backup
To create a new backup, click the "Generate new backup" button. The system will create a backup of the current module configuration.
Upload Backup
If you have a previously downloaded backup, you can upload it by clicking the "Upload backup" button. A dialog will open where you can select the backup ZIP file.
Available Backups
The list shows all created backups. You can filter by date using the date selector and refresh the list with the "Refresh list" button.
List Actions
Each backup in the list has the following available actions:
Restore backup
Restores the module configuration
Download backup
Downloads the ZIP file
Delete backup
Deletes the backup
Caution: Restoring a backup will overwrite the current module configuration. This action cannot be undone.
To restore, click the "Restore backup" button of the backup you want to recover and confirm the action in the dialog.
Support
If you need additional help or have any questions about the module, we're here to help.
