API Reference

Authorization: Bearer fsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx

Authorization: Bearer fsk_live_xxx
Content-Type: application/json   // o multipart/form-data para uploads
Accept: application/json
X-Company-Id: comp_xxxx          // opcional — si gestiona múltiples empresas

curl -X POST https://api.factura-sv.algoritmos.io/v1/documents/upload \
  -H "Authorization: Bearer fsk_live_xxx" \
  -F "file=@factura_001.pdf" \
  -F "auto_process=true" \
  -F "dte_type=03"

{
  "id": "doc_a1b2c3d4e5f6",
  "status": "processing",
  "filename": "factura_001.pdf",
  "dte_type": "03",
  "file_size": 245780,
  "created_at": "2026-02-13T14:30:00Z",
  "company_id": "comp_default"
}

{
  "id": "doc_a1b2c3d4e5f6",
  "status": "processed",
  "dte_type": "03",
  "extracted_data": {
    "emisor": { "nombre": "Empresa ABC", "nit": "0614-..." },
    "receptor": { "nombre": "Cliente XYZ", "nrc": "12345-6" },
    "items": [ /* array de líneas extraídas */ ],
    "total": 1130.00,
    "confidence": 0.97
  },
  "validation": {
    "is_valid": true,
    "errors": [],
    "warnings": ["Campo receptor.telefono vacío"]
  }
}

{
  "id": "doc_a1b2c3d4e5f6",
  "status": "accepted",
  "sello_recepcion": "2026XXXXXXXXXXXXXXXXXX",
  "codigo_generacion": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "numero_control": "DTE-03-M001-P001-000000000000042",
  "fecha_transmision": "2026-02-13T14:32:15Z",
  "observaciones": []
}

"uploaded"    → Archivo recibido, sin procesar
"processing"  → OCR/AI en ejecución
"processed"   → Datos extraídos, listo para revisión
"transmitting"→ Enviando al MH
"accepted"    → ✅ Aceptado por MH (Sello de Recepción otorgado)
"rejected"    → ❌ Rechazado por MH (ver observaciones)
"invalidated" → Documento invalidado
"error"       → Error en procesamiento (OCR falló, formato inválido)

{
  "data": [
    { "id": "doc_xxx", "status": "accepted", "dte_type": "03", ... },
    { "id": "doc_yyy", "status": "accepted", "dte_type": "01", ... }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1247,
    "total_pages": 25
  }
}

curl https://api.factura-sv.algoritmos.io/v1/documents/doc_xxx/download?format=json \
  -H "Authorization: Bearer fsk_live_xxx" \
  -o factura_firmada.json

{
  "id": "doc_a1b2c3d4e5f6",
  "status": "invalidated",
  "invalidation": {
    "sello_invalidacion": "2026INVXXXXXXXXXX",
    "fecha": "2026-02-13T15:00:00Z",
    "motivo": "Error en datos del receptor"
  }
}

{
  "name": "Mi Empresa S.A. de C.V.",
  "nit": "0614-123456-789-0",
  "nrc": "123456-7",
  "economic_activity": "62010",  // CAT-019
  "establishment_code": "M001",
  "pos_code": "P001",
  "address": {
    "department": "06",   // CAT-012: San Salvador
    "municipality": "14", // CAT-013: San Salvador
    "complement": "Col. Escalón, Calle La Reforma #123"
  },
  "phone": "2222-3333",
  "email": "[email protected]"
}

{
  "url": "https://miempresa.sv/api/factura-webhook",
  "events": [
    "document.processed",
    "document.accepted",
    "document.rejected",
    "document.invalidated"
  ],
  "secret": "whsec_xxxxxxxxx"  // Para verificar firma HMAC-SHA256
}

{
  "event": "document.accepted",
  "timestamp": "2026-02-13T14:32:15Z",
  "data": {
    "id": "doc_a1b2c3d4e5f6",
    "status": "accepted",
    "sello_recepcion": "2026XXXX...",
    "dte_type": "03",
    "company_id": "comp_xxx"
  }
}

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1739456000     // Unix timestamp
Retry-After: 42                    // Solo cuando se excede (429)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El campo receptor.nrc es obligatorio para CCF (03)",
    "details": [
      { "field": "receptor.nrc", "rule": "required" }
    ]
  }
}

import { FacturaSV } from '@factura-sv/sdk';

const client = new FacturaSV({ apiKey: 'fsk_live_xxx' });

// Subir y procesar un documento
const doc = await client.documents.upload({
  file: fs.createReadStream('factura.pdf'),
  dteType: '03'
});

// Transmitir al Ministerio de Hacienda
const result = await client.documents.transmit(doc.id);
console.log(`Sello: ${result.sello_recepcion}`);

from factura_sv import FacturaSV

client = FacturaSV(api_key="fsk_live_xxx")

# Subir y procesar
doc = client.documents.upload(
    file="factura.pdf",
    dte_type="03"
)

# Transmitir al MH
result = client.documents.transmit(doc.id)
print(f"Sello: {result.sello_recepcion}")