Documentación API IKOMSOFT

📖 Introducción

La API REST de IKOMSOFT permite acceder de forma programática a información de clientes, facturas, consignatarios, artículos y seguimiento de paquetes. Esta API utiliza peticiones HTTP estándar y devuelve respuestas en formato JSON, facilitando la integración con cualquier plataforma o lenguaje de programación.

Segura

Autenticación mediante API Key única por empresa con registro completo de todas las operaciones

Rápida

Respuestas optimizadas con tiempos de respuesta mínimos para máxima eficiencia

Completa

Acceso total a la información de tu sistema en tiempo real

RESTful

Arquitectura estándar REST fácil de integrar en cualquier proyecto

⚡ Inicio Rápido

🚀 Pasos para comenzar:

Obtén tu API Key - Contacta al equipo de IKOMSOFT para recibir tu clave única de acceso
Construye tu URL - Combina la URL base con tu API Key y el tipo de consulta deseado
Realiza la petición - Ejecuta una petición GET para consultar los datos
Procesa la respuesta - Recibirás un JSON estructurado con los datos solicitados

🔑 Autenticación

Todas las peticiones requieren el parámetro api_id con tu API Key única. Esta clave identifica tu empresa y autoriza el acceso a tus datos de forma segura.

URL Base:

https://ikomsoft.com/api/web_service.php

Ejemplo básico de uso:

                    https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=clients
                

⚙️ Parámetros Globales

Parámetro	Tipo	Requerido	Descripción
api_id	String	Obligatorio	Tu API Key única proporcionada por IKOMSOFT
type	String	Obligatorio	Tipo de consulta: `clients`, `invoices`, `consigneer`, `articles_invoice`, `status`, `invoices_by_date`

👥 1. Consultar Clientes

GET Obtener Clientes

Obtiene la lista completa de clientes registrados en tu sistema o información detallada de un cliente específico mediante su número de casillero.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
type	String	Obligatorio	Valor: `clients`
idclient	String	Opcional	Número de casillero del cliente específico

Ejemplos de uso:

Consultar todos los clientes:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=clients
                    

Consultar cliente específico:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=clients&idclient=12345
                    

Campos de la Respuesta:

✓ IkomClientId - ID único del cliente en el sistema
✓ IkomClientFirst_Name / Last_Name - Nombre y apellido del cliente
✓ IkomClientEmail - Correo electrónico de contacto
✓ IkomClientPhone / Mobile_Phone / Office_Phone - Teléfonos de contacto
✓ IkomClientAddress - Dirección completa del cliente
✓ IkomClientCountry / State / City - Ubicación geográfica
✓ IkomClientBalance - Balance actual de la cuenta
✓ IkomClientPrice_default - Precio por defecto asignado
✓ Ikomnocasillero - Número de casillero asignado
✓ IkomClientStart_Date - Fecha de inicio del cliente

🧾 2. Consultar Facturas

GET Obtener Facturas

Obtiene todas las facturas activas del sistema o filtra las facturas de un cliente específico. Incluye totales calculados automáticamente de cajas, volumen y peso para cada factura.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
type	String	Obligatorio	Valor: `invoices`
idclient	Integer	Opcional	ID del cliente (Client_Id) para filtrar facturas

Ejemplos de uso:

Consultar todas las facturas:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=invoices
                    

Consultar facturas de un cliente:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=invoices&idclient=123
                    

Campos Principales de la Respuesta:

✓ Ikominv_id - ID único de la factura
✓ Ikominvnumber - Número de factura
✓ Ikominvdate / hours - Fecha y hora de emisión
✓ Ikominvamount - Monto total de la factura
✓ Ikominvpaid / balance - Monto pagado y balance pendiente
✓ Ikominvtax / insurance - Impuestos y seguro aplicados
✓ Ikominvdiscount - Descuentos aplicados
✓ Ikomcodeqtybox - 📦 Cantidad total de cajas
✓ Ikomcodeqtyvolume - 📏 Volumen total en pies cúbicos
✓ Ikomcodeqtypeso - ⚖️ Peso total acumulado
✓ Ikomcodeconsigner - Nombre completo del consignatario

📬 3. Consultar Consignatarios

GET Obtener Consignatarios

Obtiene la lista completa de destinatarios y consignatarios registrados en el sistema con toda su información de contacto y ubicación.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
type	String	Obligatorio	Valor: `consigneer`

Ejemplo de uso:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=consigneer
                    

Campos de la Respuesta:

✓ IkomShipId - ID único del consignatario
✓ IkomShipFirstName / LastName - Nombre completo del destinatario
✓ IkomShipPhone / MobilePhone / Phoneoffice - Teléfonos de contacto
✓ IkomShipEmail - Correo electrónico
✓ IkomShipAddress - Dirección completa de entrega
✓ IkomShipCountry / State / City - Ubicación geográfica
✓ Ikomdocument - Documento de identidad
✓ Ikommunicipality / location / location2 - Detalles adicionales de ubicación

📦 4. Consultar Artículos de Facturas

GET Obtener Artículos

Obtiene todos los artículos e items asociados a las facturas del sistema, incluyendo detalles de dimensiones, peso, volumen y contenido de cada caja.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
type	String	Obligatorio	Valor: `articles_invoice`

Ejemplo de uso:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=articles_invoice
                    

Campos de la Respuesta:

✓ IkomItempId - ID único del artículo
✓ IkomItempInvoice_Id - ID de la factura asociada
✓ IkomItempDescription - Descripción detallada del artículo
✓ IkomItempQty - Cantidad de unidades
✓ IkomItempPrice / Amount - Precio unitario y monto total
✓ Ikomlargo / ancho / alto - Dimensiones (Largo x Ancho x Alto)
✓ Ikomqtypie - Volumen calculado en pies cúbicos
✓ Ikompeso - Peso del artículo
✓ Ikomcontentbox - Descripción del contenido de la caja

📍 5. Consultar Status / Tracking

GET Obtener Status de Paquetes

Permite consultar los estados disponibles en el sistema o rastrear paquetes específicos utilizando el ID de factura o el número de factura.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
type	String	Obligatorio	Valor: `status`
invoice_id	Integer	Opcional	ID de la factura para rastrear el paquete
number	String	Opcional	Número de factura para rastrear el paquete

Ejemplos de uso:

Listar todos los status disponibles:

https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=status

Rastrear por ID de factura:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=status&invoice_id=456
                    

Rastrear por número de factura:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=status&number=INV-2024-001
                    

Campos de la Respuesta:

✓ Ikomidepack - ID del paquete
✓ Ikomdate / ihour - Fecha y hora de la transacción
✓ Ikomcountry - País de origen/destino
✓ Ikombarcode - Código de barras del paquete
✓ Ikomdescription - Descripción del estado
✓ Ikomstatus - Estado actual del paquete
✓ Ikomactive - Si el paquete está activo

📅 6. Consultar Facturas por Fecha

GET Obtener Facturas de una Fecha Específica

Obtiene todas las facturas de un día específico con información completa del cliente, destinatario y todos los paquetes asociados incluyendo sus códigos de barras. Este endpoint es ideal para sincronización diaria y reportes.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
type	String	Obligatorio	Valor: `invoices_by_date`
date	String	Obligatorio	Fecha en formato `MMDDYYYY` (ejemplo: 01152025 = Enero 15, 2025)

Formato de Fecha:

Fecha Deseada	Formato MMDDYYYY	Ejemplo
1 de enero 2025	`01012025`	`&date=01012025`
15 de enero 2025	`01152025`	`&date=01152025`
4 de julio 2024	`07042024`	`&date=07042024`
25 de diciembre 2024	`12252024`	`&date=12252024`

Ejemplos de uso:

Facturas del 26 de Noviembre 2024:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=invoices_by_date&date=11262024
                    

Facturas del 15 de Enero 2025:

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=invoices_by_date&date=01152025
                    

Modo Debug (con formato HTML):

                        https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=invoices_by_date&date=11262024&format=html
                    

Estructura de la Respuesta:

La respuesta incluye un array con objetos que contienen 4 secciones principales para cada factura:

📋 1. Datos de la Factura (invoice):

✓ Ikominv_id - ID único de la factura
✓ Ikominvnumber - Número de factura (ej: LA-30360)
✓ Ikominvdate - Fecha de la factura
✓ Ikominvhours - Hora de emisión
✓ Ikominvcontainer - Número de contenedor
✓ Ikominvamount - Monto total
✓ Ikominvpaid / balance - Pagado y balance
✓ Ikomstatuspack - Estado del paquete
✓ Ikomcodekeys - Código único de la factura

👤 2. Datos del Cliente (client):

✓ IkomClientId - ID del cliente
✓ IkomClientFirst_Name / Last_Name - Nombre completo
✓ IkomClientEmail - Correo electrónico
✓ IkomClientPhone / Mobile_Phone - Teléfonos
✓ Ikomnocasillero - Número de casillero
✓ IkomClientCompany - Empresa (si aplica)

📬 3. Datos del Consignatario (consignee):

✓ IkomShipId - ID del consignatario
✓ IkomShipFirstName / LastName - Nombre del destinatario
✓ IkomShipPhone / MobilePhone - Teléfonos de contacto
✓ IkomShipEmail - Email del destinatario
✓ IkomShipAddress - Dirección de entrega completa
✓ IkomShipCity / State / Country - Ubicación
✓ Ikomdocument - Cédula o documento de identidad

📦 4. Paquetes (packages) - Array:

✓ Ikompackage_id - ID del paquete
✓ Ikombarcode - 🔖 Código de barras completo (ej: DO-LA 30360-44360-91122-1)
✓ Ikombarcode_mini - Código de barras corto
✓ Ikomcountry - País de origen/destino
✓ Ikomcontainer_scan - Contenedor escaneado
✓ Ikomstatus_id - ID del estado actual
✓ Ikomdate_scan - Fecha del último escaneo
✓ Ikomcomment - Comentarios adicionales
✓ Ikomconsolidate_number - Número de consolidación

total_packages - Cantidad total de paquetes en la factura

Ejemplo de Respuesta JSON:

{
  "error": null,
  "api_id": "DEMO123ABC456XYZ789",
  "data": [
    {
      "invoice": {
        "Ikominv_id": 44360,
        "Ikominvnumber": "LA-30360",
        "Ikominvdate": "2024-11-26",
        "Ikominvhours": "09:46:47",
        "Ikominvcontainer": "4124",
        "Ikominvamount": "90.00",
        "Ikomstatuspack": 21
      },
      "client": {
        "IkomClientId": 1247,
        "IkomClientFirst_Name": "Katherine",
        "IkomClientLast_Name": "Jimenez",
        "IkomClientEmail": "katherine@example.com",
        "Ikomnocasillero": "PACK2246"
      },
      "consignee": {
        "IkomShipFirstName": "Aurelia Margarita",
        "IkomShipLastName": "Lavandier",
        "IkomShipAddress": "Calle 8 Edificio I 8 Apto 3b",
        "IkomShipCity": "Santo Domingo",
        "Ikomdocument": "001-1616513-5"
      },
      "packages": [
        {
          "Ikompackage_id": 126942,
          "Ikombarcode": "DO-LA 30360-44360-91122-1",
          "Ikombarcode_mini": "DO-44360-91122-1",
          "Ikomcountry": "DO",
          "Ikomstatus_id": 2
        },
        {
          "Ikompackage_id": 127035,
          "Ikombarcode": "DO-LA 30360-44360-91194-1",
          "Ikombarcode_mini": "DO-44360-91194-1",
          "Ikomcountry": "DO",
          "Ikomstatus_id": 21
        }
      ],
      "total_packages": 2
    }
  ]
}

⚠️ Códigos de Error Específicos:

Error 204: Fecha no proporcionada - Incluye el parámetro date
Error 205: Formato de fecha inválido - Usa 8 dígitos en formato MMDDYYYY
Error 206: Fecha inválida - Verifica que la fecha sea válida (ej: 02302024 no existe)

✨ Casos de Uso Principales:

📊 Sincronización Diaria: Obtener todas las facturas del día para actualizar tu sistema
📝 Reportes Diarios: Generar reportes de operaciones por fecha específica
📦 Tracking Masivo: Rastrear todos los paquetes creados en una fecha
🔄 Reconciliación: Verificar facturas y paquetes entre sistemas
📨 Notificaciones: Enviar notificaciones automáticas a clientes del día

💻 Ejemplos de Implementación

<?php
// Configuración de la API
$apiKey = 'DEMO123ABC456XYZ789'; // Reemplaza con tu API Key
$apiUrl = 'https://ikomsoft.com/api/web_service.php';

// Parámetros para obtener clientes
$params = [
    'api_id' => $apiKey,
    'type' => 'clients'
];

// Construir URL con parámetros
$url = $apiUrl . '?' . http_build_query($params);

// Realizar petición
$response = file_get_contents($url);
$data = json_decode($response, true);

// Verificar respuesta y procesar datos
if ($data['error'] === null) {
    foreach ($data['data'] as $client) {
        echo "Cliente: " . $client['IkomClientFirst_Name'];
        echo " " . $client['IkomClientLast_Name'];
        echo " - Email: " . $client['IkomClientEmail'] . "\n";
        echo "Balance: $" . $client['IkomClientBalance'] . "\n\n";
    }
} else {
    echo "Error: " . $data['error'];
}
?>

// Configuración de la API
const apiKey = 'DEMO123ABC456XYZ789'; // Reemplaza con tu API Key
const apiUrl = 'https://ikomsoft.com/api/web_service.php';

// Función asíncrona para obtener clientes
async function getClients() {
    const params = new URLSearchParams({
        api_id: apiKey,
        type: 'clients'
    });
    
    try {
        const response = await fetch(`${apiUrl}?${params}`);
        const data = await response.json();
        
        if (data.error === null) {
            data.data.forEach(client => {
                console.log(`Cliente: ${client.IkomClientFirst_Name} ${client.IkomClientLast_Name}`);
                console.log(`Email: ${client.IkomClientEmail}`);
                console.log(`Balance: $${client.IkomClientBalance}`);
                console.log('---');
            });
        } else {
            console.error('Error:', data.error);
        }
    } catch (error) {
        console.error('Error en la petición:', error);
    }
}

// Ejecutar función
getClients();

import requests
import json

# Configuración de la API
api_key = 'DEMO123ABC456XYZ789'  # Reemplaza con tu API Key
api_url = 'https://ikomsoft.com/api/web_service.php'

# Parámetros de la petición
params = {
    'api_id': api_key,
    'type': 'clients'
}

# Realizar petición GET
response = requests.get(api_url, params=params)
data = response.json()

# Verificar respuesta y procesar datos
if data['error'] is None:
    for client in data['data']:
        print(f"Cliente: {client['IkomClientFirst_Name']} {client['IkomClientLast_Name']}")
        print(f"Email: {client['IkomClientEmail']}")
        print(f"Balance: ${client['IkomClientBalance']}")
        print('---')
else:
    print(f"Error: {data['error']}")

# Consultar todos los clientes
curl "https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=clients"

# Consultar cliente específico
curl "https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=clients&idclient=12345"

# Consultar facturas de un cliente
curl "https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=invoices&idclient=123"

# Consultar facturas por fecha
curl "https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=invoices_by_date&date=11262024"

# Rastrear paquete por número de factura
curl "https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=status&number=INV-2024-001"

# Obtener todos los consignatarios
curl "https://ikomsoft.com/api/web_service.php?api_id=DEMO123ABC456XYZ789&type=consigneer"

📤 Estructura de Respuestas

Respuesta Exitosa:

{
  "error": null,
  "api_id": "DEMO123ABC456XYZ789",
  "data": [
    {
      "IkomClientId": "123",
      "IkomClientFirst_Name": "Juan",
      "IkomClientLast_Name": "Pérez",
      "IkomClientEmail": "juan.perez@example.com",
      "IkomClientPhone": "+1 (809) 555-1234",
      "IkomClientBalance": 1500.00,
      "Ikomnocasillero": "CS-12345",
      "IkomClientCountry": "República Dominicana"
    }
  ]
}

Respuesta con Error:

{
  "error": "Error 201 <br> Wrong ID <br>Favor leer el manual de la API IKOMSOFT",
  "api_id": "INVALID_KEY_EXAMPLE",
  "data": []
}

⚠️ Códigos de Error

Código	Descripción	Solución
Error 200	API ID no proporcionado en la petición	Incluye el parámetro `api_id` con tu clave en la URL
Error 201	API ID inválido o incorrecto	Verifica que tu API Key sea correcta y esté activa en el sistema
Error 202	Endpoint no disponible actualmente	El tipo de consulta solicitado no está habilitado para tu cuenta
Error 203	Tipo de consulta inválido	Usa un valor válido para el parámetro `type`
Error 204	Fecha no proporcionada (invoices_by_date)	Incluye el parámetro `date` en formato MMDDYYYY
Error 205	Formato de fecha inválido	Usa exactamente 8 dígitos en formato MMDDYYYY
Error 206	Fecha inválida	Verifica que la fecha sea válida (ej: mes debe ser 01-12)
Error 500	Error interno del servidor	Contacta al equipo de soporte técnico de IKOMSOFT

✨ Mejores Prácticas y Recomendaciones

🔒 Seguridad:

Nunca expongas tu API Key en código frontend o repositorios públicos
Utiliza variables de entorno para almacenar tu API Key de forma segura
Implementa todas las peticiones desde tu servidor backend
Registra y monitorea el uso de la API para detectar anomalías
Rota tu API Key periódicamente si detectas accesos no autorizados

⚡ Rendimiento y Optimización:

Implementa caché local para datos que no cambian frecuentemente
Utiliza los parámetros de filtrado disponibles (ej: idclient, date) para reducir el volumen de datos
Evita hacer múltiples peticiones simultáneas para no sobrecargar el servidor
Configura timeouts apropiados (recomendado: 30 segundos)
Implementa reintentos automáticos con backoff exponencial en caso de fallo

📊 Manejo Correcto de Datos:

Siempre valida que error sea null antes de procesar los datos
Verifica que el array data no esté vacío antes de iterar
Maneja correctamente los tipos de datos esperados en cada campo
Implementa logging detallado para facilitar la depuración
Documenta las integraciones en tu código para facilitar el mantenimiento

📏 Limitaciones y Consideraciones Técnicas

Aspecto	Detalle
Método HTTP	Solo peticiones GET (consultas de lectura únicamente)
Formato de Respuesta	JSON exclusivamente con encoding UTF-8
Protocolo	HTTPS recomendado para mayor seguridad
Rate Limiting	Sin límite explícito - uso responsable recomendado
Registro de Operaciones	Todas las peticiones son registradas con IP, fecha, hora y parámetros
Timeout Recomendado	30 segundos para peticiones estándar
Tamaño Máximo de Respuesta	Sin límite definido - depende del volumen de datos solicitado

💬 Soporte Técnico y Contacto

🤝 ¿Necesitas ayuda con la API?

El equipo técnico de IKOMSOFT está disponible para ayudarte con cualquier duda, problema técnico o solicitud de nuevas funcionalidades en la API.

📧 Email: info@ikomsoft.com

🌐 Website: www.ikomsoft.com

📞 Horario de Atención: Lunes a Viernes, 9:00 AM - 6:00 PM (GMT-4)

⏱️ Tiempo de Respuesta: 24-48 horas laborables

📝 Para solicitar soporte, incluye:

Tu API Key (primeros y últimos 4 caracteres solamente)
Tipo de consulta que estás realizando
Mensaje de error completo (si aplica)
Código de ejemplo que estás usando
Fecha y hora aproximada del problema