API para integrar tu sistema

Emite y consulta comprobantes desde tu ERP, tienda en línea o sistema contable. Base: https://www.pruebas.facturas.xmlsync.com/api/v1 · JSON · HTTPS.

Primeros pasos

Crea tu cuenta, registra tu emisor y carga tu CSD.
En API (dentro del portal) crea una llave. Se muestra una sola vez; guárdala en un lugar seguro.
Prueba con un emisor en modo pruebas: no consume timbres ni tiene validez fiscal. Para facturar en producción, solicita la activación del emisor.

Autenticación

Envía la llave en cada petición: Authorization: Bearer fk_…. Si es inválida o fue revocada responde 401. Cada llave solo accede a los datos de su cuenta.

Endpoints

Método	Ruta	Descripción
GET	`/emisores`	Emisores de tu cuenta, entorno (pruebas/producción) y si están listos para timbrar
POST	`/facturas`	Emite una factura de ingreso
POST	`/pagos`	Emite un complemento de pago (REP)
POST	`/comprobantes/{id}/notas`	Emite una nota de crédito sobre una factura
POST	`/comprobantes/{id}/cancelar`	Solicita la cancelación
POST	`/comprobantes/{id}/reintentar`	Reintenta un comprobante con estatus `error`
GET	`/comprobantes`	Lista (filtros: referencia, estatus, uuid, tipo)
GET	`/comprobantes/{id}`	Consulta un comprobante
GET	`/comprobantes/{id}/xml` · `/pdf`	Descarga el XML timbrado o el PDF

Ejemplo: emitir una factura

curl -X POST https://www.pruebas.facturas.xmlsync.com/api/v1/facturas \
  -H "Authorization: Bearer fk_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "emisor": "AAA010101AAA",
    "referencia": "pedido-1042",
    "forma_pago": "03", "metodo_pago": "PUE",
    "cliente": { "rfc": "XAXX010101000" },
    "conceptos": [{
      "clave_prod_serv": "84111506", "clave_unidad": "E48",
      "descripcion": "Servicio de consultoría", "cantidad": 1,
      "valor_unitario": 1000, "iva": "16"
    }]
  }'

Respuesta 201 (timbrado), 202 (en proceso/incierto) o 422 (error de validación o rechazo):

{ "comprobante": { "id": 128, "estatus": "timbrado", "uuid": "…", "serie": "A", "folio": 17,
  "total": 1160.00, "xml_url": "…/api/v1/comprobantes/128/xml", "pdf_url": "…/pdf" } }

Retenciones y dólares

Cada concepto acepta retencion_isr y retencion_iva (porcentajes, p. ej. 10 y 10.666667); el total es subtotal + IVA − retenciones. Para facturar en dólares envía "moneda": "USD" y "tipo_cambio" (pesos por dólar del día). La respuesta incluye moneda, retenciones y total. El complemento de pago (REP) por ahora solo admite facturas en pesos.

Idempotencia (reintentos seguros)

Envía un valor único en referencia por cada operación de tu sistema. Si repites la petición con la misma referencia, no se emite otro comprobante: recibes el existente con "duplicado": true y código 200. Si una petición se corta por tiempo de espera, repítela con la misma referencia.

Códigos de respuesta

401 llave inválida · 402 sin timbres disponibles · 403 cuenta suspendida · 404 no encontrado
409 estado no permitido · 422 datos inválidos (con el detalle por campo) · 429 demasiadas peticiones (120 por minuto)

Webhooks

Configura una URL HTTPS en la sección API del portal. Enviamos un POST con cada cambio de estatus (timbrado, error, cancelado…), firmado con HMAC-SHA256 en la cabecera X-Facturas-Firma usando tu secreto. Verifica siempre la firma antes de confiar en el contenido.

Ejemplo en PHP

$ch = curl_init('https://www.pruebas.facturas.xmlsync.com/api/v1/emisores');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('FACTURAS_KEY')]]);
$emisores = json_decode(curl_exec($ch), true);

Ejemplo en Node.js

const r = await fetch('https://www.pruebas.facturas.xmlsync.com/api/v1/emisores', {
  headers: { Authorization: `Bearer ${process.env.FACTURAS_KEY}` } });
const { emisores } = await r.json();

Explorar la API en Swagger (OpenAPI)

Si necesitas algo que no está aquí, escríbenos.