Custom folio numbers for your CFDIs in Fiscalapi

Two requests come up again and again from those of you who integrate invoicing every day, and both involve the CFDI folio number (CFDI: Mexico's electronic invoice; folio number: the issuer's own sequential number for the CFDI; not the UUID). The first: being able to send your own folio number instead of accepting the one we assign. The second: an automatic folio number that doesn't skip ahead when an invoice is rejected. Both are live in production today.

Neither one requires changes to your integration. If you don't send the folio number today, everything keeps working exactly as it always has. But if you've been waiting months for either of these improvements, read on.

Send your own CFDI folio number

Until now, Fiscalapi generated the folio number for you. Sending the number field in your request returned a validation error. That's changed: the field is now optional, and the choice is yours.

numberstringoptional

The invoice's folio number. Optional. If you send it, your invoice carries exactly that folio number when it's stamped (stamping: the certification by a SAT-authorized provider that makes a CFDI valid). If you omit it or send it empty, Fiscalapi generates it automatically, as always. It accepts 1 to 40 characters, following the standard set by the SAT (Mexico's tax authority, Servicio de Administración Tributaria), so you can use numeric, alphanumeric, or custom-format folio numbers.

A custom invoice folio number matters most for migration. We've helped with a lot of migrations from other invoicing systems, and the pattern repeats: a company has already issued 500 invoices in its previous system, so its first invoice with Fiscalapi should naturally be number 501, not number 1. Until now, you couldn't do that. Now you send the series you were already using and set number to "501", and your numbering picks up where it left off.

The other case is internal control. Many businesses manage their own CFDI series and folio numbers as part of their accounting processes, and they need the invoice to go out with the number their system assigned, not someone else's. That scenario is covered now.

The field details and complete issuance examples are in the Fiscalapi documentation, with ready-to-use implementations in the official SDKs.

Automatic folio numbers: no more gaps from rejected invoices

This improvement is for you if you'd rather have Fiscalapi keep generating the folio number but didn't like the gaps in your numbering. You reported it many times, and you were right to.

Before

Your last stamped invoice was 500. You sent the next one with a wrong RFC (Mexico's taxpayer ID, Registro Federal de Contribuyentes) and it was rejected: folio number 501 was wasted. When you fixed it and sent it again, the invoice came out as 502. The result: 500, 502, and a gap that's hard to explain to your customers or in an internal audit.

Now

Same scenario: the request is rejected because of bad data. You fix it, send it again, and your invoice is stamped as 501. A rejected request no longer uses up the automatic folio number, so your numbering stays continuous: 500, 501, 502.

Previously, Fiscalapi assigned the folio number as soon as your request arrived, before the stamping result was known. A rejection for an invalid postal code, a mistyped RFC, or any other bad data left that number unusable. That no longer happens: when a request is rejected, its folio number becomes available again for your next attempt.

These changes are 100% backward compatible. There are no changes to the request or response format, and your current integrations keep running without any modification. If you don't send a folio number, it's generated automatically as always, and rejected requests no longer leave gaps.

Folio number vs. UUID

This is worth clearing up because it comes up in support all the time. The CFDI folio number is the internal sequential number that you or Fiscalapi assign to the CFDI, the one that appears next to the series. The UUID (folio fiscal, the unique ID the PAC assigns when it stamps a CFDI) is 36 characters long. Only the PAC (Proveedor Autorizado de Certificación, a SAT-authorized provider that stamps CFDIs) controls it. This release gives you control over the first one; the second keeps working exactly the same. If you want to understand the UUID in depth, we break it down in our guide to the folio fiscal and the CFDI UUID.

Frequently asked questions about the folio number

Do I have to change anything in my integration?

Can I use alphanumeric folio numbers or my own format?

What happens if I send the folio number empty?

I got error 307 saying the CFDI was already stamped. What do I do?

Thanks to everyone who asked for these improvements, kept insisting, and shared their real migration cases with us. That context shaped how the field works. If there's something else the folio number should do and doesn't, write to us. That's exactly where both features in this release came from.