Ingreso y traslado
TipoDeComprobante I para cobrar el flete o T para mover tu propia mercancía. En un traslado, la API deja SubTotal, Total e importes en 0, la moneda en XXX y el uso del CFDI en S01, como pide el SAT.
API de Carta Porte 3.1, timbra desde tu sistema
Envías el JSON con el complemento Carta Porte 3.1 y recibes el CFDI timbrado, ultrarrápido y válido ante el SAT, con su XML y su PDF. Antes de timbrar revisamos las reglas del SAT; si algo no cumple, te decimos qué campo corregir con el código CP del error. La API está incluida: cada CFDI timbrado usa 1 folio.
Lo que resuelve la API de Carta Porte
El mismo complemento que timbras en la web, desde tu TMS o tu ERP.
Reglas del SAT antes de timbrar
Revisamos las reglas de la matriz de errores de Carta Porte 3.1 (CP104, CP107, CP109, CP130, CP141 y CP193, entre otras). Si algo no cumple, no se timbra y no se usa folio.
Totales calculados
TotalDistRec, NumTotalMercancias y PesoBrutoTotal se calculan con tus ubicaciones y tus mercancías. No tienes que cuadrarlos a mano.
IdCCP automático
Manda IdCCP con el valor "AUTO" y la API genera el identificador de la Carta Porte con el formato del SAT.
Autotransporte, marítimo y aéreo
Ubicaciones, mercancías, figuras del transporte y documentación aduanera, con los nodos Autotransporte, TransporteMaritimo y TransporteAereo.
Si ya generas tu XML
Envía tu Carta Porte ya sellada a /invoice/stampxmlfile como archivo .xml de hasta 40 MB, o a /invoice/stampxml en Base64.
Un flete de Monterrey a Saltillo, de la petición a la respuesta
Carta Porte 3.1 de ingreso con autotransporte. El JSON va en el campo json de POST /invoice/create, con tu llave en el header X-Api-Key.
Endpoints
- POST /invoice/create
- JSON con el complemento CartaPorte31. Armamos el XML, lo sellamos con tu CSD y lo timbramos.
- POST /invoice/stampxml
- Tu XML ya sellado, codificado en Base64 (campo xmlbase64).
- POST /invoice/stampxmlfile
- Tu XML ya sellado como archivo (campo xml), de hasta 40 MB.
- IdCCP y Folio en "AUTO": la respuesta trae la Serie y el Folio asignados.
- El RFC y el nombre del emisor se toman de tu cuenta.
- Sin TotalDistRec, NumTotalMercancias ni PesoBrutoTotal: la API los calcula.
- Con autotransporte, cada destino lleva su DistanciaRecorrida y el operador (figura 01), su NumLicencia.
- Producción
- https://app.facturadigital.com.mx/api/v5
- Sandbox
- https://sandbox-app.facturadigital.com.mx/api/v5
# FD_API=https://sandbox-app.facturadigital.com.mx/api/v5
curl -X POST "$FD_API/invoice/create" \
-H "X-Api-Key: $FD_API_KEY" \
--data-urlencode "json@carta-porte.json"{
"Version": "4.0",
"Serie": "CP",
"Folio": "AUTO",
"Fecha": "AUTO",
"FormaPago": "03",
"MetodoPago": "PUE",
"Moneda": "MXN",
"TipoDeComprobante": "I",
"Exportacion": "01",
"LugarExpedicion": "64000",
"SubTotal": "5000.00",
"Total": "5800.00",
"Emisor": { "RegimenFiscal": "601" },
"Receptor": {
"Rfc": "XIA190128J61",
"Nombre": "XENON INDUSTRIAL ARTICLES",
"DomicilioFiscalReceptor": "76343",
"RegimenFiscalReceptor": "601",
"UsoCFDI": "G03"
},
"Conceptos": [{
"ClaveProdServ": "78101802",
"Cantidad": "1",
"ClaveUnidad": "E48",
"Descripcion": "Flete Monterrey a Saltillo",
"ValorUnitario": "5000.00",
"Importe": "5000.00",
"ObjetoImp": "02",
"Impuestos": { "Traslados": [{ ... }] }
}],
"Impuestos": { ... },
"Complemento": {
"CartaPorte31": {
"Version": "3.1",
"IdCCP": "AUTO",
"TranspInternac": "No",
"Ubicaciones": [
{
"TipoUbicacion": "Origen",
"RFCRemitenteDestinatario": "XIA190128J61",
"FechaHoraSalidaLlegada": "2026-09-28T08:00:00",
"Domicilio": {
"Estado": "NLE", "Pais": "MEX", "CodigoPostal": "64000"
}
},
{
"TipoUbicacion": "Destino",
"RFCRemitenteDestinatario": "XIA190128J61",
"FechaHoraSalidaLlegada": "2026-09-28T10:30:00",
"DistanciaRecorrida": "85",
"Domicilio": {
"Estado": "COA", "Pais": "MEX", "CodigoPostal": "25000"
}
}
],
"Mercancias": {
"UnidadPeso": "KGM",
"Mercancia": [{
"BienesTransp": "31161500",
"Descripcion": "Tornillería",
"Cantidad": "10",
"ClaveUnidad": "H87",
"PesoEnKg": "1200"
}],
"Autotransporte": {
"PermSCT": "TPAF01",
"NumPermisoSCT": "PERMISO-DE-MUESTRA",
"IdentificacionVehicular": {
"ConfigVehicular": "C2",
"PesoBrutoVehicular": "10.5",
"PlacaVM": "123AB4",
"AnioModeloVM": "2022"
},
"Seguros": {
"AseguraRespCivil": "ASEGURADORA DE MUESTRA",
"PolizaRespCivil": "POL-000123"
}
}
},
"FiguraTransporte": [{
"TipoFigura": "01",
"RFCFigura": "RFC_DEL_OPERADOR",
"NumLicencia": "LIC-000123",
"NombreFigura": "NOMBRE DEL OPERADOR"
}]
}
}
}{
"message": "The document was generated successfully",
"code": 200,
"cfdi": {
"UUID": "6FA90F39-2D7A-4F1C-9B3E-5C1D8A0E7B42",
"FechaTimbrado": "2026-09-28T08:01:12",
"CadenaQR": "https://verificacfdi.facturaelectronica.sat.gob.mx/...",
"XmlBase64": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
"PDF": "https://app.facturadigital.com.mx/docs/pdf/6FA90F39-...",
"XML": "https://app.facturadigital.com.mx/docs/xml/...",
"Serie": "CP",
"Folio": "1042",
...
}
}Intégrala en 4 pasos
Del sandbox a tu primera Carta Porte timbrada en producción.
- 01
Crea tu cuenta de sandbox
Es gratis y timbra con un PAC de pruebas, sin validez fiscal. Sube tu CSD y copia tu llave de Configuración → Datos de facturación.
- 02
Configura tu serie
Si mandas Folio "AUTO", da de alta la serie para el tipo de comprobante (I o T) en Configuración → Series y Folios.
- 03
Mapea tus viajes
Cada viaje de tu sistema es un CartaPorte31: origen y destinos con su distancia, mercancías con su peso, el vehículo y el operador.
- 04
Timbra y pasa a producción
Llama a POST /invoice/create y guarda UUID, Serie y Folio. Para producción cambias la URL base y la llave; tu código no cambia.
Errores frecuentes y cómo resolverlos
Los errores responden con HTTP 400 y un code en el cuerpo. Los de Carta Porte traen además, en errors, el código CP del SAT y la ruta del campo.
CódigoCuándo pasaQué hacer
400 · CP193 / CP194Hay autotransporte, pero no viene la figura del transporte o ninguna es el operador (TipoFigura 01).Agrega al operador en FiguraTransporte: con autotransporte es obligatorio.
400 · CP196El operador no trae NumLicencia.Manda el número de licencia de la figura 01.
400 · CP141Falta la DistanciaRecorrida de un destino, o viene en el origen.Con autotransporte, cada destino lleva su distancia en kilómetros; el origen no lleva distancia.
400 · CP109En una Carta Porte de ingreso, la ClaveProdServ del concepto no es de servicio de transporte.Usa una de las 41 claves de transporte que admite el SAT, como 78101802.
400 · CP107Un traslado (T) con un receptor distinto a tu empresa.En un traslado de tu propia mercancía, el receptor es tu mismo RFC.
702El comprobante no cumple el esquema del SAT.Revisa errors: cada error trae el elemento, el campo y el mensaje en español.
601 · 602Tu cuenta no tiene folios disponibles (601) o no tiene un CSD activo (602).Consulta tu saldo con GET /account/balance y sube tu CSD en Configuración → Certificados.
5037 · 50345037: no se pudo conectar para timbrar. 5034: no hubo respuesta al timbrar.Con 5037 puedes reintentar. Con 5034 el CFDI pudo haberse timbrado: búscalo en el SAT con la Serie y el Folio de la respuesta antes de reintentar.
Así llega un error de Carta Porte
errorType es cartaporte_validation y cada elemento de errors trae el código CP, la ruta del campo y el mensaje en español. La liga de docs lleva a la guía de estos errores.
{
"message": "Invalid 'CartaPorte31' complement: CP193: Falta la figura del transporte. ...",
"code": 400,
"errorType": "cartaporte_validation",
"docs": "https://docs.facturadigital.com.mx/errores/cartaporte",
"errors": [{
"severity": "error",
"code": "CP193",
"field": "Complemento.CartaPorte31.FiguraTransporte",
"message": "Falta la figura del transporte. Con autotransporte tienes que registrar al menos al operador (quien maneja la unidad)."
}]
}Sigue con
Complemento de pago
Timbra el REP de tus facturas PPD con el mismo endpoint y la misma llave.
Cancelación
Cancela un CFDI con motivos 01 a 04 y recibe el acuse del SAT. Cancelar no usa folio.
Carta Porte en la web
Tipos, reglas y llenado del complemento para quien timbra desde la app.
Sandbox
Ambiente de pruebas gratis con la misma API v5 que producción.
SDKs oficiales
Librerías para llamar la API v5 desde tu lenguaje, con los mismos endpoints.
API v5
Autenticación, endpoints y las tres formas de timbrar: JSON, XML en Base64 o archivo XML.
Preguntas sobre la API de Carta Porte
¿Algo que no está aquí? Escríbenos o revisa la referencia completa.
¿Puedo timbrar Carta Porte 3.1 por API?
Sí. Envías el CFDI con Complemento.CartaPorte31 a POST /invoice/create, de ingreso (I) o de traslado (T), y recibes el CFDI timbrado con su XML y su PDF. Si ya generas y sellas tu XML, lo timbras en /invoice/stampxml (Base64) o en /invoice/stampxmlfile (archivo de hasta 40 MB).
¿Qué medios de transporte cubre la API?
Autotransporte, transporte marítimo y transporte aéreo. La API no genera el nodo TransporteFerroviario: si tu operación es por ferrocarril, escríbenos antes de integrarla.
¿Qué pasa si mi sistema todavía manda Carta Porte 3.0?
Un CartaPorte30 se convierte a 3.1 antes de timbrar, incluido el paso de RegimenAduanero a RegimenesAduaneros. Después se valida igual que uno en 3.1.
¿Tengo que calcular TotalDistRec, NumTotalMercancias y PesoBrutoTotal?
No. La API los calcula con las distancias de los destinos, el número de mercancías y sus pesos. Si un peso o una cantidad no es un número válido, recibes CP149 o CP154 para que corrijas ese dato.
¿Cómo timbro un traslado de mi propia mercancía?
Con TipoDeComprobante T y tu propio RFC como receptor (regla CP107). La API deja SubTotal, Total e importes en 0, la moneda en XXX y el uso del CFDI en S01, quita la forma y el método de pago y marca los conceptos como no objeto de impuesto.
¿Qué pasa si la Carta Porte no cumple una regla del SAT?
No se timbra y no se usa folio. Recibes HTTP 400 con errorType cartaporte_validation y la lista errors: el código CP del SAT, la ruta del campo y el mensaje en español.
¿Cuánto cuesta la API de Carta Porte?
La API está incluida: pagas folios, no la API. Cada CFDI timbrado usa 1 folio, igual que en la web, y los folios no caducan. El sandbox es gratis.
Timbra tu primera Carta Porte en el sandbox
Es gratis y usa la misma API v5 que producción. Cuando funcione, cambias la URL base y la llave.