CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[4.19.0] 2026-07-01

Added

• Add draft support methods for retentions: retentions.updateDraft, retentions.copyToDraft, and retentions.stampDraft.

[4.18.0] 2026-06-06

Added

• Expose structured API error metadata through FacturapiError, including status, code, path, location, errors, logId, and response headers.

[4.17.0] 2026-04-27

Added

• Add support for custom request headers through the Facturapi constructor options.
• Add receipts.toInvoice to create customer invoices from multiple receipt keys.
• Add receipts.previewToInvoicePdf to generate PDF previews for to-invoice payloads.

[4.16.0] 2026-04-23

Added

• Add new export catalogs for customs regimes, transport keys, SCT permits, COFEPRIS sectors, pharmaceutical forms, special transport conditions, customs documents, transport types, transport figures, ISTMO registry, loading keys, maritime configurations, rail traffic, containers, rail cars, rail service types, transfer reasons, incoterms, and customs units.
• Expose the new enums on the Facturapi class as static getters for namespace-style access.

[4.15.0] 2026-04-13

Added

• Add organizations.updateDefaultSeries to set an organization default series by type.

Fixed

• Return blob if content-type is octet-stream. This is the coverage for zip files

[4.14.2] 2026-03-31

Fixed

• Add TaxFactor.EXENTO ("Exento") to align SDK enums with the API/OpenAPI allowed tax factor values.

[4.14.1] 2026-03-31

Fixed

• Fix organizations.checkDomainIsAvailable to call GET /organizations/domain-check with query params (instead of an unsupported PUT payload flow).
• Align method input naming to query semantics for clearer usage (query).

[4.14.0] 2026-03-04

Added

• Add facturapi.comercioExteriorCatalogs.searchTariffFractions method for Fracción Arancelaria SAT catalog
• Add organization team/access management methods under organizations: listTeamAccess, retrieveTeamAccess, removeTeamAccess, listSentTeamInvites, inviteUserToTeam, cancelTeamInvite, listReceivedTeamInvites, respondTeamInvite, listTeamRoles, listTeamRoleTemplates, listTeamRoleOperations, retrieveTeamRole, createTeamRole, updateTeamRole, and deleteTeamRole.
• Add typed responses and inputs for organization access, invites, and roles.
• Add automated test suites for Node runtime (vitest), web-simulated runtime (vitest + jsdom), and browser smoke tests (playwright).
• Add TypeScript contract tests with tsd for public SDK types.
• Add CI workflow to run runtime tests, type tests, and browser smoke tests in GitHub Actions.
• Include rfc_provider_cert in stamp-related invoice typings and responses (thanks to @tetexxr).

Changed

• Use PUT for role reassignment/update methods: organizations.updateTeamAccessRole and organizations.updateTeamRole.
• Use Authorization: Bearer <apiKey> by default in SDK requests (API supports this scheme).
• Improve cross-runtime compatibility through feature-detection based runtime handling and binary type normalization.
• Restrict npm published contents to runtime artifacts/docs (dist, README, CHANGELOG, LICENSE) using a package files whitelist.
• Pin npm to 10.9.2 in CI/deploy workflows for deterministic lockfile validation across Node versions.

Fixed

• Improve non-OK HTTP error handling fallback when JSON error bodies are malformed or missing, returning clearer text/status errors.
• Handle ReadableStream read failures during binary download conversion to Node streams to avoid unhandled rejections.
• Strengthen WebCrypto webhook signature validation by using subtle.verify and explicit hex signature validation.
• Improve debugging for invalid upload inputs with clearer unsupported file type errors.

[4.13.1] 2026-02-11

Fixed

• Fix organizations.uploadLogo and organizations.uploadCertificate in Node.js 18 by avoiding File constructor usage during upload preparation.

Changed

• Update declared Node.js engine requirement to >=18.0.0 to match runtime dependencies.

[4.13.0] 2026-02-06

Added

• Add CancellationStatus.VERIFYING ("verifying") to support SAT cancellation requests in verification.

[4.12.0] 2026-01-21

Changed

• Method of retentions.cancel now accept motive and substitution as in invoices cancellation method.

[4.11.0] 2025-12-10

Added

• Add new catalogs for cartaporte
• searchAirTransportCodes, searchTransportConfigs,searchRightsOfPassage,searchCustomsDocuments,searchPackagingTypes,searchTrailerTypes, searchHazardousMaterials, searchNavalAuthorizations, searchPortStations, searchMarineContainers

[4.10.0] 2025-09-04

Added

• Add invoices.previewPdf method to generate a preview PDF of an invoice before stamping it.

[4.9.1] 2025-07-21

Fixed

• Deprecate Organization.plan property.

Added

• Add add_ons property to the Organization type.
• Add missing attributes to Organization.customization.pdf_extra.

[4.9.0] 2025-06-16

Added

• Add organizations.updateSelfInvoiceSettings method to update self-invoice settings for the organization.

[4.8.3] 2025-05-19

Fixed

• Webhook validation. Now the signature is validated locally in Node and web environments (but not in React Native, where the API is still used).
• Type fixes for signature validation.

[4.8.2] 2025-04-23

Fixed

• Fix organizations.uploadLogo and organizations.uploadCertificate methods to accept Buffer or ReadableStream as input in Node.js.

[4.8.1] 2025-04-10

Fixed

• Fix route for customers.sendEditLinkByEmail method.

[4.8.0] 2025-04-10

Added

• Webhook events: invoice.created_from_dashboard and customer.edit_link_completed

[4.7.0] 2025-04-04

Added

• Add customers.sendEditLinkByEmail method to send an edit link to a customer via email.

[4.6.0] 2025-02-25

Added

• Allow creating edit links for customers, passing query params to create and edit customer methods.
• Edit link properties for customers.

[4.5.0] 2025-01-07

Added

• New fields for the Invoice object: received_payment_ids and target_invoice_ids, used to track payments and PPD invoices.

[4.4.4] 2024-12-18

Fixed

• Added try/catch to conditional import and define "stream" as external.

[4.4.3] 2024-12-13

Fixed

• Fix conditional import on web environments.

[4.4.2] 2024-11-28

Fixed

• Fix bug in Node.js environment in which the library was not returning the right kind of stream on download methods.

[4.4.1] 2024-11-12

Fixed

• Fix bug in which body params were not being sent in the request.

[4.4.0] 2024-11-08

Added

• Compatibility with browser environments and React Native. Now you can use Facturapi in the browser or in React Native, as long as you have a Fetch API compatible environment.
• Types for webhooks responses.
• Add organizations.me method to get the organization information.

Fixed

• Name of validateSignature parameter "signature".

[4.3.0] 2024-11-04

Added

• Add types for all method responses. Method parameters are still not typed.

[4.2.0] 2024-10-10

Added

• List Live Api Keys: listLiveApiKeys for organizations
• Delete Live Api Keys: deleteLiveApiKey for organizations
• Validate webhooks responses: validateSignature for webhooks

[4.1.2] 2024-07-15

Added

• Fix optional params for invoice

[4.1.1] 2024-06-15

Fixed

• Fix organization.createSeriesGroup and organization.updateSeriesGroup. Thanks to @pastine

[4.1.0] 2024-06-13

Added

• Methods for CRUD of series
• Create method for series: organization.createSeriesGroup
• Read method for your organization series: organization.listSeriesGroup
• Update method for an specific series: organization.updateSeriesGroup
• Delete method for an specific series: organization.deleteSeriesGroup

[4.0.0] 2024-05-23

Breaking

• Remove deprecated method products.keys in favor of catalogs.searchProducts.
• Remove deprecated method products.units in favor of catalogs.searchUnits.
• Corrected the name of the method invoices.editDraft to invoices.updateDraft.
• The rest of the changes are internal and should not affect the public API.

Added

• We rewrote the the library in TypeScript and now it's partially typed. Most request parameters and responses are not typed yet, but we plan to add more types in future releases.
• We export all type definitions, so you can use them in your TypeScript projects.
• New method to copy invoices to a new draft: invoices.copyToDraft.

[3.6.0] 2024-05-23

Added

• New method to delete certificates from the organization: organizations.deleteCertificate.
• New query param async in create invoice method:.
• New methods for draft invoices: invoices.editDraft, invoices.stampDraft.
• New method to update invoice status with the latest value from the SAT: invoices.updateStatus.

[3.5.0] 2023-12-31

Added

• Webhooks API

[3.4.0] 2023-10-19

Added

• Add invoices.downloadCancellationReceiptPdf.

[3.3.0] 2022-12-14

Added

• Add invoices.downloadCancellationReceiptXml, receipts.sendByEmail and receipts.downloadPdf.

[3.2.0] 2022-01-17

Note: Although this update includes a breaking change, only the minor version will be bumped, since we haven't officially announced the new API version yet.

Breaking

• Remove organizations.getApiKeys.

Added

• Add organizations.getTestApiKey, organizations.renewTestApiKey and organizations.renewLiveApiKey.

[3.1.0] 2022-01-17

Added

• Allow setting the API version in the client constructor.

[3.0.0] 2022-01-16

Breaking

• Change API version to point to /v2, in order to support CFDI 4.0

[2.7.0] 2021-12-27

Added

• Support sending params to invoices.cancel method.

[2.6.1] 2021-09-05

Fixed

• Stop logging request config

[2.6.0] 2021-08-06

Added

• New endpoint: tools.validateTaxId.

[2.5.0] 2021-04-13

Added

• Support for Retentions API

Security

• Updated dependencies to address potential vulnerabilities.

[2.4.0] 2020-12-24 🎄

Added

• New method on receipts API: createGlobalInvoice

[2.3.1] 2020-05-28

Fixed

• facturapi.organizations.uploadCertificate only accepted FileStreams. Now it supports any kind of readable Stream, as well as Buffer.

[2.3.0] 2020-05-28

Added

• Support for receipts API
• Edit organization's receipts settings
• Check domain availability
• Select organization's domain

[2.2.3] 2020-03-05

Fixed

• Use correct endpoint for catalogs.searchProducts

[2.2.2] 2019-11-29

Added

• Catalogs API
  • Search product keys using catalogs.searchProducts.
  • Search unit keys using catalogs.searchUnits.

Fixed

• Updated all dependencies to clear security warnings
• Previously swallowing messages from non-axios errors

Deprecated

• product.keys and product.units are deprecated in favor of the new catalogs API, and will be removed on the next major release.

[2.0.0] 2018-08-04

Breaking changes

• Now you must create the Facturapi instance using the new keyword every time.

Before:

// This was allowed
const facturapi = Facturapi('YOUR_API_KEY');

Now:

// Now you must always use new
const facturapi = new Facturapi('YOUR_API_KEY');

[1.2.0] 2018-08-04

Fixed

• Reject with an Error, not with an object

[1.1.0] 2018-05-06

Added

• Support Organizations API

[1.0.0] - 2018-05-01

Added

• Search product_keys using facturapi.products.keys('your search')
• Search unit_keys using facturapi.products.units('your search')
• Constants for PaymentMethod, InvoiceType, InvoiceUse, InvoiceRelation

Breaking changes

• Now contants should be accessed as static properties from the Facturapi class, instead of from the instance.

Before:

const facturapi = new Facturapi('YOUR_API_KEY');
console.log(facturapi.TaxType.IVA); // > IVA

Now:

console.log(Facturapi.TaxType.IVA); // > IVA

[0.1.3] - 2017-06-20

Fixed

• Protocol should be HTTPS

[0.1.2] - 2017-06-20

Added

• First release
• Wrapper methods for:
  • Customers
  • Products
  • Invoices
• Added README file