Ask the SAT about up to 25 invoices in one call — same service and same answer per invoice as cfdi_status, with the SAT's request for restraint built in: at most 2 requests in flight, duplicates asked once, answers remembered in memory for 10 minutes (an outage is never remembered), and once 2 consecutive requests have failed no new one is started (one already in flight still finishes). Use it to reconcile a handful of invoices; it is not a bulk-verification pipeline, and the SAT states its service is sized for up to 2 million queries per hour and asks callers not to raise their volume.

Each item is either { xml } (preferred — the four values are derived from it) or { rfc_emisor, rfc_receptor, total, uuid }. An item that cannot be queried (bad XML, unstamped, malformed field) is reported on its own line with the reason and costs no request; it does not fail the batch.

Per item, outcome is: queried (asked the SAT now), cached (answered from memory, up to 10 minutes old), duplicate (same invoice as an earlier item), rejected (never sent; see error) or skipped (not attempted after repeated outages). A queried item whose result.available is false means the SAT did not answer — a statement about the SAT, never about the invoice. The same applies to skipped.

Args:

• items (array of 1-25): each with xml OR rfc_emisor + rfc_receptor + total + uuid.

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { total, queried, cached, duplicates, rejected, skipped, unavailable, stopped_after_outage, items[{index, outcome, source, error, uuid, result}] }, where result has the shape cfdi_status returns (without source).

Example: "Are these three invoices still live?" -> cfdi_batch_status(items=[{xml:"…"},{xml:"…"},{xml:"…"}]).

Ask the SAT whether an invoice actually exists and is still live. This queries the public ConsultaCFDIService SOAP endpoint — the same service the QR code printed on every Mexican invoice points at — so it needs no credentials, no CSD and no PAC contract.

Pass either the four values the SAT keys on (issuer RFC, receiver RFC, total, UUID) or the whole xml, in which case they are derived from it with the same reader parse_cfdi uses. Deriving them from the XML is the more reliable route: the total must be formatted exactly the way the printed-representation spec demands (six decimals, trailing zeros trimmed), and a total written in another format can come back as a spurious 'No Encontrado'.

What comes back, each with its meaning spelled out:

• Estado — Vigente / Cancelado / No Encontrado.

• EsCancelable — whether the issuer can cancel it unilaterally, needs the receiver's approval, or cannot cancel it at all.

• EstatusCancelacion — whether a cancellation is in progress, was accepted, was rejected, or lapsed.

• ValidacionEFOS — whether the issuer, and any third-party RFC the invoice was issued on behalf of (a cuenta de terceros), appears on the SAT's definitive 69-B list of companies that invoice simulated operations. Read with the code table the SAT documents (service documentation v1.4, section 3): 100, 101 and 104 put the issuer on the list; 102 and 103 mean the issuer is NOT on it but a third-party RFC is; 200 and 201 mean the issuer is not on it (201: nor any third party). efos_state speaks of the issuer only and efos_third_party_state of the third parties; an empty field or an undocumented code is unknown, with the raw code kept in validacion_efos.

• CodigoEstatus — the service's own result code.

Fail-soft by design. The SAT publishes no SLA and no status page, and the endpoint does go down; its documentation states capacity for up to 2 million queries per hour and asks callers not to raise their query volume, so query once per invoice and cache the answer. On timeout, refusal or a malformed answer this returns available: false with the reason instead of raising — a failed lookup is a statement about the SAT, never about the invoice. Never report a document as invalid on the strength of an unreachable service. 10-second timeout; one retry after a timeout, network error or 5xx, never after a 4xx.

Args (either shape):

• xml (string), OR rfc_emisor + rfc_receptor + total + uuid (all strings).

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { available, unavailable_reason, endpoint, expression, attempts, elapsed_ms, source, status{codigo_estatus, query_outcome, estado, document_state, document_meaning, es_cancelable, cancellable_state, cancellable_meaning, estatus_cancelacion, cancellation_state, cancellation_meaning, validacion_efos, efos_state, efos_third_party_state, efos_meaning, raw} | null, findings[] }.

Example: "Is this invoice still valid?" -> cfdi_status(xml="<cfdi:Comprobante …>").

Generate structurally valid Mexican identifiers for fixtures, database seeds and demos — generated, not taken from any real record.

For a person each record carries a coherent set: the RFC and the CURP are derived from the same name, sex, birth date and state, the CLABE's bank code is a real Banxico participant, and the NSS satisfies its Luhn digit. For a company, a razón social with a matching persona-moral RFC and a CLABE.

Why generated instead of hand-written: an RFC or CURP typed by hand almost never satisfies its check digit, so it fails the first validation your own code runs, and a seed file full of 'AAAA010101AAA' teaches your tests nothing.

These pass validation but are nobody's on purpose. They are generated from common names, so a CURP or phone number can coincide with a real person's by chance; they are not looked up at the SAT, RENAPO, IMSS or Banxico — do not send them to the SAT's status service or to a PAC.

Args:

• kind ('person' | 'company'): what to generate (default 'person').

• count (integer 1-100): how many records (default 1).

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { kind, count, people[{nombre, apellido_paterno, apellido_materno, sexo, fecha_nacimiento, entidad, entidad_nombre, rfc, curp, clabe, banco, nss, codigo_postal, telefono, email}], companies[{razon_social, rfc, clabe, banco, codigo_postal, fecha_constitucion}], findings[] }.

Example: "Give me 5 fake Mexican customers with valid RFC and CURP" -> generate_test_data(kind="person", count=5).

Turn the XML of a Mexican electronic invoice (CFDI 4.0) into structured JSON: header, issuer, receiver, every line item with its transferred and withheld taxes, the tax totals, and the Timbre Fiscal Digital (UUID, stamp date, SAT certificate number, PAC's RFC) — or timbre: null when the document was never stamped.

Three things this does beyond reading attributes:

1. It labels the catalogue codes. '601' becomes 'General de Ley Personas Morales', 'G03' becomes 'Gastos en general', 'PPD' becomes 'Pago en parcialidades o diferido'. An unknown code is reported as unknown rather than guessed at.

2. It validates both RFCs (issuer and receiver) with the full modulus-11 check, and flags the SAT generics.

3. It checks the arithmetic: subtotal − discount + transferred − withheld should equal the declared total. A mismatch is a warning, not a verdict — rounding at the line level is allowed within a centavo.

It walks the document by local element name, so it does not care whether the PAC used the cfdi: and tfd: prefixes, different ones, or none.

Which documents it takes. Any XML whose root is Comprobante: CFDI 4.0 (including tipo P with the Pagos 2.0 complement and tipo N with Nómina), and 3.3 with a version warning. Of the complements it reads only the Timbre Fiscal Digital and local taxes (ImpuestosLocales); any other present is named in findings but its content is not extracted. A 'Retenciones e información de pagos' document is a different SAT document and is refused with that explanation. Input is capped (default 2,000,000 characters, 200,000 elements), a DOCTYPE is refused, and attribute values are cut at 4,000 characters.

What this does NOT do: it does not verify the digital signature, and it does not ask the SAT anything. A document that parses cleanly can still be cancelled, or have been fabricated wholesale. Use cfdi_status for the SAT's own answer.

Args:

• xml (string): the CFDI XML.

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { version, serie, folio, fecha, tipo(+label), forma_pago(+label), metodo_pago(+label), moneda, tipo_cambio, sub_total, descuento, total, lugar_expedicion, exportacion, condiciones_de_pago, no_certificado, emisor{rfc, nombre, regimen(+label), rfc_valid, rfc_kind, rfc_errors}, receptor{… domicilio, uso(+label)}, conceptos[{descripcion, clave_prod_serv, cantidad, clave_unidad, unidad, valor_unitario, importe, descuento, objeto_imp(+label), traslados[], retenciones[]}], concepto_count, total_trasladados, total_retenidos, stamped, timbre{uuid, fecha_timbrado, no_certificado_sat, rfc_prov_certif} | null, arithmetic{…}, findings[] }.

Example: "Read this invoice and tell me who issued it and for how much" -> parse_cfdi(xml="<cfdi:Comprobante …>").

Look up the code tables a CFDI is written in, without downloading the SAT's spreadsheet. Nine catalogues, all bundled — this tool never touches the network.

• regimen_fiscal (c_RegimenFiscal) — tax regime of issuer and receiver

• uso_cfdi (c_UsoCFDI) — what the receiver does with the invoice

• forma_pago (c_FormaPago) — cash, transfer, card, …

• metodo_pago (c_MetodoPago) — PUE vs PPD

• tipo_comprobante (c_TipoDeComprobante) — I/E/T/N/P

• objeto_imp (c_ObjetoImp) — whether a line item is subject to tax (CFDI 4.0)

• impuestos (c_Impuesto) — ISR / IVA / IEPS

• bancos_clabe — Banxico participants by the first three CLABE digits

• estados_curp — RENAPO's state keys for CURP positions 12-13

With no query you get the whole catalogue. With one, an exact code match wins (leading zeros are ignored, so '1' finds '01'); failing that it falls back to a case- and accent-insensitive substring search over both code and label, so 'confianza' finds 626 and 'oaxaca' finds OC.

Two honesty notes carried in the output: the bank list is a curated subset of Banxico's participant catalogue rather than the whole thing, and the CURP state keys are RENAPO's own — they do not match INEGI or ISO 3166-2:MX codes.

Args:

• catalog (enum): one of regimen_fiscal, uso_cfdi, forma_pago, metodo_pago, tipo_comprobante, objeto_imp, impuestos, bancos_clabe, estados_curp.

• query (string, optional): an exact code, or text to search for.

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { catalog, official_name, authority, description, used_in, query, match_type, total_entries, match_count, entries[{code, label}], truncated, notes[] }.

Example: "What does UsoCFDI G03 mean?" -> sat_catalog_lookup(catalog="uso_cfdi", query="G03").

Validate an 18-digit CLABE (Clave Bancaria Estandarizada, Banxico Circular 3/2012) — the account number every SPEI transfer in Mexico is addressed to — and name the bank behind it.

Structure: 3 digits of bank + 3 of plaza (city/branch) + 11 of account + 1 control digit.

The control digit is the part everybody gets wrong. The weights cycle 3-7-1, and each weighted product counts only its last digit (the product modulo 10): 9 × 7 = 63 counts as 3. Implementations that borrow the Luhn habit of adding the product's digits (6 + 3 = 9) compute a different control digit — for the base 09000000000000000 the algorithm gives 7 and the Luhn-style sum gives 1. (Reducing modulo 10 before or after summing gives the same result; that is not where they go wrong.) This uses the correct algorithm.

The bank code is resolved against a curated subset of Banxico's participant catalogue. A code that is not in the subset is reported as unknown rather than given an invented name. The plaza code is reported verbatim: the full plaza catalogue is not bundled, so no city is guessed.

Args:

• value (string): the CLABE. Spaces and dashes are normalised away.

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { input, normalized, formatted, valid, parts{banco, plaza, cuenta, digito}, bank_code, bank_name, plaza_code, plaza_note, expected_check_digit, errors[{code, message}], findings[] }.

Example: "Which bank is CLABE 012180012345678903?" -> validate_clabe(value="012180012345678903").

Validate a Mexican CURP (Clave Única de Registro de Población) — the 18-character population ID issued by RENAPO — and decode everything it encodes: birth date, sex, state of birth and the century marker.

The 18th character is a base-37 modulus-10 check digit over the first 17, and this checks it. Two details it gets right that a regex does not:

• The state keys are RENAPO's own. 'DF' is Ciudad de México, 'MC' is Estado de México, 'NE' means born abroad. They do not match the INEGI or ISO 3166-2:MX codes, so a lookup against those tables silently mislabels people.

• The homoclave character carries the century. A digit (position 17) means born before 2000; a letter means from 2000 onwards. Without it, positions 5-10 ('99' as a year) are ambiguous.

Names that would spell one of RENAPO's inconvenient words are flagged: a real CURP carries an X in the second position instead.

Structural validity is not registration. Only RENAPO can confirm a CURP belongs to a real person, and this server never asks it.

Args:

• value (string): the CURP. Spaces, dashes and lower case are normalised away.

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { input, normalized, valid, parts{...}, birth_date, sex, sex_label, state_key, state_name, century_marker, expected_check_digit, errors[{code, message}], findings[] }.

Example: "Decode BOXW310820HNERXN09" -> validate_curp(value="BOXW310820HNERXN09").

Validate an 11-digit NSS (Número de Seguridad Social) issued by the IMSS, and split it into its fields: 2 digits of subdelegación, 2 of the year the holder was registered, 2 of the year of birth, 4 of serial, and a Luhn check digit over the first ten.

The two year fields are informational only. The IMSS has issued numbers whose years do not line up with the holder's records, so a mismatch is not grounds to reject a number — only the check digit is.

Args:

• value (string): the NSS. Spaces and dashes are normalised away.

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { input, normalized, valid, parts{subdelegacion, anioAlta, anioNacimiento, folio, digito}, expected_check_digit, errors[{code, message}], findings[] }.

Example: "Is 12345678903 a valid NSS?" -> validate_nss(value="12345678903").

Validate a Mexican RFC (Registro Federal de Contribuyentes) — the SAT taxpayer ID — and break it into its parts. Works for both shapes: 13 characters for a persona física (individual) and 12 for a persona moral (company).

The last character is a modulus-11 check digit over the preceding ones, and this checks it. Two SAT-issued generics are special-cased and reported as such:

• XAXX010101000 (público en general) does NOT satisfy the check-digit algorithm — the arithmetic asks for a '4' where the SAT wrote a '0'. It is valid by decree, not by maths, which is exactly why so many home-grown validators wrongly reject invoices to the general public.

• XEXX010101000 (residentes en el extranjero) DOES satisfy it on its own.

The tool reports is_generic and check_digit_satisfied separately so you never have to conflate the two.

Structural validity is not registration. A well-formed RFC may belong to nobody. Only the SAT can say whether one is registered and active, and this server never asks.

Args:

• value (string): the RFC. Spaces, dashes and lower case are normalised away.

• response_format ('markdown' | 'json'): output format (default 'markdown').

Returns: { input, normalized, valid, kind, is_generic, generic_note, parts{iniciales, fecha, homoclave, digito}, birth_date, expected_check_digit, check_digit_satisfied, errors[{code, message}], findings[] }.

Example: "Is GODE561231GR8 a valid RFC?" -> validate_rfc(value="GODE561231GR8").