Batches

A batch does from a CSV what the JSON endpoints do one document at a time: stamp invoices or retention certificates. Use it when you send thousands or millions of documents, such as a monthly cycle of certificates for your workers.

How it worksCopy Anchor Link

1. POST /batches with the type of the rows and, if you want, defaults. It answers with upload_url and upload_expires_at, 24 hours later. Only this call returns upload_url, because the URL is a write credential: GET /batches/{id} always answers it as null. If you lost it, repeat POST /batches with the same Idempotency-Key.
2. PUT the CSV to upload_url, plain or compressed with gzip. It needs no token: the URL itself authorizes the upload. For a large file, upload it in parts. heru checks the format and the catalogs of every row, not the receiver against the SAT, and the batch goes validating.
3. GET /batches/{id} until it is ready, done when every document is a duplicate, or invalid when no document is valid and at least one failed validation. A ready batch shows what can and what cannot be processed, before anything is stamped: valid_documents and invalid_documents (and valid_rows and invalid_rows), the first 100 problems in errors with the row, the column and a code, all of them in errors_url, and the estimate of when it would finish. Only rows are rejected, never the whole file because of a bad row: the valid documents go ahead, and you can fix the rest in a new batch.
4. POST /batches/{id}/process stamps the valid documents. If fits_lifetime is false it answers 409 BATCH_EXCEEDS_CAPACITY and starts nothing, unless you ask for allow_partial. The batch goes processing, then done. Each stamped document sends its own event (invoice.stamped or retention_certificate.stamped) as soon as it is stamped, and batch.done fires when every valid document has its outcome. You can pause, resume or cancel it on the way.
5. Read report_url for the result of every row. The report_url (and errors_url) inside the batch.done event is a signed link valid for 15 minutes from when the event was written: if you receive the event later than that, or a retry arrives later, call GET /batches/{id} for a fresh link.

Uploading never stamps anything: only process does.

A credential that covers several of your companies and does not name one answers 422 COMPANY_REQUIRED to POST /batches, GET /batches/{id} and POST /batches/{id}/process. See Companies.

The fileCopy Anchor Link

UTF-8, comma separated with RFC 4180 quoting, and a header row. Column names are case-insensitive and their order does not matter; columns that are not listed are ignored. Each column takes the same values as the field of the JSON endpoint it comes from, and a few exist only in batches, marked as such in the tables below. Columns marked * are required, in the row or in defaults.

Rows that share external_id are one document, and they must be together. Put them one after the other: if the same external_id appears again further down the file, all its rows are invalid with EXTERNAL_ID_NOT_CONTIGUOUS. Their document columns must match on every row (DOCUMENT_MISMATCH). If any row of a document does not pass validation, the whole document is not stamped.

LimitsCopy Anchor Link

DefaultsCopy Anchor Link

Instead of repeating a value on every row, send it once in defaults, as strings. It takes any document or line column of the type. For each field the row wins, then defaults, then what the JSON endpoint assumes for your company. An unknown column or an invalid value answers 422 VALIDATION_FAILED and creates nothing; GET /batches/{id} returns them normalized.

{
  "type": "invoice",
  "defaults": {
    "receiver_rfc": "CDE170303B61",
    "payment_form": "03",
    "product_code": "78101800",
    "quantity": "1",
    "unit_code": "E48",
    "tax_object": "02",
    "vat_rate": "16%"
  }
}

external_id,third_party_rfc,third_party_worker_id,notify_email,description,unit_price,metadata_contract_id
INV-2026-000501,HEGL900101K44,,courier-1@example.com,Servicio de entrega a domicilio,1077.586207,CT-0001
INV-2026-000502,,wrk_01m4ra8w0he5esnnsew0v9ffkv,courier-2@example.com,Servicio de entrega a domicilio,862.068966,CT-0002

PartiesCopy Anchor Link

Each party is identified by its RFC or by its heru id: *_rfc, or one of *_worker_id, *_company_id, *_merchant_id and *_customer_id, as far as the role has that column. heru looks an RFC up among the workers, merchants and customers of your company. The receiver always needs one of them. The issuer too, unless the row has no issuer columns at all, which means the company of your token. A third party, which is always a worker, needs one when the invoice has a third party.

*_worker_external_id (the external_id you gave the worker) is optional and is not enough by itself: it only confirms the party identified by the RFC or the heru id.

The same goes for the other roles, with the role's own RFC column. A file with no column able to identify the receiver is not rejected as a whole: each row is invalid with PARTY_IDENTIFIER_REQUIRED, unless defaults gives a value for one.

When an RFC exists as several kinds of party in your company, the kinds the role allows decide; if that leaves more than one, use <role>_kind (company, worker, merchant or customer) or an id, or the row is invalid with PARTY_AMBIGUOUS.

What heru checksCopy Anchor Link

Batches check format and catalogs. They do not verify the receiver against the SAT. Batch files are expected to contain data already checked with fiscal validations, so check your receivers before you build the file. That applies to invoices and retention certificates alike.

If the stamping authority refuses a document, for instance because of its receiver, that document is failed in the report, with its reason in error_code and error_message, and the rest of the batch goes on. Fix it and send it in a new batch. heru never replaces a receiver with a generic RFC, never applies a different withholding rate because of it and never alters your amounts.

ValuesCopy Anchor Link

heru corrects a few things and rejects everything else, with the row, the column and a code.

InvoicesCopy Anchor Link

One row per item.

Retention certificatesCopy Anchor Link

One row per service. With retention code 26, heru computes the amounts and the withholdings from the services, as POST /retention-certificates does; see the retention certificates guide. If you send them too, heru compares them to within one cent and tells you the value it computed (AMOUNT_MISMATCH).

external_id,receiver_rfc,receiver_name,receiver_tax_regime,receiver_postal_code,start_month,end_month,year,retention_code,platform_service_type,platform_periodicity,service_date,service_payment_form,service_price_without_vat,service_vat_rate,service_commission_rate,service_commission_amount
RET-2026-09-0001,TAD190521KX1,TACOS EL ALIADO DEMO,601,03100,09,09,2026,26,05,02,2026-09-07,03,18450.00,0.16,0.25,4612.50
RET-2026-09-0001,TAD190521KX1,TACOS EL ALIADO DEMO,601,03100,09,09,2026,26,05,02,2026-09-14,03,21300.00,0.16,0.25,5325.00
RET-2026-09-0002,HEGL900101K44,JOSE LUIS HERNANDEZ GARCIA,625,06600,09,09,2026,26,02,02,2026-09-06,03,2850.00,0.16,0.10,285.00
RET-2026-09-0002,HEGL900101K44,JOSE LUIS HERNANDEZ GARCIA,625,06600,09,09,2026,26,02,02,2026-09-27,09,500.00,,,

Large filesCopy Anchor Link

upload_url is a resumable upload session, valid until upload_expires_at. One PUT with the whole file works. For a large file, compress it and send it in parts, so a dropped connection costs you one part and not the whole upload.

Gzip. Compress the CSV with gzip and upload it as it is: heru detects it from its content, so you do not need Content-Encoding. CSV compresses well, usually to a fifth or less.

gzip -k invoices.csv
curl -X PUT -T invoices.csv.gz "$UPLOAD_URL"

Parts. Send each part with Content-Range. Every part except the last must be a multiple of 256 KiB. heru answers 308 until the last byte arrives, and the batch stays awaiting_upload until then. This file has 300 MiB:

curl -i -X PUT -T part-1 -H "Content-Range: bytes 0-268435455/*" "$UPLOAD_URL"
curl -i -X PUT -T part-2 -H "Content-Range: bytes 268435456-314572799/314572800" "$UPLOAD_URL"

Resume. Ask how much arrived with an empty PUT. The Range header of the 308 answer says the last byte received, and you continue from the next one.

curl -i -X PUT -H "Content-Length: 0" -H "Content-Range: bytes */*" "$UPLOAD_URL"

If the file has not fully arrived by upload_expires_at, the batch goes invalid with UPLOAD_EXPIRED: create a new one.

ProgressCopy Anchor Link

GET /batches/{id} counts rows and documents separately, because one document can take several rows. succeeded, failed, cancelled and pending_review count documents.

Processing paceCopy Anchor Link

heru processes batches at its own pace, with a quota per company and a cap shared by all its clients, so that no batch takes over the stamping capacity of everyone else. Splitting a file into several batches does not make it faster.

• A ready batch carries an estimate. Once it is ready, estimated_completion_at says when heru expects it to finish and fits_lifetime whether that date is within the 20 days counted from created_at. Both come from the pace available to your company at that moment. It is an estimate, not a promise: the pace can change when other work runs, and a batch still unfinished after 20 days is cancelled, even if it said fits_lifetime: true. Before ready both are null.
• Plan for days or weeks, within 20 days. Validating a file at the limit can take around an hour, and a file of tens of millions of documents takes weeks to stamp. A batch lives 20 days at most, so if you have a date to meet or a file that may not fit, talk to your account team before uploading it.
• Events arrive as documents are stamped. You do not need to wait for batch.done: each document sends its own webhook.
• Progress can stop for a while with the batch still processing. When the PAC or the SAT do not answer, or when heru has to slow down, nothing is lost: documents wait and are retried, and a retry does not fail the document.
• A batch can outlive issue_date. The SAT allows stamping up to 72 hours after the issue date, and heru checks it again just before stamping. A document that left the window ends failed with ISSUE_DATE_OUT_OF_WINDOW. For a large file, leave issue_date empty: the document takes the moment heru prepares it, and it does not expire.

A batch that will not finishCopy Anchor Link

If fits_lifetime is false, POST /batches/{id}/process answers 409 BATCH_EXCEEDS_CAPACITY by default and stamps nothing, so a batch known not to finish does not start. You have two ways out:

• Split the file into several batches that fit, or ask your account team for more capacity.
• Start it anyway with allow_partial. heru stamps what fits and, 20 days after created_at, cancels what is still pending, with the same semantics as cancel.

{ "allow_partial": true }

While emission is paused for maintenance, a ready batch may report fits_lifetime false and process answer 409 BATCH_EXCEEDS_CAPACITY until it resumes. allow_partial still starts it.

The body is optional. Without it, or with false, the default applies.

Pause, resume and cancelCopy Anchor Link

POST /batches/{id}/pause, /resume and /cancel take no body and no Idempotency-Key: repeating one is safe. They answer 202 with the batch, or 409 BATCH_INVALID_STATE when its state does not allow them, and change nothing else. process is in the table to show where it stands: where the table says 409 it answers 409 BATCH_NOT_READY. A batch in awaiting_upload or validating can still reach ready; one that is invalid, cancelling, cancelled or done never will, so upload the file to a new batch.

In the last moment of processing, once every document has finished and the report is being written, pause, resume and cancel answer 409: the batch is about to be done.

Pause stops heru from preparing more documents. The batch shows paused at once, but documents already prepared still go to the PAC, so the counters can advance for a few minutes; in_flight_documents says how many are left. They finish so that they do not sit aging toward the 72-hour limit during a long pause. Only a batch in processing can be paused, because validating stamps nothing and a ready batch waits for you anyway, up to its 20 days. A pause does not stop those 20 days. If nothing is left to do when you pause, the batch still reaches done.

Resume continues from where it stopped.

Cancel stops what is pending. It never cancels a CFDI.

• Documents already stamped stay stamped and appear in the report. To cancel one, use its own DELETE endpoint.
• Documents on their way to the PAC finish, and end stamped or failed.
• Everything else becomes cancelled with error_code BATCH_CANCELLED. A document that was already prepared loses the folio reserved for it, which leaves a gap in that series.
• cancelling can last tens of minutes on a very large file, while heru writes the report.
• If a document still has no outcome after a bounded wait, it is pending_review and the batch closes. If it gets stamped later, its webhook arrives.
• batch.done fires once, with status cancelled, the counters and report_url, if the batch had reached process. There is no separate event. A batch cancelled in ready has a report but no event, and one cancelled before ready has neither, and its counters stay partial.

To finish what was left, upload the same file to a new batch: what was stamped comes back duplicate and only the rest is stamped. If everything was already stamped, every document is a duplicate: the batch ends done with its report and stamps nothing, and batch.done fires with status done and its report_url even though you never called process. A batch with no valid document that mixes duplicates with documents that failed validation is invalid.

A batch lives 20 days at most. They count from created_at, which is the moment of POST /batches, whatever its status, paused or not. A batch still unfinished at that point is cancelled exactly as if you had called cancel in its current status: same statuses, same BATCH_CANCELLED for what was pending, same report and same batch.done rule.

ErrorsCopy Anchor Link

errors holds the first 100 problems, in row order, each with row, column, code and reason. The header is row 1, so the first data row is row 2. error_count has the total, and errors_url a gzip CSV with every problem (row,column,code,message), signed for 15 minutes: a new GET gives you a new link. The same goes for the link in the batch.done event: its 15 minutes count from when the event was written, so a late event or a late retry needs a GET /batches/{id}. A problem with the file itself has row 0 and an empty column, and the batch goes invalid. Messages name the column and never repeat an RFC or a CURP.

{
  "status": "ready",
  "created_at": "2026-10-28T15:04:05Z",
  "estimated_completion_at": "2026-11-02T18:00:00Z",
  "fits_lifetime": true,
  "total_rows": 6,
  "validated_rows": 6,
  "valid_rows": 5,
  "invalid_rows": 1,
  "total_documents": 3,
  "valid_documents": 2,
  "invalid_documents": 1,
  "duplicates": 0,
  "errors": [
    { "row": 7, "column": "service_commission_amount", "code": "RULE_VIOLATION", "reason": "must equal service_commission_base × service_commission_rate (2475.00), within one cent" }
  ],
  "error_count": 1,
  "errors_url": "https://files.heru.app/batches/bat_01m4ra8wpbev7sf851m6pn6gm7-errors.csv.gz"
}

The reportCopy Anchor Link

report_url is a CSV with one line per row of your file, in the same order, signed for 15 minutes: a new GET gives you a new link. The same goes for the link in the batch.done event: its 15 minutes count from when the event was written, so a late event or a late retry needs a GET /batches/{id}. It is stored with gzip and served with Content-Encoding: gzip, so a plain download gives you plain CSV. It has these columns, plus your metadata_*:

row, external_id, status, id, uuid, error_code, error_message, notes

The stamped data can differ from your row. When the receiver is registered in heru and your row carries a different receiver_name, receiver_tax_regime, receiver_postal_code or receiver_curp, the document is stamped with the registered data and notes says so, naming the columns and never their values:

receiver_data_overridden:receiver_name;receiver_postal_code

It is a note, not an error: status is stamped, error_code is empty, and receiver_overrides counts these documents. An empty column does not count as different, and the RFC is never overwritten: an id that points to another RFC is PARTY_MISMATCH. The counter is an estimate until the batch closes, because the registered data can change between validating and stamping; the note in the report is what was stamped.

Sending a document again. external_id is unique per company and type across batches, so a repeated external_id comes back duplicate and is never stamped twice. A document already stamped with the same external_id wins over its own validation errors: it is reported duplicate, not invalid, so uploading a file again days later does not fail on rows that were already stamped. EXTERNAL_ID_NOT_CONTIGUOUS still applies. A failed or cancelled document can go again in a new batch.