Timbra

Appearance

On this page

Cancelación por CSD ​

Solicita la cancelación de un CFDI firmando la petición con tus Certificados de Sello Digital (CSD).

POST/api/masivo/cfdi33/cancel/csd

Cancela un CFDI con tus Certificados de Sello Digital.

Auth: BearerContent-Type: application/jsonConsume timbre: No

Request ​

CampoTipoObligatorioDescripción
uuidstringSíUUID del CFDI que quieres cancelar.
motivostringNoMotivo de cancelación del SAT. Por defecto 03.
folio_sustitutostringCondicionalUUID del CFDI que sustituye al cancelado. Obligatorio cuando motivo es 01.
b64CerstringNoCertificado del emisor en formato PEM. Si se omite, se usa el CSD configurado en tu cuenta.
b64KeystringNoLlave privada del emisor en formato PEM. Si se omite, se usa el CSD configurado en tu cuenta.
passwordstringCondicionalContraseña de la llave privada. Obligatoria si tu CSD tiene contraseña.

Recomendado: usa el CSD de tu cuenta

Si ya cargaste tus CSD en el panel de Timbra, no envíes b64Cer, b64Key ni password. La API los toma automáticamente de tu cuenta. Es la forma más segura y evita manejar certificados en cada petición.

Motivos de cancelación ​

ClaveMotivo
01Comprobante emitido con errores con relación. Requiere folio_sustituto.
02Comprobante emitido con errores sin relación.
03No se llevó a cabo la operación.
04Operación nominativa relacionada en una factura global.

Ejemplo ​

json
{
  "uuid": "A1B2C3D4-5E6F-7890-ABCD-EF1234567890",
  "motivo": "02",
  "folio_sustituto": ""
}

Para cancelar con motivo 01:

json
{
  "uuid": "A1B2C3D4-5E6F-7890-ABCD-EF1234567890",
  "motivo": "01",
  "folio_sustituto": "B2C3D4E5-6F70-8901-BCDE-F23456789012"
}

Ejemplos ​

bash
curl -X POST "https://dashboard.timbra.com.mx/api/masivo/cfdi33/cancel/csd" \
  -H "Authorization: Bearer tmb_live_tu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "A1B2C3D4-5E6F-7890-ABCD-EF1234567890",
    "motivo": "02",
    "folio_sustituto": ""
  }'
js
const response = await fetch(
  'https://dashboard.timbra.com.mx/api/masivo/cfdi33/cancel/csd',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TIMBRA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      uuid: 'A1B2C3D4-5E6F-7890-ABCD-EF1234567890',
      motivo: '02',
      folio_sustituto: ''
    })
  }
)

const result = await response.json()

if (!response.ok) {
  throw new Error(result.message)
}

console.log('Acuse:', result.data.acuse)
python
import os
import requests

response = requests.post(
    "https://dashboard.timbra.com.mx/api/masivo/cfdi33/cancel/csd",
    headers={
        "Authorization": f"Bearer {os.environ['TIMBRA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "uuid": "A1B2C3D4-5E6F-7890-ABCD-EF1234567890",
        "motivo": "02",
        "folio_sustituto": "",
    },
)

result = response.json()

if response.status_code != 200:
    raise Exception(result["message"])

print("Acuse:", result["data"]["acuse"])

Response ​

json
{
  "status": "success",
  "data": {
    "msg": "Se ha cancelado correctamente",
    "uuid": "A1B2C3D4-5E6F-7890-ABCD-EF1234567890",
    "acuse": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Acuse ...>"
  }
}

data.acuse contiene el acuse de cancelación en XML.

Errores ​

HTTPCausa
400Falta uuid.
400No hay CSD configurados en la cuenta y no se enviaron b64Cer y b64Key.
400El SAT o el PAC rechazaron la cancelación. El detalle viene en message.
401La API Key falta, es inválida o fue revocada.
500Error interno al procesar la cancelación.

Ejemplo cuando faltan los CSD:

json
{
  "status": "error",
  "message": "No se encontraron los Certificados de Sello Digital (CSD) para realizar la cancelación."
}

Notas ​

  • La cancelación no consume timbres.
  • En modo Test, el RFC del emisor debe ser un RFC de prueba del SAT y el CSD debe ser de pruebas. No uses certificados de producción en Sandbox.
  • Si no tienes tus CSD a la mano, usa Cancelación por UUID.
  • Después de cancelar, guarda el acuse. Es el comprobante de que la operación se realizó correctamente.