ContaDB.mx
Iniciar sesiónCrear cuenta

API CFDI para developers. REST + SDK Python.

Timbra CFDI 4.0, complementos de Pagos y Nómina desde tu propio sistema. Bolsa prepagada, idempotency keys y auto-recarga vía Stripe.

EmpezarVer bolsasSDK en PyPI
contadb_sdk · quickstart
# pip install contadb-sdk
from contadb_sdk import ContaDBClient
 
with ContaDBClient(api_token="cdb_test_TU_TOKEN_AQUI") as client:
    resultado = client.timbrar(
        cfdi_xml=cfdi_firmado_xml,
        idempotency_key="factura-001",
    )
 
print(f"UUID:           {resultado.uuid}")
print(f"Saldo restante: {resultado.saldo_restante} timbres")

Quickstart

Tu primer timbrado en 3 líneas

Cuenta → token TEST → emisor sandbox → descargar Certificado Sandbox → firmar con el SDK → POST /timbrar (con Idempotency-Key) → cancelar. Al cambiar a cdb_ + CSD SAT pasas a live.

  1. 01Crea tu cuenta y verifica el correo
  2. 02Entra al panel y genera un token Test (cdb_test_)
  3. 03Crea un emisor sandbox (RFC ficticio, sin SAT)
  4. 04Descarga el Certificado Sandbox (.cer, .key, password)
  5. 05pip install contadb-sdk y carga el certificado
  6. 06Arma un CFDI I PUE (o global / egreso)
  7. 07POST /api/v1/timbrar con Idempotency-Key
  8. 08Guarda el UUID y el XML sintético
  9. 09POST /api/v1/cancelar con el mismo certificado
  10. 10Prueba errores con RFC receptor reservados
  11. 11Renueva la bolsa sandbox o cambia a token live + CSD SAT
POST /api/v1/timbrar
# pip install contadb-sdk
from contadb_sdk import ContaDBClient
 
with ContaDBClient(api_token="cdb_test_TU_TOKEN_AQUI") as client:
    resultado = client.timbrar(
        cfdi_xml=cfdi_firmado_xml,
        idempotency_key="factura-001",
    )
 
print(f"UUID:           {resultado.uuid}")
print(f"Saldo restante: {resultado.saldo_restante} timbres")
TESTLIVE
Tokencdb_test_cdb_
PACSandbox ContaDB (in-process)PAC de producción
RedNinguna llamada externaPAC / SAT
CertificadoCertificado Sandbox (CSD simulado)CSD SAT del emisor
Validez fiscalNinguna. CFDI sintéticoCFDI fiscal
StripeNo (400)Recargas y auto-recarga
TimbresBolsa sandbox del tenant (200 / 14 d)Bolsas paid por token

Los certificados Sandbox son generados por ContaDB exclusivamente para pruebas y no pueden utilizarse para emitir CFDI fiscales ante el SAT. Envía siempre el header Idempotency-Key en TEST y LIVE.

Recetas POS

  • S1 · Factura I PUE al cliente
  • S2 · Factura global del día (público en general)
  • S4 · Egreso / nota de crédito (devolución)
  • S5 · Cancelación motivos 01–04

RFC receptor reservados (TEST)

  • ERCE010101AAA CERTIFICADO_INVALIDO
  • ERSE010101AAA SELLO_INVALIDO
  • ERCF010101AAA CFDI_NO_VALIDO
  • ERRF010101AAA RFC_NO_VALIDO
  • ERPA010101AAA ERROR_PAC (rollback)
  • ERCA010101AAA cancelación rechazada

Bolsas de timbres

Pago único. Sin mensualidad.

Recarga cuando quieras o activa la auto-recarga vía Stripe. Tu saldo no vence pronto.

100
timbres
$200MXN

+ IVA · pago único

  • Vigencia 12 meses
  • $2.00 por timbre
  • Auto-recarga opcional
Crear cuenta
Más popular
500
timbres
$850MXN

+ IVA · pago único

  • Vigencia 12 meses
  • $1.70 por timbre
  • Auto-recarga opcional
Crear cuenta
1,000
timbres
$1,500MXN

+ IVA · pago único

  • Vigencia 12 meses
  • $1.50 por timbre
  • Auto-recarga opcional
Crear cuenta
10,000
timbres
$10,000MXN

+ IVA · pago único

  • Vigencia 24 meses
  • $1.00 por timbre
  • Auto-recarga opcional
Crear cuenta

Precios MXN, antes de IVA. Pago único vía Stripe. La auto-recarga compra el mismo paquete cuando el saldo baja del umbral que tú definas.

Endpoints

REST sobre api.contadb.mx

Autenticación con Authorization: Bearer <token>.

POST
/api/v1/timbrar
Timbra un CFDI 4.0 ya firmado. Misma ruta en TEST y LIVE.
POST
/api/v1/cancelar
Solicita cancelación. En TEST el PAC es sintético (sin red).
GET
/api/v1/saldo
Consulta timbres. Header X-ContaDB-Environment: test|live.
GET/POST
/api/v1/sandbox-emisores
CRUD de emisores sandbox (JWT panel). Bearer test: /sandbox/emisores.
POST
/api/v1/sandbox/bolsa/renovar
Renueva la bolsa sandbox (Bearer test). Panel: /sandbox-bolsa/renovar.
POST
/api/v1/recargas
Stripe Checkout (solo tokens live).

Complementos soportados

Todo el ecosistema CFDI 4.0

Recepción de Pagos 2.0
Complemento 2.0 para CFDI tipo P.
Nómina 1.2
Complemento nomina12 para CFDI tipo N.
CFDI relacionados
Sustitución, devoluciones, notas de crédito.
Cancelación
Motivos 01, 02, 03 y 04 con acuse XML.

Detalles técnicos

Pensado para producción

Idempotency keys

Envía Idempotency-Key en cada timbrado para evitar duplicados en reintentos.

Rate limit: 10 req/s

Por token. Si excedes recibes HTTP 429 con RATE_LIMIT_EXCEEDED.

Protección anti-abuso

Bloqueo automático de 5 minutos tras 5 errores consecutivos del mismo token.

Auto-recarga vía Stripe

Define un umbral y un paquete preferido: cuando el saldo baja, recargamos por ti.

Crea tu cuenta, genera un token, timbra.

Sin mensualidad, sin compromisos. Paga sólo los timbres que uses.

Crear cuenta gratisVer SDK en PyPI