Developer notes
Technical reference for developers who customize Mexico CFDI 4.0 e-Invoicing.
Add-on identity
Section titled “Add-on identity”| Item | Value |
|---|---|
| Add-on id | kv_cfdi_mexico |
| Function prefix | fn_kv_cfdi_mexico_ |
| Language variables | kv_cfdi_mexico.* |
| CSS scope | .kv-cfdi-mexico (admin), .kv-cfdi (customer order page) |
| PHP namespace | Tygh\Addons\KvCfdiMexico |
Structure
Section titled “Structure”| Class | Role |
|---|---|
Cfdi\Builder |
Pure function: order -> provider neutral CFDI model (Ingreso, Egreso, global invoice), taxes, rounding, discounts, periods |
Cfdi\Xml |
Model -> CFDI 4.0 XML (unsigned, placeholders for the seal), validation against the shipped SAT schema, reading of stamped XML, SAT verification URL |
Cfdi\Qr |
QR code encoder (SVG) |
Sat\Catalogs |
Subsets of the SAT catalogues (regime, use, payment forms, motives, units …), RFC pattern |
Context |
Settings, issuer, currency and exchange rate, payment form, SAT keys of an order |
Pac\Facturama, Pac\Facturapi |
Mapping of the model to each PAC API (create, XML, cancel) |
Client\Api, Client\BaseClient |
HTTP (cURL, TLS verification, timeouts), authentication per PAC, error mapping, masked logging |
Documents, Generators\Cfdi40, Transport\Provider |
Documents (kinds I, E, G), creation rules, build, stamping |
Fiscal, Mapping |
Customer fiscal profile fields, SAT keys per product / category |
Mail |
XML attachment of the order e-mails |
Queue, Jobs |
Job queue (back-off 5 min / 15 min / 1 h / 3 h / 12 h); handlers send_document, cancel_document, poll_status, webhook; recurring work (global invoice) in Jobs::schedule() |
Accounts, Secret, Config, Access, Log |
Credentials (AES-256-GCM), settings, access, log |
Database tables
Section titled “Database tables”| Table | Purpose |
|---|---|
?:kv_cfdi_mexico_accounts |
PAC credentials and issuer data per company (secrets sealed) |
?:kv_cfdi_mexico_documents |
Documents: kind I / E / G, model JSON (content), stamped xml, uuid, cancellation state |
?:kv_cfdi_mexico_global_orders |
Orders contained in a global invoice |
?:kv_cfdi_mexico_sat |
SAT keys per product (P) and category (C) |
?:kv_cfdi_mexico_jobs, ?:kv_cfdi_mexico_log |
Queue and log |
Hooks used
Section titled “Hooks used”PHP: change_order_status_post (issue / credit status), delete_order (log only), update_product_post and update_category_post (SAT keys), mailer_create_message_before (XML attachment). Template hooks (admin): orders:manage_header, orders:manage_data, orders:tabs_extra, products:detailed_content, categories:detailed_content; storefront: orders:info.
The SAT schema
Section titled “The SAT schema”resources/xsd/ contains cfdv40.xsd, tdCFDI.xsd, catCFDI.xsd and TimbreFiscalDigitalv11.xsd as published by the SAT, with the import paths made local. In catCFDI.xsd the enumerations of c_CodigoPostal, c_ClaveProdServ and c_Colonia (more than 150,000 values) are replaced by their format; the other catalogues are complete. validate.xsd imports the two namespaces so that stamped XML validates in one pass.
Test without a PAC
Section titled “Test without a PAC”The base URL can be overridden for tests in config.local.php (development only):
$config['kv_cfdi_mexico_base_url'] = 'http://127.0.0.1:11830';node tests/mock-server/server.js 11830 starts a local stand-in of both PAC APIs (it follows their public documentation); node tests/e2e/e2e.mjs runs the HTTP end-to-end test against it; php tests/unit.php runs the unit tests (about 110 checks without a store).
Template overrides
Section titled “Template overrides”Admin templates live in design/backend/templates/addons/kv_cfdi_mexico/. Do not edit them in a store; they are replaced on update.