Documentación de la API

Autenticación

Todas las solicitudes deben incluir tu API Key en el header X-API-Key. Genera y administra tus claves desde el panel de tu cuenta.

X-API-Key: fai_live_xxxxxxxxxxxx

curl -X GET https://factuia.cl/api/v1/empresa/saldo \
  -H "X-API-Key: fai_live_xxxxxxxxxxxx"

Errores y códigos HTTP

Los errores devuelven un JSON con la clave message y, en casos de validación, errors.

// Ejemplo respuesta 422
{
  "message": "El RUT del receptor es inválido.",
  "errors": {
    "receptor.rut": ["El RUT 12345678-0 no existe en el SII."]
  }
}

Rate limiting

El límite se devuelve en los headers de cada respuesta.

Emite una factura afecta (tipo 33) o exenta (tipo 34) firmada y enviada al SII en tiempo real. Si el SII acepta el documento, devuelve el folio asignado y el XML firmado.

{
  "tipo": "33",          // 33 afecta | 34 exenta
  "receptor": {
    "rut": "76123456-7",
    "razon_social": "Cliente SA",
    "giro": "Tecnología",
    "direccion": "Av. Apoquindo 1234",
    "ciudad": "Santiago",
    "comuna": "Las Condes"  // opcional
  },
  "items": [
    {
      "nombre": "Consultoría abril",
      "cantidad": 1,
      "precio_unitario": 500000,
      "descuento_pct": 0   // opcional
    }
  ],
  "forma_pago": "contado",  // contado | credito
  "referencia": "OC-2026-001", // opcional
  "observacion": "..."       // opcional
}

{
  "id": "dte_abc123",
  "folio": 1042,
  "tipo": 33,
  "estado_sii": "ACEPTADO",
  "monto_total": 595000,
  "pdf_url": "https://factuia.cl/api/v1/dte/dte_abc123/pdf",
  "xml_url": "https://factuia.cl/api/v1/dte/dte_abc123/xml",
  "emitido_en": "2026-04-08T10:23:00Z"
}

Emite una boleta electrónica afecta (tipo 39) o exenta (tipo 41). El receptor es facultativo — si se omite, se emite a consumidor final.

{
  "tipo": "39",              // 39 afecta | 41 exenta
  "receptor": {             // opcional en boleta
    "rut": "12345678-9",
    "razon_social": "Juan Pérez"
  },
  "items": [
    { "nombre": "Producto A", "cantidad": 2, "precio_unitario": 15000 }
  ]
}

Emite una nota de crédito electrónica referenciando el DTE original. Puede anular completamente o hacer un ajuste parcial.

{
  "dte_referencia_id": "dte_abc123",   // ID interno del DTE a referenciar
  "motivo": "Anulación de factura",
  "tipo_nc": "anulacion",    // anulacion | correccion | descuento
  "items": [                           // omitir para anulación total
    { "nombre": "Ajuste precio", "cantidad": 1, "precio_unitario": 50000 }
  ]
}

Emite una nota de débito referenciando el DTE original, para cobros adicionales o correcciones al alza.

{
  "dte_referencia_id": "dte_abc123",
  "motivo": "Cobro adicional por flete",
  "items": [
    { "nombre": "Flete adicional", "cantidad": 1, "precio_unitario": 30000 }
  ]
}

{
  "receptor": {
    "rut": "76123456-7", "razon_social": "Bodega Sur",
    "direccion_despacho": "Ruta 5 Sur km 12", "ciudad": "Maipú"
  },
  "indicador_traslado": 1,  // 1=venta 2=consignación 3=traslado interno
  "items": [
    { "nombre": "Cajas producto X", "cantidad": 50, "precio_unitario": 8000 }
  ]
}

Envía hasta 100 DTEs del mismo tipo en una sola llamada. El procesamiento es asíncrono — se devuelve un lote_id para consultar el estado de cada documento.

{
  "tipo": "33",
  "documentos": [
    {
      "receptor": { ... },
      "items": [ ... ]
    },
    { ... }   // hasta 100
  ]
}

{
  "lote_id": "lot_xyz789",
  "total": 12,
  "estado": "procesando",
  "webhook_url": "https://tu-app.com/webhook"
}

Devuelve el estado actualizado de un DTE. El campo estado_sii se sincroniza en tiempo real con el SII.

// Response 200
{
  "id": "dte_abc123",
  "tipo": 33,
  "folio": 1042,
  "estado_sii": "ACEPTADO",   // PENDIENTE | ACEPTADO | RECHAZADO | REPARO
  "receptor_rut": "76123456-7",
  "receptor_razon_social": "Cliente SA",
  "monto_neto": 500000,
  "monto_iva": 95000,
  "monto_total": 595000,
  "emitido_en": "2026-04-08T10:23:00Z",
  "pdf_url": "https://factuia.cl/api/v1/dte/dte_abc123/pdf"
}

Descargar PDF y XML

// Headers de respuesta
Content-Type: application/pdf
Content-Disposition: attachment; filename="F33-1042.pdf"

// Response 200
{
  "plan": "Profesional",
  "dtes_emitidos_mes": 47,
  "dtes_limite_mes": 200,
  "ciclo_renovacion": "2026-05-01",
  "folios": {
    "33": { "disponibles": 450, "proximo_timbraje": 100 },
    "39": { "disponibles": 820, "proximo_timbraje": 500 }
  }
}

Verifica matemáticamente el dígito verificador y, opcionalmente, consulta la actividad en el SII.

{
  "rut": "76123456-7",
  "valido": true,
  "razon_social": "Empresa Ejemplo SpA",
  "actividad_economica": "620200 - Actividades de consultoría informática",
  "inicio_actividades": "2018-03-14"
}

Webhooks

Factuia puede notificar a una URL de tu sistema cuando un DTE cambia de estado. Configura tu URL desde el panel de tu empresa en Ajustes → Webhooks.

Verificar firma

// PHP
$secret    = env('FACTUIA_WEBHOOK_SECRET');
$payload   = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($signature, $_SERVER['HTTP_X_FACTUIA_SIGNATURE'])) {
    http_response_code(401); exit;
}

Eventos disponibles

Payload de ejemplo

{
  "evento": "dte.aceptado",
  "timestamp": "2026-04-08T10:23:05Z",
  "data": {
    "id": "dte_abc123",
    "tipo": 33,
    "folio": 1042,
    "estado_sii": "ACEPTADO",
    "monto_total": 595000
  }
}