Documentación API

Crear nueva API key con permisos específicos.

{
  "name": "ERP Integration",
  "permissions": ["emit", "list", "export", "invalidate"]
}

{
  "api_key": "fsv_live_abc123...",
  "key_prefix": "fsv_live_abc1****",
  "permissions": ["emit", "list", "export", "invalidate"]
}

⚠️ La API key completa solo se muestra una vez. Guárdela de forma segura.

Listar API keys activas (nunca muestra la clave completa).

[
  {
    "id": "uuid",
    "key_prefix": "fsv_live_abc1****",
    "name": "ERP Integration",
    "permissions": ["emit", "list"],
    "is_active": true,
    "created_at": "2026-02-23T..."
  }
]

Revocar API key permanentemente.

Emitir un DTE. Firma con RSA-SHA256, transmite al MH y retorna sello de recepción. ~1.5s end-to-end.

{
  "tipo_dte": "01",
  "condicion_operacion": 1,
  "receptor": {
    "nombre": "Juan Pérez",
    "tipoDocumento": "13",
    "numDocumento": "012345678",
    "correo": "juan@email.com"
  },
  "items": [
    {
      "descripcion": "Servicio de consultoría",
      "cantidad": 1,
      "precioUni": 113.00,
      "uniMedida": 59
    }
  ]
}

{
  "success": true,
  "estado": "PROCESADO",
  "selloRecibido": "2026022...",
  "codigoGeneracion": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "numeroControl": "DTE-01-M001P001-000000000000001",
  "dte_id": "uuid"
}

Vista previa del DTE sin transmitir al MH. Útil para validación antes de emisión definitiva.

Emitir hasta 100 DTEs en una sola llamada. Cada DTE se procesa individualmente con su propio estado.

{
  "dtes": [
    {
      "tipo_dte": "01",
      "receptor": { "nombre": "Cliente 1", "tipoDocumento": "13", "numDocumento": "012345678" },
      "items": [{ "descripcion": "Producto A", "cantidad": 2, "precioUni": 56.50, "uniMedida": 59 }]
    },
    {
      "tipo_dte": "03",
      "receptor": { "nombre": "Empresa X", "tipoDocumento": "36", "numDocumento": "0614-010180-103-0", "nrc": "12345-6" },
      "items": [{ "descripcion": "Servicio B", "cantidad": 1, "precioUni": 500.00, "uniMedida": 59 }]
    }
  ]
}

{
  "total": 2,
  "procesados": 2,
  "fallidos": 0,
  "resultados": [
    { "index": 0, "estado": "PROCESADO", "selloRecibido": "...", "codigoGeneracion": "..." },
    { "index": 1, "estado": "PROCESADO", "selloRecibido": "...", "codigoGeneracion": "..." }
  ]
}

Listar DTEs con filtros opcionales: tipo, estado, fecha, receptor, paginación.

?tipo_dte=01           # Filtrar por tipo
&estado=PROCESADO      # PROCESADO | RECHAZADO | ANULADO
&fecha_desde=2026-01-01
&fecha_hasta=2026-12-31
&receptor=Juan         # Búsqueda por nombre
&page=1&per_page=50

[
  {
    "id": "uuid",
    "tipo_dte": "01",
    "numero_control": "DTE-01-M001P001-000000000000001",
    "estado": "PROCESADO",
    "monto_total": 113.00,
    "fecha_emision": "2026-02-23",
    "receptor_nombre": "Juan Pérez"
  }
]

Detalle completo de un DTE: JSON del documento, JWS firmado, sello del MH.

Descargar PDF del DTE con código QR de verificación del MH embebido. Retorna application/pdf.

Exportar historial de DTEs en formato XLSX o PDF con filtros.

Invalidar un DTE previamente procesado. Firma la anulación y la transmite al MH. Ventana: 90 días calendario.

{
  "codigo_generacion": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "tipo_dte": "01",
  "motivo_anulacion": 2,
  "nombre_solicita": "Juan Pérez",
  "tipo_doc_solicita": "36",
  "num_doc_solicita": "00000000-0",
  "nombre_responsable": "María García",
  "tipo_doc_responsable": "36",
  "num_doc_responsable": "00000000-0"
}

{
  "success": true,
  "selloRecibido": "...",
  "estado": "ANULADO"
}

Libro de Ventas Contribuyente (CCF tipo 03). Parámetros: year, month, format (xlsx|pdf).

Libro de Ventas Consumidor Final (Factura tipo 01). Parámetros: year, month, format (xlsx|pdf).

Resumen IVA mensual consolidado por tipo de DTE. Parámetros: year, month, format (xlsx|pdf).

Anexo 1: CCF + Notas de Crédito + Notas de Débito (CSV).

Anexo 2: Facturas + Sujeto Excluido (CSV).

Anexo 3: Retenciones tipo 07 (CSV).

ZIP consolidado con los 3 anexos listos para declaración.

Listar DTEs en cola de contingencia.

Procesar y retransmitir DTEs encolados.

{
  "processed": 3,
  "failed": 1,
  "remaining": 0
}

Listar productos del catálogo de la organización.

Crear producto.

{
  "codigo": "SRV001",
  "descripcion": "Servicio de consultoría",
  "precio": 100.00,
  "uniMedida": 59
}

Listar receptores frecuentes con búsqueda. Parámetro: q (búsqueda por nombre/NIT).

Crear receptor frecuente.

Buscar actividades económicas del MH (989 códigos CAT-019). Parámetro: q (búsqueda), limit.

Consultar balance actual de créditos de la organización.

{
  "credit_balance": 847,
  "alert_level": null
}

Historial de transacciones de créditos (compras, consumos, ajustes).

Registrar un webhook.

{
  "url": "https://mi-erp.com/webhook/factura-sv",
  "events": ["dte.emitted", "dte.invalidated"],
  "secret": "mi_secreto_hmac"
}

Listar webhooks registrados.

Eliminar webhook.

Upload archivo CSV/XLSX. Analiza estructura y retorna mapeo de columnas detectado para confirmación.

Content-Type: multipart/form-data
file: archivo.xlsx

Ejecutar import con mapeo confirmado. Crea receptores y/o productos en catálogo.

Import automático sin confirmación (usa mapeo por defecto).

Listar organizaciones del usuario actual y obtener la organización activa.

Cambiar de organización activa (multi-empresa).

Especificacion completa del estandar FSV1 (sin auth).

Generar Tarjeta Fiscal Digital con QR.

Decodificar QR fiscal FSV1 o legacy.

Buscar identidad por NIT en directorio. Parametro: nit.

Resolver receptor para emision DTE a partir de QR o NIT.

Generar QR para un receptor registrado.

Decodificar QR escaneado y retornar datos del receptor.

Generar QR sin cuenta (uso publico).

Leer configuracion email de la organizacion.

Guardar SMTP custom (password encriptado AES-256).

Enviar email de prueba para verificar configuracion.

Volver a correo de plataforma por defecto.

Leer configuracion WhatsApp de la organizacion.

Guardar token y phone ID de WhatsApp Business.

Enviar mensaje de prueba.

Enviar DTE especifico por WhatsApp al receptor.

Listar cuentas por cobrar.

Estadisticas de cobro.

Antiguedad de saldos.

Registrar pago recibido.

Listar cuentas por pagar.

Registrar pago realizado.

Listar DTEs recibidos.

Subir JSON de DTE recibido.

Generar libro de compras.

Cuadre IVA (debito fiscal vs credito fiscal).

Resumen mensual de DTEs recibidos.

Plan de cuentas de la organizacion.

Listar partidas contables generadas.

Balance de comprobacion.

Inicializar plan de cuentas estandar.

Listar inventario de la organizacion.

Registrar movimiento de inventario.

Kardex del producto (historial de movimientos).

Upload archivos (PDF, JSON, XML) y recibir CSV estructurado de salida.

Vista previa antes de exportar — verificar datos extraidos.

Dashboard consolidado del despacho con metricas de todas las empresas.

Agregar empresa cliente al despacho.

Reporte consolidado multi-empresa.

Subir CSV de ventas para comparar contra DTEs emitidos.

Listar reconciliaciones.

Detalle de reconciliacion con discrepancias encontradas.

Registrar aceptacion de documento legal.

Estado de documentos legales aceptados.

Verificacion publica por hash SHA-256 (para auditores).

Listar notificaciones del usuario.

Conteo de notificaciones no leidas.

Marcar todas las notificaciones como leidas.