SanBar EXPress NFe & POS-PDV BR

By SanBar

0+ active installationsVersion 1.0.0

POS (PDV) for WooCommerce with Brazilian NF-e and NFC-e invoicing, issued straight to SEFAZ. Cash register and receipts.

Description

SanBar EXPress NFe & POS-PDV BR is a full-screen point of sale (POS, called PDV in Brazil) for WooCommerce stores. In Brazil it also issues the fiscal documents: NF-e (model 55) and NFC-e (model 65), straight from the POS or from online-store orders, with its own fiscal engine (NFePHP libraries) and your A1 digital certificate. No third-party invoicing provider and no per-invoice fee. In Portuguese the plugin is called EXPress Fiscal PDV.

Features

Point of sale (POS / PDV)

  • Full-screen sale screen: product search (name, SKU, barcode), cart, quantity, discount, payment methods and change for cash
  • Keyboard shortcuts (F1 to F9) on every step of the sale, with optional discreet hints
  • Sale recorded as a regular WooCommerce order (stock is reduced by WooCommerce itself)
  • Thermal printing of the NFC-e and of a non-fiscal receipt: via browser, QZ Tray or WebUSB, with printer diagnostics, automatic paper cut and cash drawer opening
  • PDV and online-store sales kept apart in the Orders screen, with a status filter and the native WooCommerce order open in a panel

Fiscal invoicing, Brazil (NF-e / NFC-e)

  • NF-e and NFC-e issuing, from online-store orders and from POS sales
  • Cancellation, correction letter (CC-e), number voiding (inutilização) and return invoices (devolução)
  • SEFAZ service status check and invoice consultation
  • DANFE in A4 PDF and NFC-e receipt (DANFE NFC-e with QR code)
  • Batch export of invoices (XML/PDF in a ZIP)
  • Per-product fiscal fields (NCM, CEST, CSOSN, CFOP, origin, units, GTIN…) on the product edit screen
  • Rules that block invoices SEFAZ would reject (MEI and Simples Nacional combinations, ICMS-ST, NFC-e restrictions) before sending
  • Interstate sales to final consumers with the right CFOP, and Simples Nacional ICMS credit with the legal text added automatically
  • Approximate taxes on the invoice (Lei 12.741/2012, “De Olho no Imposto”)
  • NFC-e offline contingency: when SEFAZ or the internet is down, the receipt is issued, marked as contingency, and sent to SEFAZ automatically when the connection returns
  • Lost-response protection: a sale never gets two invoices, even if the connection drops while sending
  • GTIN lookup on the SEFAZ Centralized GTIN Registry with your certificate, offered to other plugins of the suite

Checkout and customers

  • Native checkout fields (CPF/CNPJ, number, neighborhood, WhatsApp, postal code lookup) shown, hidden or required as you choose

  • Invoice / order printed on A4, detailed quote with logo, and content declaration (declaração de conteúdo)

  • Internal sale (pedido interno) from the admin, with per-sale price editing authorized by an administrator password

Integration with the SanBar Suite

Works on its own. When the other plugins are installed, they connect without depending on each other:

  • SanBar EXPress Fiscal Check-BR — reads the store regime (CRT) configured here; checks each product’s fiscal data before the invoice is issued, and its GTIN lookup uses this plugin’s certificate to query SEFAZ
  • SanBar EXPress Store Manager — the fiscal fields edited in its grid are the same ones this plugin uses to issue invoices
  • SanBar EXPress NF-e XML Import — products created from purchase invoices arrive with NCM, CEST, origin and units already filled in

Technical requirements

  • PHP 8.0 or higher (the plugin declares this in its header, so WordPress will not activate it on older PHP). The plugin’s own code does not depend on PHP 8 features; the requirement comes from the bundled libraries: some of them (for example psr/log 3.x, used by the NFePHP stack) are published for PHP 8.0 or newer, and their Composer autoloader already stops with a clear message on older PHP. The header declares it so WordPress shows the requirement before installing.
  • WordPress 6.0 or higher and WooCommerce 7.0 or higher
  • A1 digital certificate (e-CNPJ) of the store, for the fiscal part
  • PHP extensions required by the sped-nfe library: zlib, dom, openssl, soap, json, simplexml, libxml
  • gd, required by sped-da (DANFE PDF, barcode and QR code)

The Inter and IBM Plex Mono fonts used by the screens are bundled with the plugin (SIL Open Font License 1.1, see assets/fonts/); nothing is loaded from external font services.

External services

This plugin connects to the services below. None of them is contacted just because the plugin is active: each call happens only when the action described is used. Nothing is sent to the plugin author.

Invoicing

SEFAZ web services (Secretarias da Fazenda of each state, SVRS and SVAN; national portal: www.nfe.fazenda.gov.br). They are the official government servers that authorize electronic invoices. The invoice XML (signed with your A1 certificate), cancellations, correction letters, number voiding, status checks and GTIN queries are sent to the endpoint of your state, only when you issue or query a document. The government publishes no separate terms of use or privacy policy for these web services; their use is governed by the tax legislation.

IBGE Localidades API (servicodados.ibge.gov.br, provided by the Brazilian Institute of Geography and Statistics). Used to download the list of cities of a state, because the NF-e requires the IBGE city code. Sent: only the state code, when the list is needed; no store, customer or invoice data. Terms of use: none published for this public API; its documentation is at servicodados.ibge.gov.br/api/docs/localidades. Privacy policy: none published for this API; the request carries no personal data.

Packagist (repo.packagist.org, the public package registry of the PHP community: packagist.org/about). Used only when you click “Check for updates” in Settings, to compare the versions of the bundled NFePHP libraries. Sent: the library names (for example nfephp-org/sped-nfe); no store, customer or invoice data. Terms of use and privacy policy: Packagist publishes none for this public metadata API (contact page: packagist.org/contact).

Address lookup

ViaCEP (viacep.com.br) and BrasilAPI (brasilapi.com.br). Resolve a Brazilian postal code (CEP) into street, district and city. Sent: the CEP typed by the cashier (PDV), or by the customer at checkout when the postal code lookup is on (Settings → Checkout and payments; it can be turned off). The lookup runs from the visitor’s browser or from the server. ViaCEP: it publishes no terms of use or privacy policy, only a usage note on its home page. BrasilAPI: terms of use (the project says they are still being written) and an open-source repository under the MIT license (github.com/BrasilAPI/BrasilAPI); it publishes no privacy policy. Only the postal code is sent, never names or other personal data.

Printing

QZ Tray (qz.io, license, privacy). Optional program that you install on the cashier’s computer for silent thermal printing. The plugin talks to it on that computer only (local WebSocket); the receipt content is not sent to any server.

Bundled libraries

Source and versions are in composer.json and composer.lock:

  • NFePHP sped-nfe, sped-common, sped-da and sped-gtin — github.com/nfephp-org (licenses in each package’s composer.json)
  • tc-lib-barcode and tc-lib-color — github.com/tecnickcom (LGPL-3.0)
  • justinrainbow/json-schema and psr/log — MIT
  • QZ Tray JavaScript (qz-tray.js), qz.io — LGPL-2.1

The DANFE and event PDFs and the printed receipts carry no credit line (“Powered by NFePHP” or the plugin name) unless you turn on Settings → Printing → Show the plugin credits.

Installation

  1. Upload the sanbar-express-nfe-pdv-br folder to /wp-content/plugins/, or install via Plugins → Add New → Upload.
  2. Activate the plugin (WooCommerce must be active).
  3. Go to SB Softwares → EXP NFe & POS-PDV (or EXP NFe & POS-PDV in the main menu, without the SB Softwares Hub) → Settings.
  4. Upload the A1 certificate, fill in the issuer data and the tax regime (CRT), and start in the homologation (test) environment.

FAQ

Do I need a third-party invoicing service?

No. The plugin signs and sends the invoices to SEFAZ itself, using your A1 certificate.

Which tax regimes are supported?

The invoice engine follows the regime set in the settings (CRT). Its validation rules are focused on MEI (CRT 4) and Simples Nacional (CRT 1).

Where are the invoices and the certificate stored?

In the WordPress database (the XML files compressed), never in a public folder of the site — so they are included in your regular database backups and are not lost when the plugin is updated. Keep the XML files for at least 5 years, as required by law.

What happens to my data when I delete the plugin?

Nothing is removed. Deleting the plugin leaves this in the database, on purpose:

  • The issued invoices (authorized XML), the events (cancellations, correction letters), the voided number ranges (table {prefix}nfbr_arquivos) and the plugin settings.
  • Your digital certificate, in the site vault (the option sanbar_certificado). It is shared with SanBar EXPress Fiscal Check-BR, which may still need it, and whether to remove it is your choice.

Your orders, products and their fiscal fields are never touched.

To have the certificate removed automatically, turn on “Also delete the digital certificate when the plugin is deleted” in Settings → Testes tab (off by default; it also removes the certificate for Fiscal Check-BR). The issued invoices are never removed.

To remove the certificate by hand, do it before deleting the plugin: in Settings → Testes tab, click Apagar certificado. Or, after deleting, remove the option sanbar_certificado (and nfbr_certificado, if it still exists) from the {prefix}options table of the database.

Why the invoices are kept: the issuer must keep the invoice’s digital file for the period set by the tax legislation, and make it available to the tax authority on request. Deleting a plugin must not destroy documents you are legally required to keep.

  • Ajuste SINIEF 07/05, cláusula décima (which instituted the NF-e; the NFC-e follows the same Ajuste, as amended): “O emitente deverá manter a NF-e em arquivo digital, sob sua guarda e responsabilidade, pelo prazo estabelecido na legislação tributária, mesmo que fora da empresa, devendo ser disponibilizado para a Administração Tributária quando solicitado.” Text at CONFAZ.
  • Código Tributário Nacional (Lei 5.172/1966), art. 195, parágrafo único: commercial and tax records and the documents that support them must be kept until the tax credits they refer to are time-barred. The periods are set by arts. 173 and 174 (five years, counted as those articles provide). That is why the readme says “at least 5 years”.

State rules can add requirements, so ask your accountant before deleting anything. This is information, not legal advice.

If you really want everything gone (after the legal period, and after exporting a copy), delete the table {prefix}nfbr_arquivos and the options starting with nfbr_ by hand.

My certificate is old or the upload fails. What can I do?

Some older A1 certificates (.pfx) use RC2/3DES encryption that current servers (OpenSSL 3) cannot read. This plugin then tries to convert the file by itself (see the next question). If the server does not allow it, convert it on your computer and upload the new file. There is also a “?” help next to the upload with these steps:

  • openssl pkcs12 -legacy -in old.pfx -nodes -out temp.pem
  • openssl pkcs12 -export -in temp.pem -out new.pfx
  • rm temp.pem

Run them in this order. The first asks for the old file’s password; the second asks you to choose a password for the new file (type it twice; it can be the same). temp.pem holds your private key without protection, so delete it right away (on the Windows Command Prompt use del temp.pem). If you get “unknown option -legacy”, your OpenSSL is old: remove -legacy. On Windows, Git for Windows includes OpenSSL in Git Bash. You can also ask your certificate authority to re-issue or export the A1 in the new format. Keep the original file, and never send the certificate or its password by e-mail or chat.

Does the plugin run commands on my server?

Only one, and only in the case above: when you upload an old-format certificate, this plugin runs the server’s openssl program (PHP exec) to re-encode the file you just sent.

  • The program is looked up in fixed, standard paths; nothing from the request goes into the command, and every argument goes through escapeshellarg.
  • The password is passed through a file, never on the command line.
  • The four temporary files are created with permission 0600 (owner only) before any content is written, and are always deleted afterwards. One of them holds the private key unprotected, which is why this matters.
  • It never runs at any other time. If exec is disabled or openssl is missing, nothing runs and you are told how to convert the file yourself.

Is the certificate shared with SanBar EXPress Fiscal Check-BR?

Yes. There is one certificate per site, kept in the site vault (the option sanbar_certificado), and both plugins read and write the same one:

  • If the vault is empty, you can send the certificate here or in SanBar EXPress Fiscal Check-BR. If it already has a certificate, the plugin shows it and does not offer the upload. To replace it, delete the current one first (Settings → Testes tab → Apagar certificado) and send the new one.
  • It works with the other plugin active, deactivated or not installed.
  • It is stored encrypted: the .pfx file and its password are sealed together with libsodium (authenticated encryption), using a key derived from your site’s security keys (the salts in wp-config.php). Anything altered in the database is refused. If you change the site’s security keys the certificate can no longer be opened: the plugin says so and you send it again.
  • If you move the site or change the security keys (salts) in wp-config.php, the certificate can no longer be opened. The plugin then says so on the Settings screen and when issuing, and asks you to restore the previous keys or upload the certificate again. Keep a copy of your .pfx file.
  • Deleting a plugin does not remove the certificate (see “What happens to my data when I delete the plugin?”).

Does the plugin use frames (iframes)?

Yes, only to show the plugin’s own screens inside the plugin’s home screen, and to open a WooCommerce order inside the Orders screen. Every frame loads a page of your own site’s admin (same address, same login session and the same user permissions); no external site or remote content is ever framed. Without the right permission, the page inside the frame shows the usual WordPress access error.

Is the fiscal part limited?

No. Issuing, cancelling, correcting and voiding NF-e/NFC-e are fully available.

Screenshots

Changelog

1.0.0

  • Initial release.