# Timbrar una factura

`POST https://api.fiscalisto.com/v1/invoices`

Revisa la factura con las reglas del SAT, la sella y la timbra en una sola llamada. Responde con la factura timbrada (status valid) o, si el PAC tarda, en processing (escuche invoice.stamped). Lo que puede omitir tiene el valor usual: PUE, MXN, uso G03 (S01 con régimen 616), objeto de impuesto 02, IVA 16%, cantidad 1, unidad E48.

## Parámetros

| Nombre | Dónde | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `Idempotency-Key` | encabezado | sí | Uno nuevo por comprobante (8 a 255 caracteres; su id de pedido sirve). Si la respuesta se pierde, repita la solicitud con el mismo valor: contesta lo mismo y nunca se timbra dos veces. |

## Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `issuer` | string (iss_…) |  | Emisor (iss_…). Si la llave tiene un solo emisor o la cuenta tiene uno solo, puede omitirse. |
| `branch` | string (brn_…) |  | Sucursal (brn_…) desde donde se factura: su código postal va en LugarExpedicion, su dirección en el PDF y, si las tiene, sus series. Sin ella, el domicilio fiscal del emisor (la Matriz). |
| `warehouse` | string (whs_…) |  | Almacén (whs_…) de donde salen sus productos con track_stock. Por omisión, el de su sucursal (o el de la Matriz). |
| `customer` | string (cus_…) o objeto | sí | Cliente (Receptor): el id de uno de su catálogo (cus_…) o sus datos en un objeto. |
| `customer.tax_id` | string | sí | RFC (Rfc), 12 caracteres una persona moral y 13 una física. |
| `customer.legal_name` | string | sí | Nombre o razón social tal como está en la constancia de situación fiscal, sin el régimen de capital (sin «S.A. de C.V.»). (hasta 300 caracteres) |
| `customer.tax_system` | string | sí | Régimen fiscal (RegimenFiscal), clave de c_RegimenFiscal: 601, 612, 626… |
| `customer.zip` | string | sí | Código postal del domicilio fiscal del cliente (DomicilioFiscalReceptor), 5 dígitos. |
| `customer.email` | string o null |  | Correo a donde se envía (varios separados por comas). Solo se usa si se pide enviarlo. |
| `customer.foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `customer.foreign.country` | string | sí | País de residencia fiscal, clave de 3 letras de c_Pais (USA, CAN…). (3 caracteres) |
| `customer.foreign.tax_id` | string | sí | Número de registro de identidad fiscal en su país (NumRegIdTrib). (hasta 40 caracteres) |
| `customer.ieps_taxpayer` | boolean |  | true si el cliente es contribuyente de IEPS: el IEPS va desglosado en vez de sumado al precio. |
| `items` | arreglo de objeto | sí | Conceptos (Conceptos), al menos uno. (hasta 200) |
| `items[].product` | string (prd_…) |  | Un producto de su catálogo (prd_…): toma su clave, unidad, precio e impuestos. |
| `items[].description` | string |  | Descripción del concepto (Descripcion), hasta 1,000 caracteres. (hasta 1000 caracteres) |
| `items[].product_key` | string |  | Clave del producto o servicio (ClaveProdServ), 8 dígitos de c_ClaveProdServ. Búsquela con GET /v1/sat_catalogs/product_keys?q=… |
| `items[].unit_key` | string |  | Clave de unidad (ClaveUnidad) de c_ClaveUnidad: E48 unidad de servicio (por omisión), H87 pieza, ACT actividad… (hasta 5 caracteres) |
| `items[].unit_name` | string o null |  | Nombre de la unidad (Unidad), hasta 20 caracteres. |
| `items[].sku` | string o null |  | Número de identificación o SKU (NoIdentificacion). |
| `items[].quantity` | number |  | Cantidad (Cantidad). Por omisión 1. (de -∞ a 1000000000) |
| `items[].unit_price` | number |  | Precio unitario antes de impuestos (ValorUnitario). (de 0 a 1000000000000) |
| `items[].discount` | number |  | Descuento (Descuento). (de 0 a 1000000000000) |
| `items[].taxability` | `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08` |  | Objeto de impuesto (ObjetoImp), c_ObjetoImp: 01 no objeto, 02 sí objeto (por omisión), 03 sin desglose, 04 no causa… |
| `items[].iva` | `0`, `0.16`, `0.08`, `exento` |  | Tasa de IVA trasladado: 0.16 (por omisión), 0.08 (región fronteriza), 0 o exento. |
| `items[].ieps` | number |  | IEPS trasladado: tasa (0.265…) o cuota en pesos por unidad, según ieps_factor. (de 0 a 72.1605) |
| `items[].ieps_factor` | `Tasa`, `Cuota` |  | Tasa o Cuota (TipoFactor del IEPS). |
| `items[].ieps_units` | number |  | Unidades de IEPS a cuota (litros, cigarros…), si no son la cantidad. (de -∞ a 1000000000) |
| `items[].iva_retention` | number |  | Tasa de IVA retenido (por ejemplo 0.106667, dos terceras partes del 16%). (de 0 a 0.16) |
| `items[].isr_retention` | number |  | Tasa de ISR retenido (por ejemplo 0.10 honorarios, 0.0125 RESICO). (de 0 a 0.35) |
| `items[].predial` | arreglo de string |  | Números de cuenta predial (CuentaPredial) en arrendamiento. (hasta 10) |
| `items[].pedimentos` | arreglo de string |  | Números de pedimento (InformacionAduanera) de mercancía importada. (hasta 50) |
| `items[].third_party` | objeto |  | A cuenta de terceros (ACuentaTerceros): RFC, nombre, régimen y código postal. |
| `items[].third_party.tax_id` | string | sí | RFC de a cuenta de quién (RfcACuentaTerceros). (hasta 13 caracteres) |
| `items[].third_party.name` | string | sí | Nombre (NombreACuentaTerceros). (hasta 300 caracteres) |
| `items[].third_party.tax_system` | string | sí | Régimen fiscal (RegimenFiscalACuentaTerceros), c_RegimenFiscal. |
| `items[].third_party.zip` | string | sí | Código postal de su domicilio fiscal (DomicilioFiscalACuentaTerceros). |
| `items[].iedu` | objeto |  | Complemento de instituciones educativas privadas (IEDU): alumno, CURP, nivel y RVOE. |
| `items[].iedu.student_name` | string | sí | Nombre del alumno (nombreAlumno). (hasta 300 caracteres) |
| `items[].iedu.curp` | string | sí | CURP, 18 caracteres. (18 caracteres) |
| `items[].iedu.level` | `Preescolar`, `Primaria`, `Secundaria`, `Profesional técnico`, `Bachillerato o su equivalente` | sí | Nivel educativo (nivelEducativo). |
| `items[].iedu.rvoe` | string | sí | Reconocimiento de validez oficial de estudios (autRVOE). (hasta 30 caracteres) |
| `items[].iedu.payer_tax_id` | string o null |  | RFC de quien paga, si no es el receptor (rfcPago). |
| `items[].used_vehicle` | objeto |  | Complemento de vehículo usado. |
| `items[].used_vehicle.purchase_amount` | number | sí | Monto de adquisición (montoAdquisicion). (de -∞ a 1000000000000) |
| `items[].used_vehicle.sale_amount` | number | sí | Monto de enajenación (montoEnajenacion). (de -∞ a 1000000000000) |
| `items[].used_vehicle.vehicle_key` | string | sí | Clave vehicular (claveVehicular). (hasta 7 caracteres) |
| `items[].used_vehicle.make` | string | sí | Marca (marca). (hasta 50 caracteres) |
| `items[].used_vehicle.type` | string | sí | Tipo o versión (tipo). (hasta 50 caracteres) |
| `items[].used_vehicle.model` | string | sí | Año del modelo (modelo), 4 dígitos. |
| `items[].used_vehicle.engine_number` | string |  | Número de motor (numeroMotor). (hasta 17 caracteres) |
| `items[].used_vehicle.serial_number` | string |  | Número de serie (numeroSerie). (hasta 17 caracteres) |
| `items[].used_vehicle.niv` | string |  | Número de identificación vehicular (NIV). (hasta 17 caracteres) |
| `items[].used_vehicle.guide_value` | number | sí | Valor según la guía EBC o Libro Azul (valor). (de -∞ a 1000000000000) |
| `items[].used_vehicle.customs` | arreglo de objeto |  | Información aduanera de la importación del vehículo (InformacionAduanera). (hasta 10) |
| `items[].used_vehicle.customs[].number` | string | sí | Número del documento de importación (numero). (hasta 100 caracteres) |
| `items[].used_vehicle.customs[].date` | string | sí | Fecha del documento (fecha), AAAA-MM-DD. |
| `items[].used_vehicle.customs[].office` | string |  | Aduana (aduana). (hasta 100 caracteres) |
| `items[].addenda` | objeto |  | Addenda del receptor (Walmart, Soriana…), con sus propios campos. |
| `type` | `I`, `T` |  | I ingreso (por omisión; con global, factura global) o T traslado. Notas de crédito: POST /v1/credit_notes. Pagos: POST /v1/payments. (por omisión "I") |
| `carta_porte` | objeto |  | Complemento Carta Porte 3.1 (traslado de mercancías). |
| `carta_porte.modes` | arreglo de `01`, `02`, `03`, `04` |  | Cómo viajan las mercancías (c_CveTransporte): 01 autotransporte, 02 marítimo, 03 aéreo, 04 ferroviario; varios si es intermodal. Por omisión 01. (hasta 4) |
| `carta_porte.international` | objeto |  | Transporte internacional (TranspInternac Sí): entrada o salida, país, vía y regímenes aduaneros. |
| `carta_porte.international.direction` | `Entrada`, `Salida` | sí | EntradaSalidaMerc: Entrada o Salida. |
| `carta_porte.international.country` | string | sí | País de origen o destino (PaisOrigenDestino), c_Pais. (3 caracteres) |
| `carta_porte.international.via` | string | sí | Vía de entrada o salida (ViaEntradaSalida), c_CveTransporte (05 ducto incluido). (hasta 2 caracteres) |
| `carta_porte.international.regimes` | arreglo de string | sí | Regímenes aduaneros (RegimenAduanero), c_RegimenAduanero. (hasta 10) |
| `carta_porte.istmo` | objeto |  | Corredor Interoceánico del Istmo de Tehuantepec: polos de origen y destino (c_RegistroISTMO). |
| `carta_porte.istmo.origin` | string | sí | Polo de origen (UbicacionPoloOrigen). (hasta 2 caracteres) |
| `carta_porte.istmo.destination` | string | sí | Polo de destino (UbicacionPoloDestino). (hasta 2 caracteres) |
| `carta_porte.reverse_logistics` | boolean |  | Autotransporte: true si es logística inversa, recolección o devolución. |
| `carta_porte.origin` | objeto | sí | Ubicación de origen (Ubicacion TipoUbicacion Origen): remitente, fecha y hora de salida y domicilio. |
| `carta_porte.origin.tax_id` | string | sí | RFC del remitente (RFCRemitenteDestinatario); XEXX010101000 si es extranjero. |
| `carta_porte.origin.name` | string |  | Nombre del remitente (NombreRemitenteDestinatario). (hasta 254 caracteres) |
| `carta_porte.origin.foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `carta_porte.origin.foreign.tax_id` | string | sí | Número de registro de identidad fiscal en su país (NumRegIdTrib). (hasta 40 caracteres) |
| `carta_porte.origin.foreign.country` | string | sí | País de residencia fiscal, clave de 3 letras de c_Pais (USA, CAN…). (3 caracteres) |
| `carta_porte.origin.date_time` | string | sí | Fecha y hora de salida (origen) o llegada (destino), AAAA-MM-DDTHH:MM, hora local. |
| `carta_porte.origin.distance_km` | number |  | Distancia recorrida desde la ubicación anterior, en km (DistanciaRecorrida). Autotransporte y ferroviario. (de -∞ a 99999) |
| `carta_porte.origin.station` | objeto |  | Estación, puerto o aeropuerto (TipoEstacion y NumEstacion de c_Estaciones). Solo sin autotransporte. |
| `carta_porte.origin.station.type` | string |  | Tipo de estación (TipoEstacion): 01 origen, 02 intermedia, 03 destino final. (hasta 2 caracteres) |
| `carta_porte.origin.station.number` | string |  | Clave de la estación, puerto o aeropuerto (NumEstacion), c_Estaciones. (hasta 12 caracteres) |
| `carta_porte.origin.station.name` | string |  | Nombre de la estación (NombreEstacion). (hasta 50 caracteres) |
| `carta_porte.origin.station.foreign` | boolean |  | true si la estación está en el extranjero (va sin TipoEstacion). |
| `carta_porte.origin.navigation` | `Altura`, `Cabotaje` |  | Marítimo: tipo de tráfico (NavegacionTrafico), Altura o Cabotaje. |
| `carta_porte.origin.address` | objeto | sí | Domicilio (Domicilio). En México basta el código postal: estado, municipio y localidad se toman de c_CodigoPostal. |
| `carta_porte.origin.address.street` | string |  | Calle (Calle). (hasta 100 caracteres) |
| `carta_porte.origin.address.exterior` | string |  | Número exterior (NumeroExterior). (hasta 55 caracteres) |
| `carta_porte.origin.address.interior` | string |  | Número interior (NumeroInterior). (hasta 55 caracteres) |
| `carta_porte.origin.address.zip` | string | sí | Código postal (CodigoPostal). En México se deducen de él estado, municipio y localidad. (hasta 12 caracteres) |
| `carta_porte.origin.address.country` | string |  | País (Pais), c_Pais. Por omisión MEX. (3 caracteres) |
| `carta_porte.origin.address.state` | string |  | Estado (Estado): en el extranjero c_Estado para USA y CAN, o texto. (hasta 30 caracteres) |
| `carta_porte.origin.address.municipality` | string |  | Municipio (Municipio), en el extranjero como texto. (hasta 120 caracteres) |
| `carta_porte.origin.address.locality` | string |  | Localidad (Localidad), en el extranjero como texto. (hasta 120 caracteres) |
| `carta_porte.origin.address.colony` | string |  | Colonia (Colonia), en el extranjero como texto. (hasta 120 caracteres) |
| `carta_porte.destinations` | arreglo de objeto | sí | Ubicaciones de destino (TipoUbicacion Destino), en orden: destinatario, llegada, distancia y domicilio. (hasta 20) |
| `carta_porte.destinations[].tax_id` | string | sí | RFC del destinatario (RFCRemitenteDestinatario); XEXX010101000 si es extranjero. |
| `carta_porte.destinations[].name` | string |  | Nombre del destinatario (NombreRemitenteDestinatario). (hasta 254 caracteres) |
| `carta_porte.destinations[].foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `carta_porte.destinations[].foreign.tax_id` | string | sí | Número de registro de identidad fiscal en su país (NumRegIdTrib). (hasta 40 caracteres) |
| `carta_porte.destinations[].foreign.country` | string | sí | País de residencia fiscal, clave de 3 letras de c_Pais (USA, CAN…). (3 caracteres) |
| `carta_porte.destinations[].date_time` | string | sí | Fecha y hora de salida (origen) o llegada (destino), AAAA-MM-DDTHH:MM, hora local. |
| `carta_porte.destinations[].distance_km` | number |  | Distancia recorrida desde la ubicación anterior, en km (DistanciaRecorrida). Autotransporte y ferroviario. (de -∞ a 99999) |
| `carta_porte.destinations[].station` | objeto |  | Estación, puerto o aeropuerto (TipoEstacion y NumEstacion de c_Estaciones). Solo sin autotransporte. |
| `carta_porte.destinations[].station.type` | string |  | Tipo de estación (TipoEstacion): 01 origen, 02 intermedia, 03 destino final. (hasta 2 caracteres) |
| `carta_porte.destinations[].station.number` | string |  | Clave de la estación, puerto o aeropuerto (NumEstacion), c_Estaciones. (hasta 12 caracteres) |
| `carta_porte.destinations[].station.name` | string |  | Nombre de la estación (NombreEstacion). (hasta 50 caracteres) |
| `carta_porte.destinations[].station.foreign` | boolean |  | true si la estación está en el extranjero (va sin TipoEstacion). |
| `carta_porte.destinations[].navigation` | `Altura`, `Cabotaje` |  | Marítimo: tipo de tráfico (NavegacionTrafico), Altura o Cabotaje. |
| `carta_porte.destinations[].address` | objeto | sí | Domicilio (Domicilio). En México basta el código postal: estado, municipio y localidad se toman de c_CodigoPostal. |
| `carta_porte.destinations[].address.street` | string |  | Calle (Calle). (hasta 100 caracteres) |
| `carta_porte.destinations[].address.exterior` | string |  | Número exterior (NumeroExterior). (hasta 55 caracteres) |
| `carta_porte.destinations[].address.interior` | string |  | Número interior (NumeroInterior). (hasta 55 caracteres) |
| `carta_porte.destinations[].address.zip` | string | sí | Código postal (CodigoPostal). En México se deducen de él estado, municipio y localidad. (hasta 12 caracteres) |
| `carta_porte.destinations[].address.country` | string |  | País (Pais), c_Pais. Por omisión MEX. (3 caracteres) |
| `carta_porte.destinations[].address.state` | string |  | Estado (Estado): en el extranjero c_Estado para USA y CAN, o texto. (hasta 30 caracteres) |
| `carta_porte.destinations[].address.municipality` | string |  | Municipio (Municipio), en el extranjero como texto. (hasta 120 caracteres) |
| `carta_porte.destinations[].address.locality` | string |  | Localidad (Localidad), en el extranjero como texto. (hasta 120 caracteres) |
| `carta_porte.destinations[].address.colony` | string |  | Colonia (Colonia), en el extranjero como texto. (hasta 120 caracteres) |
| `carta_porte.goods` | arreglo de objeto | sí | Mercancías (Mercancia) que se transportan. (hasta 200) |
| `carta_porte.goods[].product_key` | string | sí | Clave del bien transportado (BienesTransp), c_ClaveProdServCP. |
| `carta_porte.goods[].description` | string | sí | Descripción de la mercancía (Descripcion). (hasta 1000 caracteres) |
| `carta_porte.goods[].quantity` | number | sí | Cantidad (Cantidad). (de -∞ a 1000000000) |
| `carta_porte.goods[].unit_key` | string | sí | Clave de unidad (ClaveUnidad), c_ClaveUnidad. (hasta 5 caracteres) |
| `carta_porte.goods[].weight_kg` | number | sí | Peso en kilogramos (PesoEnKg). (de 0.001 a 100000000) |
| `carta_porte.goods[].dimensions` | string |  | Dimensiones (Dimensiones), como 30/40/30cm o en plg. (hasta 20 caracteres) |
| `carta_porte.goods[].hazmat` | objeto |  | Material peligroso (MaterialPeligroso Sí): clave UN y embalaje. |
| `carta_porte.goods[].hazmat.key` | string | sí | Clave del material peligroso (CveMaterialPeligroso), c_MaterialPeligroso (número UN). (hasta 4 caracteres) |
| `carta_porte.goods[].hazmat.packaging` | string | sí | Tipo de embalaje (Embalaje), c_TipoEmbalaje. (hasta 4 caracteres) |
| `carta_porte.goods[].hazmat.packaging_description` | string |  | Descripción del embalaje (DescripEmbalaje). (hasta 100 caracteres) |
| `carta_porte.goods[].cofepris` | objeto |  | Datos COFEPRIS de la mercancía: sector y lo que pide cada uno (medicamentos, precursores, psicotrópicos, sustancias tóxicas, plaguicidas). |
| `carta_porte.goods[].cofepris.sector` | string | sí | Sector COFEPRIS (SectorCOFEPRIS): 01 medicamento, 02 precursores y químicos de uso dual, 03 psicotrópicos y estupefacientes, 04 sustancias tóxicas, 05 plaguicidas y fertilizantes. (hasta 2 caracteres) |
| `carta_porte.goods[].cofepris.active_ingredient` | string |  | Nombre del ingrediente activo (NombreIngredienteActivo). (hasta 1000 caracteres) |
| `carta_porte.goods[].cofepris.chemical_name` | string |  | Nombre químico (NomQuimico). (hasta 150 caracteres) |
| `carta_porte.goods[].cofepris.generic_name` | string |  | Denominación genérica del producto (DenominacionGenericaProd). (hasta 50 caracteres) |
| `carta_porte.goods[].cofepris.brand_name` | string |  | Denominación distintiva o marca (DenominacionDistintivaProd). (hasta 50 caracteres) |
| `carta_porte.goods[].cofepris.manufacturer` | string |  | Fabricante (Fabricante). (hasta 240 caracteres) |
| `carta_porte.goods[].cofepris.expiry` | string |  | Fecha de caducidad (FechaCaducidad), AAAA-MM-DD. (hasta 10 caracteres) |
| `carta_porte.goods[].cofepris.lot` | string |  | Lote del medicamento (LoteMedicamento). (hasta 10 caracteres) |
| `carta_porte.goods[].cofepris.form` | string |  | Forma farmacéutica (FormaFarmaceutica), c_FormaFarmaceutica. (hasta 2 caracteres) |
| `carta_porte.goods[].cofepris.conditions` | string |  | Condiciones especiales de transporte (CondicionesEspTransp), c_CondicionesEspeciales. (hasta 2 caracteres) |
| `carta_porte.goods[].cofepris.sanitary_registry` | string |  | Registro sanitario o folio de autorización (RegistroSanitarioFolioAutorizacion). (hasta 15 caracteres) |
| `carta_porte.goods[].cofepris.import_permit` | string |  | Permiso de importación (PermisoImportacion). (hasta 6 caracteres) |
| `carta_porte.goods[].cofepris.vucem_folio` | string |  | Folio de importación VUCEM (FolioImpoVUCEM). (hasta 25 caracteres) |
| `carta_porte.goods[].cofepris.cas` | string |  | Número CAS de la sustancia (NumCAS). (hasta 15 caracteres) |
| `carta_porte.goods[].cofepris.importer` | string |  | Razón social de la empresa importadora (RazonSocialEmpImp). (hasta 80 caracteres) |
| `carta_porte.goods[].cofepris.pesticide_registry` | string |  | Registro sanitario de plaguicidas COFEPRIS (NumRegSanPlagCOFEPRIS). (hasta 60 caracteres) |
| `carta_porte.goods[].cofepris.manufacturer_data` | string |  | Datos del fabricante (DatosFabricante). (hasta 600 caracteres) |
| `carta_porte.goods[].cofepris.formulator_data` | string |  | Datos del formulador (DatosFormulador). (hasta 600 caracteres) |
| `carta_porte.goods[].cofepris.maquilador_data` | string |  | Datos del maquilador (DatosMaquilador). (hasta 600 caracteres) |
| `carta_porte.goods[].cofepris.authorized_use` | string |  | Uso autorizado (UsoAutorizado). (hasta 1000 caracteres) |
| `carta_porte.goods[].value` | number |  | Valor de la mercancía (ValorMercancia); obligatorio en transporte aéreo. (de 0 a 1000000000000000) |
| `carta_porte.goods[].currency` | string |  | Moneda del valor de la mercancía (Moneda), c_Moneda. (3 caracteres) |
| `carta_porte.goods[].tariff` | string |  | Fracción arancelaria (FraccionArancelaria), 10 dígitos. Transporte internacional. (hasta 10 caracteres) |
| `carta_porte.goods[].cce_uuid` | string |  | UUID del CFDI con complemento de comercio exterior (UUIDComercioExt). (hasta 36 caracteres) |
| `carta_porte.goods[].material` | objeto |  | Tipo de materia (TipoMateria, c_TipoMateria) y su descripción si es «otra». |
| `carta_porte.goods[].material.type` | string | sí | Tipo de materia (TipoMateria), c_TipoMateria. (hasta 2 caracteres) |
| `carta_porte.goods[].material.description` | string |  | Descripción de la materia (DescripcionMateria), con el tipo 05 otra. (hasta 50 caracteres) |
| `carta_porte.goods[].customs_docs` | arreglo de objeto |  | Documentación aduanera (DocumentacionAduanera) de la mercancía en transporte internacional. (hasta 20) |
| `carta_porte.goods[].customs_docs[].type` | string | sí | Tipo de documento (TipoDocumento), c_DocumentoAduanero: 01 pedimento… (hasta 2 caracteres) |
| `carta_porte.goods[].customs_docs[].pedimento` | string |  | Número de pedimento (NumPedimento), con el formato «NN  NN  NNNN  NNNNNNN». Solo con el tipo 01. (hasta 21 caracteres) |
| `carta_porte.goods[].customs_docs[].doc_id` | string |  | Identificador del documento aduanero (IdentDocAduanero), con un tipo distinto de 01. (hasta 150 caracteres) |
| `carta_porte.goods[].customs_docs[].importer_tax_id` | string |  | RFC del importador (RFCImpo), con un pedimento. (hasta 13 caracteres) |
| `carta_porte.goods[].guides` | arreglo de objeto |  | Paquetería: guías de los paquetes o tarimas (GuiasIdentificacion). (hasta 100) |
| `carta_porte.goods[].guides[].number` | string | sí | Número de guía (NumeroGuiaIdentificacion). (hasta 30 caracteres) |
| `carta_porte.goods[].guides[].description` | string | sí | Descripción del contenido (DescripGuiaIdentificacion). (hasta 1000 caracteres) |
| `carta_porte.goods[].guides[].weight_kg` | number | sí | Peso en kilogramos (PesoEnKg). (de 0 a 100000000) |
| `carta_porte.goods[].quantities` | arreglo de objeto |  | Cuánto va a cada destino (CantidadTransporta), por destino. (hasta 40) |
| `carta_porte.goods[].quantities[].quantity` | number | sí | Cantidad que va a ese destino. (de -∞ a 1000000000) |
| `carta_porte.goods[].quantities[].destination` | integer | sí | El destino, por su posición en destinations (desde 0). (de 0 a 19) |
| `carta_porte.goods[].quantities[].mode` | `01`, `02`, `03`, `04` |  | Medio en que va esa cantidad (CvesTransporte), c_CveTransporte. |
| `carta_porte.goods[].detail` | objeto |  | Marítimo: detalle de la mercancía (DetalleMercancia): kilos netos, tara y piezas. |
| `carta_porte.goods[].detail.net_kg` | number | sí | Peso neto en kg (PesoNeto). (de 0 a 100000000) |
| `carta_porte.goods[].detail.tare_kg` | number | sí | Tara en kg (PesoTara). (de 0 a 100000000) |
| `carta_porte.goods[].detail.pieces` | integer |  | Número de piezas (NumPiezas). (de 0 a 1000000000) |
| `carta_porte.goods[].stcc` | string |  | Ferroviario: clave STCC (ClaveSTCC). (hasta 7 caracteres) |
| `carta_porte.vehicle` | objeto |  | Autotransporte (Autotransporte): vehículo, permiso SCT, seguros y remolques. |
| `carta_porte.vehicle.config` | string | sí | Configuración vehicular (ConfigVehicular), c_ConfigAutotransporte: C2, T3S2… (hasta 10 caracteres) |
| `carta_porte.vehicle.plate` | string | sí | Placa (PlacaVM), sin guiones ni espacios. (hasta 10 caracteres) |
| `carta_porte.vehicle.year` | integer | sí | Año del modelo (AnioModeloVM). (de 0 a 2100) |
| `carta_porte.vehicle.gross_weight` | number | sí | Peso bruto vehicular en toneladas (PesoBrutoVehicular). (de 0 a 999) |
| `carta_porte.vehicle.permit_type` | string | sí | Tipo de permiso SCT (PermSCT), c_TipoPermiso. (hasta 50 caracteres) |
| `carta_porte.vehicle.permit_number` | string | sí | Número de permiso SCT (NumPermisoSCT). (hasta 50 caracteres) |
| `carta_porte.vehicle.insurer` | string | sí | Aseguradora de responsabilidad civil (AseguraRespCivil). (hasta 50 caracteres) |
| `carta_porte.vehicle.policy` | string | sí | Póliza de responsabilidad civil (PolizaRespCivil). (hasta 30 caracteres) |
| `carta_porte.vehicle.env_insurer` | string |  | Aseguradora de daños al medio ambiente (AseguraMedAmbiente); obligatoria con material peligroso. (hasta 50 caracteres) |
| `carta_porte.vehicle.env_policy` | string |  | Póliza de daños al medio ambiente (PolizaMedAmbiente). (hasta 30 caracteres) |
| `carta_porte.vehicle.cargo_insurer` | string |  | Aseguradora de la carga (AseguraCarga). (hasta 50 caracteres) |
| `carta_porte.vehicle.cargo_policy` | string |  | Póliza de la carga (PolizaCarga). (hasta 30 caracteres) |
| `carta_porte.vehicle.premium` | number |  | Prima del seguro (PrimaSeguro). (de 0 a 1000000000000) |
| `carta_porte.vehicle.trailers` | arreglo de objeto |  | Remolques o semirremolques (Remolque): tipo (c_SubTipoRem) y placa. (hasta 2) |
| `carta_porte.vehicle.trailers[].type` | string | sí | Subtipo de remolque (SubTipoRem), c_SubTipoRem. (hasta 10 caracteres) |
| `carta_porte.vehicle.trailers[].plate` | string | sí | Placa del remolque (Placa). (hasta 10 caracteres) |
| `carta_porte.sea` | objeto |  | Transporte marítimo (TransporteMaritimo): embarcación, naviero y contenedores. |
| `carta_porte.sea.permit_type` | string |  | Tipo de permiso SCT (PermSCT), c_TipoPermiso. (hasta 10 caracteres) |
| `carta_porte.sea.permit_number` | string |  | Número de permiso SCT (NumPermisoSCT). (hasta 30 caracteres) |
| `carta_porte.sea.insurer` | string |  | Aseguradora de responsabilidad civil (AseguraRespCivil). (hasta 50 caracteres) |
| `carta_porte.sea.policy` | string |  | Póliza de responsabilidad civil (PolizaRespCivil). (hasta 30 caracteres) |
| `carta_porte.sea.vessel_type` | string | sí | Tipo de embarcación (TipoEmbarcacion), c_ConfigMaritima. (hasta 4 caracteres) |
| `carta_porte.sea.registration` | string | sí | Matrícula (Matricula). (hasta 30 caracteres) |
| `carta_porte.sea.imo` | string | sí | Número IMO (NumeroOMI): IMO y 7 dígitos. (hasta 10 caracteres) |
| `carta_porte.sea.year` | integer |  | Año de la embarcación (AnioEmbarcacion). (de 0 a 2100) |
| `carta_porte.sea.vessel_name` | string |  | Nombre de la embarcación (NombreEmbarc). (hasta 50 caracteres) |
| `carta_porte.sea.flag` | string | sí | Nacionalidad de la embarcación (NacionalidadEmbarc), c_Pais. (3 caracteres) |
| `carta_porte.sea.gross_tonnage` | number | sí | Unidades de arqueo bruto (UnidadesDeArqBruto). (de 0 a 1000000000) |
| `carta_porte.sea.cargo_type` | string | sí | Tipo de carga (TipoCarga), c_ClaveTipoCarga. (hasta 4 caracteres) |
| `carta_porte.sea.length` | number |  | Eslora en metros (Eslora). (de 0 a 100000) |
| `carta_porte.sea.beam` | number |  | Manga en metros (Manga). (de 0 a 100000) |
| `carta_porte.sea.draft` | number |  | Calado en metros (Calado). (de 0 a 100000) |
| `carta_porte.sea.depth` | number |  | Puntal en metros (Puntal). (de 0 a 100000) |
| `carta_porte.sea.line` | string |  | Línea naviera (LineaNaviera). (hasta 50 caracteres) |
| `carta_porte.sea.agent_name` | string | sí | Nombre del agente naviero consignatario (NombreAgenteNaviero). (hasta 100 caracteres) |
| `carta_porte.sea.agent_authorization` | string | sí | Autorización del agente naviero (NumAutorizacionNaviero), c_NumAutorizacionNaviero. (hasta 20 caracteres) |
| `carta_porte.sea.voyage` | string |  | Número de viaje (NumViaje). (hasta 30 caracteres) |
| `carta_porte.sea.bill_of_lading` | string |  | Número de conocimiento de embarque (NumConocEmbarc). (hasta 30 caracteres) |
| `carta_porte.sea.temp_permit` | string |  | Permiso temporal de navegación (PermisoTempNavegacion), para una embarcación extranjera. (hasta 19 caracteres) |
| `carta_porte.sea.containers` | arreglo de objeto |  | Contenedores (Contenedor). (hasta 100) |
| `carta_porte.sea.containers[].type` | string | sí | Tipo de contenedor (TipoContenedor), c_ContenedorMaritimo o c_Contenedor en ferroviario. (hasta 6 caracteres) |
| `carta_porte.sea.containers[].registration` | string |  | Matrícula (Matricula). (hasta 15 caracteres) |
| `carta_porte.sea.containers[].seal` | string |  | Número de precinto (NumPrecinto). (hasta 20 caracteres) |
| `carta_porte.sea.containers[].related_id_ccp` | string |  | Ferri: el IdCCP de la Carta Porte del autotransporte a bordo (IdCCPRelacionado). (hasta 36 caracteres) |
| `carta_porte.sea.containers[].truck_plate` | string |  | Ferri: placa del vehículo a bordo (PlacaVMCCP). (hasta 10 caracteres) |
| `carta_porte.sea.containers[].certified_at` | string |  | Ferri: fecha de certificación de la Carta Porte del vehículo (FechaCertificacionCCP). (hasta 19 caracteres) |
| `carta_porte.sea.containers[].trailers` | arreglo de objeto |  | Remolques o semirremolques (Remolque): tipo (c_SubTipoRem) y placa. (hasta 2) |
| `carta_porte.sea.containers[].trailers[].type` | string | sí | Subtipo de remolque (SubTipoRem), c_SubTipoRem. (hasta 10 caracteres) |
| `carta_porte.sea.containers[].trailers[].plate` | string | sí | Placa del remolque (Placa). (hasta 10 caracteres) |
| `carta_porte.air` | objeto |  | Transporte aéreo (TransporteAereo): permiso, guía y transportista. |
| `carta_porte.air.permit_type` | string | sí | Tipo de permiso SCT (PermSCT), c_TipoPermiso. (hasta 10 caracteres) |
| `carta_porte.air.permit_number` | string | sí | Número de permiso SCT (NumPermisoSCT). (hasta 50 caracteres) |
| `carta_porte.air.aircraft` | string |  | Matrícula de la aeronave (MatriculaAeronave). (hasta 11 caracteres) |
| `carta_porte.air.insurer` | string |  | Aseguradora de responsabilidad civil (AseguraRespCivil). (hasta 50 caracteres) |
| `carta_porte.air.policy` | string |  | Póliza de responsabilidad civil (PolizaRespCivil). (hasta 30 caracteres) |
| `carta_porte.air.waybill` | string | sí | Número de guía aérea (NumeroGuia), de 12 a 15 caracteres. (hasta 15 caracteres) |
| `carta_porte.air.contract_place` | string |  | Lugar del contrato (LugarContrato). (hasta 120 caracteres) |
| `carta_porte.air.carrier` | string | sí | Código del transportista (CodigoTransportista), c_CodigoTransporteAereo. (hasta 6 caracteres) |
| `carta_porte.air.shipper` | objeto |  | Embarcador (RFCEmbarcador o NumRegIdTribEmbarc y ResidenciaFiscalEmbarc, NombreEmbarcador). |
| `carta_porte.air.shipper.tax_id` | string |  | RFC del embarcador (RFCEmbarcador). (hasta 13 caracteres) |
| `carta_porte.air.shipper.foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `carta_porte.air.shipper.foreign.tax_id` | string | sí | Número de registro de identidad fiscal en su país (NumRegIdTrib). (hasta 40 caracteres) |
| `carta_porte.air.shipper.foreign.country` | string | sí | País de residencia fiscal, clave de 3 letras de c_Pais (USA, CAN…). (3 caracteres) |
| `carta_porte.air.shipper.name` | string |  | Nombre del embarcador (NombreEmbarcador). (hasta 254 caracteres) |
| `carta_porte.air.rate_charge` | number |  | Cargo por tasación (CargoPorTasacion). (de 0 a 1000000000000000) |
| `carta_porte.rail` | objeto |  | Transporte ferroviario (TransporteFerroviario): servicio, tráfico, derechos de paso y carros. |
| `carta_porte.rail.service` | string | sí | Tipo de servicio (TipoDeServicio), c_TipoDeServicio. (hasta 4 caracteres) |
| `carta_porte.rail.traffic` | string | sí | Tipo de tráfico (TipoDeTrafico), c_TipoDeTrafico. (hasta 4 caracteres) |
| `carta_porte.rail.insurer` | string |  | Aseguradora de responsabilidad civil (AseguraRespCivil). (hasta 50 caracteres) |
| `carta_porte.rail.policy` | string |  | Póliza de responsabilidad civil (PolizaRespCivil). (hasta 30 caracteres) |
| `carta_porte.rail.rights` | arreglo de objeto |  | Derechos de paso (DerechosDePaso): tipo y kilómetros. (hasta 50) |
| `carta_porte.rail.rights[].type` | string | sí | Tipo de derecho de paso (TipoDerechoDePaso), c_DerechosDePaso. (hasta 6 caracteres) |
| `carta_porte.rail.rights[].km` | number | sí | Kilometraje pagado (KilometrajePagado). (de 0 a 100000) |
| `carta_porte.rail.cars` | arreglo de objeto | sí | Carros (Carro). (hasta 200) |
| `carta_porte.rail.cars[].type` | string | sí | Tipo de carro (TipoCarro), c_TipoCarro. (hasta 4 caracteres) |
| `carta_porte.rail.cars[].registration` | string | sí | Matrícula (Matricula). (hasta 15 caracteres) |
| `carta_porte.rail.cars[].guide` | string | sí | Guía del carro (GuiaCarro). (hasta 15 caracteres) |
| `carta_porte.rail.cars[].net_tons` | number | sí | Toneladas netas del carro (ToneladasNetasCarro). (de 0 a 1000000) |
| `carta_porte.rail.cars[].containers` | arreglo de objeto |  | Contenedores (Contenedor). (hasta 10) |
| `carta_porte.rail.cars[].containers[].type` | string | sí | Tipo de contenedor (TipoContenedor), c_ContenedorMaritimo o c_Contenedor en ferroviario. (hasta 4 caracteres) |
| `carta_porte.rail.cars[].containers[].empty_kg` | number | sí | Peso del contenedor vacío en kg (PesoContenedorVacio). (de 0 a 100000000) |
| `carta_porte.rail.cars[].containers[].net_kg` | number | sí | Peso neto en kg (PesoNeto). (de 0 a 100000000) |
| `carta_porte.drivers` | arreglo de objeto | sí | Operadores (FiguraTransporte tipo 01): RFC, licencia y nombre. (hasta 5) |
| `carta_porte.drivers[].tax_id` | string o `""` | sí | RFC del operador (RFCFigura); vacío si es extranjero (con foreign). |
| `carta_porte.drivers[].license` | string | sí | Número de licencia (NumLicencia). (hasta 16 caracteres) |
| `carta_porte.drivers[].name` | string | sí | Nombre del operador (NombreFigura). (hasta 254 caracteres) |
| `carta_porte.drivers[].foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `carta_porte.drivers[].foreign.tax_id` | string | sí | Número de registro de identidad fiscal en su país (NumRegIdTrib). (hasta 40 caracteres) |
| `carta_porte.drivers[].foreign.country` | string | sí | País de residencia fiscal, clave de 3 letras de c_Pais (USA, CAN…). (3 caracteres) |
| `carta_porte.figures` | arreglo de objeto |  | Otras figuras de transporte: 02 propietario, 03 arrendador, 04 notificado, 05 integrante de coordinados. (hasta 10) |
| `carta_porte.figures[].type` | `02`, `03`, `04`, `05` | sí | Tipo de figura (TipoFigura): 02 propietario, 03 arrendador, 04 notificado, 05 integrante. |
| `carta_porte.figures[].tax_id` | string |  | RFC de la figura (RFCFigura). |
| `carta_porte.figures[].foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `carta_porte.figures[].foreign.tax_id` | string | sí | Número de registro de identidad fiscal en su país (NumRegIdTrib). (hasta 40 caracteres) |
| `carta_porte.figures[].foreign.country` | string | sí | País de residencia fiscal, clave de 3 letras de c_Pais (USA, CAN…). (3 caracteres) |
| `carta_porte.figures[].name` | string | sí | Nombre de la figura (NombreFigura). (hasta 254 caracteres) |
| `carta_porte.figures[].parts` | arreglo de string |  | Partes del transporte que posee o arrienda (ParteTransporte), c_ParteTransporte. (hasta 20) |
| `carta_porte.figures[].address` | objeto |  | Domicilio (Domicilio). En México basta el código postal: estado, municipio y localidad se toman de c_CodigoPostal. |
| `carta_porte.figures[].address.street` | string |  | Calle (Calle). (hasta 100 caracteres) |
| `carta_porte.figures[].address.exterior` | string |  | Número exterior (NumeroExterior). (hasta 55 caracteres) |
| `carta_porte.figures[].address.interior` | string |  | Número interior (NumeroInterior). (hasta 55 caracteres) |
| `carta_porte.figures[].address.zip` | string | sí | Código postal (CodigoPostal). En México se deducen de él estado, municipio y localidad. (hasta 12 caracteres) |
| `carta_porte.figures[].address.country` | string |  | País (Pais), c_Pais. Por omisión MEX. (3 caracteres) |
| `carta_porte.figures[].address.state` | string |  | Estado (Estado): en el extranjero c_Estado para USA y CAN, o texto. (hasta 30 caracteres) |
| `carta_porte.figures[].address.municipality` | string |  | Municipio (Municipio), en el extranjero como texto. (hasta 120 caracteres) |
| `carta_porte.figures[].address.locality` | string |  | Localidad (Localidad), en el extranjero como texto. (hasta 120 caracteres) |
| `carta_porte.figures[].address.colony` | string |  | Colonia (Colonia), en el extranjero como texto. (hasta 120 caracteres) |
| `ine` | objeto |  | Complemento INE (procesos electorales). |
| `ine.process` | `Ordinario`, `Precampaña`, `Campaña` | sí | Tipo de proceso (TipoProceso): Ordinario, Precampaña o Campaña. |
| `ine.committee` | `Ejecutivo Nacional`, `Ejecutivo Estatal`, `Directivo Estatal` |  | Tipo de comité (TipoComite), con el proceso Ordinario. |
| `ine.accounting_id` | string |  | Clave de contabilidad (IdContabilidad), hasta 6 dígitos. |
| `ine.entities` | arreglo de objeto |  | Entidades (Entidad): clave del estado, ámbito y claves de contabilidad. (hasta 64) |
| `ine.entities[].key` | string | sí | Clave de la entidad (ClaveEntidad), 3 letras. (3 caracteres) |
| `ine.entities[].scope` | `Local`, `Federal` |  | Ámbito (Ambito): Local o Federal. |
| `ine.entities[].accounting_ids` | arreglo de string |  | Claves de contabilidad (IdContabilidad). (hasta 50) |
| `leyendas` | arreglo de objeto |  | Complemento de leyendas fiscales. (hasta 10) |
| `leyendas[].text` | string | sí | Texto de la leyenda (textoLeyenda). (hasta 1000 caracteres) |
| `leyendas[].disposition` | string |  | Disposición fiscal (disposicionFiscal), por ejemplo LISR. (hasta 30 caracteres) |
| `leyendas[].norm` | string |  | Norma o artículo (norma). (hasta 100 caracteres) |
| `donation` | objeto |  | Complemento de donatarias. |
| `donation.in_kind` | boolean |  | true si el donativo es en especie (va sin forma de pago en efectivo). |
| `donation.deducted` | boolean |  | true si el donativo es deducible para quien lo da. |
| `local_taxes` | arreglo de objeto |  | Impuestos locales (complemento implocal): traslados y retenciones estatales. (hasta 20) |
| `local_taxes[].retention` | boolean | sí | true si es una retención local; false si es un traslado. |
| `local_taxes[].name` | string | sí | Nombre del impuesto local (ImpLocTrasladado o ImpLocRetenido), como ISH. (hasta 100 caracteres) |
| `local_taxes[].rate` | number | sí | Tasa en por ciento (TasadeTraslado o TasadeRetencion). (de 0 a 100) |
| `local_taxes[].amount` | number | sí | Importe del impuesto local. (de 0 a 1000000000000) |
| `export` | `01`, `02`, `03`, `04` |  | Exportación (Exportacion), c_Exportacion: 01 no aplica (por omisión), 02 definitiva… |
| `comercio_exterior` | objeto |  | Complemento de comercio exterior 2.0. |
| `comercio_exterior.motive` | `"05"` |  | Motivo de traslado (MotivoTraslado): 05 envío de mercancías propias. |
| `comercio_exterior.owners` | arreglo de objeto |  | Propietarios de la mercancía si no es el emisor (Propietario), con motive 05. (hasta 10) |
| `comercio_exterior.owners[].tax_id` | string | sí | Número de registro tributario del propietario (NumRegIdTrib). (hasta 40 caracteres) |
| `comercio_exterior.owners[].country` | string | sí | País de residencia del propietario (ResidenciaFiscal), c_Pais. (3 caracteres) |
| `comercio_exterior.incoterm` | string |  | Incoterm (Incoterm), c_INCOTERM: EXW, FOB, CIF, DAP, DDP… (3 caracteres) |
| `comercio_exterior.certificate` | string |  | Número de certificado de origen (NumCertificadoOrigen). (hasta 40 caracteres) |
| `comercio_exterior.usd_rate` | number | sí | Tipo de cambio a dólares (TipoCambioUSD). (de -∞ a 1000000) |
| `comercio_exterior.issuer_curp` | string |  | CURP del emisor persona física (Emisor Curp). (18 caracteres) |
| `comercio_exterior.issuer_address` | objeto |  | Domicilio del emisor (Emisor Domicilio): calle y números; lo demás sale de su código postal. |
| `comercio_exterior.issuer_address.street` | string | sí | Calle (Calle). (hasta 100 caracteres) |
| `comercio_exterior.issuer_address.exterior` | string |  | Número exterior (NumeroExterior). (hasta 55 caracteres) |
| `comercio_exterior.issuer_address.interior` | string |  | Número interior (NumeroInterior). (hasta 55 caracteres) |
| `comercio_exterior.issuer_address.zip` | string |  | Código postal del emisor (CodigoPostal). |
| `comercio_exterior.receiver_address` | objeto |  | Domicilio del receptor en el extranjero (Receptor Domicilio). |
| `comercio_exterior.receiver_address.street` | string | sí | Calle (Calle). (hasta 100 caracteres) |
| `comercio_exterior.receiver_address.exterior` | string |  | Número exterior (NumeroExterior). (hasta 55 caracteres) |
| `comercio_exterior.receiver_address.interior` | string |  | Número interior (NumeroInterior). (hasta 55 caracteres) |
| `comercio_exterior.receiver_address.colony` | string |  | Colonia (Colonia), en el extranjero como texto. (hasta 120 caracteres) |
| `comercio_exterior.receiver_address.locality` | string |  | Localidad (Localidad), en el extranjero como texto. (hasta 120 caracteres) |
| `comercio_exterior.receiver_address.municipality` | string |  | Municipio (Municipio), en el extranjero como texto. (hasta 120 caracteres) |
| `comercio_exterior.receiver_address.state` | string |  | Estado (Estado), c_Estado para USA y CAN. (hasta 30 caracteres) |
| `comercio_exterior.receiver_address.country` | string | sí | País (Pais), c_Pais. (3 caracteres) |
| `comercio_exterior.receiver_address.zip` | string | sí | Código postal en su país (CodigoPostal). (hasta 12 caracteres) |
| `comercio_exterior.recipient` | objeto |  | Destinatario, si no es el receptor (Destinatario). |
| `comercio_exterior.recipient.name` | string |  | Nombre del destinatario (Nombre). (hasta 300 caracteres) |
| `comercio_exterior.recipient.tax_id` | string |  | Número de registro tributario del destinatario (NumRegIdTrib). (hasta 40 caracteres) |
| `comercio_exterior.recipient.address` | objeto | sí | Domicilio del destinatario (Domicilio). |
| `comercio_exterior.recipient.address.street` | string | sí | Calle (Calle). (hasta 100 caracteres) |
| `comercio_exterior.recipient.address.exterior` | string |  | Número exterior (NumeroExterior). (hasta 55 caracteres) |
| `comercio_exterior.recipient.address.interior` | string |  | Número interior (NumeroInterior). (hasta 55 caracteres) |
| `comercio_exterior.recipient.address.colony` | string |  | Colonia (Colonia), en el extranjero como texto. (hasta 120 caracteres) |
| `comercio_exterior.recipient.address.locality` | string |  | Localidad (Localidad), en el extranjero como texto. (hasta 120 caracteres) |
| `comercio_exterior.recipient.address.municipality` | string |  | Municipio (Municipio), en el extranjero como texto. (hasta 120 caracteres) |
| `comercio_exterior.recipient.address.state` | string |  | Estado (Estado): en el extranjero c_Estado para USA y CAN, o texto. (hasta 30 caracteres) |
| `comercio_exterior.recipient.address.country` | string | sí | País (Pais), c_Pais. Por omisión MEX. (3 caracteres) |
| `comercio_exterior.recipient.address.zip` | string | sí | Código postal (CodigoPostal). En México se deducen de él estado, municipio y localidad. (hasta 12 caracteres) |
| `comercio_exterior.goods` | arreglo de objeto | sí | Mercancías (Mercancia), una por concepto exportado. (hasta 200) |
| `comercio_exterior.goods[].id` | string |  | Número de identificación de la mercancía (NoIdentificacion): el sku de su concepto. (hasta 100 caracteres) |
| `comercio_exterior.goods[].tariff` | string |  | Fracción arancelaria (FraccionArancelaria), 10 dígitos. Transporte internacional. |
| `comercio_exterior.goods[].unit` | string | sí | Unidad aduana (UnidadAduana), c_UnidadAduana. |
| `comercio_exterior.goods[].quantity` | number |  | Cantidad en la unidad aduana (CantidadAduana). (de -∞ a 100000000000000) |
| `comercio_exterior.goods[].unit_value_usd` | number |  | Valor unitario en dólares (ValorUnitarioAduana). (de 0 a 10000000000000000) |
| `comercio_exterior.notes` | string |  | Observaciones del complemento (Observaciones). (hasta 300 caracteres) |
| `global` | objeto |  | Factura global a público en general (InformacionGlobal): periodicidad, meses y año. |
| `global.periodicity` | string | sí | Periodicidad (Periodicidad), c_Periodicidad: 01 diario, 02 semanal, 03 quincenal, 04 mensual, 05 bimestral. |
| `global.months` | string | sí | Meses (Meses), c_Meses: 01 a 12, o 13 a 18 bimestres. |
| `global.year` | integer | sí | Año (Año). (de 2022 a 2100) |
| `use` | string |  | Uso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616. |
| `payment_form` | string |  | Forma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99. |
| `payment_method` | `PUE`, `PPD` |  | Método de pago (MetodoPago): PUE (una sola exhibición, por omisión) o PPD (en parcialidades o diferido, se cobra con complementos de pago). |
| `paid_later` | boolean |  | Con PUE: true si aún no le pagan («Por cobrar» en la app) aunque se pagará este mes. |
| `currency` | string |  | Moneda, clave ISO 4217 de c_Moneda (MXN, USD, EUR…). Por omisión MXN. (3 caracteres) |
| `series` | string |  | Serie (Serie), hasta 25 caracteres. Cada serie lleva sus propios folios. (hasta 25 caracteres) |
| `notes` | string |  | Observaciones que aparecen en el PDF (no van en el XML). (hasta 1000 caracteres) |
| `pdf_language` | `es`, `en`, `bi` |  | Idioma del PDF: es (por omisión) o en. |
| `addenda` | objeto |  | Addenda del receptor (Walmart, Soriana…), con sus propios campos. |
| `related` | objeto |  | CFDI relacionados (CfdiRelacionados): tipo de relación de c_TipoRelacion y los UUID. |
| `related.relationship` | string | sí | Tipo de relación (TipoRelacion): 01 nota de crédito, 03 devolución, 04 sustitución, 07 anticipo… |
| `related.uuids` | arreglo de string | sí | Folios fiscales relacionados. (hasta 20) |
| `exchange_rate` | number |  | Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior. (de -∞ a 1000000) |
| `folio` | integer |  | Folio (Folio). Fiscalisto asigna el siguiente de la serie; mande uno solo si debe ser ese. (de 1 a 2000000000) |
| `continue_sequence` | boolean |  | Con un folio elegido: true para que los siguientes sigan desde ese número. |
| `date` | string |  | Fecha de emisión (Fecha) si no es ahora, AAAA-MM-DDTHH:MM:SS hora de la Ciudad de México: hasta 72 horas antes. |
| `send_email` | boolean |  | true para mandar el PDF y el XML por correo al timbrar, con el diseño de Fiscalisto. Por omisión no se envía. (por omisión false) |
| `email_cc` | string o null |  | Correos con copia, separados por comas. |
| `metadata` | objeto |  | Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks. |

Ejemplo:

```json
{
  "customer": {
    "tax_id": "ICV060329BY0",
    "legal_name": "INMOBILIARIA CVA",
    "tax_system": "601",
    "zip": "33826",
    "email": "pagos@cva.example"
  },
  "payment_form": "03",
  "items": [
    {
      "description": "Mensualidad",
      "product_key": "86121700",
      "quantity": 2,
      "unit_price": 2500
    }
  ],
  "send_email": true,
  "metadata": {
    "pedido": "A-1042"
  }
}
```

## Con el SDK de TypeScript

```ts
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

const invoice = await fiscalisto.invoices.create({
  customer: {
    tax_id: "ICV060329BY0",
    legal_name: "INMOBILIARIA CVA",
    tax_system: "601",
    zip: "33826",
    email: "pagos@cva.example",
  },
  payment_form: "03",
  items: [
    {
      description: "Mensualidad",
      product_key: "86121700",
      quantity: 2,
      unit_price: 2500,
    },
  ],
  send_email: true,
  metadata: { pedido: "A-1042" },
}, { idempotencyKey: "pedido-A-1042" });
```

## Con el SDK de Python

```python
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

invoice = fiscalisto.invoices.create({
    "customer": {
        "tax_id": "ICV060329BY0",
        "legal_name": "INMOBILIARIA CVA",
        "tax_system": "601",
        "zip": "33826",
        "email": "pagos@cva.example",
    },
    "payment_form": "03",
    "items": [
        {
            "description": "Mensualidad",
            "product_key": "86121700",
            "quantity": 2,
            "unit_price": 2500,
        },
    ],
    "send_email": True,
    "metadata": {"pedido": "A-1042"},
}, idempotency_key="pedido-A-1042")
```

## Con el SDK de PHP

```php
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

$invoice = $fiscalisto->invoices->create([
    'customer' => [
        'tax_id' => 'ICV060329BY0',
        'legal_name' => 'INMOBILIARIA CVA',
        'tax_system' => '601',
        'zip' => '33826',
        'email' => 'pagos@cva.example',
    ],
    'payment_form' => '03',
    'items' => [
        [
            'description' => 'Mensualidad',
            'product_key' => '86121700',
            'quantity' => 2,
            'unit_price' => 2500,
        ],
    ],
    'send_email' => true,
    'metadata' => ['pedido' => 'A-1042'],
], ['idempotency_key' => 'pedido-A-1042']);
```

## Con el SDK de .NET

```csharp
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var invoice = await fiscalisto.Invoices.CreateAsync(new InvoiceCreate
{
    Customer = new InvoiceCreateCustomer
    {
        TaxId = "ICV060329BY0",
        LegalName = "INMOBILIARIA CVA",
        TaxSystem = "601",
        Zip = "33826",
        Email = "pagos@cva.example",
    },
    PaymentForm = "03",
    Items = new()
    {
        new()
        {
            Description = "Mensualidad",
            ProductKey = "86121700",
            Quantity = 2,
            UnitPrice = 2500,
        },
    },
    SendEmail = true,
    Metadata = new() { ["pedido"] = "A-1042" },
}, new RequestOptions { IdempotencyKey = "pedido-A-1042" });
```

## Con el SDK de Go

```go
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	invoice, err := client.Invoices.Create(ctx, &fiscalisto.InvoiceCreate{
		Customer: fiscalisto.ObjectOf(fiscalisto.InvoiceCreateCustomer{
			TaxID:     "ICV060329BY0",
			LegalName: "INMOBILIARIA CVA",
			TaxSystem: "601",
			Zip:       "33826",
			Email:     fiscalisto.String("pagos@cva.example"),
		}),
		PaymentForm: fiscalisto.String("03"),
		Items: []fiscalisto.InvoiceCreateItem{
			{
				Description: fiscalisto.String("Mensualidad"),
				ProductKey:  fiscalisto.String("86121700"),
				Quantity:    fiscalisto.Float64(2),
				UnitPrice:   fiscalisto.Float64(2500),
			},
		},
		SendEmail: fiscalisto.Bool(true),
		Metadata:  map[string]string{"pedido": "A-1042"},
	}, fiscalisto.WithIdempotencyKey("pedido-A-1042"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(invoice.ID)
}
```

## Con el SDK de Java

```java
import com.fiscalisto.FiscalistoClient;
import com.fiscalisto.RequestOptions;
import com.fiscalisto.model.InvoiceCreate;
import com.fiscalisto.model.InvoiceCreateCustomer;
import com.fiscalisto.model.InvoiceCreateItem;
import java.util.List;
import java.util.Map;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var invoice = fiscalisto.invoices().create(new InvoiceCreate()
        .setCustomer(new InvoiceCreateCustomer()
                .setTaxId("ICV060329BY0")
                .setLegalName("INMOBILIARIA CVA")
                .setTaxSystem("601")
                .setZip("33826")
                .setEmail("pagos@cva.example"))
        .setPaymentForm("03")
        .setItems(List.of(
                new InvoiceCreateItem()
                        .setDescription("Mensualidad")
                        .setProductKey("86121700")
                        .setQuantity(2)
                        .setUnitPrice(2500)
        ))
        .setSendEmail(true)
        .setMetadata(Map.of("pedido", "A-1042")), RequestOptions.idempotencyKey("pedido-A-1042"));
System.out.println(invoice.getId());
```

## Respuesta 201

Correcto. Repetir la solicitud con la misma Idempotency-Key contesta lo mismo, con el mismo status y el encabezado idempotent-replayed: true.

Un objeto `Invoice`:

| Campo | Tipo | Siempre viene | Descripción |
| --- | --- | --- | --- |
| `id` | string | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `object` | `"invoice"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `issuer` | string | sí | El emisor (iss_…). |
| `branch` | string o null | sí | La sucursal (brn_…) desde donde se timbró, o null (el domicilio fiscal del emisor). Sus pagos y notas de crédito la siguen. |
| `type` | `I`, `E`, `P`, `T`, `N` | sí | Tipo de comprobante (TipoDeComprobante): I ingreso, E egreso, P pago, T traslado, N nómina. |
| `status` | `processing`, `pending`, `valid`, `rejected`, `canceled` | sí | processing: el PAC no ha contestado (se resuelve sola; escuche invoice.stamped). valid: timbrada. pending: timbrada con una cancelación en espera del cliente. rejected: el SAT o el PAC no la aceptaron (ver error). canceled: cancelada. |
| `uuid` | string o null | sí | Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas. |
| `series` | string o null | sí | Serie (Serie), hasta 25 caracteres. Cada serie lleva sus propios folios. |
| `folio` | string o null | sí | Folio (Folio). Fiscalisto asigna el siguiente de la serie; mande uno solo si debe ser ese. |
| `date` | string o null | sí | Fecha de emisión (Fecha), hora de la Ciudad de México. |
| `customer` | objeto | sí | Cliente (Receptor): el id de uno de su catálogo (cus_…) o sus datos en un objeto. |
| `customer.tax_id` | string o null | sí | RFC (Rfc), 12 caracteres una persona moral y 13 una física. |
| `customer.legal_name` | string o null | sí | Nombre o razón social tal como está en la constancia de situación fiscal, sin el régimen de capital (sin «S.A. de C.V.»). |
| `customer.tax_system` | string |  | Régimen fiscal (RegimenFiscal), clave de c_RegimenFiscal: 601, 612, 626… |
| `customer.zip` | string |  | Código postal del domicilio fiscal del cliente (DomicilioFiscalReceptor), 5 dígitos. |
| `customer.foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `use` | string o null | sí | Uso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616. |
| `payment_form` | string o null | sí | Forma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99. |
| `payment_method` | string o null | sí | Método de pago (MetodoPago): PUE (una sola exhibición, por omisión) o PPD (en parcialidades o diferido, se cobra con complementos de pago). |
| `currency` | string | sí | Moneda, clave ISO 4217 de c_Moneda (MXN, USD, EUR…). Por omisión MXN. |
| `exchange_rate` | number o null | sí | Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior. |
| `items` | arreglo de objeto | sí | Conceptos (Conceptos), al menos uno. |
| `subtotal` | number o null | sí | Suma de los importes antes de impuestos y descuentos (SubTotal). |
| `discount` | number o null | sí | Descuento (Descuento). |
| `taxes` | objeto o null | sí | Impuestos del comprobante, por tipo. |
| `taxes.iva` | number o null | sí | IVA trasladado. |
| `taxes.ieps` | number o null | sí | IEPS trasladado. |
| `taxes.iva_withheld` | number o null | sí | IVA retenido. |
| `taxes.isr_withheld` | number o null | sí | ISR retenido. |
| `taxes.local_transferred` | number o null | sí | Impuestos locales trasladados. |
| `taxes.local_withheld` | number o null | sí | Impuestos locales retenidos. |
| `total` | number o null | sí | Total en la moneda del comprobante (Total). |
| `payment_status` | `paid`, `partial`, `unpaid` o null | sí | Si ya se cobró (Cuentas por cobrar): paid, partial (complementos de pago o notas de crédito por una parte) o unpaid. Una PUE está paid, salvo con paid_later hasta POST /v1/invoices/{id}/mark_paid. null si no es de ingreso o no está vigente. |
| `amount_due` | number o null | sí | Lo que falta por cobrar, en su moneda, o null. |
| `amount_paid` | number o null | sí | Lo cobrado: complementos de pago y notas de crédito vigentes, o todo si es PUE pagada. null si no aplica. |
| `related` | objeto o null | sí | CFDI relacionados (CfdiRelacionados): tipo de relación de c_TipoRelacion y los UUID. |
| `payment` | objeto o null |  | Solo en un complemento de pago (type P). |
| `payment.date` | string o null | sí | Fecha del pago (FechaPago). |
| `payment.payment_form` | string o null | sí | Forma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99. |
| `payment.currency` | string | sí | Moneda del pago (MonedaP). |
| `payment.exchange_rate` | number o null | sí | Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior. |
| `payment.amount` | number | sí | Monto del pago (Monto). |
| `payment.operation_number` | string o null | sí | Número de operación del pago (NumOperacion), como el rastreo SPEI. |
| `payment.documents` | arreglo de objeto | sí | Las facturas que paga (DoctoRelacionado). |
| `payment.documents[].uuid` | string | sí | Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas. |
| `payment.documents[].series` | string o null | sí | Serie de la factura pagada. |
| `payment.documents[].folio` | string o null | sí | Folio de la factura pagada. |
| `payment.documents[].currency` | string | sí | Moneda de la factura pagada (MonedaDR). |
| `payment.documents[].partiality` | integer | sí | Número de parcialidad (NumParcialidad). (de -9007199254740991 a 9007199254740991) |
| `payment.documents[].previous_balance` | number | sí | Saldo anterior de la factura (ImpSaldoAnt). |
| `payment.documents[].amount` | number | sí | Lo que se paga de esa factura (ImpPagado), en la moneda de la factura. |
| `payment.documents[].remaining` | number | sí | Saldo insoluto después de este pago (ImpSaldoInsoluto). |
| `payroll` | objeto |  | Solo en un recibo de nómina (type N). |
| `payroll.periodicity` | string | sí | Periodicidad del pago (PeriodicidadPago): 02 semanal, 03 catorcenal, 04 quincenal (por omisión), 05 mensual. |
| `payroll.period` | objeto | sí | Periodo (Periodo): mes inicial, mes final y año. |
| `payroll.period.start` | string | sí | Primer día del periodo (FechaInicialPago), AAAA-MM-DD. |
| `payroll.period.end` | string | sí | Último día del periodo (FechaFinalPago), AAAA-MM-DD. |
| `payroll.period.payment_date` | string | sí | Fecha de pago (FechaPago), AAAA-MM-DD. Por omisión el último día del periodo. |
| `payroll.days` | number | sí | Días pagados (NumDiasPagados). Por omisión, todos los del periodo que le tocan. |
| `payroll.employer` | objeto | sí | El patrón (Emisor del complemento): registro patronal y CURP si es persona física. |
| `payroll.employer.employer_registration` | string o null | sí | Registro patronal ante el IMSS (RegistroPatronal), 11 caracteres. Necesario para timbrar nómina. |
| `payroll.employer.curp` | string o null | sí | CURP, 18 caracteres. |
| `payroll.employee` | objeto | sí | El empleado (emp_…). |
| `payroll.employee.id` | string o null | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `payroll.employee.number` | string | sí | Número de empleado (NumEmpleado). |
| `payroll.employee.curp` | string | sí | CURP, 18 caracteres. |
| `payroll.employee.social_security_number` | string o null | sí | Número de seguridad social (NumSeguridadSocial), 11 dígitos. |
| `payroll.employee.start_date` | string | sí | Fecha de inicio de la relación laboral (FechaInicioRelLaboral), AAAA-MM-DD. |
| `payroll.employee.contract_type` | string | sí | Tipo de contrato (TipoContrato), c_TipoContrato. Por omisión 01, por tiempo indeterminado. |
| `payroll.employee.unionized` | boolean | sí | true si es sindicalizado (Sindicalizado). |
| `payroll.employee.workday_type` | string | sí | Tipo de jornada (TipoJornada), c_TipoJornada. Por omisión 01, diurna. |
| `payroll.employee.regime_type` | string | sí | Tipo de régimen (TipoRegimen): 02 sueldos y salarios. |
| `payroll.employee.department` | string o null |  | Departamento (Departamento). |
| `payroll.employee.position` | string o null |  | Puesto (Puesto). |
| `payroll.employee.risk_class` | string o null | sí | Clase de riesgo del puesto ante el IMSS (RiesgoPuesto), 1 a 5. Por omisión 1. |
| `payroll.employee.contribution_base_salary` | number o null | sí | Salario base de cotización (SalarioBaseCotApor). |
| `payroll.employee.integrated_daily_salary` | number o null | sí | Salario diario integrado (SalarioDiarioIntegrado): no menor al salario diario. |
| `payroll.employee.state` | string | sí | Entidad federativa donde trabaja (ClaveEntFed): JAL, CMX, NLE… |
| `payroll.perceptions` | arreglo de objeto | sí | Percepciones (Percepcion): sueldo y demás, gravado y exento. |
| `payroll.perceptions[].type` | string | sí | Tipo de percepción (TipoPercepcion), c_TipoPercepcion: 001 sueldos… |
| `payroll.perceptions[].key` | string | sí | Clave del patrón (Clave). |
| `payroll.perceptions[].concept` | string | sí | Concepto (Concepto). |
| `payroll.perceptions[].taxed` | number | sí | Importe gravado (ImporteGravado). |
| `payroll.perceptions[].exempt` | number | sí | Importe exento (ImporteExento). |
| `payroll.deductions` | arreglo de objeto | sí | Deducciones (Deduccion): ISR, cuotas IMSS y demás. |
| `payroll.deductions[].type` | string | sí | Tipo de deducción (TipoDeduccion), c_TipoDeduccion: 001 IMSS, 002 ISR… |
| `payroll.deductions[].key` | string | sí | Clave del patrón (Clave). |
| `payroll.deductions[].concept` | string | sí | Concepto (Concepto). |
| `payroll.deductions[].amount` | number | sí | Importe (Importe). |
| `payroll.other_payments` | arreglo de objeto | sí | Otros pagos (OtroPago): subsidio para el empleo. |
| `payroll.other_payments[].type` | string | sí | Tipo de otro pago (TipoOtroPago), c_TipoOtroPago: 002 subsidio para el empleo. |
| `payroll.other_payments[].key` | string | sí | Clave del patrón (Clave). |
| `payroll.other_payments[].concept` | string | sí | Concepto (Concepto). |
| `payroll.other_payments[].amount` | number | sí | Importe pagado (Importe). |
| `payroll.other_payments[].subsidy_caused` | number |  | Subsidio causado (SubsidioCausado). |
| `payroll.other_payments[].subsidy_applied` | number |  | Del subsidio causado, el ISR que evitó (no va en el XML). |
| `global` | objeto |  | Solo en una factura global. |
| `cancellation` | objeto o null | sí | La cancelación, si se pidió: estado, motivo, sustituto y cuándo. |
| `cancellation.status` | string o null | sí | pending (espera la respuesta del cliente), accepted (cancelada), rejected (el cliente la rechazó) o lapsed (venció; puede pedirla otra vez). |
| `cancellation.motive` | string o null | sí | Motivo de cancelación (c_MotivoCancelacion): 01 con errores con relación (lleva substitution), 02 con errores sin relación (por omisión), 03 no se llevó a cabo, 04 solo en una factura global, cuando una venta incluida se facturó a nombre del cliente. |
| `cancellation.substitution` | string o null | sí | El comprobante que sustituye a este (su id o su UUID), con el motivo 01. |
| `cancellation.canceled_at` | string (date-time) o null | sí | Cuándo se canceló. |
| `email` | objeto o null | sí | El envío por correo: a quién, con copia a quién y cuándo (null si no se ha enviado). |
| `email.to` | string o null | sí | A quién (correos separados por comas). |
| `email.cc` | string o null | sí | Con copia (correos separados por comas). |
| `email.sent_at` | string (date-time) o null | sí | Cuándo se envió. |
| `error` | objeto o null | sí | Por qué el SAT o el PAC no lo aceptaron: mensaje, código del SAT y texto original. |
| `error.message` | string | sí | Qué pasó y cómo corregirlo, para una persona. |
| `error.sat_code` | string o null | sí | Código del SAT o del PAC (CFDI40xxx). |
| `error.raw` | string | sí | El texto original del PAC. |
| `recurring_invoice` | string o null | sí | La factura recurrente (rin_…) que la timbró sola, o null si se timbró con una llamada. |
| `created_at` | string (date-time) o null | sí | Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00). |
| `metadata` | objeto | sí | Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks. |
| `warnings` | arreglo de string |  | Avisos que no impidieron timbrar (por ejemplo, el XML se guardará después). |
| `email_error` | string |  | Por qué no se pudo mandar el correo; el comprobante sí se timbró. |
| `substitutes` | objeto |  | La factura que esta sustituyó y si quedó cancelada. |
| `substitutes.invoice` | string | sí | La factura sustituida (inv_…). |
| `substitutes.canceled` | boolean | sí | true si la sustituida ya quedó cancelada. |
| `substitutes.cancel_error` | string |  | Por qué no se pudo cancelar la sustituida (cancélela con POST /v1/invoices/{id}/cancel). |
| `advance_application` | objeto |  | La aplicación del anticipo: método, nota de aplicación y su estado. |
| `advance_application.advance` | string o null | sí | El anticipo, como factura (inv_…). |
| `advance_application.advance_uuid` | string | sí | El folio fiscal del anticipo. |
| `advance_application.method` | `egreso`, `remanente` | sí | egreso (la factura completa y después una nota de crédito por el anticipo, opción A) o remanente (la factura solo por lo que falta, opción B). |
| `advance_application.status` | `done`, `credit_note_pending` | sí | done (listo) o credit_note_pending (falta timbrar la nota de aplicación: repita la solicitud con la misma Idempotency-Key). |
| `advance_application.credit_note` | string o null | sí | La nota de aplicación del anticipo (inv_…), con method egreso. |
| `advance_application.credit_note_error` | string |  | Por qué no se timbró la nota de aplicación (repita con la misma Idempotency-Key). |

```json
{
  "id": "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg",
  "object": "invoice",
  "livemode": false,
  "issuer": "iss_OufpKqnrvx9p",
  "branch": null,
  "type": "I",
  "status": "valid",
  "uuid": "5F1E8C2A-3B7D-4C9E-A1B2-C3D4E5F60718",
  "series": null,
  "folio": "1",
  "date": "2026-10-24T10:15:42",
  "customer": {
    "tax_id": "ICV060329BY0",
    "legal_name": "INMOBILIARIA CVA",
    "tax_system": "601",
    "zip": "33826"
  },
  "use": "I04",
  "payment_form": "03",
  "payment_method": "PUE",
  "currency": "MXN",
  "exchange_rate": null,
  "items": [
    {
      "description": "Mensualidad",
      "product_key": "86121700",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio",
      "sku": "MEN-1",
      "quantity": 2,
      "unit_price": 2500,
      "taxability": "02",
      "iva": "0.16"
    }
  ],
  "subtotal": 5000,
  "discount": 0,
  "taxes": {
    "iva": 800,
    "ieps": 0,
    "iva_withheld": 0,
    "isr_withheld": 0,
    "local_transferred": 0,
    "local_withheld": 0
  },
  "total": 5800,
  "payment_status": "paid",
  "amount_due": 0,
  "amount_paid": 5800,
  "related": null,
  "cancellation": null,
  "email": null,
  "error": null,
  "recurring_invoice": null,
  "created_at": "2026-10-24T10:15:42-06:00",
  "metadata": {}
}
```

## Respuesta 202

El PAC no contestó a tiempo: el comprobante queda en processing y se timbra solo en unos momentos. Escuche el evento *.stamped o consúltelo con GET; repetir la solicitud con la misma Idempotency-Key contesta su estado sin timbrar otra vez.

Un objeto `Invoice`:

| Campo | Tipo | Siempre viene | Descripción |
| --- | --- | --- | --- |
| `id` | string | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `object` | `"invoice"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `issuer` | string | sí | El emisor (iss_…). |
| `branch` | string o null | sí | La sucursal (brn_…) desde donde se timbró, o null (el domicilio fiscal del emisor). Sus pagos y notas de crédito la siguen. |
| `type` | `I`, `E`, `P`, `T`, `N` | sí | Tipo de comprobante (TipoDeComprobante): I ingreso, E egreso, P pago, T traslado, N nómina. |
| `status` | `processing`, `pending`, `valid`, `rejected`, `canceled` | sí | processing: el PAC no ha contestado (se resuelve sola; escuche invoice.stamped). valid: timbrada. pending: timbrada con una cancelación en espera del cliente. rejected: el SAT o el PAC no la aceptaron (ver error). canceled: cancelada. |
| `uuid` | string o null | sí | Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas. |
| `series` | string o null | sí | Serie (Serie), hasta 25 caracteres. Cada serie lleva sus propios folios. |
| `folio` | string o null | sí | Folio (Folio). Fiscalisto asigna el siguiente de la serie; mande uno solo si debe ser ese. |
| `date` | string o null | sí | Fecha de emisión (Fecha), hora de la Ciudad de México. |
| `customer` | objeto | sí | Cliente (Receptor): el id de uno de su catálogo (cus_…) o sus datos en un objeto. |
| `customer.tax_id` | string o null | sí | RFC (Rfc), 12 caracteres una persona moral y 13 una física. |
| `customer.legal_name` | string o null | sí | Nombre o razón social tal como está en la constancia de situación fiscal, sin el régimen de capital (sin «S.A. de C.V.»). |
| `customer.tax_system` | string |  | Régimen fiscal (RegimenFiscal), clave de c_RegimenFiscal: 601, 612, 626… |
| `customer.zip` | string |  | Código postal del domicilio fiscal del cliente (DomicilioFiscalReceptor), 5 dígitos. |
| `customer.foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `use` | string o null | sí | Uso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616. |
| `payment_form` | string o null | sí | Forma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99. |
| `payment_method` | string o null | sí | Método de pago (MetodoPago): PUE (una sola exhibición, por omisión) o PPD (en parcialidades o diferido, se cobra con complementos de pago). |
| `currency` | string | sí | Moneda, clave ISO 4217 de c_Moneda (MXN, USD, EUR…). Por omisión MXN. |
| `exchange_rate` | number o null | sí | Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior. |
| `items` | arreglo de objeto | sí | Conceptos (Conceptos), al menos uno. |
| `subtotal` | number o null | sí | Suma de los importes antes de impuestos y descuentos (SubTotal). |
| `discount` | number o null | sí | Descuento (Descuento). |
| `taxes` | objeto o null | sí | Impuestos del comprobante, por tipo. |
| `taxes.iva` | number o null | sí | IVA trasladado. |
| `taxes.ieps` | number o null | sí | IEPS trasladado. |
| `taxes.iva_withheld` | number o null | sí | IVA retenido. |
| `taxes.isr_withheld` | number o null | sí | ISR retenido. |
| `taxes.local_transferred` | number o null | sí | Impuestos locales trasladados. |
| `taxes.local_withheld` | number o null | sí | Impuestos locales retenidos. |
| `total` | number o null | sí | Total en la moneda del comprobante (Total). |
| `payment_status` | `paid`, `partial`, `unpaid` o null | sí | Si ya se cobró (Cuentas por cobrar): paid, partial (complementos de pago o notas de crédito por una parte) o unpaid. Una PUE está paid, salvo con paid_later hasta POST /v1/invoices/{id}/mark_paid. null si no es de ingreso o no está vigente. |
| `amount_due` | number o null | sí | Lo que falta por cobrar, en su moneda, o null. |
| `amount_paid` | number o null | sí | Lo cobrado: complementos de pago y notas de crédito vigentes, o todo si es PUE pagada. null si no aplica. |
| `related` | objeto o null | sí | CFDI relacionados (CfdiRelacionados): tipo de relación de c_TipoRelacion y los UUID. |
| `payment` | objeto o null |  | Solo en un complemento de pago (type P). |
| `payment.date` | string o null | sí | Fecha del pago (FechaPago). |
| `payment.payment_form` | string o null | sí | Forma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99. |
| `payment.currency` | string | sí | Moneda del pago (MonedaP). |
| `payment.exchange_rate` | number o null | sí | Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior. |
| `payment.amount` | number | sí | Monto del pago (Monto). |
| `payment.operation_number` | string o null | sí | Número de operación del pago (NumOperacion), como el rastreo SPEI. |
| `payment.documents` | arreglo de objeto | sí | Las facturas que paga (DoctoRelacionado). |
| `payment.documents[].uuid` | string | sí | Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas. |
| `payment.documents[].series` | string o null | sí | Serie de la factura pagada. |
| `payment.documents[].folio` | string o null | sí | Folio de la factura pagada. |
| `payment.documents[].currency` | string | sí | Moneda de la factura pagada (MonedaDR). |
| `payment.documents[].partiality` | integer | sí | Número de parcialidad (NumParcialidad). (de -9007199254740991 a 9007199254740991) |
| `payment.documents[].previous_balance` | number | sí | Saldo anterior de la factura (ImpSaldoAnt). |
| `payment.documents[].amount` | number | sí | Lo que se paga de esa factura (ImpPagado), en la moneda de la factura. |
| `payment.documents[].remaining` | number | sí | Saldo insoluto después de este pago (ImpSaldoInsoluto). |
| `payroll` | objeto |  | Solo en un recibo de nómina (type N). |
| `payroll.periodicity` | string | sí | Periodicidad del pago (PeriodicidadPago): 02 semanal, 03 catorcenal, 04 quincenal (por omisión), 05 mensual. |
| `payroll.period` | objeto | sí | Periodo (Periodo): mes inicial, mes final y año. |
| `payroll.period.start` | string | sí | Primer día del periodo (FechaInicialPago), AAAA-MM-DD. |
| `payroll.period.end` | string | sí | Último día del periodo (FechaFinalPago), AAAA-MM-DD. |
| `payroll.period.payment_date` | string | sí | Fecha de pago (FechaPago), AAAA-MM-DD. Por omisión el último día del periodo. |
| `payroll.days` | number | sí | Días pagados (NumDiasPagados). Por omisión, todos los del periodo que le tocan. |
| `payroll.employer` | objeto | sí | El patrón (Emisor del complemento): registro patronal y CURP si es persona física. |
| `payroll.employer.employer_registration` | string o null | sí | Registro patronal ante el IMSS (RegistroPatronal), 11 caracteres. Necesario para timbrar nómina. |
| `payroll.employer.curp` | string o null | sí | CURP, 18 caracteres. |
| `payroll.employee` | objeto | sí | El empleado (emp_…). |
| `payroll.employee.id` | string o null | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `payroll.employee.number` | string | sí | Número de empleado (NumEmpleado). |
| `payroll.employee.curp` | string | sí | CURP, 18 caracteres. |
| `payroll.employee.social_security_number` | string o null | sí | Número de seguridad social (NumSeguridadSocial), 11 dígitos. |
| `payroll.employee.start_date` | string | sí | Fecha de inicio de la relación laboral (FechaInicioRelLaboral), AAAA-MM-DD. |
| `payroll.employee.contract_type` | string | sí | Tipo de contrato (TipoContrato), c_TipoContrato. Por omisión 01, por tiempo indeterminado. |
| `payroll.employee.unionized` | boolean | sí | true si es sindicalizado (Sindicalizado). |
| `payroll.employee.workday_type` | string | sí | Tipo de jornada (TipoJornada), c_TipoJornada. Por omisión 01, diurna. |
| `payroll.employee.regime_type` | string | sí | Tipo de régimen (TipoRegimen): 02 sueldos y salarios. |
| `payroll.employee.department` | string o null |  | Departamento (Departamento). |
| `payroll.employee.position` | string o null |  | Puesto (Puesto). |
| `payroll.employee.risk_class` | string o null | sí | Clase de riesgo del puesto ante el IMSS (RiesgoPuesto), 1 a 5. Por omisión 1. |
| `payroll.employee.contribution_base_salary` | number o null | sí | Salario base de cotización (SalarioBaseCotApor). |
| `payroll.employee.integrated_daily_salary` | number o null | sí | Salario diario integrado (SalarioDiarioIntegrado): no menor al salario diario. |
| `payroll.employee.state` | string | sí | Entidad federativa donde trabaja (ClaveEntFed): JAL, CMX, NLE… |
| `payroll.perceptions` | arreglo de objeto | sí | Percepciones (Percepcion): sueldo y demás, gravado y exento. |
| `payroll.perceptions[].type` | string | sí | Tipo de percepción (TipoPercepcion), c_TipoPercepcion: 001 sueldos… |
| `payroll.perceptions[].key` | string | sí | Clave del patrón (Clave). |
| `payroll.perceptions[].concept` | string | sí | Concepto (Concepto). |
| `payroll.perceptions[].taxed` | number | sí | Importe gravado (ImporteGravado). |
| `payroll.perceptions[].exempt` | number | sí | Importe exento (ImporteExento). |
| `payroll.deductions` | arreglo de objeto | sí | Deducciones (Deduccion): ISR, cuotas IMSS y demás. |
| `payroll.deductions[].type` | string | sí | Tipo de deducción (TipoDeduccion), c_TipoDeduccion: 001 IMSS, 002 ISR… |
| `payroll.deductions[].key` | string | sí | Clave del patrón (Clave). |
| `payroll.deductions[].concept` | string | sí | Concepto (Concepto). |
| `payroll.deductions[].amount` | number | sí | Importe (Importe). |
| `payroll.other_payments` | arreglo de objeto | sí | Otros pagos (OtroPago): subsidio para el empleo. |
| `payroll.other_payments[].type` | string | sí | Tipo de otro pago (TipoOtroPago), c_TipoOtroPago: 002 subsidio para el empleo. |
| `payroll.other_payments[].key` | string | sí | Clave del patrón (Clave). |
| `payroll.other_payments[].concept` | string | sí | Concepto (Concepto). |
| `payroll.other_payments[].amount` | number | sí | Importe pagado (Importe). |
| `payroll.other_payments[].subsidy_caused` | number |  | Subsidio causado (SubsidioCausado). |
| `payroll.other_payments[].subsidy_applied` | number |  | Del subsidio causado, el ISR que evitó (no va en el XML). |
| `global` | objeto |  | Solo en una factura global. |
| `cancellation` | objeto o null | sí | La cancelación, si se pidió: estado, motivo, sustituto y cuándo. |
| `cancellation.status` | string o null | sí | pending (espera la respuesta del cliente), accepted (cancelada), rejected (el cliente la rechazó) o lapsed (venció; puede pedirla otra vez). |
| `cancellation.motive` | string o null | sí | Motivo de cancelación (c_MotivoCancelacion): 01 con errores con relación (lleva substitution), 02 con errores sin relación (por omisión), 03 no se llevó a cabo, 04 solo en una factura global, cuando una venta incluida se facturó a nombre del cliente. |
| `cancellation.substitution` | string o null | sí | El comprobante que sustituye a este (su id o su UUID), con el motivo 01. |
| `cancellation.canceled_at` | string (date-time) o null | sí | Cuándo se canceló. |
| `email` | objeto o null | sí | El envío por correo: a quién, con copia a quién y cuándo (null si no se ha enviado). |
| `email.to` | string o null | sí | A quién (correos separados por comas). |
| `email.cc` | string o null | sí | Con copia (correos separados por comas). |
| `email.sent_at` | string (date-time) o null | sí | Cuándo se envió. |
| `error` | objeto o null | sí | Por qué el SAT o el PAC no lo aceptaron: mensaje, código del SAT y texto original. |
| `error.message` | string | sí | Qué pasó y cómo corregirlo, para una persona. |
| `error.sat_code` | string o null | sí | Código del SAT o del PAC (CFDI40xxx). |
| `error.raw` | string | sí | El texto original del PAC. |
| `recurring_invoice` | string o null | sí | La factura recurrente (rin_…) que la timbró sola, o null si se timbró con una llamada. |
| `created_at` | string (date-time) o null | sí | Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00). |
| `metadata` | objeto | sí | Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks. |
| `warnings` | arreglo de string |  | Avisos que no impidieron timbrar (por ejemplo, el XML se guardará después). |
| `email_error` | string |  | Por qué no se pudo mandar el correo; el comprobante sí se timbró. |
| `substitutes` | objeto |  | La factura que esta sustituyó y si quedó cancelada. |
| `substitutes.invoice` | string | sí | La factura sustituida (inv_…). |
| `substitutes.canceled` | boolean | sí | true si la sustituida ya quedó cancelada. |
| `substitutes.cancel_error` | string |  | Por qué no se pudo cancelar la sustituida (cancélela con POST /v1/invoices/{id}/cancel). |
| `advance_application` | objeto |  | La aplicación del anticipo: método, nota de aplicación y su estado. |
| `advance_application.advance` | string o null | sí | El anticipo, como factura (inv_…). |
| `advance_application.advance_uuid` | string | sí | El folio fiscal del anticipo. |
| `advance_application.method` | `egreso`, `remanente` | sí | egreso (la factura completa y después una nota de crédito por el anticipo, opción A) o remanente (la factura solo por lo que falta, opción B). |
| `advance_application.status` | `done`, `credit_note_pending` | sí | done (listo) o credit_note_pending (falta timbrar la nota de aplicación: repita la solicitud con la misma Idempotency-Key). |
| `advance_application.credit_note` | string o null | sí | La nota de aplicación del anticipo (inv_…), con method egreso. |
| `advance_application.credit_note_error` | string |  | Por qué no se timbró la nota de aplicación (repita con la misma Idempotency-Key). |

```json
{
  "id": "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg",
  "object": "invoice",
  "livemode": false,
  "issuer": "iss_OufpKqnrvx9p",
  "branch": null,
  "type": "I",
  "status": "valid",
  "uuid": "5F1E8C2A-3B7D-4C9E-A1B2-C3D4E5F60718",
  "series": null,
  "folio": "1",
  "date": "2026-10-24T10:15:42",
  "customer": {
    "tax_id": "ICV060329BY0",
    "legal_name": "INMOBILIARIA CVA",
    "tax_system": "601",
    "zip": "33826"
  },
  "use": "I04",
  "payment_form": "03",
  "payment_method": "PUE",
  "currency": "MXN",
  "exchange_rate": null,
  "items": [
    {
      "description": "Mensualidad",
      "product_key": "86121700",
      "unit_key": "E48",
      "unit_name": "Unidad de servicio",
      "sku": "MEN-1",
      "quantity": 2,
      "unit_price": 2500,
      "taxability": "02",
      "iva": "0.16"
    }
  ],
  "subtotal": 5000,
  "discount": 0,
  "taxes": {
    "iva": 800,
    "ieps": 0,
    "iva_withheld": 0,
    "isr_withheld": 0,
    "local_transferred": 0,
    "local_withheld": 0
  },
  "total": 5800,
  "payment_status": "paid",
  "amount_due": 0,
  "amount_paid": 5800,
  "related": null,
  "cancellation": null,
  "email": null,
  "error": null,
  "recurring_invoice": null,
  "created_at": "2026-10-24T10:15:42-06:00",
  "metadata": {}
}
```

## Errores

Puede responder 400, 401, 402, 403, 404, 409, 422, 429, 500 con el cuerpo de error de siempre; cada código está en https://fiscalisto.com/docs/api/errores.md.