API DE CARTA PORTE 3.1

¿Qué es la Carta Porte?

Es el complemento que ampara el traslado de mercancía por territorio nacional. Detalla qué se mueve, de dónde a dónde, en qué vehículo y con qué operador. Si transportas bienes por carretera, vía férrea, mar o aire, la unidad debe llevarlo — y quien revisa en carretera lo pide.

Aplica tanto si eres transportista (emites un CFDI de traslado o de ingreso por el flete) como si mueves mercancía propia con tus vehículos. Ese segundo caso sorprende a muchos: no hace falta dedicarse al transporte para necesitar Carta Porte.

La estructura: tres secciones obligatorias

La versión vigente es la 3.1. Es el complemento más extenso del catálogo del SAT, y su esqueleto son tres bloques que no puedes omitir:

• Ubicaciones — el origen y el destino. Cada una lleva su TipoUbicacion, el RFCRemitenteDestinatario, la fecha y hora de salida o llegada, y el domicilio completo.
• Mercancias — qué se transporta: peso, unidades, clave de producto, y el bloque del medio de transporte (AutotransporteFederal, TransporteMaritimo o TransporteAereo).
• FiguraTransporte — quién interviene en el traslado. Se declara con TipoFigura y es obligatorio cuando el dueño del medio de transporte no es quien emite el comprobante.

Por qué esto se integra y no se captura

La Carta Porte tiene decenas de campos y muchos salen de catálogos del SAT: claves de unidad, tipos de permiso SCT, configuraciones vehiculares, claves de producto para transporte. Capturar eso a mano por cada embarque no es viable en cuanto pasas de unas pocas salidas al día.

El patrón que funciona es tener los datos que no cambian ya cargados —tus unidades con su placa, configuración y número de permiso; tus operadores con su RFC y licencia— y que la integración solo aporte lo variable: qué se carga, a dónde va y qué unidad lo lleva.

Facturama expone endpoints de catálogos específicos de Carta Porte, así que puedes resolver las claves programáticamente en vez de mantener copias que se desactualizan.

Traslado o ingreso: decide antes de programar

La Carta Porte puede acompañar a dos tipos de comprobante distintos, y la elección no es estética:

• CFDI de traslado — mueves mercancía propia. No hay cobro, el comprobante va en ceros.
• CFDI de ingreso — prestas el servicio de transporte y cobras un flete. El comprobante lleva el importe del servicio.

Si eres transportista, casi siempre es el segundo. Si eres una distribuidora moviendo su propio inventario entre almacenes, el primero. Modelarlo mal significa rehacer el flujo, así que conviene tenerlo claro en la fase de diseño.

Cancelaciones y cambios de última hora

En logística los planes cambian: se poncha una llanta, se reasigna la unidad, el cliente aplaza la entrega. Si el CFDI ya está timbrado con una unidad y sale otra, hay que cancelarlo y volver a emitir con los datos correctos.

Por eso conviene timbrar lo más cerca posible de la salida real, no la noche anterior al planificar. Cada hora de anticipación es una hora en la que algo puede cambiar y obligarte a rehacer el comprobante.

Ciclo de vida y SDKs

Consulta por Id, descarga de XML y PDF —el PDF es el que va impreso en la unidad—, envío por correo y cancelación. Librerías oficiales en PHP, Python, JavaScript, Java, Ruby y .NET (4.5+).

Si además exportas la mercancía, revisa el complemento de comercio exterior: son complementarios, no alternativos.

Preguntas frecuentes

¿Necesito Carta Porte si muevo mercancía propia?

Sí. Aunque no cobres flete, el traslado por territorio nacional debe estar amparado. En ese caso se emite un CFDI de traslado con el complemento.

¿Cuántas ubicaciones debe llevar?

Al menos dos —origen y destino— cuando el traslado es por autotransporte federal, marítimo o aéreo.

¿Qué versión está vigente?

La 3.1. Si tu integración quedó en 3.0 o en 2.0, toca actualizarla: las versiones anteriores dejan de aceptarse.

¿Puedo cancelar una Carta Porte ya timbrada?

Sí, con el Id del comprobante. Es lo que corresponde cuando cambia la unidad o el operador después de timbrar.