Documentación de la API de Wardian

Catálogos globales (datos de referencia, públicos). Usa table=all para traerlos todos.

const res = await fetch("//wardian.com.co/dist/api/references/tables.php?table=unidades");
const data = await res.json();

{
  "success": true,
  "data": [
    { "id": 70, "code": "94", "name": "unidad" }
  ]
}

Lista los productos del usuario dueño de la API Key. Acepta paginación: ?pagina=1&search=texto.

{
  "success": true,
  "data": [
    { "id": 123, "code_reference": "SKU-001", "name": "Camiseta", "price": "50000.00", "tax_rate": "19.00" }
  ]
}

Crea un producto. Se envía como multipart/form-data (permite imágenes en files[]).

{
  "type": "Producto",
  "code_reference": "SKU-001",
  "name": "Camiseta",
  "price": "50000",
  "unit_measure_id": "70",
  "standard_code_id": "1",
  "tax_rate": "19",
  "categoria_id": "5"
}

{
  "status": "success",
  "message": "Producto registrado exitosamente",
  "data": { "producto_id": 123, "code_reference": "SKU-001", "name": "Camiseta" }
}

Edita un producto existente. Mismos campos que crear, más:

{ "id": "123", "name": "Camiseta Premium", "price": "60000" }

{ "status": "success", "message": "Producto actualizado exitosamente" }

Lista los terceros (clientes/proveedores) del usuario. Acepta ?pagina=1&search=texto.

{
  "success": true,
  "data": [
    { "id": 45, "identification": "901234567", "company_name": "ACME SAS", "email": "info@acme.co" }
  ]
}

Crea un tercero.

{
  "typeSelector": "Empresa",
  "identification_document_id": "31",
  "identification": "901234567",
  "email": "info@acme.co",
  "phone": "3001234567",
  "address": "Calle 1 # 2-3",
  "tribute_id": "21"
}

{
  "status": "success",
  "message": "Tercero creado exitosamente",
  "data": { "tercero_id": 45, "name": "ACME SAS", "identification": "901234567", "email": "info@acme.co", "phone": "3001234567" }
}

Edita un tercero. Mismos campos que crear, más:

{ "tercero_id": "45", "email": "nuevo@acme.co", "phone": "3009999999" }

{ "status": "success", "message": "Tercero actualizado exitosamente" }

Lista las categorías de productos del usuario.

{
  "success": true,
  "data": [
    { "id": 5, "nombre": "Ropa", "descripcion": "Prendas de vestir", "color": "#CFFF00", "activo": 1 }
  ]
}

Crea una categoría de productos.

{ "nombre": "Ropa", "descripcion": "Prendas de vestir", "color": "#CFFF00", "activo": "1" }

{
  "status": "success",
  "message": "Categoría creada exitosamente",
  "data": { "categoria_id": 5, "nombre": "Ropa", "descripcion": "Prendas de vestir", "color": "#CFFF00" }
}

Edita una categoría. Mismos campos que crear, más:

{ "categoria_id": "5", "nombre": "Ropa y Calzado" }

{ "status": "success", "message": "Categoría actualizada exitosamente" }

Genera una factura electrónica de venta estándar (multipart/form-data). Responde JSON con el resultado DIAN.

Cabecera

Ítems — products[]

Ejemplo

{
  "customer": "45",
  "numbering_range_id": "502",
  "payment_form": "1",
  "payment_due_date": "2026-07-02",
  "payment_method_code": "10",
  "observation": "Gracias por su compra",
  "products": [
    {
      "id": "123",
      "code_reference": "SKU-001",
      "name": "Camiseta",
      "quantity": "2",
      "price": "50000",
      "tax_rate": "19",
      "unit_measure_id": "70",
      "standard_code_id": "1",
      "tribute_id": "1",
      "discount_rate": "0",
      "is_excluded": "0"
    }
  ]
}

{
  "status": "success",
  "message": "Factura creada exitosamente",
  "data": {
    "invoice_id": 47014,
    "bill_number": "SETP990000227",
    "cufe": "7b4a382a9a751cc88156a47f2eac24c7987353d1...",
    "code_reference": "INV6a46c29683f15fdc6"
  }
}

Genera una factura electrónica de venta por mandato. Responde JSON con el resultado DIAN.

Cabecera

Mismos campos que la factura estándar (customer, numbering_range_id, payment_form, payment_method_code, observation, payment_due_date, company, moneda…). El operation_type se fija internamente en 11.

Ítems — products[]

Mismos campos que la factura estándar (id, code_reference, name, quantity, price, tax_rate, catálogos, retenciones…) más los datos del mandante por el que se factura ese ítem:

Ejemplo

{
  "customer": "45",
  "numbering_range_id": "502",
  "payment_form": "1",
  "payment_due_date": "2026-07-02",
  "payment_method_code": "10",
  "observation": "Facturación por mandato",
  "products": [
    {
      "id": "123",
      "code_reference": "SKU-001",
      "name": "Canon de arrendamiento",
      "quantity": "1",
      "price": "1000000",
      "tax_rate": "0",
      "unit_measure_id": "70",
      "standard_code_id": "1",
      "tribute_id": "1",
      "discount_rate": "0",
      "is_excluded": "0",
      "mandate_identification": "901234567",
      "mandate_identification_document_id": "31",
      "mandate_dv": "8"
    }
  ]
}

{
  "status": "success",
  "message": "Factura de mandato creada exitosamente",
  "data": {
    "invoice_id": 47021,
    "code_reference": "INV6a46c29683f15fdc6",
    "bill_number": "SETP990000228",
    "api_status": "Created",
    "cufe": "8c5b493b0b862dd99267b58a3fbd35d8098464e2...",
    "comprobante_id": 90312
  }
}

Genera un tiquete POS electrónico. Responde JSON con el resultado DIAN.

Cabecera

Ítems — products[]

Ejemplo

{
  "customer": "8",
  "payment_form": "1",
  "payment_method_code": "10",
  "observation": "Venta POS",
  "products": [
    {
      "id": "72707",
      "code_reference": "ENVIO-SHOPIFY",
      "name": "Envío - Estándar",
      "quantity": "1",
      "price": "4000",
      "tax_rate": "0",
      "discount_rate": "0",
      "unit_measure_id": "70",
      "standard_code_id": "1",
      "tribute_id": "22",
      "is_excluded": "0",
      "requiere_stock": "0"
    }
  ]
}

{
  "status": "success",
  "message": "Factura POS creada exitosamente",
  "data": {
    "invoice_id": 47016,
    "bill_number": "EPOS71",
    "cufe": "20764680cd9bd7b8d62c72442e012887c912cfc8...",
    "api_status": "Created",
    "dian_response": { "bill": { "number": "EPOS71", "cufe": "2076...", "total": 4000, "id": "347619492" } }
  }
}

Genera una factura electrónica RIPS. Responde JSON con el resultado DIAN.

Cabecera

Ejemplo

{
  "rips_id": "30",
  "invoice_type": "rips",
  "customer": "8",
  "numbering_range_id": "100",
  "payment_form": "1",
  "payment_method_code": "10",
  "payment_due_date": "2026-07-02",
  "company": "NEXO CONTABLE",
  "observation": "Servicios de salud - paquete RIPS"
}

{
  "status": "success",
  "message": "Factura creada exitosamente",
  "data": {
    "invoice_id": 47021,
    "code_reference": "INV6a46da95177b095bb",
    "bill_number": "SETP990000231",
    "api_status": "Created",
    "cufe": "ad3a694a73e1a211f585d259c329c160031dbe2f...",
    "dian_response": { "bill": { "number": "SETP990000231", "total": 7350000 } }
  }
}

Cuerpo

{
  "usuario_id_rips": 29,
  "payload": {
    "numDocumentoIdObligado": "900123456",
    "numNota": "00001234",
    "tipoNota": "RS",
    "usuarios": [ { "...": "ver Estructura del payload" } ]
  }
}

{
  "status": "ok",
  "cuv": "a1b2c3...",
  "paquete_id": 30,
  "usuario_id_rips": 29,
  "usuario_id_envio": 29
}

Solo devuelve paquetes con cuv no vacío.

{
  "status": "success",
  "data": {
    "rips_id": 30,
    "rips_cuv": "a1b2c3...",
    "rips_cufe": null,
    "numbering_range_id": 100,
    "invoice_type": "rips",
    "health_data": { "provider_code": "...", "patient": { "...": "" } },
    "items": [ { "code_references": "890201", "name": "Consulta", "price": 50000 } ]
  },
  "suggested_customer": { "id": 8, "name": "EPS ..." }
}

Cuerpo

{ "rips_id": 30, "cufe": "ad3a694a73e1..." }

{
  "status": "success",
  "message": "RIPS regenerado correctamente con CUV real",
  "cuv": "a1b2c3...",
  "estado": "validado",
  "is_simulated": false
}

Acepta multipart/form-data (archivo) o JSON (base64). La API Key determina el usuario: solo puedes adjuntar sobre tus facturas.

Campos

* Envía uno de los dos. El XML debe ser de factura (raíz Invoice o AttachedDocument); si trae CUFE (cbc:UUID) debe coincidir con el de la factura — así no se puede adjuntar el XML de otra.

Ejemplo real

XML de ejemplo por tipo de factura — todos son documentos reales tal como se enviaron a la DIAN:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" …>
    <cbc:ID>FEPI13</cbc:ID>
    <cbc:UUID schemeID="1" schemeName="CUFE-SHA384">4fa0ee0c14522b25d3218f3ce42605c8d31ebc157a5e5f2c…</cbc:UUID>
    <cbc:IssueDate>2026-08-31</cbc:IssueDate>
    …

{
  "bill_number": "FEPI13",
  "xml_base64": "PEludm9pY2UgeG1sbnM9InVybjpvYXNpczpuYW1lczpzcGVjaWZpY2F0aW9uOnVibDpzY2hl…"
}

{
  "success": true,
  "message": "XML adjuntado a la factura FEPI13.",
  "data": {
    "factura_id": 663033,
    "bill_number": "FEPI13",
    "cufe": "4fa0ee0c14522b25d3218f3ce42605c8d31ebc157a5e5f2cb7688a7f778d0e4631b2fbd3a428d7457e7f2f2b0f598501",
    "bytes": 19740,
    "adjuntado_en": "2026-08-31 16:10:00"
  }
}

Errores

Genera un documento soporte electrónico. Acepta application/x-www-form-urlencoded o multipart/form-data. Responde JSON con el resultado DIAN. El documento soporte no lleva IVA (compra a no obligado).

Cabecera

Ítems — products[]

Ejemplo

{
  "customer": "48",
  "numbering_range_id": "100",
  "payment_form": "1",
  "payment_method_code": "47",
  "issue_date": "2026-07-14",
  "observation": "Compra a proveedor no obligado",
  "products": [
    {
      "code_reference": "SERV-01",
      "name": "Servicio de mantenimiento",
      "quantity": "1",
      "price": "500000",
      "discount_rate": "0",
      "unit_measure_id": "70",
      "standard_code_id": "1",
      "ret_fuente_rate": "4"
    }
  ]
}

{
  "status": "success",
  "success": true,
  "data": {
    "document_id": 618,
    "code_reference": "INV6a46c29683f15fdc6",
    "number": "DS-1",
    "cuds": "a1b2c3d4e5f6...",
    "api_status": "Created"
  }
}

{
  "status": "success",
  "success": true,
  "message": "Borrador guardado",
  "data": { "document_id": 618, "estado": "Borrador" }
}

Cuerpo

{
  "entorno": "qa",
  "base_url": "https://<la-que-emitio-minsalud>",
  "tenant_id": "00000000-0000-0000-0000-000000000000",
  "client_id": "<client-id>",
  "client_secret": "<client-secret>",
  "subscription_key": "<ocp-apim-subscription-key>",
  "scope": "api://rda/.default",
  "auto_enviar": 0
}

{
  "evento_id": 4242,
  "entorno": "qa",
  "valido": true,
  "errores": [],
  "bundle": {
    "resourceType": "Bundle",
    "type": "document",
    "identifier": { "value": "…uuid…" },
    "entry": [
      { "resource": { "resourceType": "Composition", "id": "Composition-0" } },
      { "resource": { "resourceType": "Patient", "id": "CC-1000200300" } },
      { "resource": { "resourceType": "Practitioner", "id": "CC-79123456" } },
      { "resource": { "resourceType": "Organization", "id": "230010255201" } },
      { "resource": { "resourceType": "Location", "id": "230010255201-01" } },
      { "resource": { "resourceType": "Encounter", "id": "Encounter-0" } },
      { "resource": { "resourceType": "DocumentReference", "id": "DocumentReference-0" } },
      { "resource": { "resourceType": "Condition", "id": "Condition-0" } }
    ]
  }
}

Cuerpo

{
  "estado": "aceptado",
  "paquete_id": 17,
  "http_code": 200,
  "rda_id": "RDA-000123",
  "mensaje": "RDA aceptado por IHCE.",
  "errores": []
}

Estados y códigos

Devuelve los paquetes del tenant, el conteo por estado y un bloque aptitud con lo que falta para que los envíos pasen la validación de registros de MinSalud (EVOL, RETHUS, REPS, DIVIPOLA).

{
  "paquetes": [
    { "id": 17, "estado": "aceptado", "entorno": "qa", "rda_id": "RDA-000123",
      "fecha_evento": "2026-07-20", "diagnostico_codigo": "J00", "intentos": 1 }
  ],
  "por_estado": { "aceptado": 12, "rechazado": 1 },
  "aptitud": {
    "pacientes_total": 340,
    "pacientes_sin_fecha_nac": 0,
    "pacientes_sin_sexo_biologico": 12,
    "profesionales": 3,
    "ips_con_habilitacion": 1,
    "eventos_completados": 512,
    "eventos_sin_diagnostico": 4,
    "credenciales": { "qa": "lista", "preproduccion": "sin configurar", "produccion": "sin configurar" }
  }
}

Lista paginada de colaboradores.

Ficha completa de un colaborador.

Crea un colaborador y, opcionalmente, su contrato laboral.

Mismos campos que crear, más id y los de retención en la fuente: retefuente_dependientes, retefuente_dependientes_pct, retefuente_vivienda, retefuente_medicina_prepagada, retefuente_afc, retefuente_aporte_vol_pension.

Crea el contrato mínimo para un colaborador que no tiene ninguno. Es el prerrequisito del motor de nómina.

Activa o desactiva un colaborador. Campos: collaborator_id req, activo req.

multipart/form-data. Campos: collaborator_id req, fichero en foto req.

Histórico salarial. Campos: collaborator_id req, fecha_referencia y page opc.

Saldo de vacaciones. Campos: collaborator_id req, fecha_referencia opc.

Devuelve el salario mínimo, el auxilio de transporte y la UVT del año.

Escribe las cifras legales del año. Acepta cuerpo JSON nativo.

{
  "anio": 2026,
  "smmlv": 1623500,
  "auxilio": 200000,
  "uvt": 49799,
  "decreto_smmlv": "Decreto 2613 de 2025",
  "decreto_auxilio": "Decreto 2614 de 2025",
  "es_transitorio": 0,
  "observaciones": ""
}

Lista las nóminas. Filtros opcionales: year y collaborator_id.

{
  "status": "success",
  "data": [
    {
      "id": "512", "periodo": "1", "mes": "8", "anio": "2026",
      "estado": "Borrador", "creado_en": "2026-08-30 11:02:41",
      "total_colaboradores": "13", "total_neto": "31450000.00",
      "periodo_texto": "Ago 2026", "periodo_tipo": "Mensual"
    }
  ],
  "count": 1
}

Calcula la nómina de un colaborador. No guarda nada.

{
  "status": "success",
  "data": {
    "collaborator_id": 48,
    "nombre_completo": "ANDRÉS FELIPE GÓMEZ RUIZ",
    "salario_base": 2500000, "auxilio_transporte": 200000, "aplica_auxilio": true,
    "dias_trabajados": 30, "dias_base": 30, "dias_periodo": 30,
    "periodo_pago": "Mensual",
    "salario_proporcional": 2500000, "auxilio_proporcional": 200000,
    "base_seguridad_social": 2500000,
    "salud_empleado": 100000, "pension_empleado": 100000, "fsp": 0,
    "prestamos_descontados": 150000,
    "detalle_prestamos": [
      { "id": "31", "tipo": "prestamo_empresa", "valor_descontado": 150000 }
    ],
    "total_devengado": 2700000, "total_deducido": 350000, "neto_a_pagar": 2350000,
    "smmlv": 1623500, "periodo_year": 2026, "periodo_month": 8
  }
}

La misma calculadora para varios colaboradores. Es el paso previo a guardar.

{
  "status": "success",
  "data": [ /* un objeto por colaborador, idéntico al de calculate.php */ ],
  "errors": [ { "collaborator_id": 99, "message": "Colaborador no encontrado (ID: 99)" } ],
  "count": 12
}

Guarda la nómina. Acepta cuerpo JSON nativo. La cabecera nace en estado Borrador y las filas en Liquidada.

{
  "periodo_year": 2026,
  "periodo_month": 8,
  "periodo": 1,
  "observaciones": "Nómina de agosto",
  "detalles": [
    {
      "collaborator_id": 48,
      "salario_base": 2500000,
      "auxilio_transporte": 200000,
      "dias_trabajados": 30,
      "salud_empleado": 100000,
      "pension_empleado": 100000,
      "fsp": 0,
      "prestamos_descontados": 150000,
      "detalle_prestamos": [ { "id": 31, "valor_descontado": 150000 } ],
      "otras_deducciones": 0,
      "neto_a_pagar": 2350000
    }
  ]
}

{ "status": "success", "message": "Nómina guardada exitosamente", "data": { "nomina_id": 512 } }

Liquida con valores por defecto los colaboradores que quedaron pendientes en la nómina. Único campo: nomina_id req.

{ "status": "success", "message": "13 colaborador(es) liquidado(s) con datos por defecto.",
  "liquidados": 13, "errores": [] }

{ "status": "success", "message": "Todos los colaboradores ya están liquidados", "liquidados": 0 }

{ "status": "partial",
  "message": "11 colaborador(es) liquidado(s), pero 2 quedaron sin liquidar y NO se pueden enviar a la DIAN así.",
  "liquidados": 11, "errores": ["Colaborador #99: Colaborador no encontrado (ID: 99)"] }

Genera o regenera los asientos contables de la nómina. Campo: nomina_id req.

Radica el documento de nómina electrónica de un colaborador ante la DIAN.

Nota de ajuste, anulación o regeneración contable de una nómina ya radicada.

Envía la nota de ajuste a la DIAN. Campos: nomina_id, collaborator_id, cune_referencia.

Simulacro: dice qué se deshará y qué no. No modifica nada.

{
  "status": "success",
  "nomina": { "id": 512, "periodo": "2026-08 (periodo 1)", "estado": "Enviada",
              "colaboradores": 13, "total": 31450000 },
  "se_deshace": [
    { "concepto": "Devolución a caja/banco", "detalle": "Bancolombia Cta. Corriente", "valor": 31450000 },
    { "concepto": "Saldos de préstamos restaurados", "detalle": "3 pago(s)", "valor": 450000 },
    { "concepto": "Comprobantes contables eliminados", "detalle": "3 comprobante(s)", "valor": null }
  ],
  "no_se_deshace": [
    "5 comprobante(s) siguen vigentes en la DIAN. Debe enviar la Nota de Ajuste antes de poder eliminar.",
    "Ya se enviaron los desprendibles por correo a los colaboradores. Esos correos no se pueden retirar."
  ],
  "bloqueado": true
}

Elimina la nómina revirtiendo todos sus efectos. Irreversible.

{
  "status": "success",
  "message": "Nómina NE-512 eliminada correctamente",
  "revertido": {
    "caja_devuelto": 31450000, "prestamos_restaurados": 3, "prestamos_valor": 450000,
    "comprobantes_anulados": 3, "pagos_programados_borrados": 1, "prestaciones_ajustadas": 13
  },
  "avisos": ["El préstamo #31 lo creó esta nómina pero ya tiene pagos de otras; se conserva."]
}

{ "status": "error", "code": "dian_pendiente",
  "message": "No se puede eliminar: 5 comprobante(s) siguen vigentes en la DIAN...",
  "dian": { "enviados": 13, "ajustados": 8, "pendientes": 5 } }

{ "status": "error", "code": "motivo_requerido",
  "message": "El motivo es demasiado corto; explique brevemente por qué se elimina." }

{ "status": "error", "code": "reversion_imposible",
  "message": "No se puede determinar de qué cuenta salió el dinero..." }

{ "status": "pila_confirm",
  "message": "Esta nómina tiene una planilla PILA en estado PAGADA.",
  "pila": { "planilla_id": "88", "estado": "pagada", "sent_to_suaporte": true } }

Crea una nómina completa desde un Excel. Requiere multipart/form-data — este endpoint no acepta JSON.

La fila 1 son los encabezados. Escríbelos sin tildes: se ignoran mayúsculas, espacios y asteriscos, pero no se normalizan los acentos.

{
  "status": "success",
  "message": "11 colaborador(es) importados en nómina #513",
  "data": { "nomina_id": 513, "processed": 11, "skipped": 2, "total_neto": 27340000 },
  "warnings": ["Fila 5: Identificación '9998887' no encontrada"]
}

Pagos a personal temporal, al margen de la nómina electrónica (sin DIAN ni PILA). Un solo endpoint con cuatro operaciones según action. Acepta JSON.

collaborator_id, dias_trabajados, salario_base, bonificaciones, deducciones, notas.

{
  "action": "create",
  "periodo": "Mensual",
  "mes": 8, "anio": 2026,
  "observaciones": "Refuerzo temporada",
  "empleados": [
    { "collaborator_id": 77, "dias_trabajados": 12, "salario_base": 2000000,
      "bonificaciones": 0, "deducciones": 0, "notas": "" }
  ]
}

Lista los pagos temporales. Campos: pagina, search (busca por id u observaciones, no por nombre). Página fija de 10. Estados: Pendiente y Pagado.

Envía un enlace de aprobación de la nómina por correo o WhatsApp.

Lista las liquidaciones. Campos: collaborator_id, estado, year, page. Página fija de 20.

Detalle completo de una liquidación.

Calcula la liquidación de un colaborador. No guarda nada. Su respuesta es exactamente lo que espera create.php.

Cálculo masivo. Campo collaborator_ids req (array real). No acepta nominas_vinculadas.

Guarda la liquidación en estado Borrador. Reenvía aquí la salida de calculate.php.

Aprueba la liquidación: termina el contrato, consolida préstamos, compensa dotación y contabiliza.

Simulacro de eliminación, igual que el de nómina: se_deshace[], no_se_deshace[] y bloqueado. No modifica nada.

Elimina revirtiendo todos los efectos. Campos: id req, motivo req (mínimo 10 caracteres). Requiere permiso de eliminación.

Anula sin borrar: revierte todo pero conserva el registro en estado Anulada. Campos: id req, motivo opc. Requiere permiso de eliminación.

Saldo causado, pagado y pendiente por concepto. Campos: collaborator_id opc, year opc.

Previsualiza el pago de una prestación.

{
  "status": "success",
  "data": {
    "concepto": "cesantias", "concepto_label": "Cesantías",
    "dias": 120, "base_calculo": 2749095, "valor": 916365,
    "formula": "(2749095 × 120) / 360",
    "base_detalle": [
      { "concepto": "Salario mensual", "valor": 2500000 },
      { "concepto": "Auxilio de transporte", "valor": 249095 }
    ],
    "fecha_corte": "2026-04-30", "dias_base": 360,
    "ya_pagado": 0, "plazo_pago_legal": "2027-02-14",
    "norma": "Art. 249 CST y Ley 50 de 1990: se consignan al fondo a más tardar el 14 de febrero.",
    "avisos": []
  }
}

Lo mismo para toda la plantilla. Campos: concepto req, periodo_year req, fecha_corte opc. Devuelve elegibles[] y omitidos[] con su motivo. Puede tardar: cuenta ~1 segundo por colaborador.

Registra el pago. Campos: collaborator_id req, concepto req, periodo_year req, fecha_pago req, fecha_corte, fondo_cesantias, observaciones opc.

Registra el pago para toda la plantilla, en una sola transacción.

Histórico de pagos. Campos: collaborator_id, concepto, year, page. Página fija de 20.

Borra un pago registrado. Campo: id req.

Recalcula las provisiones de un año. Campo: year opc.

Calcula el plan de cuotas sin guardar nada.

{
  "status": "success",
  "data": {
    "numero_cuotas": 6, "cuota": 200000, "ultima_cuota": 200000,
    "total_plan": 1200000, "fecha_fin_estimada": "2026-07-15", "periodo_pago": "mensual",
    "cuotas": [
      { "numero_cuota": 1, "fecha_vencimiento": "2026-02-15",
        "valor": 200000, "valor_abonado": 0, "estado": "Pendiente" }
    ]
  }
}

Registra un préstamo, libranza o embargo.

Registra un abono. Campos: prestamo_id req, valor req (no puede exceder el saldo), fecha_pago, observaciones, nomina_id opc.

Lista préstamos. Campos: collaborator_id, tipo, estado, page. Trae alerta_pago (proximo/vencido) y dias_para_pago con signo.

Abonos de un préstamo. En los descontados por liquidación, periodo, mes y anio vienen vacíos.

Elimina el préstamo y sus abonos. Campo: id req.

{
  "status": "error", "code": "prestamo_referenciado",
  "message": "No se puede eliminar el préstamo: tiene abonos ligados a liquidación #42 (Aprobada)...",
  "bloqueos": ["liquidación #42 (Aprobada), 300.000 descontados", "2 abono(s) descontados en nómina"]
}

Programa las entregas del año. Campos: year opc, collaborator_id opc.

Entregas del año. Campos: collaborator_id, year (siempre se aplica: por defecto el año actual), estado. Incluye un resumen por estado.

Entregas pendientes de todos los años, con total_compensacion. Es lo que se envía como dotacion_pendiente a la liquidación.

Ítems de una entrega o de una plantilla. Campos: entrega_id, plantilla_id opc.

Marca la entrega como realizada. Campos: id req (debe estar Pendiente), fecha_entrega, descripcion, observaciones, checklist (cadena JSON), pago_opcion, cuenta_bancaria_id, fecha_pago.

Sub-campos de checklist[]: item_nombre req, categoria, cantidad, talla, entregado, observaciones.

Envía el acta al colaborador para firma digital. Campos: id req, email opc.

Elimina una entrega. Campo: id req.

Campo: solo_activas=1 opc. Aquí la clave del ítem es nombre (en checklist_get el mismo dato se llama item_nombre).

Crea o actualiza. Campos: id (0 = crear), nombre req, descripcion, activa, items (cadena JSON: nombre, categoria, requiere_talla, cantidad_default).

Campo: id req.

Registra una incapacidad y la sincroniza con la nómina abierta del periodo.

{
  "status": "success",
  "message": "Incapacidad registrada correctamente y sincronizada con nómina del período",
  "data": { "id": "12", "dias": 5, "synced_nomina_id": "88" }
}

Lista las incapacidades del colaborador.

Actualización parcial: solo se escriben los campos presentes. Campo id req.

Campo: id req.

Crea un memorando y envía el enlace de firma al colaborador.

Lista los memorandos.

Campo: id req.

Plantilla de la carta. Campo tipo opc. El campo source indica si es propia (custom) o la interna (default). Marcadores disponibles: {{nombre_empresa}}, {{nit_empresa}}, {{nombre_colaborador}}, {{identificacion}}, {{cargo}}, {{tipo}}, {{asunto}}, {{descripcion}}, {{fecha}}.

Campos: contenido_template req, template_id, nombre, tipo_memorando opc.

multipart/form-data. Campos: collaborator_id req, tipo_documento req (cedula, eps, arl, pension, ccf, examen_medico, otro), fichero en archivo req, más observaciones y fecha_documento opc.

Máximo 10 MB. Formatos: PDF, JPEG, PNG, WebP y Word.

Lista los documentos. No enlaces a ruta_archivo directamente: usa download.php.

Descarga el fichero.

Campo: id req. Irreversible.

Genera el archivo plano (Resolución 2388 de 2016).

{
  "status": "error",
  "message": "Hay 2 colaborador(es) sin códigos de SS completos. Sincronice BDUA para EPS/AFP.",
  "data": { "incomplete": [
    { "id": 90, "nombre": "Juan Diaz", "identification": "79123456",
      "missing": ["EPS", "AFP"], "bdua_last_sync": null }
  ]}
}

Genera la planilla a partir de una nómina. Campos: nomina_id req, tipo_planilla opc.

Planilla de retiro. Campo: liquidacion_id req (debe estar Aprobada). Los días se topan en 30 por norma (Decreto 1990 de 2016).

Valida el archivo contra SuAporte. Campo: planilla_id req. Devuelve codigo_planilla, numero_planilla, contadores e inconsistencias[].

Corrección automática. Campo: planilla_id req.

Inconsistencias paginadas. Campos: planilla_id req, page, limit (máx. 500).

Totales de la planilla según el operador. Requiere el número. Esta consulta guarda los totales, así que también escribe.

Marca la planilla como asistida y obtiene el PIN. Campos: planilla_id req, causal opc.

Paga la planilla. Campo: planilla_id req (debe tener PIN).

URL de pago por PSE. También guarda la URL obtenida.

Consulta el estado del pago.

Reversa el pago. Campo: planilla_id req (estado exactamente pagada).

Lista planillas. Campos: periodo_year, periodo_month, estado, page, limit (máx. 100).

Cabecera y detalle por colaborador, con IBC y cotizaciones.

Descarga el archivo plano. No devuelve JSON: transmite el fichero de texto.

Nóminas consolidables del periodo. Campos: periodo_year, periodo_month. Incluye is_complete_month.

Estado de sincronización. Campos: module req (nomina, prestaciones o liquidacion), más nomina_id, liquidacion_id, year, month según el módulo.

Solo multipart/form-data — este endpoint no acepta JSON ni con API Key. Fichero Excel en archivo req. Devuelve un id_archivo que hay que consultar después.

Estado del proceso masivo.

Consulta la afiliación de un colaborador y actualiza su EPS y AFP. Campo: collaborator_id req.

Consulta por documento, sin tocar ninguna ficha. Campos: tipo_documento req, numero_documento req.

Sincroniza toda la plantilla. Sin parámetros.

Consulta si toca sincronizar (GET) o la ejecuta (POST con force opcional).

Configuración de SuAporte, con el PIN enmascarado.

Campos: tipo_documento req, numero_documento req, pin y clave_secreta (obligatorios la primera vez; en blanco conservan el valor), aportante_tipo, codigo_arl, codigo_ccf, bdua_auto_sync_days opc.

Prueba la conexión. Sin parámetros. El campo authorized devuelve siempre false y no debe interpretarse.

GET lista el catálogo (filtro tipo: EPS, AFP, ARL, CCF, CES). POST admite action: add, edit o toggle.

Datos de la empresa como aportante en SuAporte. aportante_create.php y aportante_update.php los crean y actualizan (campo tipo_aportante: pyme por defecto, independiente o corporate).

Registra entrada, salida o descanso. Tiene dos formas de autenticarse, y cada una pide cosas distintas.

Genera el código QR de marcación. Sin collaborator_id devuelve el de empresa (el que se proyecta en la entrada, sirve para toda la plantilla); con él, uno personal.

{
  "status": "success",
  "data": {
    "token": "eyJ1aWQiOjcsInRzIjoxNzg3NTA0OTMxLCJub25jZSI6...",
    "url": "https://wardian.com.co/dist/roster/asistencia_qr.php?token=...",
    "scope": "empresa", "expires_in": 480, "refresh_in": 40
  }
}

Código fijo para el cartel impreso. GET lo consulta; POST con accion=rotar lo cambia — y eso invalida todos los carteles ya impresos. Rotar exige ser administrador.

Marcaciones del periodo. Campos: collaborator_id, fecha_desde, fecha_hasta opc (por defecto, el mes en curso). Incluye descansos[], horas_brutas y horas_trabajadas (ya con descansos descontados).

Resumen por colaborador: dias_marcados, total_horas, dias_sin_salida.

Corrige una marcación. Campos: id req, motivo req, pin si aplica, más hora_entrada, hora_salida y observaciones opc. Es actualización parcial: lo que omitas se conserva.

Elimina una marcación y sus descansos. Campos: id req, motivo req, pin si aplica.

Configura la clave de marcación manual. Campos: pin req (4–20 caracteres; vacío la desactiva), pin_actual req si ya existe una — también para desactivarla. Solo administradores.

Calcula horas extra y recargos comparando las marcaciones con el horario. Solo propone, no escribe. Campos: fecha_desde req, fecha_hasta req, collaborator_id opc.

{
  "status": "success",
  "data": [
    { "collaborator_id": 88, "nombre": "Ana Perez",
      "novedades": [
        { "fecha": "2026-08-14", "tipo": "HORA EXTRA DIURNA",
          "factor": 25, "horas": 1.5, "valor": 18750, "es_recargo": false }
      ],
      "resumen": { "dias_trabajados": 21, "horas_extra": 6.5 },
      "origen_horario": "asignado" }
  ],
  "sin_horario": [ { "collaborator_id": 91, "nombre": "Luis Gomez" } ],
  "horario_inferido": [ { "collaborator_id": 90, "nombre": "Juan Diaz" } ]
}

Aplica esas novedades a la nómina. Campos: nomina_id req, novedades req (cadena JSON: el data[] de calculate_extras).

Sugiere los días a pagar según las ausencias reales. Campos: nomina_id req, collaborator_id req. Solo lectura.

Un endpoint con varias operaciones según action: list, create, update, delete, toggle.

{
  "action": "create",
  "nombre": "Sede Norte",
  "poligono": [[4.7010,-74.0460],[4.7015,-74.0440],[4.6995,-74.0445]],
  "collaborator_ids": [88, 90, 91]
}

Envía el enlace de marcación por correo o WhatsApp. action: destinatarios (simulacro), enviar, marcar_enviado.

Campos: ids req en enviar (cadena JSON, máximo 25 por llamada), canales (email y/o whatsapp), momento, alcance, collaborator_id.

Configura el envío automático. Campos: envio_auto, envio_canal_email, envio_canal_whatsapp, envio_salida, envio_anticipacion_min (5 a 50 minutos). Solo administradores. No tiene consulta GET.

Enrola el patrón facial. Campos: collaborator_id req, descriptor req (cadena JSON con al menos 64 números), source_photo opc. Uno por colaborador: volver a enrolar sobrescribe.

Estado de enrolamiento facial y foto por colaborador. Sin parámetros.

Horarios con su detalle diario y descansos. Campo solo_activos=1 opc. Los días van de 1 (lunes) a 7 (domingo).

Crea o actualiza un horario. Campos: id (0 = crear), nombre req, descripcion, detalle (cadena JSON).

Sub-campos de detalle[]: dia_semana req, hora_entrada, hora_salida, es_descanso, almuerzo_inicio, almuerzo_fin, descansos[] (con inicio, fin, nombre).

Campo: id req. Se bloquea si el horario está asignado a contratos vigentes.

Solicitudes del portal. Campos: type req (vacation, incapacidad, permission), status opc (Pendiente por defecto, Aprobada, Rechazada, Cancelada, all).

Campos: request_type req y request_id req. Ojo: aquí el parámetro se llama request_type, mientras que en list.php es type.

Aprueba la solicitud y la sincroniza con la nómina abierta. Campos: request_type req, request_id req, observaciones opc.

Campos: request_type req, request_id req, observaciones req (obligatorias al rechazar). No tiene ningún efecto sobre la nómina.

Envía el acceso al portal del empleado. Campos: collaborator_id req (o la palabra __all__), method opc (email por defecto, whatsapp).