Documentación de la API de Wardian

Integra facturación electrónica, inventarios y más. Todas las peticiones se autentican con una API Key.

Base URL: //demo.wardian.com.co/dist/api/
Formato: JSON
Autenticación: header X-API-Key

Autenticación

Envía tu API Key en el header X-API-Key en cada petición. Si falta o es inválida, la API responde 401 Unauthorized.

X-API-Key: wrd_tu_api_key_aqui

1 Generar tu API Key

En tu panel, ve a Software → Documentación → API Keys y presiona Generar API Key. Cópiala y guárdala; solo se muestra completa al crearla.

Ir a generar mi API Key

2 Primer request

Toda petición lleva el header X-API-Key. Para POST, envía el cuerpo en JSON con Content-Type: application/json. Las respuestas son JSON.

GET (listar)

const res = await fetch("//demo.wardian.com.co/dist/api/products/data_list.php", {
  headers: { "X-API-Key": "wrd_tu_api_key_aqui" }
});
const data = await res.json();

POST (crear)

const res = await fetch("//demo.wardian.com.co/dist/api/third/create.php", {
  method: "POST",
  headers: {
    "X-API-Key": "wrd_tu_api_key_aqui",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ /* campos del endpoint */ })
});
const data = await res.json();

Códigos de error

Código	Significado
`200`	OK
`400`	Petición inválida (faltan datos)
`401`	API Key inválida o ausente
`404`	Recurso no encontrado
`500`	Error interno

Relaciones (catálogos)

Varios campos de productos, terceros y de la factura estándar no son valores libres: referencian catálogos (IDs de la DIAN / DANE). Obtén los valores válidos antes de crear.

GET//demo.wardian.com.co/dist/api/references/tables.php?table={catalogo}

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

Campo que lo usa	table=	Descripción
`unit_measure_id`	`unidades`	Unidades de medida DIAN
`standard_code_id`	`codigos_estandar`	Códigos estándar de adopción
`tribute_id`	`tributos`	Tributos (IVA, INC, etc.)
`identification_document_id`	`documentos_identidad`	Tipos de documento (CC, NIT…)
`municipalities_code`	`municipios`	Municipios (DANE)
`country_code`	`paises`	Países
—	`responsabilidades_iva`, `regimen_iva`, `autorretenciones`, `bancos`	Otros catálogos disponibles

GET (público, sin API Key)

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

Response

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

Catálogos con endpoint propio (requieren `X-API-Key`)

Campo	Endpoint	Notas
`categoria_id`	`api/settings/categories/list.php`	Categorías del usuario
`numbering_range_id`	`api/numbering_ranges/list.php`	Resoluciones / rangos de numeración
`payment_method_code`	`api/pos/list_payment_methods.php`	Métodos de pago DIAN
`tax_rate`	—	Valor directo: `0`, `5`, `8`, `19`

La factura estándar (api/invoice/generate.php) usa estas mismas relaciones en su customer (identification_document_id, tribute_id, municipalities_code) y en cada ítem (unit_measure_id, standard_code_id, tax_rate), más numbering_range_id y payment_method_code.

Productos

Campos como unit_measure_id, standard_code_id, tax_rate, categoria_id y tribute_id referencian catálogos. Consulta Relaciones / Catálogos para obtener los valores válidos. Son las mismas relaciones que usa la factura estándar.

GET//demo.wardian.com.co/dist/api/products/data_list.php

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

Response

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

POST//demo.wardian.com.co/dist/api/products/create.php

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

Campo		Descripción
`type`	req	Tipo de producto
`code_reference`	req	Código / referencia único
`name`	req	Nombre del producto
`price`	req	Precio de venta
`unit_measure_id`	req	Unidad de medida (id DIAN)
`standard_code_id`	req	Código estándar (id)
`tax_rate`, `cost_price`, `wholesale_price`	opc	Impuesto, costo, precio mayorista
`categoria_id`, `details`, `requiere_stock`, `stock`	opc	Categoría, detalles, control de stock
`contenido_presentacion`, `lote`, `fecha_vencimiento`, `cums_codigo`	opc	Presentación, lote, vencimiento, CUMS
`files[]`	opc	Imágenes del producto

Request (JSON)

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

Response

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

Para adjuntar imágenes usa multipart/form-data (campo files[]) en vez de JSON.

POST//demo.wardian.com.co/dist/api/products/edit.php

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

Campo		Descripción
`id`	req	ID del producto a editar

Request (JSON)

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

Response

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

Terceros

GET//demo.wardian.com.co/dist/api/third/data_list.php

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

Response

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

POST//demo.wardian.com.co/dist/api/third/create.php

Crea un tercero.

Campo		Descripción
`typeSelector`	req	Tipo (Persona / Empresa)
`identification_document_id`	req	Tipo de documento (id DIAN)
`identification`	req	Número de identificación
`address`, `email`, `phone`	req	Dirección, correo, teléfono
`tribute_id`	req	Responsabilidad tributaria (id)
`dv`, `company_name`, `name`, `last_name`, `trade_name`	opc	DV, razón social, nombres, nombre comercial
`ciiu`, `country_code`, `municipalities_code`	opc	CIIU, país, municipio (DANE)

Request (JSON)

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

Response

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

POST//demo.wardian.com.co/dist/api/third/edit.php

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

Campo		Descripción
`tercero_id`	req	ID del tercero a editar

Request (JSON)

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

Response

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

Categorías

GET//demo.wardian.com.co/dist/api/settings/categories/list.php

Lista las categorías de productos del usuario.

Response

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

POST//demo.wardian.com.co/dist/api/settings/categories/create.php

Crea una categoría de productos.

Campo		Descripción
`nombre`	req	Nombre de la categoría
`descripcion`, `color`, `icono`, `activo`	opc	Descripción, color, ícono, estado
`configuracion_puc_activa`, `cuenta_ingreso_venta`, `cuenta_costo_venta`, `cuenta_inventario`, `cuenta_compra`…	opc	Cuentas contables PUC (si se activa la config)

Request (JSON)

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

Response

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

POST//demo.wardian.com.co/dist/api/settings/categories/edit.php

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

Campo		Descripción
`categoria_id`	req	ID de la categoría a editar

Request (JSON)

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

Response

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

Crear factura estándar

Antes de facturar: crea/ten el tercero (obtienes su id) y los productos, y ten a mano el numbering_range_id (ver Catálogos). La factura se envía a la DIAN y responde con el número y el CUFE.

Requisito de la cuenta: tu cuenta (la dueña de la API Key) debe estar habilitada en la DIAN — con credenciales DIAN configuradas y un rango de numeración autorizado. Sin eso, la DIAN responde error. El entorno (pruebas/producción) lo determina la configuración DIAN de tu cuenta.

POST//demo.wardian.com.co/dist/api/invoice/generate.php

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

Cabecera

Campo		Descripción
`customer`	req	ID del tercero (de `api/third`)
`numbering_range_id`	req	Rango de numeración / resolución
`payment_form`	req	`1` Contado · `2` Crédito
`payment_method_code`	req	Método de pago (catálogo)
`observation`	opc	Nota / observación
`payment_due_date`	opc	Fecha de vencimiento (si crédito)
`company`	opc	Nombre del emisor (para el correo/PDF)
`reference_code`, `cuenta_bancaria_id`, `cost_center_id`	opc	Referencia, cuenta bancaria, centro de costo
`currency_code`, `currency_value`, `currency_date`	opc	Moneda (por defecto COP)

Ítems — `products[]`

Campo		Descripción
`id`	req	ID del producto (de `api/products`)
`code_reference`, `name`	req	Código y nombre del ítem
`quantity`, `price`	req	Cantidad y precio unitario
`tax_rate`	req	% IVA: 0, 5, 8, 19
`unit_measure_id`, `standard_code_id`, `tribute_id`	req	Catálogos (ver Relaciones)
`discount_rate`, `is_excluded`	opc	% descuento, excluido de IVA (0/1)
`ret_fuente_rate`, `ret_iva_rate`, `ret_ica_rate`	opc	Retenciones (si el cliente retiene)

Ejemplo

Request (JSON)

{
  "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"
    }
  ]
}

Response

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

Importante: envía payment_due_date (una fecha, aun en contado) y en cada ítem discount_rate e is_excluded con valor (ej. 0). La DIAN rechaza campos vacíos/nulos con "Datos de la factura incompletos".

Crear factura por mandato

La facturación por mandato (operation_type 11) permite facturar por cuenta de terceros mandantes. Es idéntica a la factura estándar, pero cada ítem indica el mandante por el que se factura. La DIAN responde con el número y el CUFE.

Requisito de la cuenta: igual que la factura estándar — tu cuenta debe estar habilitada en la DIAN (credenciales configuradas y rango de numeración autorizado).

POST//demo.wardian.com.co/dist/api/invoice/generate_mandate.php

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:

Campo		Descripción
`mandate_identification`	req	Identificación (NIT/CC) del tercero mandante. Si va vacío, el ítem se factura sin mandato.
`mandate_identification_document_id`	req	Tipo de documento del mandante (catálogo `documentos_identidad`)
`mandate_dv`	opc	Dígito de verificación del mandante (si aplica)

Ejemplo

Request (JSON)

{
  "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"
    }
  ]
}

Response

{
  "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
  }
}

Importante: igual que la factura estándar, envía payment_due_date y en cada ítem discount_rate e is_excluded con valor. Para facturar por mandato, cada ítem debe incluir mandate_identification (y su mandate_identification_document_id) del mandante.

Crear tiquete POS

Emite un tiquete POS electrónico (documento Factura de Venta POS) a la DIAN. Mismo formato de request que la factura estándar; usa el rango de numeración POS de tu cuenta.

Requisito de la cuenta: tu cuenta debe estar habilitada en la DIAN y tener un rango activo de tipo Factura de Venta POS. Si no envías numbering_range_id, se detecta automáticamente el rango POS activo del titular.

POST//demo.wardian.com.co/dist/api/invoice/generate_pos.php

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

Cabecera

Campo		Descripción
`customer`	req	ID del tercero (de `api/third`)
`payment_form`	req	`1` Contado · `2` Crédito
`payment_method_code`	opc	Método de pago DIAN (por defecto `10`)
`numbering_range_id`	opc	Rango POS. Si se omite, se auto-detecta el rango `Factura de Venta POS` activo
`observation`	opc	Nota (por defecto "Tiquete POS Electrónico")
`payment_due_date`, `municipality_id`, `tip_amount`, `seller_id`	opc	Vencimiento, municipio, propina, vendedor

Ítems — `products[]`

Campo		Descripción
`id`	req	ID del producto (de `api/products`)
`code_reference`, `name`	req	Código y nombre del ítem
`quantity`, `price`, `discount_rate`	req	Cantidad, precio unitario, % descuento
`tax_rate`	req	% IVA: 0, 5, 8, 19
`unit_measure_id`, `standard_code_id`, `tribute_id`	req	Catálogos (ver Relaciones)
`is_excluded`, `requiere_stock`, `withholding_tax_rate`	opc	Excluido de IVA (0/1), control de stock, retención

Ejemplo

Request (JSON)

{
  "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"
    }
  ]
}

Response

{
  "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" } }
  }
}

El endpoint descuenta inventario de los ítems con requiere_stock=1 dentro de la transacción. Envía numbering_range_id explícito si manejas varios rangos POS por sucursal.

Crear factura RIPS (salud)

Emite una factura electrónica RIPS (sector salud — Registro Individual de Prestación de Servicios de Salud). La factura DIAN incluye los datos de salud (pacientes, servicios, CUPS) del paquete RIPS previamente validado en la plataforma.

Requisitos de la cuenta: habilitación DIAN (credenciales configuradas y rango de numeración autorizado) y un paquete RIPS validado (rips_id) creado desde el módulo de RIPS. Los datos clínicos (paciente/servicios) se toman de ese paquete, no se envían en el request.

POST//demo.wardian.com.co/dist/api/invoice/generate_rips.php

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

Cabecera

Campo		Descripción
`rips_id`	req	ID del paquete RIPS validado. De él se cargan pacientes y servicios de salud.
`invoice_type`	req	Debe ser `"rips"`
`customer`	req	ID del tercero (pagador — normalmente la EPS/entidad)
`numbering_range_id`	req	Rango de numeración / resolución
`payment_form`	req	`1` Contado · `2` Crédito
`payment_method_code`	req	Método de pago (catálogo)
`payment_due_date`	req	Fecha de vencimiento (una fecha, aun en contado)
`company`	req	Nombre del emisor (requerido para la notificación por correo)
`observation`	opc	Nota / observación
`cuenta_bancaria_id`, `cost_center_id`, moneda	opc	Cuenta bancaria, centro de costo, divisa

Los ítems (products) y los datos clínicos (health_data) se derivan automáticamente del paquete rips_id. No es necesario enviarlos.

Ejemplo

Request (JSON)

{
  "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"
}

Response

{
  "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 } }
  }
}

Importante: (1) el rips_id debe estar en estado validado y pertenecer a tu cuenta; (2) la cuenta debe tener credenciales DIAN configuradas; (3) envía payment_due_date (la DIAN rechaza con "Datos de la factura incompletos" si falta) y company (requerido por la notificación por correo). Los ítems y datos clínicos salen del paquete RIPS.

Crear documento soporte

El documento soporte se emite en compras a proveedores no obligados a facturar. Antes: ten el tercero/proveedor (su id), los ítems y el numbering_range_id del rango de documento soporte. Se envía a la DIAN y responde con el número y el CUDS.

Requisito de la cuenta: la cuenta dueña de la API Key debe estar habilitada en la DIAN, con credenciales y un rango de numeración de documento soporte autorizado.

POST//demo.wardian.com.co/dist/api/document_support/generate.php

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

Campo		Descripción
`customer`	req	ID del proveedor (tercero, de `api/third`)
`numbering_range_id`	req	Rango de numeración de documento soporte
`payment_form`	req	`1` Contado · `2` Crédito
`payment_method_code`	req	Método de pago (catálogo)
`issue_date`	opc	Fecha de emisión (por defecto hoy)
`payment_due_date`	opc	Fecha de vencimiento (si crédito)
`observation`	opc	Nota / observación
`cuenta_bancaria_id`, `cuenta_cxp_codigo`, `cost_center_id`	opc	Cuenta bancaria (pago), CxP (crédito), centro de costo
`save_draft`	opc	`1` = guardar como Borrador (no se envía a la DIAN)

Ítems — `products[]`

Campo		Descripción
`code_reference`, `name`	req	Código y nombre del ítem
`quantity`, `price`	req	Cantidad y precio unitario
`discount_rate`	req	% descuento (ej. `0`)
`unit_measure_id`, `standard_code_id`	req	Catálogos (ver Relaciones)
`ret_fuente_rate`, `ret_ica_rate`, `withholding_config_id`	opc	Retenciones (ReteFuente / ReteICA)

Ejemplo

Request (JSON)

{
  "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"
    }
  ]
}

Response (emitido)

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

Response (save_draft=1)

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

Con save_draft=1 el documento queda en Borrador (no va a la DIAN) para revisar/emitir después desde el panel. Un borrador se puede convertir en documento soporte emitido.

Documentación de la API de Wardian

Autenticación

1 Generar tu API Key

2 Primer request

Códigos de error

Relaciones (catálogos)

Catálogos con endpoint propio (requieren X-API-Key)

Productos

Terceros

Categorías

Crear factura estándar

Cabecera

Ítems — products[]

Ejemplo

Crear factura por mandato

Cabecera

Ítems — products[]

Ejemplo

Crear tiquete POS

Cabecera

Ítems — products[]

Ejemplo

Crear factura RIPS (salud)

Cabecera

Ejemplo

Crear documento soporte

Cabecera

Ítems — products[]

Ejemplo

Catálogos con endpoint propio (requieren `X-API-Key`)

Ítems — `products[]`

Ítems — `products[]`

Ítems — `products[]`

Ítems — `products[]`