API de Facturación Electrónica
Integración Fiscal Directa DIAN

Sin SIIVRO

Con SIIVRO

Por tenant

Para SaaS

Para ERP

Fuente: Configurado por ítem en el request

Fuente: Extraído del RUT y tipo de cliente

Fuente: Extraído del RUT y ciudad del cliente

{
  "document_type": "01",
  "external_id": "ORD-2025-00847",
  "customer": {
    "identification": "901944128",
    "dv": "3",
    "name": "COLABSOFT SAS",
    "email": "contabilidad@colabsoft.com",
    "address": "Calle 72 # 10-07, Bogotá"
  },
  "items": [
    {
      "description": "Licencia plataforma SaaS — Mensual",
      "quantity": 1,
      "price": 250000,
      "tax_rate": "19.00"
    },
    {
      "description": "Soporte técnico prioritario",
      "quantity": 2,
      "price": 50000,
      "tax_rate": "19.00"
    }
  ],
  "notes": "Pago neto 30 días. NIT vendedor: 900123456-1"
}

{
  "id": "inv_9x2kA7p3",
  "status": "DIAN_ACCEPTED",
  "cufe": "a8f3c2d1e9b...7e8273x",
  "dian_date": "2025-04-24T15:32:11-05:00",
  "totals": {
    "subtotal": 350000,
    "iva": 66500,
    "retefuente": 10500,
    "reteica": 3850,
    "total": 402150
  },
  "qr_code": "https://siivro.cloud/v/a8f3c2...",
  "xml_path": "https://storage.siivro.com/xml/inv_9x2kA7p3.xml",
  "pdf_path": "https://storage.siivro.com/pdf/inv_9x2kA7p3.pdf"
}

Factura aceptada. CUFE emitido. Validez legal inmediata.

La DIAN rechazó. Ver campo dian_errors. Corregir y reenviar.

WebService DIAN sin respuesta síncrona. Esperar webhook.

En cola de firma. Estado transitorio, no requiere acción.

Software como Servicio

Sistema de Gestión Empresarial

Comercio Electrónico

Punto de Venta

Gestión de Transporte

Gestión Hotelera

// Correcto: el frontend llama a TU backend
const handleInvoice = async () => {
  const res = await fetch("/api/create-invoice", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      customer: { identification: nit, name: razonSocial },
      items: cartItems.map(item => ({
        description: item.name,
        quantity: item.qty,
        price: item.price,
        tax_rate: "19.00"
      }))
    })
  });
  const { pdf_path, cufe } = await res.json();
  window.open(pdf_path);
};

// INCORRECTO: nunca hagas esto desde el frontend
// fetch("https://api.siivro.com/v1/invoices", {
//   headers: { "Authorization": "Bearer YOUR_KEY" } // expone la key
// });

// POST /api/create-invoice
app.post("/api/create-invoice", async (req, res) => {
  const { customer, items } = req.body;

  if (!customer.identification || !items.length) {
    return res.status(400).json({ error: "Datos incompletos" });
  }

  const siivroRes = await fetch("https://api.siivro.com/v1/invoices", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SIIVRO_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document_type: "01", customer, items })
  });

  const invoice = await siivroRes.json();

  return res.json({
    cufe: invoice.cufe,
    pdf_path: invoice.pdf_path,
    status: invoice.status
  });
});

// app/Http/Controllers/InvoiceController.php
public function store(Request $request)
{
    $validated = $request->validate([
        'customer.identification' => 'required|string',
        'customer.name'           => 'required|string',
        'items'                   => 'required|array|min:1',
    ]);

    $response = Http::withToken(config('services.siivro.key'))
        ->post('https://api.siivro.com/v1/invoices', [
            'document_type' => '01',
            'customer'      => $validated['customer'],
            'items'         => $validated['items'],
        ]);

    return response()->json([
        'cufe'     => $response['cufe'],
        'pdf_path' => $response['pdf_path'],
        'status'   => $response['status'],
    ]);
}

Lo que NO puedes hacer

El proceso correcto

{
  "document_type": "91",
  "customer": {
    "identification": "901944128",
    "name": "COLABSOFT SAS"
  },
  "billing_reference": {
    "invoice_id": "inv_9x2kA7p3",
    "cufe": "a8f3c2d1e9b...7e8273x",
    "reason": "Error en descripción del servicio"
  },
  "items": [
    {
      "description": "Ajuste — Licencia plataforma SaaS",
      "quantity": 1,
      "price": 250000,
      "tax_rate": "19.00"
    }
  ]
}

Facturación offline

Emisión de facturas en papel (tipo 02). Se reportan masivamente a la DIAN una vez restablecido el sistema.

Sistema alterno

Uso de un sistema de facturación alterno habilitado por la DIAN. Numeración diferenciada.

Reporte posterior

Reporte masivo a la DIAN con todas las facturas emitidas durante el período de contingencia.

Caso A — Respuesta síncrona

Caso B — Respuesta asincrónica

Cuándo reintentar y cuándo no

{
  "url": "https://tu-sistema.com/webhooks/siivro",
  "events": ["invoice.updated"],
  "secret": "tu_clave_para_validar_firma"
}

{
  "event": "invoice.updated",
  "invoice_id": "inv_9x2kA7p3",
  "external_id": "ORD-2025-00847",
  "status": "DIAN_ACCEPTED",
  "cufe": "a8f3c2d1e9b...7e8273x",
  "pdf_path": "https://storage.siivro.com/pdf/inv_9x2kA7p3.pdf",
  "timestamp": "2025-04-24T15:34:02-05:00",
  "signature": "sha256=abc123..."
}

Actualizar estado en DB — habilitar descarga PDF — notificar usuario

Marcar factura como rechazada — mostrar error — solicitar corrección

Versión actual

Versión estable en producción. Se recomienda siempre integrar con la versión más reciente para acceder a las últimas capacidades fiscales.

Versiones futuras

Cuando se introduzcan cambios con ruptura de compatibilidad, SIIVRO publica una nueva versión. La anterior sigue funcionando hasta su retiro formal.

Garantías de retrocompatibilidad

Política de notificación de cambios

SIIVRO notifica con mínimo 30 días de anticipación cualquier cambio relevante en la API. Los cambios mayores pasan por un programa beta con usuarios seleccionados antes del lanzamiento general.

Creación de facturas

Por tenant

Consultas GET

Por tenant

Registro de webhooks

Por tenant

Descarga de documentos

Por tenant

Headers de respuesta relevantes

La DIAN valida el NIT del receptor contra el RUT. Un NIT inválido resulta en rechazo inmediato (FAD01). Valida el NIT antes de presentarlo al usuario como opción.

Reintentar sin external_id puede crear múltiples facturas por la misma operación. Siempre envía un external_id único por transacción y controla si ya fue procesada.

El frontend puede ser manipulado. Valida cantidades, precios y datos del cliente en tu backend antes de enviarlos a SIIVRO. Un price: 0 o un NIT vacío genera error inmediato.

Una factura aceptada por la DIAN es un documento fiscal con validez legal. No existe endpoint de eliminación. El único mecanismo es una nota crédito (tipo 91).

PROCESSING no es un error. Es un estado válido que indica que la DIAN no respondió de forma síncrona. Escucha el webhook y actualiza tu sistema cuando llegue el resultado.

Las resoluciones tienen fechas de vencimiento y rangos de numeración. Cuando se agotan o vencen, el sistema falla. SIIVRO gestiona la resolución activa automáticamente.

La API Key de SIIVRO tiene acceso a toda la facturación del tenant. Nunca la incluyas en código cliente, variables de entorno públicas o repositorios de código.

SIIVRO se comunica directamente con el WebService de la DIAN sin capas de intermediación. Menos saltos, menos tiempo de espera, menos puntos de fallo.

Sin librerías de firma criptográfica, sin parsers XML, sin clientes SOAP, sin gestión de certificados. Tu codebase es más pequeño y más mantenible.

La complejidad fiscal vive en SIIVRO. Tu backend solo hace HTTP POST. Si la DIAN cambia su esquema, SIIVRO se actualiza sin que toques código.

La arquitectura multi-tenant nativa permite agregar N empresas sin duplicar infraestructura. Un solo punto de integración gestiona múltiples clientes.

Checklist de salida a producción

{
  "invoice_id": "inv_9x2kA7p3",
  "external_id": "ORD-2025-00847",
  "events": [
    {
      "status": "PENDING_SIGN",
      "timestamp": "2025-04-24T15:32:00-05:00",
      "actor": "system"
    },
    {
      "status": "PROCESSING",
      "timestamp": "2025-04-24T15:32:01-05:00",
      "actor": "system",
      "detail": "XML firmado. Transmitiendo a DIAN."
    },
    {
      "status": "DIAN_ACCEPTED",
      "timestamp": "2025-04-24T15:32:11-05:00",
      "actor": "dian",
      "cufe": "a8f3c2d1e9b...7e8273x",
      "detail": "ApplicationResponse recibido y procesado."
    }
  ],
  "webhook_sent": true,
  "webhook_attempts": 1,
  "webhook_last_status": 200
}