Saltar al contenido principal

Crear Carta Porte

Este endpoint permite crear y sellar un CFDI de Traslado con el complemento Carta Porte v3.1.

  • Método HTTP: POST
  • URL: /invoices

Cabeceras​

{
"Content-Type": string,requerido
↳Formato del cuerpo de la petición.
↳Valores permitidos: "application/json"
"Authorization": string,opcional
↳Token de autenticación Bearer JWT en formato: Bearer <token>
"x-organization-id": string,requerido
↳Identificador único de la organización emisora del CFDI.
↳Formato: uuid
"x-api-key": string,opcional
↳API Key como método alternativo de autenticación en lugar del token Bearer.
"x-idempotency": stringrequerido
↳UUID único para prevenir la creación de comprobantes duplicados. Si se envía el mismo UUID en solicitudes posteriores, se devolverá el comprobante original.
↳Formato: uuid
}

*Debes usar uno de los dos métodos de autenticación: Authorization (Bearer JWT) o x-api-key.

Rate Limiting

Este endpoint tiene un límite de 30 solicitudes por minuto por organización.

Estructura del Request​

El cuerpo de la petición es un objeto JSON que representa el CrearComprobanteDto.

Objeto Principal: CrearComprobanteDto​

{
"tipoDeComprobante": string,requerido
↳Tipo de comprobante. Debe ser T para CFDI de Traslado (transporte de mercancías sin contraprestación).
↳Valores permitidos: "T"
"receptor": object,requerido
↳Objeto que contiene los datos fiscales del receptor del CFDI (destinatario de la mercancía o propietario del transporte).
"conceptos": array,requerido
↳Arreglo de conceptos del CFDI. Para traslados con Carta Porte debe incluir la descripción del servicio de transporte.
"moneda": string,requerido
↳Clave de la moneda del comprobante según el catálogo c_Moneda del SAT. Para traslados generalmente es MXN.
"exportacion": string,requerido
↳Clave que indica si el comprobante ampara una operación de exportación definitiva, temporal o no aplica según el catálogo c_Exportacion.
"lugarExpedicion": string,requerido
↳Código postal del domicilio fiscal del emisor del comprobante (donde inicia el traslado).
↳Patrón: ^[0-9]{5}$
"fecha": string,requerido
↳Fecha y hora de expedición del comprobante en formato ISO 8601 (YYYY-MM-DDTHH:mm:ss). Debe coincidir con la fecha de inicio del traslado.
↳Formato: date-time
"complementoCartaPorte": objectrequerido
↳Nodo que contiene la información del Complemento Carta Porte versión 3.1. Este nodo es obligatorio para comprobantes tipo T que amparen el transporte de bienes y mercancías.
}

Objeto: ReceptorDto​

{
"rfc": string,requerido
↳RFC del receptor del CFDI (destinatario de las mercancías). Debe tener 12 caracteres para personas morales o 13 para personas físicas.
↳Longitud: 12-13 caracteres · Patrón: ^[A-ZÑ&]{3,4}[0-9]{6}[A-Z0-9]{3}$
"nombre": string,requerido
↳Nombre o Razón Social del receptor. Debe coincidir con el nombre registrado en el SAT para el RFC proporcionado.
↳Longitud máxima: 254 caracteres
"regimenFiscal": string,requerido
↳Clave del régimen fiscal del receptor según el catálogo c_RegimenFiscal del SAT (ejemplo: 601 - General de Ley Personas Morales, 612 - Personas Físicas con Actividades Empresariales).
"domicilioFiscal": string,requerido
↳Código postal del domicilio fiscal del receptor registrado ante el SAT.
↳Patrón: ^[0-9]{5}$
"email": string,requerido
↳Correo electrónico del receptor para el envío automático del CFDI timbrado en formato XML y PDF.
↳Formato: email
"telefono": stringopcional
↳Número telefónico de contacto del receptor (opcional).
}

Objeto: ConceptoDto​

{
"descripcion": string,requerido
↳Descripción del servicio de transporte o traslado de mercancías.
"valorUnitario": number,requerido
↳Precio unitario del concepto. Para traslados sin contraprestación debe ser 0.
"cantidad": number,requerido
↳Cantidad de unidades del concepto. Generalmente 1 para servicios de transporte.
"claveProdServ": string,requerido
↳Clave del producto o servicio según el catálogo c_ClaveProdServ del SAT. Para servicios de transporte se recomienda usar claves del grupo 78 (Transporte, correo y almacenamiento).
"claveUnidad": string,requerido
↳Clave de la unidad de medida según el catálogo c_ClaveUnidad del SAT. Para servicios se recomienda E48 (Unidad de servicio).
"objetoImp": stringrequerido
↳Clave que indica si el concepto es objeto de impuesto según el catálogo c_ObjetoImp. Para traslados sin contraprestación usar 01 (No objeto de impuesto).
}

Objeto Principal: ComplementoCartaPorteDto​

{
"transpInternac": string,requerido
↳Indicador de si el transporte es internacional. Valores permitidos: Sí (cuando cruza fronteras internacionales) o No (transporte nacional).
↳Valores permitidos: "Sí""No"
"entradaSalidaMerc": string,opcional
↳Indica si las mercancías entran o salen del territorio nacional. Este campo es obligatorio cuando transpInternac es Sí. Valores: Entrada o Salida.
"paisOrigenDestino": string,opcional
↳Clave del país de origen (si es entrada) o destino (si es salida) de las mercancías según el catálogo c_Pais. Obligatorio cuando transpInternac es Sí.
"viaEntradaSalida": string,opcional
↳Clave de la vía de entrada o salida de las mercancías según el catálogo c_CveTransporte (01-Autotransporte, 02-Marítimo, 03-Aéreo, 04-Ferroviario, 05-Ducto). Obligatorio cuando transpInternac es Sí.
"totalDistRec": number,opcional
↳Distancia total recorrida en kilómetros desde el origen hasta el destino final del traslado (opcional pero recomendado).
"ubicaciones": array,requerido
↳Arreglo que contiene las ubicaciones de origen, destino y puntos intermedios del traslado. Debe incluir al menos una ubicación de origen y una de destino.
"mercancias": array,requerido
↳Arreglo que describe las mercancías o bienes que se están transportando. Debe incluir al menos una mercancía.
"permSCT": string,requerido
↳Clave del tipo de permiso proporcionado por la SCT (Secretaría de Comunicaciones y Transportes) según el catálogo c_TipPermiso. Ejemplo: TPAF01 (Autotransporte Federal de Carga General).
"numPermisoSCT": string,requerido
↳Número del permiso otorgado por la SCT al transportista. Debe coincidir con el permiso vigente.
"identificacionVehicular": object,requerido
↳Objeto que contiene la información de identificación del vehículo automotor utilizado para el traslado.
"seguros": object,requerido
↳Objeto que contiene la información de las pólizas de seguro que amparan las mercancías y el vehículo durante el traslado.
"remolques": array,opcional
↳Arreglo que contiene la información de los remolques utilizados en el transporte (opcional, solo si aplica).
"figuraTransporte": arrayrequerido
↳Arreglo que contiene información de las figuras de transporte que intervienen en el traslado (operadores, propietarios, arrendadores). Debe incluir al menos el operador del vehículo.
}

Objeto: UbicacionDto​

{
"tipoUbicacion": string,requerido
↳Tipo de ubicación según el catálogo c_TipoUbicacion. Valores: Origen (punto de partida), Destino (punto final) o Intermedio (punto de paso).
↳Valores permitidos: "Origen""Destino""Intermedio"
"idUbicacion": string,opcional
↳Identificador único de la ubicación para referencia interna (opcional).
"rfcRemitenteDestinatario": string,requerido
↳RFC del remitente (si es origen) o destinatario (si es destino) de las mercancías en esta ubicación.
↳Patrón: ^[A-ZÑ&]{3,4}[0-9]{6}[A-Z0-9]{3}$
"nombreRemitenteDestinatario": string,opcional
↳Nombre o razón social del remitente o destinatario (opcional pero recomendado).
"fechaHoraSalidaLlegada": string,requerido
↳Fecha y hora programada de salida (si es origen) o llegada (si es destino) en formato ISO 8601.
↳Formato: date-time
"distanciaRecorrida": number,opcional
↳Distancia recorrida en kilómetros desde la ubicación anterior hasta esta ubicación (obligatorio para destino e intermedios).
"domicilio": object,requerido
↳Objeto que contiene la información del domicilio físico de la ubicación.
"tipoEstacion": string,opcional
↳Tipo de estación según el catálogo c_TipoEstacion. Solo aplica para transporte ferroviario o marítimo.
"navegacionDeTrafico": stringopcional
↳Clave de navegación de tráfico marítimo según el catálogo c_NavegacionTrafico. Solo aplica para transporte marítimo.
}

Objeto: DomicilioDto​

{
"calle": string,opcional
↳Nombre de la calle del domicilio (opcional).
"numeroExterior": string,opcional
↳Número exterior del domicilio (opcional).
"numeroInterior": string,opcional
↳Número interior del domicilio (opcional).
"colonia": string,opcional
↳Nombre de la colonia o urbanización (opcional).
"localidad": string,opcional
↳Clave de la localidad según el catálogo c_Localidad del SAT (opcional).
"referencia": string,opcional
↳Referencia adicional para facilitar la ubicación del domicilio (opcional).
"municipio": string,requerido
↳Clave del municipio o alcaldía según el catálogo c_Municipio del SAT. Este campo es obligatorio para ubicaciones en México.
"estado": string,requerido
↳Clave del estado según el catálogo c_Estado del SAT. Este campo es obligatorio para ubicaciones en México.
"pais": string,requerido
↳Clave del país según el catálogo c_Pais del SAT. Para ubicaciones en México debe ser MEX.
"codigoPostal": stringrequerido
↳Código postal del domicilio. Debe corresponder a un código postal válido según el catálogo c_CodigoPostal.
↳Patrón: ^[0-9]{5}$
}

Objeto: MercanciaDto​

{
"bienesTransp": string,requerido
↳Clave del tipo de bien o mercancía transportada según el catálogo c_ClaveProdServCP del SAT. Este catálogo es específico para Carta Porte.
"descripcion": string,opcional
↳Descripción detallada de la mercancía o bien transportado (opcional pero recomendado para claridad).
"cantidad": number,requerido
↳Cantidad de bienes transportados expresada en la unidad de medida especificada.
"claveUnidad": string,requerido
↳Clave de la unidad de medida según el catálogo c_ClaveUnidad del SAT (ejemplo: KGM para kilogramos, XBX para cajas).
"pesoEnKg": number,requerido
↳Peso bruto total de la mercancía expresado en kilogramos. Este valor es obligatorio y se utiliza para verificar la capacidad del vehículo.
"materialPeligroso": string,opcional
↳Indicador de si la mercancía es considerada material peligroso. Valores: Sí o No.
↳Valores permitidos: "Sí""No"
"cveMaterialPeligroso": string,opcional
↳Clave del material peligroso según el catálogo c_MaterialPeligroso. Este campo es obligatorio cuando materialPeligroso es Sí.
"embalaje": string,opcional
↳Clave del tipo de embalaje utilizado según el catálogo c_TipoEmbalaje (opcional).
"valorMercancia": number,opcional
↳Valor comercial declarado de la mercancía en la moneda especificada (opcional pero recomendado para efectos de seguro).
"moneda": string,opcional
↳Clave de la moneda del valor de la mercancía según el catálogo c_Moneda. Este campo es obligatorio cuando se especifica valorMercancia.
"fraccionArancelaria": string,opcional
↳Fracción arancelaria de la mercancía según la Tarifa de la Ley de los Impuestos Generales de Importación y Exportación (opcional, obligatorio para operaciones de comercio exterior).
"uuidComercioExt": string,opcional
↳Folio fiscal (UUID) del CFDI con complemento de comercio exterior relacionado (opcional, solo si la mercancía proviene de una operación de importación/exportación).
↳Formato: uuid
"documentacionAduanera": arrayopcional
↳Arreglo que contiene la información de los documentos aduaneros que amparan la importación o exportación de la mercancía (opcional).
}

Objeto: IdentificacionVehicularDto​

{
"configVehicular": string,requerido
↳Clave de la configuración vehicular del autotransporte según el catálogo c_ConfigAutotransporte (ejemplo: T3S1 para tractocamión con semirremolque). Esta clave determina la capacidad de carga permitida.
"placaVM": string,requerido
↳Número de placa del vehículo motor registrado ante la autoridad correspondiente.
"anioModeloVM": numberrequerido
↳Año del modelo del vehículo motor. Debe ser un año válido de fabricación.
↳Valor mínimo: 1900
}

Objeto: SegurosDto​

{
"aseguraRespCivil": string,requerido
↳Nombre de la aseguradora que cubre la responsabilidad civil del transportista. Este seguro es obligatorio según la ley.
"polizaRespCivil": string,requerido
↳Número de póliza del seguro de responsabilidad civil. Debe estar vigente durante el traslado.
"aseguraCarga": string,opcional
↳Nombre de la aseguradora que cubre la carga transportada (opcional pero recomendado para mercancías de valor).
"polizaCarga": string,opcional
↳Número de póliza del seguro de carga (opcional).
"aseguraMedAmbiente": string,opcional
↳Nombre de la aseguradora que cubre daños al medio ambiente (obligatorio para materiales peligrosos).
"polizaMedAmbiente": stringopcional
↳Número de póliza del seguro de medio ambiente (obligatorio para materiales peligrosos).
}

Objeto: TiposFiguraDto​

{
"tipoFigura": string,requerido
↳Clave del tipo de figura de transporte según el catálogo c_FiguraTransporte (ejemplo: 01-Operador, 02-Propietario, 03-Arrendador, 04-Notificado).
"rfcFigura": string,requerido
↳RFC de la persona o empresa que desempeña el rol especificado en tipoFigura.
↳Patrón: ^[A-ZÑ&]{3,4}[0-9]{6}[A-Z0-9]{3}$
"numLicencia": string,opcional
↳Número de licencia federal del operador. Este campo es obligatorio cuando tipoFigura es 01 (Operador).
"nombreFigura": string,opcional
↳Nombre completo de la persona o razón social de la empresa que desempeña el rol (opcional pero recomendado).
"numRegIdTribFigura": string,opcional
↳Número de registro de identificación tributaria para figuras extranjeras (opcional, solo para operadores o propietarios extranjeros).
"residenciaFiscalFigura": string,opcional
↳Clave del país de residencia fiscal según el catálogo c_Pais. Este campo es obligatorio cuando se especifica numRegIdTribFigura.
"partesTransporte": arrayopcional
↳Arreglo que especifica las partes del transporte en las que participa la figura (opcional, para casos especiales de operadores que manejan solo ciertas partes del trayecto).
}

Ejemplos de Código​

curl -X POST https://sandbox.lummy.io/invoices \
  -H "Content-Type: application/json" \
  -H "x-organization-id: ${LUMMY_ORG_ID}" \
  -H "x-api-key: ${LUMMY_API_KEY}" \
  -H "x-idempotency: $(uuidgen)" \
  -d '{
    "tipoDeComprobante": "T",
    "receptor": {
      "rfc": "XAXX010101000",
      "nombre": "Receptor de Prueba",
      "regimenFiscal": "601",
      "domicilioFiscal": "12345",
      "email": "receptor@ejemplo.com"
    },
    "conceptos": [
      {
        "claveProdServ": "84111506",
        "cantidad": 1,
        "claveUnidad": "E48",
        "descripcion": "Servicio de transporte de mercancías",
        "valorUnitario": 0,
        "objetoImp": "01"
      }
    ],
    "moneda": "MXN",
    "exportacion": "01",
    "lugarExpedicion": "06500",
    "fecha": "2025-01-15T12:00:00",
    "complementoCartaPorte": {
      "transpInternac": "No",
      "totalDistRec": 150.5,
      "ubicaciones": [
        {
          "tipoUbicacion": "Origen",
          "rfcRemitenteDestinatario": "AAA010101AAA",
          "fechaHoraSalidaLlegada": "2025-01-15T08:00:00",
          "domicilio": {
            "municipio": "015",
            "estado": "CMX",
            "pais": "MEX",
            "codigoPostal": "03900"
          }
        },
        {
          "tipoUbicacion": "Destino",
          "rfcRemitenteDestinatario": "BBB020202BBB",
          "fechaHoraSalidaLlegada": "2025-01-15T12:00:00",
          "distanciaRecorrida": 150.5,
          "domicilio": {
            "municipio": "002",
            "estado": "JAL",
            "pais": "MEX",
            "codigoPostal": "44100"
          }
        }
      ],
      "mercancias": [
        {
          "bienesTransp": "10101504",
          "cantidad": 1000,
          "claveUnidad": "KGM",
          "pesoEnKg": 1500
        }
      ],
      "permSCT": "TPAF01",
      "numPermisoSCT": "ABC123456",
      "identificacionVehicular": {
        "configVehicular": "T3S1",
        "placaVM": "XYZ-789",
        "anioModeloVM": 2020
      },
      "seguros": {
        "aseguraRespCivil": "Seguros Atlas S.A.",
        "polizaRespCivil": "POL-123456"
      },
      "figuraTransporte": [
        {
          "tipoFigura": "01",
          "rfcFigura": "AAAA010101AAA",
          "numLicencia": "A1234567"
        }
      ]
    }
  }'

Respuesta Exitosa (HTTP 201 Created)​

Todas las respuestas siguen el formato estándar StandardResponse:

{
  "requestId": "abc123-def456",
  "data": {
    "invoiceId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "cfdiUuid": "cfa52b8b-93f2-4e6b-8c73-64ad88deb17c",
    "verificationUrl": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=cfa52b8b-93f2-4e6b-8c73-64ad88deb17c",
    "xmlUrl": "https://lummy-invoices.s3.amazonaws.com/cfdi/cfa52b8b-93f2-4e6b-8c73-64ad88deb17c.xml",
    "status": "stamped"
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}
CampoTipoDescripción
requestIdstringID único de la solicitud para trazabilidad
data.invoiceIdstring (UUID)ID interno de la factura en Lummy
data.cfdiUuidstring (UUID)UUID fiscal del SAT - Folio fiscal del CFDI timbrado
data.verificationUrlstring (URL)URL para verificar el CFDI en el portal del SAT
data.xmlUrlstring (URL)URL pública para descargar el XML timbrado
data.statusstringEstado del timbrado: stamped o pending_stamping
timestampstring (ISO)Fecha y hora de la respuesta
pathstringRuta del endpoint
methodstringMétodo HTTP de la solicitud
Generación de PDF

El archivo PDF se genera de forma asíncrona después del timbrado y se envía automáticamente por correo electrónico al receptor.

Respuesta Pendiente de Timbrado (HTTP 201 Created)​

Si el PAC no responde o hay un error temporal, la factura se guarda y se reintenta automáticamente:

{
  "requestId": "abc123-def456",
  "data": {
    "invoiceId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "cfdiUuid": "",
    "verificationUrl": "",
    "xmlUrl": "",
    "status": "pending_stamping",
    "retryInfo": {
      "nextRetryAt": "2025-01-20T10:05:00.000Z",
      "attempt": 1,
      "maxAttempts": 5
    }
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}
CampoTipoDescripción
data.statusstringpending_stamping indica que el timbrado está en cola
data.retryInfo.nextRetryAtstring (ISO)Fecha y hora del próximo reintento automático
data.retryInfo.attemptnumberNúmero de intento actual
data.retryInfo.maxAttemptsnumberNúmero máximo de reintentos (5)
Reintentos Automáticos

El sistema reintenta automáticamente el timbrado con backoff exponencial. Puedes consultar el estado con GET /invoices/{invoiceId}.

Respuestas de Error​

Todas las respuestas de error siguen el formato estándar StandardResponse:

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Descripción del error",
    "code": "ERROR_CODE",
    "status": 400
  },
  "timestamp": "2025-01-20T10:00:00.000Z",
  "path": "/invoices",
  "method": "POST"
}
CódigoDescripción
400Datos de entrada inválidos (ubicaciones, mercancías, vehículo, etc.)
401Token de autenticación inválido o expirado
403Sin permisos (suscripción inactiva, scope insuficiente)
404Sucursal o CSD no encontrado
409Clave de idempotencia ya usada
422Rechazo del PAC/SAT (datos de carta porte inválidos)
429Rate limit excedido (máximo 30 solicitudes por minuto)
500Error interno del servidor

Errores Comunes de Carta Porte​

Error SATDescripción
CCP30101Falta nodo de ubicación origen o destino
CCP30102Distancia recorrida no válida
CCP30103RFC del remitente/destinatario inválido
CCP30104Permiso SCT no válido para el tipo de transporte
CCP30105Configuración vehicular incompatible con el peso
CCP30106Falta número de licencia para el operador
CCP30107Material peligroso requiere clave de embalaje