Timbre · API Docs

Introducción

API REST para emisión, cancelación y consulta de CFDI 4.0 ante el SAT. Multi-RFC: una sola API key puede operar sobre varios RFCs registrados.

Autenticación

Todas las llamadas a /api/v1/* requieren un header Authorization: Bearer ... con una API key generada en el panel admin.

Authorization: Bearer pk_live_abc123XYZ...
Content-Type: application/json

Las keys se crean por cliente desde el panel. Cada key tiene un prefijo que indica su modo:

Ambiente de pruebas (sandbox)

El sandbox se activa automáticamente cuando se cumple cualquiera de:

• Usas una API key pk_test_*
• El issuer (RFC) está marcado como "Es certificado de pruebas"

En modo sandbox, el TFD devuelto tiene NoCertificadoSAT empezando con dígito "2" (ej. 20001000000300022323) — esto es la marca oficial del SAT para timbrados de prueba. Ningún timbre se descuenta del balance en sandbox.

GET /api/v1/health

Endpoint público sin auth — útil para monitoreo y status pages.

curl https://facturacion.fast-fix.com.mx/api/v1/health

{
  "status": "ok",
  "checks": {
    "database": { "ok": true, "ms": 4 },
    "stamping": { "ok": true, "ms": 312 }
  },
  "timestamp": "2026-05-16T..."
}

GET /api/v1/balance

Saldo actual de timbres del cliente al que pertenece la API key.

curl https://facturacion.fast-fix.com.mx/api/v1/balance \
  -H "Authorization: Bearer pk_test_..."

{
  "data": {
    "balance": "100",
    "pricePerTimbreCentavos": 150
  }
}

GET /api/v1/issuers

Lista los RFCs (issuers) configurados para este cliente.

curl https://facturacion.fast-fix.com.mx/api/v1/issuers \
  -H "Authorization: Bearer pk_test_..."

{
  "data": [
    {
      "id": "iss_abc...",
      "rfc": "XAXX010101000",
      "razonSocial": "MI EMPRESA SA DE CV",
      "regimenFiscal": "601",
      "codigoPostal": "78215",
      "isTest": false,
      "csdSerial": "30001000...",
      "csdValidFrom": "2024-01-01T00:00:00.000Z",
      "csdValidTo": "2028-01-01T00:00:00.000Z"
    }
  ]
}

Para registrar un RFC nuevo con su CSD, usa POST /AltaEmpresaWithCertificado.

Códigos de error de timbrado

Cuando el SAT rechaza un CFDI, devolvemos el código de error correspondiente en details.code dentro de la respuesta de stamping_rejected.

Lista basada en los códigos estándar del SAT. Si recibes un código no listado, contacta a soporte.

Catálogos del SAT

Los siguientes campos del CFDI 4.0 sólo aceptan valores de catálogos publicados por el SAT. Si mandas un valor fuera del catálogo, el PAC rechazará el timbrado con error CFDI40113 o similar. Aquí tienes los valores más comunes — para el catálogo oficial completo y actualizado consulta el portal del SAT.

Tipo de comprobante (TipoDeComprobante)

Identifica el tipo de CFDI que se está emitiendo. Es atributo del nodo raíz cfdi:Comprobante.

Exportación

Indica si la operación es de comercio exterior. Atributo de cfdi:Comprobante.

Forma de pago (FormaPago)

Cómo se paga la operación. Atributo de cfdi:Comprobante. Si el método es PPD el SAT obliga a usar 99 (Por definir).

Método de pago (MetodoPago)

Cuándo se paga la operación. Solo dos valores válidos.

Uso de CFDI (UsoCFDI)

Cómo lo va a usar el receptor. Es atributo de cfdi:Receptor. Debe ser coherente con el régimen fiscal del receptor; los regímenes de personas morales y físicas tienen catálogos distintos permitidos por el SAT.

Régimen Fiscal (RegimenFiscal / RegimenFiscalReceptor)

Bajo qué régimen tributa el emisor o receptor. El régimen del emisor debe coincidir con el que tiene registrado ante el SAT en su Constancia de Situación Fiscal.

Estas tablas se actualizan eventualmente. Si el SAT publica nuevos valores y todavía no aparecen aquí, igual los aceptamos al timbrar — el PAC valida directo contra el catálogo oficial.

API de timbrado

Endpoints de bajo nivel para alta de empresa en el servicio de timbrado, emisión, cancelación y consulta. Si tu integración usa los endpoints de alto nivel (sección anterior), puedes ignorar esta parte — esos se construyen sobre estos.

POST /api/v1/AltaEmpresaWithCertificado

Registra un nuevo RFC en el PAC subiendo su Certificado de Sello Digital. Solo se requiere una vez por RFC. Si la empresa ya estaba registrada el PAC responderá con un mensaje indicándolo.

Body (JSON)

{
  "rfc": "ABC123456789",
  "razonSocial": "MI EMPRESA SA DE CV",
  "cer": "MIIF...",            // base64 del archivo .cer
  "key": "MIIE...",            // base64 del archivo .key (no la PEM desencriptada)
  "contrasena": "csd-password",
  "observaciones": ""          // opcional
}

cURL

# Codifica tus archivos primero
CER=$(base64 -w0 < empresa.cer)
KEY=$(base64 -w0 < empresa.key)

curl -X POST https://facturacion.fast-fix.com.mx/api/v1/AltaEmpresaWithCertificado \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d "{
    \"rfc\": \"ABC123456789\",
    \"razonSocial\": \"MI EMPRESA SA DE CV\",
    \"cer\": \"$CER\",
    \"key\": \"$KEY\",
    \"contrasena\": \"csd-password\"
  }"

Respuesta (200 OK)

{
  "ok": true,
  "message": "Empresa registrada correctamente",
  "rawResponse": "<s:Envelope>...</s:Envelope>",
  "durationMs": 487
}

Respuesta (422 — el PAC rechazó)

{
  "ok": false,
  "message": "RFC ya registrado previamente",
  "rawResponse": "...",
  "durationMs": 312
}

POST /api/v1/AltaCertificado

Renueva el CSD de una empresa que ya pasó por AltaEmpresaWithCertificado. Útil cuando el CSD actual vence o se reemplaza por uno nuevo del SAT.

Body (JSON)

{
  "rfc": "ABC123456789",
  "cer": "MIIF...",            // base64 del nuevo .cer
  "key": "MIIE...",            // base64 del nuevo .key
  "contrasena": "csd-password"
}

cURL

curl -X POST https://facturacion.fast-fix.com.mx/api/v1/AltaCertificado \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rfc": "ABC123456789",
    "cer": "MIIF...",
    "key": "MIIE...",
    "contrasena": "csd-password"
  }'

Respuesta (200 OK)

{
  "ok": true,
  "message": "Certificado actualizado correctamente",
  "rawResponse": "...",
  "durationMs": 412
}

POST /api/v1/TimbrarSellarBase64

Timbra un CFDI 4.0 que ya construiste tú. El XML viaja en base64 — el servicio lo sella con el CSD que registraste con AltaEmpresaWithCertificado. Devolvemos el XML timbrado (con el nodo TFD) y, si el sistema lo generó, un PDF en base64.

Estructura del XML que debes enviar

Construye un CFDI 4.0 completo pero sin sellar: deja vacíos los atributos Sello, NoCertificado y Certificado — el servicio los llena usando el CSD que registraste previamente. No incluyas el nodo TimbreFiscalDigital; el servicio lo agrega. Todos los importes deben cuadrar y los catálogos del SAT (ClaveProdServ, ClaveUnidad, RegimenFiscal, UsoCFDI, etc.) deben ser válidos.

<?xml version="1.0" encoding="UTF-8"?>
<cfdi:Comprobante
    xmlns:cfdi="http://www.sat.gob.mx/cfd/4"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.sat.gob.mx/cfd/4 http://www.sat.gob.mx/sitio_internet/cfd/4/cfdv40.xsd"
    Version="4.0"
    Serie="A"
    Folio="1001"
    Fecha="2026-05-20T10:00:00"
    Sello=""
    FormaPago="03"
    NoCertificado=""
    Certificado=""
    SubTotal="100.00"
    Moneda="MXN"
    Total="116.00"
    TipoDeComprobante="I"
    Exportacion="01"
    MetodoPago="PUE"
    LugarExpedicion="78215">

  <cfdi:Emisor
    Rfc="ABC123456789"
    Nombre="MI EMPRESA SA DE CV"
    RegimenFiscal="601" />

  <cfdi:Receptor
    Rfc="XAXX010101000"
    Nombre="PUBLICO EN GENERAL"
    DomicilioFiscalReceptor="78215"
    RegimenFiscalReceptor="616"
    UsoCFDI="S01" />

  <cfdi:Conceptos>
    <cfdi:Concepto
      ClaveProdServ="84111506"
      Cantidad="1"
      ClaveUnidad="E48"
      Descripcion="Servicio profesional"
      ValorUnitario="100.00"
      Importe="100.00"
      ObjetoImp="02">
      <cfdi:Impuestos>
        <cfdi:Traslados>
          <cfdi:Traslado
            Base="100.00"
            Impuesto="002"
            TipoFactor="Tasa"
            TasaOCuota="0.160000"
            Importe="16.00" />
        </cfdi:Traslados>
      </cfdi:Impuestos>
    </cfdi:Concepto>
  </cfdi:Conceptos>

  <cfdi:Impuestos TotalImpuestosTrasladados="16.00">
    <cfdi:Traslados>
      <cfdi:Traslado
        Base="100.00"
        Impuesto="002"
        TipoFactor="Tasa"
        TasaOCuota="0.160000"
        Importe="16.00" />
    </cfdi:Traslados>
  </cfdi:Impuestos>

</cfdi:Comprobante>

Reglas críticas del CFDI 4.0

Body (JSON)

{
  "xml": "PD94bWwgdmVy..."   // base64 del XML de arriba
}

cURL

XML=$(base64 -w0 < cfdi-sin-sellar.xml)

curl -X POST https://facturacion.fast-fix.com.mx/api/v1/TimbrarSellarBase64 \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d "{ \"xml\": \"$XML\" }"

Respuesta (200 OK — éxito)

{
  "code": "100",
  "message": "Comprobante timbrado satisfactoriamente",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "xml": "<?xml version=\"1.0\"...>",        // CFDI 4.0 timbrado con TFD
  "pdf": "JVBERi0xLjQK...",                   // base64 del PDF (puede ser null)
  "durationMs": 1247
}

Respuesta (422 — el SAT rechazó)

{
  "code": "301",
  "message": "XML mal formado",
  "uuid": null,
  "xml": null,
  "pdf": null,
  "durationMs": 312
}

Respuesta (402 — sin saldo)

{
  "code": "insufficient_balance",
  "message": "Sin saldo de timbres...",
  "uuid": null, "xml": null, "pdf": null
}

POST /api/v1/TimbrarSellarBase64Test

Variante sandbox de TimbrarSellarBase64. Manda el CFDI al ambiente de pruebas del SAT — el TFD que regresa tiene un NoCertificadoSATque empieza con "2" (ej. 20001000000300022323), marca oficial de prueba. Nunca descuenta del balance, sin importar si tu API key es pk_live_* o pk_test_*.

Body (JSON)

{ "xml": "PD94bWwgdmVy..." }   // base64 del CFDI 4.0 sin sellar

cURL

XML=$(base64 -w0 < cfdi-sin-sellar.xml)

curl -X POST https://facturacion.fast-fix.com.mx/api/v1/TimbrarSellarBase64Test \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d "{ \"xml\": \"$XML\" }"

Respuesta

Mismo shape que /TimbrarSellarBase64: { code, message, uuid, xml, pdf, durationMs }.

POST /api/v1/Cancelar

Solicita cancelación de un CFDI ante el SAT. Si el comprobante tiene relación de pago o pasaron más de 72 horas desde la emisión, el SAT puede requerir aceptación del receptor — en ese caso estatus será false y la cancelación queda en en_proceso_cancelacion.

Body (JSON)

{
  "rfcEmisor": "ABC123456789",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "motivo": "02",                  // 01 | 02 | 03 | 04
  "folioSustitucion": ""           // requerido solo si motivo=01
}

Motivos SAT

cURL

curl -X POST https://facturacion.fast-fix.com.mx/api/v1/Cancelar \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rfcEmisor": "ABC123456789",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "motivo": "02"
  }'

Respuesta (200 OK — cancelado)

{
  "estatus": true,
  "code": "201",
  "message": "Solicitud de cancelación aceptada",
  "acuse": "<Acuse>...</Acuse>",
  "durationMs": 1832
}

Respuesta (422 — rechazo / requiere aceptación)

{
  "estatus": false,
  "code": "707",
  "message": "El UUID no existe o ya fue cancelado",
  "acuse": null,
  "durationMs": 412
}

POST /api/v1/CancelarTest

Sandbox de Cancelar. Misma firma; va al ambiente de pruebas del SAT. Útil para validar tu integración antes de mover a producción.

curl -X POST https://facturacion.fast-fix.com.mx/api/v1/CancelarTest \
  -H "Authorization: Bearer pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "rfcEmisor": "...", "uuid": "...", "motivo": "02" }'

POST /api/v1/ConsultaCertificado

Consulta los datos del CSD registrado para un RFC: número de certificado, fecha de inicio y de expiración. Útil para validar antes de timbrar que el CSD sigue vigente.

Body (JSON)

{ "rfc": "ABC123456789" }

cURL

curl -X POST https://facturacion.fast-fix.com.mx/api/v1/ConsultaCertificado \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "rfc": "ABC123456789" }'

Respuesta (200 OK — encontrado)

{
  "found": true,
  "rfc": "ABC123456789",
  "noCertificado": "30001000000500003456",
  "vigencia": "2024-01-15T12:00:00",
  "expira": "2028-01-15T12:00:00",
  "mensaje": null,
  "durationMs": 312
}

Respuesta (404 — sin CSD registrado)

{
  "found": false,
  "rfc": null,
  "noCertificado": null,
  "vigencia": null,
  "expira": null,
  "mensaje": "RFC sin certificado registrado"
}

POST /api/v1/ConsultaEstatusSAT

Consulta el estatus actual de un CFDI directamente con el SAT. Sirve para saber si está Vigente, Cancelado o En proceso, y para obtener el acuse oficial.

Body (JSON)

{
  "rfcEmisor": "ABC123456789",
  "rfcReceptor": "XAXX010101000",
  "total": "116.00",
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

cURL

curl -X POST https://facturacion.fast-fix.com.mx/api/v1/ConsultaEstatusSAT \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rfcEmisor": "ABC123456789",
    "rfcReceptor": "XAXX010101000",
    "total": "116.00",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

Respuesta (200 OK)

{
  "code": "S - Comprobante obtenido satisfactoriamente.",
  "message": "Vigente",
  "acuse": "<Acuse Estado=\"Vigente\" CodigoEstatus=\"S\" ... />",
  "durationMs": 482
}

Postman Collection

Para acelerar la integración, expusimos toda la API como una colección de Postman v2.1.0 con las 11 peticiones organizadas en 3 carpetas (Status, Issuers, API de timbrado). Cada petición trae un body de ejemplo con datos válidos del SAT.

Cómo importar

1. En Postman: File → Import (o botón "Import" en la barra superior).
2. Arrastra el archivo timbre-api.postman_collection.json o pega su contenido.
3. Confirma "Import as Postman Collection v2.1".

Configurar variables de la colección

En Postman, clic derecho sobre la colección Timbre API → Edit → Variables. Ajusta:

La auth Bearer está configurada a nivel colección — todas las peticiones heredan {{apiKey}} automáticamente excepto GET /health que es pública.

Probar rápido

Si quieres probar desde Postman o tu cliente HTTP favorito, los pasos mínimos son:

1. Solicita una API key pk_test_* al admin
2. GET /api/v1/health — verifica que el sistema responde
3. GET /api/v1/balance — confirma que tu key tiene acceso
4. POST /api/v1/AltaEmpresaWithCertificado — registra el RFC subiendo su CSD
5. POST /api/v1/TimbrarSellarBase64Test — timbra un CFDI 4.0 en sandbox para validar
6. POST /api/v1/TimbrarSellarBase64 — timbra en producción (descuenta 1 timbre del saldo)