Documentación de la API de Wardian

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

const res = await fetch("//qa.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[]).

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

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

Campo		Descripción
id	req	ID del producto a editar

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

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)

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

Campo		Descripción
tercero_id	req	ID del tercero a editar

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

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)

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

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

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

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

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

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

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

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

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

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

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

Campo		Descripción
payload	req	El JSON RIPS completo — ver Estructura del payload (numDocumentoIdObligado, usuarios[] con servicios.consultas/servicios.procedimientos, …).
usuario_id_rips	opc	Dueño del RIPS. Por defecto, quien envía. Un principal puede enviar por sus subusuarios.
cufe	opc	CUFE de una FEV ya emitida. Si se envía, el RIPS se convierte a modo con factura (la raíz numFactura toma el número de esa factura) y se valida así. El CUFE se resuelve localmente contra tus facturas; no se escribe dentro del RIPS.

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

Campo		Descripción
rips_id	req	ID del paquete a revalidar.
cufe	opc	Si se envía, convierte el paquete a modo con factura (raíz numFactura = número de esa FEV, resuelta localmente) antes de reenviar. El payload convertido se persiste.

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

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

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

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

Campo		Descripción
entorno	req	qa | preproduccion | produccion
base_url	req	La URL que emitió MinSalud. Debe ser https://.
tenant_id	req	Tenant de Azure AD contra el que se pide el token.
client_id	req
client_secret	req	Obligatorio al crear. Al editar, envíalo vacío para conservar el guardado.
subscription_key	req	El Ocp-Apim-Subscription-Key. Mismo criterio que el secreto.
scope	req	Scope OAuth2, normalmente api://…/.default.
prestador_id	opc	IPS a la que pertenece la credencial, si el tenant opera varias.
auto_enviar	opc	0 por defecto. Con 1, cada atención completada dispara el envío.
op_enviar_ambulatorio	opc	Ruta de la operación. Configurable porque el Manual documenta menos operaciones que la guía FHIR.

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

Campo		Descripción
evento_id	req	Evento clínico a reportar.
entorno	opc	qa por defecto.
forzar	opc	Reenvía aunque el contenido sea idéntico a un envío ya aceptado.
confirmar_produccion	opc	Obligatorio si entorno es produccion. Salvaguarda contra envíos accidentales.

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

Estados y códigos

Estado	HTTP	Significado
aceptado	200	IHCE devolvió el identificador del RDA.
duplicado	200	El encuentro ya se había reportado con el mismo contenido. No se reenvía.
enviado	202	Respondió 200 pero sin identificador reconocible.
borrador	422	No pasó la validación local. No se envió.
rechazado	422	IHCE devolvió 400. Los issue del OperationOutcome vienen en errores.
error	502	Fallo de red o HTTP inesperado. Reintentable.

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