TakePOS Digital Invoice

TakePOS Digital Invoice

Summary: Lets a buyer of a TakePOS sale request an electronic invoice by scanning a QR code on the receipt.
Module version: 1.0.0
Declared compatibility: Dolibarr 23.0 or later, PHP 7.2 or later
Last documentation review: 2026-09-29

Demo video:

Demo site: Open the demo site

Publisher website: 01Consulting

This guide covers installation, settings, receipt QR codes, the customer workflow, request tracking, EInvoicing integration, permissions, and troubleshooting.

1. Purpose and scope

TakePOS sales are often recorded against the generic third party assigned to a terminal. This module gives the buyer of a paid sale a way to provide company details, confirm an email address, and request the electronic invoice for that existing sale.

The module identifies or creates a customer third party, links the TakePOS invoice to it, prepares the electronic invoice with EInvoicing, sends it to the approved platform configured there, then emails the requester the official readable PDF retrieved from that platform.

The public workflow is intended for French companies with an active 14-digit SIRET. It does not create a new commercial invoice; it operates on the already-paid TakePOS invoice. Individuals and foreign companies are not supported.

2. End-to-end workflow

1. When a TakePOS invoice is validated, the module creates a random 64-character identifier and stores it in the invoice hash extrafield.
2. The receipt prints or displays a QR code that opens the public form for that invoice.
3. The buyer submits company details and a SIRET. The module checks the fields, email domain, and available official register data.
4. The module sends a confirmation link to the submitted email address. Processing does not start until the link is opened.
5. After confirmation, the module reuses the matching third party or creates one, then links the paid invoice to it.
6. EInvoicing generates the electronic document using the configured protocol and sends it to the approved platform.
7. The module retrieves the platform’s official readable PDF and emails it to the requester.

Errors are recorded on the request. An authorized user can retry processing. If the invoice has already been transmitted, the existing platform flow is reused to retrieve the PDF; the invoice is not sent a second time.

3. Requirements and compatibility

• Dolibarr: the module descriptor declares Dolibarr 23.0 or later; the module was prepared for Dolibarr 23.0.3.
• PHP: minimum declared version is 7.2.
• Dolibarr modules: Invoices, TakePOS, and EInvoicing must be enabled.
• EInvoicing: configure an approved platform, satisfy its prerequisites, and select the CII or Factur-X protocol.
• Email: outbound email from Dolibarr must be configured.
• Server connectivity: the server must be able to reach the Company Search API, DNS, and, if enabled, the Verifalia API over HTTPS.
• Customer access: the public Dolibarr URL must be reachable from the phone scanning the receipt.
• TakePOS terminal: each relevant point of sale must have a default generic third party, used to determine whether the buyer is still anonymous.

4. Installation, activation, and updates

4.1. Install and activate

1. Copy the takeposdigitalinvoice directory to htdocs/custom.
2. In Dolibarr, open Home > Setup > Modules/Applications.
3. Enable TakePOS Digital Invoice. First check that Invoices, TakePOS, and EInvoicing are installed and enabled.
4. Open the module configuration and set the General and Email tabs.
5. Grant the required read and process permissions to the relevant users.
6. Add the QR tag to the browser receipt template and/or ESC/POS template used by the terminal.
7. Make a test sale and verify the QR code, public form, email confirmation, and request tracking.

Activation loads the request table, adds the invoice hash extrafield (varchar, 64 characters), declares the tracking menu and invoice tab, registers permissions, and declares the retention scheduled task. An activation migration also handles the former CII tracking columns and, where possible, fills in the format from documents already generated.

4.2. Update

Back up the database and Dolibarr documents before updating. Replace the module files with the new version, then reactivate the module if its menu or tab declaration has changed. Activation runs the migrations declared by the module. Afterward, check the configuration page, request menu, and a TakePOS invoice tab.

4.3. Disable or uninstall

The effects on tables, the extrafield, and documents depend on the operation selected in Dolibarr. Back up data before uninstalling and review the consequences shown by Dolibarr. The public workflow does not operate while the module is disabled.

5. Permissions, menus, and screens

Permission or screen	Purpose
Read requests	Opens the request list and tracking tab on a TakePOS invoice. Dolibarr permission to view the invoice is also required.
Process requests	Allows Retry and Cancel actions in the list and invoice tab.
Administer requests	Permission declared in the module descriptor. Configuration pages also require Dolibarr administrator status.
Configuration	Available to Dolibarr administrators from the module settings; includes General, Email, and About tabs.

The Billing/Payments > TakePOS Digital Invoice menu is shown to users with read permission. The invoice tab is shown only on invoices originating from TakePOS and to users with the same permission.

6. General settings

Open the module settings and select the General tab. The defaults below are defined by the configuration page; Dolibarr may retain a value already stored for the entity.

Setting	Default	Effect
Public link lifetime	30 days	Period from invoice validation; minimum one day.
Maximum attempts	5	Limits submissions for the same invoice and hashed IP address.
Rate-limit window	15 minutes	Time window applied to the attempt counter.
Completed request retention	365 days	The scheduled cleanup can delete completed requests after this period.
Error request retention	90 days	The scheduled cleanup can delete requests in error after this period.
Privacy policy URL	Empty	Optional link displayed below the public form when configured.
QR code message	“Scan this QR code to request your electronic invoice.”	Text printed or displayed with the QR code; an empty message falls back to the translated text.
Public form URL	Computed	Read-only value; verify it from outside the server.

7. Email and PDF settings

In the Email tab, configure the following:

Setting	Initial value	Description
Confirmation token lifetime	24 hours	The link is single-use and expires at its stored expiry time.
Resend delay	2 minutes	Minimum delay before requesting another email for the invoice.
Sender name	Empty	Optional name used with Dolibarr’s general sender address.
Verifalia verification	Disabled	Optional external deliverability check; requires API username and password.
Verifalia timeout	20 seconds	Allowed range: 5–30 seconds per call.
PDF retrieval attempts	4	Allowed range: 1–6 checks of the same platform flow.
Delay between attempts	2 seconds	Allowed range: 1–5 seconds; no new transmission is made.

The sender address comes from MAIN_MAIL_EMAIL_FROM in Dolibarr’s general email configuration. The module sender name is used for confirmation and PDF emails. If Verifalia is enabled without credentials, or its service rejects the request, submission is blocked with an appropriate error.

8. Add the QR code to receipts

8.1. Browser receipt

1. Open the TakePOS setup and edit the relevant browser receipt template.
2. Insert the __DOL_FAC_NUM__ tag once where the QR code should appear.
3. Save the template and print a receipt for a newly validated TakePOS invoice.

On a browser receipt, the substitution displays a QR image produced by Dolibarr’s TCPDF engine, with the configured message. The module loads the invoice extrafields before performing the substitution.

8.2. ESC/POS printer

1. In the RAW/Text printer setup, open the receipt template.
2. Add {dol_fac_num} once.
3. Select this template for the terminal and run a print check.

The module documents this tag in the ESC/POS template help and replaces it with the native QR instruction {dol_print_qrcode} followed by the public URL. The ESC/POS replacements also recognize {DOL_FAC_NUM} and {__DOL_FAC_NUM__}. The QR message is sent as ESC/POS text after the code.

The module also prepares the substitutions __DOL_FAC_NUM_URL__, dol_fac_num, and __dol_fac_num__. If a valid hash is unavailable, substitutions are empty; while printing ESC/POS, the module tries to create the hash. If it fails, the tag is removed from the printout and an error is written to the Dolibarr log.

Do not add the tag in two locations in the same template. After enabling the module, verify a newly validated invoice: the hash is created by the TakePOS invoice validation trigger. Older receipts are not reprinted automatically.

9. Public form and requested data

The public page looks up the invoice using its hash. It requires the invoice to originate from TakePOS, the link to be within its lifetime, the invoice to be paid/closed, and the invoice still to be linked to the terminal’s default generic third party.

The public summary displays the seller, sale date, total including tax, terminal, and invoice reference masked except for its last four characters. It does not display sale lines, payment information, third-party identity, or the full invoice reference.

The form asks for:

• company name;
• address and optional additional address;
• postal code and town;
• 14-digit SIRET;
• email address.

The country is set to France in third-party processing; the form does not offer a country selector. The privacy policy link appears only when configured.

10. Company and email checks

10.1. SIRET check

The module queries the public Company Search API at https://recherche-entreprises.api.gouv.fr/search?q= using the submitted SIRET. It requires 14 digits, finds the matching establishment, and checks that its administrative status is active. It also compares the company name with the official data after normalizing accents, case, and separators, then compares the postal code and town (case and accents are normalized for the town).

Current check limitation: the submitted street address is stored and may be used to create the third party, but the code does not compare it with the address returned by the API. Consistency checks cover the name, postal code, and town, not the street. A missing, closed, or invalid SIRET, or a mismatch in these checked fields, blocks submission. Network, DNS, TLS, timeout, unreadable-response, and service rate-limit errors produce specific or generic errors and do not create a third party.

10.2. Email address check

The module checks the email format, then uses DNS to check that the domain has an MX record. If Verifalia is enabled, its API is also called: addresses classified as undeliverable or disposable are rejected; deliverable, risky, and unknown results are accepted by this check. A service failure or credentials/credit error blocks submission when the option is enabled.

Email confirmation is still required even when Verifalia is disabled or returns an accepted result. The random token sent to the customer is stored hashed in the database, expires according to the configured duration, and can be used once. Resending is subject to the configured minimum delay.

11. Confirmation and invoice processing

1. After a valid submission, the request is stored in the tracking table as Pending confirmation. A confirmation link is sent to the submitted address.
2. The customer opens the link before it expires. The token is consumed and the request changes to Ready.
3. Processing reloads the invoice and confirms it originates from TakePOS and is paid/closed. An atomic lock prevents the same request from being processed concurrently.
4. The module searches for a third party by exact SIRET, then by SIREN (the first nine digits), preferring an exact SIRET match. If none exists, it creates a French customer third party and lets Dolibarr assign the customer code.
5. The TakePOS invoice is linked to this third party. Generation or sending through EInvoicing is refused while the invoice is still linked to the terminal’s default third party.
6. The module checks that EInvoicing is enabled, its prerequisites are met, and its configured protocol is CII or Factur-X. It marks only this invoice as ready for EInvoicing generation.
7. EInvoicing generates a document for the selected protocol. For Factur-X, the Dolibarr source PDF is generated before requesting the hybrid Factur-X document. For CII, the protocol produces an XML file.
8. The provider configured in EInvoicing transmits the invoice to the approved platform. The module records the generation, transmission, and format steps.
9. The module queries the platform flow for its ReadableView resource, which must be a readable PDF. It makes the configured number of attempts if the view is not ready yet.
10. The official readable PDF is saved in the invoice document directory and emailed to the customer as an attachment.
11. After the email is sent successfully, the request changes to Completed.

With CII, the XML file is used for transmission and the customer receives the platform’s official readable PDF. With Factur-X, the hybrid document is generated and transmitted, while the customer attachment remains the readable PDF retrieved from the platform. This module does not email the standard Dolibarr PDF to the customer.

12. Request statuses

Status	Meaning	Next step
Pending confirmation	The request is stored, but its email address has not been confirmed.	The customer must open the link before it expires.
Ready	Email is confirmed and processing can start.	Automatic processing or the Retry action.
Processing	The request is reserved for processing.	Wait for processing to finish and check detailed status.
Error	A step failed; its error code and step are retained.	Fix the cause and retry if email was confirmed.
Completed	Transmission and PDF email both succeeded.	The public link reports that the request has already been processed.
Canceled	The public link can no longer be used.	No standard retry is offered.

The table also stores separate indicators for email confirmation, SIRET validation, third-party linking, EInvoicing generation, platform transmission, PDF email, protocol used, error step, and creation, modification, completion, or cancellation dates.

13. Track and manage requests

13.1. Request list

Open Billing/Payments > TakePOS Digital Invoice. The list shows the invoice, third party when known, SIRET, email address, status, last error code, and creation date. Columns can be sorted and results are paginated. Filters include invoice reference, third party, SIRET, email, and status. Invoice and third-party references open their Dolibarr records.

13.2. Invoice tab

On a TakePOS invoice, open the TakePOS Digital Invoice tab. It shows status, creation and modification dates, email confirmation, requester email, SIRET, protocol, generation/transmission/PDF email status, and, on failure, the step and error message. A download button is available when a readable PDF is present.

13.3. Retry

Retry is offered for a request whose email has been confirmed and whose status is Ready or Error. Processing resumes and uses the recorded indicators and platform flow. If transmission already succeeded, retry does not send a second invoice; it attempts to retrieve the PDF and complete delivery to the customer.

13.4. Cancel

Cancel asks for confirmation, invalidates the public link, and marks the request canceled unless it is already completed or canceled. The TakePOS invoice cancellation trigger also cancels a non-completed request. The request remains available for tracking until it is purged.

14. EInvoicing configuration and sending conditions

TakePOS Digital Invoice does not replace EInvoicing or configure the approved platform. Configure the EInvoicing module separately: select the platform, credentials, and protocol. This version’s workflow accepts only the CII and FACTURX protocol values.

An anonymous TakePOS customer cannot receive an electronic invoice while the invoice remains linked to the terminal’s generic third party. The module checks this explicitly, including in the hook that intercepts direct EInvoicing generate or send actions on a TakePOS invoice. Identifying the customer makes only that invoice eligible; it does not change the global TakePOS invoice eligibility setting.

If the EInvoicing protocol is changed after transmission, the module blocks using a different format for that request and asks for the format associated with the already-submitted flow to be restored. This avoids an inconsistent or duplicate transmission.

15. Stored data, files, and privacy

• Invoice extrafield: hash, a random 64-character public identifier. Do not publish it separately or edit it manually.
• Request table: entity, invoice, optional third party, SIRET, company name, address, postal code, town, email, hashed IP fingerprint, hashed token and expiry, counters, statuses, errors, and timestamps.
• Documents: the EInvoicing electronic file and the platform’s readable PDF are stored with the invoice documents.
• Public summary: limited sale-identification details; invoice lines, payments, and third-party identity are not exposed before identification.
• Logs: the dedicated log is DOL_DATA_ROOT/takeposdigitalinvoice/module.log. Technical error details may also be present in Dolibarr logs. Review and redact logs before sharing them.

The retention task is scheduled daily. It deletes completed requests according to completion date and error requests according to modification date. This cleanup method does not delete pending, ready, processing, or canceled requests. The task that purges requests does not delete invoice documents.

16. Triggers, hooks, and substitutions

• BILL_VALIDATE: for a validated TakePOS invoice, the trigger ensures the public hash exists and creates it if missing.
• BILL_CANCEL: for a canceled TakePOS invoice, the trigger cancels its non-completed request.
• Browser receipt: the hook loads invoice extrafields before TakePOS substitutions are processed.
• ESC/POS templates: the hook adds the QR tag description to template help and substitutes the tag in the text sent to the printer.
• EInvoicing actions: a hook blocks direct generation or sending for a TakePOS invoice that remains linked to the default third party.
• Substitutions: the module provides __DOL_FAC_NUM__, __DOL_FAC_NUM_URL__, dol_fac_num, and __dol_fac_num__ for a TakePOS invoice with a valid hash.
• Scheduled task: periodically purges completed or error requests after their configured retention periods.

17. Troubleshooting

The QR code is missing from the browser receipt

Check that the module is enabled, the invoice comes from TakePOS, the template contains __DOL_FAC_NUM__, and the invoice was validated after activation. Check that the tag is not repeated. Browser substitution requires the hash to be loaded in the invoice extrafields.

The QR code is missing from the ESC/POS printout

Check the active RAW/Text template, the exact recognized tag, and that the template does not already send an equivalent tag. If the hash could not be stored, check Dolibarr logs and database/write permissions.

The public link is rejected

The hash must be valid; the invoice must originate from TakePOS, be closed/paid, and remain linked to the terminal’s generic third party. The link expires based on the validation date and configured duration. A completed request is reported as already processed; a canceled request cannot be used.

SIRET verification fails

Check the 14 digits, establishment status, company name, postal code, and town. A mismatch in these values or an unavailable API blocks the request. Current code does not compare the submitted street with the API address.

No confirmation email arrives

Check the address, domain and MX record, Dolibarr outbound email setup, and spam folder. If Verifalia is enabled, check the credentials, configured timeout, and service authentication or credit errors.

Confirmation succeeded but processing failed

Check the latest error and failed step in the list or invoice tab. Verify the third-party link, EInvoicing activation and setup, CII/Factur-X protocol, and access to Dolibarr documents. Then use Retry if the user has process permission.

Transmission succeeded but the PDF is not ready

The platform may create its readable view asynchronously. Retry later; the module checks the existing flow and does not transmit the invoice again.

The download button is unavailable

The button is enabled when the saved readable PDF is available, or when the invoice tab can use an accessible EInvoicing PDF as a fallback.

18. Limitations and operational precautions

• The current public workflow is for French companies with an active SIRET; it does not support individuals or foreign companies.
• Establishment consistency checks cover company name, postal code, and town; current code does not compare the street address with official data.
• The module retains one request per invoice. Do not create concurrent requests for the same invoice.
• Do not manually remove or edit the hash, tokens, or processing indicators in the database.
• Do not change the EInvoicing protocol during a request that has already been transmitted without restoring the format of its existing flow.
• Do not edit the invoice’s third party while it is being processed.
• Cleanup removes completed and error request history after the configured retention periods; retain any needed tracking information before then.

19. Support

For help or to report a problem, contact contact@01consulting.eu. Include the module and Dolibarr versions, receipt type, workflow step, request status, error code, and approximate time. Redact SIRET, email addresses, tokens, platform credentials, invoice details, and any other confidential information from screenshots and log extracts.