Timbrado V4 (CustomID, PDF y Email)

El conjunto de endpoints Timbrado V4 permite emitir o timbrar comprobantes CFDI 4.0 con control de duplicidad por customid, generación automática de representación impresa en PDF y entrega inmediata por correo electrónico a tus clientes.

Auth: Bearer TokenIdempotencia: CustomID (72 hrs TTL)Consumo base: 1 timbreValor agregado (PDF / Email): 2 timbres totales

Modelo de Precios y Consumo

Modalidad	Headers Requeridos	Timbres Consumidos (Live)	Timbres Consumidos (Test)
Timbrado estándar	Ninguno o solo `customid`	1 timbre	0 timbres
Con PDF	`extra: pdf`	2 timbres (1 base + 1 valor agregado)	0 timbres
Con Email	`email: cliente@correo.com`	2 timbres (1 base + 1 valor agregado)	0 timbres
Con PDF + Email	`extra: pdf` y `email: ...`	2 timbres (el recargo cubre ambos servicios)	0 timbres

[!TIP] En entorno de pruebas (Test / Sandbox), no se descuenta ningún timbre independientemente de si solicitas PDF o envío por correo.

Endpoints Disponibles

1. Emisión desde JSON (CFDI 4.0)

Genera el XML, sella con tus certificados CSD y timbra ante el SAT.

POST/api/masivo/v4/cfdi33/issue/json/v4

Emite y timbra un CFDI 4.0 desde un objeto JSON canónico.

Content-Type: application/json
Body: Objeto JSON con la estructura CFDI 4.0 (Emisor, Receptor, Conceptos, etc.).

2. Emisión desde XML sin sellar

Recibe el XML del CFDI 4.0 sin sellar, lo sella con tus certificados en Timbra y lo timbra.

POST/api/masivo/v4/cfdi33/issue/v4

Sella y timbra un comprobante XML sin sellar.

Formatos de envío soportados:

application/json: { "data": "<cfdi:Comprobante ...>" }
multipart/form-data: archivo XML o campo xml
application/xml o text/plain: XML directo en el body

3. Timbrado de XML pre-sellado

Timbra un comprobante que ya fue previamente sellado por tu sistema.

POST/api/masivo/v4/cfdi33/stamp/v4

Timbra un CFDI 4.0 previamente sellado.

Formatos de envío soportados:

application/json: { "data": "<cfdi:Comprobante ...>" }
multipart/form-data: archivo XML o campo xml
application/xml o text/plain: XML directo en el body

Headers Especiales

Header	Tipo	Descripción
`Authorization`	`Bearer <token>`	Obligatorio. Tu API Key generada en el dashboard de Timbra.
`customid`	`string`	Opcional. Identificador único de tu transacción (ej. ID de orden o UUID interno). Tiene una vigencia de 72 horas. Si reenvías la petición con el mismo `customid`, Timbra responderá con error `CFDI3307` y te devolverá el CFDI original sin consumir timbres adicionales.
`extra`	`string`	Opcional. Envía `pdf` para generar automáticamente la representación impresa en PDF.
`email`	`string`	Opcional. Lista de correos separados por comas para enviar al cliente su factura con los archivos XML y PDF adjuntos.

Manejo de Idempotencia (`customid`)

Si una petición falla por intermitencia de red o timeout en tu cliente, puedes reintentarla con seguridad usando el mismo customid.

Si el comprobante ya había sido timbrado dentro de las últimas 72 horas para ese mismo RFC emisor:

No se vuelve a emitir ante el SAT ni el PAC.
No se deduce saldo de timbres.
Se devuelve inmediatamente un código HTTP 400 con la estructura de error estándar:

json

{
  "status": "error",
  "message": "CFDI3307 - Timbre duplicado. El customId proporcionado está duplicado.",
  "messageDetail": null,
  "data": {
    "uuid": "43924765-a844-484b-a91c-148df2df3df7",
    "tfd": "<tfd:TimbreFiscalDigital .../>",
    "cfdi": "<cfdi:Comprobante .../>"
  }
}

Ejemplos de Integración

Ejemplo cURL (JSON con PDF y Email)

bash

curl -X POST https://timbra.com.mx/api/masivo/v4/cfdi33/issue/json/v4 \
  -H "Authorization: Bearer mi_token_secreto_live" \
  -H "Content-Type: application/json" \
  -H "customid: orden-ecommerce-8942" \
  -H "extra: pdf" \
  -H "email: pagos@cliente.com, contabilidad@empresa.com" \
  -d '{
    "Version": "4.0",
    "Serie": "A",
    "Folio": "500",
    "Fecha": "2026-10-22T12:00:00",
    "FormaPago": "01",
    "MetodoPago": "PUE",
    "LugarExpedicion": "26015",
    "Moneda": "MXN",
    "TipoDeComprobante": "I",
    "Exportacion": "01",
    "SubTotal": "1000.00",
    "Total": "1160.00",
    "Emisor": {
      "Rfc": "EKU9003173C9",
      "Nombre": "ESCUELA KEMPER URGATE",
      "RegimenFiscal": "601"
    },
    "Receptor": {
      "Rfc": "URE180429TM6",
      "Nombre": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
      "DomicilioFiscalReceptor": "86991",
      "RegimenFiscalReceptor": "601",
      "UsoCFDI": "G01"
    },
    "Conceptos": [
      {
        "ClaveProdServ": "43231500",
        "NoIdentificacion": "LIC-01",
        "Cantidad": "1",
        "ClaveUnidad": "E48",
        "Unidad": "Servicio",
        "Descripcion": "Suscripción a plataforma SaaS",
        "ValorUnitario": "1000.00",
        "Importe": "1000.00",
        "ObjetoImp": "02",
        "Impuestos": {
          "Traslados": [
            {
              "Base": "1000.00",
              "Impuesto": "002",
              "TipoFactor": "Tasa",
              "TasaOCuota": "0.160000",
              "Importe": "160.00"
            }
          ]
        }
      }
    ],
    "Impuestos": {
      "TotalImpuestosTrasladados": "160.00",
      "Traslados": [
        {
          "Base": "1000.00",
          "Impuesto": "002",
          "TipoFactor": "Tasa",
          "TasaOCuota": "0.160000",
          "Importe": "160.00"
        }
      ]
    }
  }'

Ejemplo Node.js (Fetch)

javascript

const response = await fetch('https://timbra.com.mx/api/masivo/v4/cfdi33/issue/json/v4', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.TIMBRA_API_KEY,
    'Content-Type': 'application/json',
    'customid': 'pedido-' + Date.now(),
    'extra': 'pdf',
    'email': 'cliente@ejemplo.com'
  },
  body: JSON.stringify({
    Version: '4.0',
    Serie: 'F',
    Folio: '1001',
    Fecha: '2026-10-22T10:30:00',
    FormaPago: '03',
    MetodoPago: 'PUE',
    LugarExpedicion: '26015',
    Moneda: 'MXN',
    TipoDeComprobante: 'I',
    Exportacion: '01',
    SubTotal: '500.00',
    Total: '580.00',
    Emisor: {
      Rfc: 'EKU9003173C9',
      Nombre: 'ESCUELA KEMPER URGATE',
      RegimenFiscal: '601'
    },
    Receptor: {
      Rfc: 'URE180429TM6',
      Nombre: 'UNIVERSIDAD ROBOTICA ESPAÑOLA',
      DomicilioFiscalReceptor: '86991',
      RegimenFiscalReceptor: '601',
      UsoCFDI: 'G03'
    },
    Conceptos: [
      {
        ClaveProdServ: '80141600',
        Cantidad: '1',
        ClaveUnidad: 'E48',
        Descripcion: 'Asesoría profesional',
        ValorUnitario: '500.00',
        Importe: '500.00',
        ObjetoImp: '02',
        Impuestos: {
          Traslados: [
            { Base: '500.00', Impuesto: '002', TipoFactor: 'Tasa', TasaOCuota: '0.160000', Importe: '80.00' }
          ]
        }
      }
    ],
    Impuestos: {
      TotalImpuestosTrasladados: '80.00',
      Traslados: [
        { Base: '500.00', Impuesto: '002', TipoFactor: 'Tasa', TasaOCuota: '0.160000', Importe: '80.00' }
      ]
    }
  })
});

const data = await response.json();
console.log(data);

Respuesta Exitosa (200 OK)

json

{
  "status": "success",
  "data": {
    "uuid": "43924765-a844-484b-a91c-148df2df3df7",
    "cfdi": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><cfdi:Comprobante ...",
    "tfd": "<tfd:TimbreFiscalDigital xmlns:tfd=\"http://www.sat.gob.mx/TimbreFiscalDigital\" Version=\"1.1\" UUID=\"43924765-a844-484b-a91c-148df2df3df7\" ... />"
  }
}

Timbrado V4 (CustomID, PDF y Email) ​

Modelo de Precios y Consumo ​

Endpoints Disponibles ​

1. Emisión desde JSON (CFDI 4.0) ​

2. Emisión desde XML sin sellar ​

3. Timbrado de XML pre-sellado ​

Headers Especiales ​

Manejo de Idempotencia (customid) ​

Ejemplos de Integración ​

Ejemplo cURL (JSON con PDF y Email) ​

Ejemplo Node.js (Fetch) ​

Respuesta Exitosa (200 OK) ​