API de datos v1 · Solo lectura · JSON y CSV
Ventas, compras, inventario, kárdex y contabilidad en Power BI, Excel, Google Sheets o su propio sistema, con una clave de solo lectura que usted controla: elige qué puede ver, desde dónde y hasta cuándo. Sin exportar archivos a mano, sin copiar y pegar, sin esperar al cierre del mes.
$ curl -H "Authorization: Bearer $KOSTOA_API_KEY" \
"https://kontanex.com/api/datos/v1/ventas?desde=2026-10-01&hasta=2026-10-31&limite=2"{
"conjunto": "ventas",
"pagina": 1,
"limite": 2,
"filas": 2,
"hay_mas": true,
"siguiente": "/api/datos/v1/ventas?desde=2026-10-01&hasta=2026-10-31&pagina=2&limite=2&formato=json",
"datos": [
{
"id": 4821,
"fecha": "2026-10-01",
"tipo_documento": "01",
"tipo_documento_nombre": "FACTURA",
"numero": "001-001-000004821",
"cliente_identificacion": "0992345678001",
"cliente_razon_social": "DISTRIBUIDORA EL MANGLAR S.A.",
"vendedor": "Ana Torres",
"base_0": 0.00,
"base_gravada": 1250.00,
"iva": 187.50,
"ice": 0.00,
"propina": 0.00,
"total": 1437.50,
"moneda": "USD",
"estado_contable": "MAYORIZADO",
"estado_sri": "AUTORIZADO",
"base_diferenciada": 0.00,
"iva_diferenciado": 0.00
},
{ "id": 4822, "fecha": "2026-10-01", "...": "..." }
]
}Tableros en Power BI que se actualizan solos: margen por cliente, ventas por vendedor, inventario valorizado, flujo de bancos.
El libro diario y el plan de cuentas en Excel para armar sus propios balances, conciliaciones y anexos sin re-digitar nada.
Un REST simple, predecible y documentado: un GET por conjunto, paginación clara, errores con mensaje y código.
Kontanex publica sus datos como conjuntos (ventas, compras, existencias, asientos…). Cada conjunto es una dirección web que responde una tabla. Su herramienta la pide con una clave, y Kontanex le contesta solo con lo que esa clave puede ver, solo de su empresa y solo para leer.
Elija un plan y díganos qué conjuntos, hasta cuándo y desde qué IP. Kontanex emite la clave y se la entrega una sola vez.
Power BI, Excel, Python o su ERP envían la clave en un encabezado HTTPS y piden el conjunto que necesitan.
Kontanex responde solo con lo que la clave permite, de su empresa, en JSON o CSV, y anota cada consulta.
Un complemento mensual por empresa, sin cobro por consulta ni por fila. La clave la emite Kontanex con el plan contratado; el plan fija cuántas consultas por minuto admite.
Para gerencia y contabilidad que analizan en Power BI o Excel.
Para conectar Kontanex con su ERP, tienda en línea o sistema propio.
Para grupos con varias empresas, auditoría o volúmenes altos.
kst_: guárdela, nadie podrá volver a mostrarla.curl -H "Authorization: Bearer $KOSTOA_API_KEY" \ "https://kontanex.com/api/datos/v1/ventas?desde=2026-10-01&hasta=2026-10-31&limite=2"
La respuesta trae los datos y cómo seguir:
{
"conjunto": "ventas",
"pagina": 1,
"limite": 2,
"filas": 2,
"hay_mas": true,
"siguiente": "/api/datos/v1/ventas?desde=2026-10-01&hasta=2026-10-31&pagina=2&limite=2&formato=json",
"datos": [
{
"id": 4821,
"fecha": "2026-10-01",
"tipo_documento": "01",
"tipo_documento_nombre": "FACTURA",
"numero": "001-001-000004821",
"cliente_identificacion": "0992345678001",
"cliente_razon_social": "DISTRIBUIDORA EL MANGLAR S.A.",
"vendedor": "Ana Torres",
"base_0": 0.00,
"base_gravada": 1250.00,
"iva": 187.50,
"ice": 0.00,
"propina": 0.00,
"total": 1437.50,
"moneda": "USD",
"estado_contable": "MAYORIZADO",
"estado_sri": "AUTORIZADO",
"base_diferenciada": 0.00,
"iva_diferenciado": 0.00
},
{ "id": 4822, "fecha": "2026-10-01", "...": "..." }
]
} Envíe la clave en uno de estos dos encabezados. Son equivalentes; Power BI, Excel y Google Sheets se llevan mejor con X-Api-Key.
Nunca ponga la clave en la URL (?api_key=…): Kontanex la rechaza, porque las direcciones quedan guardadas en historiales, proxies y registros. Tampoco la ponga en el código de una página web ni en un repositorio: guárdela en una variable de entorno o un gestor de secretos.
Dirección base: https://kontanex.com/api/datos/v1. Dos operaciones, las dos con GET.
El catálogo: su empresa, los datos de la clave y cada conjunto que puede leer, con sus columnas y tipos (entero, decimal, texto, fecha, fecha_hora, booleano). Úselo para descubrir el esquema sin leer esta página.
curl -H "X-Api-Key: $KOSTOA_API_KEY" https://kontanex.com/api/datos/v1
{
"empresa": { "ruc": "0791234567001", "razon_social": "COMERCIAL EL ESTERO S.A.", ... },
"clave": { "nombre": "Power BI gerencia", "prefijo": "kst_1a2b3c4d5e6f", "vence": "2027-01-19" },
"conjuntos": [
{
"codigo": "ventas",
"descripcion": "Comprobantes de venta registrados (cabecera): totales, cliente, vendedor y estado.",
"filtra_por_fecha": true,
"url": "/api/datos/v1/ventas",
"columnas": [ { "nombre": "id", "tipo": "entero" }, { "nombre": "fecha", "tipo": "fecha" }, ... ]
}
]
}Las filas del conjunto, ordenadas de forma estable. Parámetros, todos opcionales:
| Parámetro | Tipo | Qué hace |
|---|---|---|
| desde | fecha (aaaa-mm-dd) | Desde esta fecha, incluida. Solo en conjuntos con fecha. |
| hasta | fecha (aaaa-mm-dd) | Hasta esta fecha, incluida. Solo en conjuntos con fecha. |
| pagina | entero | Página a leer; empieza en 1. Por defecto 1. |
| limite | entero | Filas por página, de 1 a 10.000. Por defecto 1.000. |
| formato | json | csv | csv devuelve un archivo listo para Excel (UTF-8 con BOM). Por defecto json. |
En JSON, hay_mas indica si quedan filas y siguiente trae la dirección exacta de la próxima página (con sus mismos filtros). En CSV lo mismo viaja en los encabezados X-Hay-Mas y Link: <…>; rel="next". Pida hasta 10.000 filas por página: pocas consultas grandes rinden más que muchas pequeñas. Los números llegan como números (sin comillas), las fechas en ISO (2026-10-21) y los montos en dólares.
Quince conjuntos cubren el día a día de la empresa. Todos traen id; los marcados con fecha aceptan desde y hasta. Se relacionan entre sí por venta_id, compra_id, producto_codigo, cliente_identificacion, cuenta y los códigos de centros y bodegas: un modelo estrella listo para Power BI.
/ventasFacturas, notas de crédito y demás comprobantes de venta registrados (sin borradores ni anulados).
fecha, tipo_documento, numero, cliente_identificacion, cliente_razon_social, vendedor, base_0, base_gravada, iva, ice, propina, total, estado_contable, estado_sri, base_diferenciada, iva_diferenciado
/ventas_detalleQué se vendió, cuánto y a qué precio, con bodega y centros.
venta_id, fecha, numero, producto_codigo, producto, unidad, cantidad, precio, porcentaje_descuento, subtotal, bodega, centro_produccion, centro_costo
/comprasComprobantes de compra registrados con proveedor, bases, IVA y retención.
fecha, tipo_documento, numero, proveedor_identificacion, proveedor_razon_social, base_0, base_gravada, base_no_objeto, base_exenta, iva, ice, total, valor_retenido, estado_contable
/compras_detalleQué se compró, a qué costo y a qué centro se cargó.
compra_id, fecha, numero, producto_codigo, producto, unidad, cantidad, costo, porcentaje_descuento, subtotal, bodega, centro_produccion, centro_costo
/productosEl catálogo completo con categoría, marca y unidad.
codigo, codigo_alterno, codigo_barras, descripcion, categoria, marca, unidad, grava_iva, peso_kg, estado
/existenciasSaldo de hoy por producto y bodega, valorizado a costo promedio.
producto_id, producto_codigo, producto, bodega_id, bodega, bodega_nombre, saldo, costo_promedio, valor, ultimo_costo, ultima_fecha
/kardexCada entrada y salida de inventario con su costo.
fecha, tipo_transaccion, numero_documento, producto_codigo, producto, bodega, cantidad_entrada, cantidad_salida, cantidad_saldo, costo_entrada, costo_salida, costo_saldo, costo_promedio, centro_produccion
/clientesIdentificación, contacto, días y línea de crédito.
identificacion, razon_social, nombre_comercial, correo, telefono, direccion, dias_credito, linea_credito, exportador, estado
/proveedoresIdentificación, contacto, categoría y crédito.
identificacion, razon_social, nombre_comercial, correo, telefono, direccion, dias_credito, cupo_credito, categoria, estado
/plan_cuentasTodas las cuentas con tipo, naturaleza y cuenta padre.
codigo, descripcion, tipo, naturaleza, es_detalle, cuenta_padre
/asientosUna fila por línea de asiento en el libro: arme balances y estados de resultados a su medida.
asiento_id, asiento_numero, fecha, concepto, estado_contable, cuenta, cuenta_nombre, debe, haber, referencia, centro_produccion, centro_costo
/movimientos_bancariosIngresos y egresos por banco; de la cuenta solo viajan los 4 últimos dígitos.
fecha, banco, cuenta_final, tipo_documento, numero_cheque, beneficiario, ingreso, egreso, conciliado
/centros_costoEl árbol de centros de costo con su centro de producción.
codigo, descripcion, naturaleza, centro_padre, centro_produccion, estado
/centros_produccionPlantas, fincas, cocinas o líneas que transforman.
codigo, nombre, actividad, estado
/bodegasBodegas con su tipo y centro de producción.
codigo, descripcion, tipo, centro_produccion, estado
Copie, pegue y cambie la clave. Todos los ejemplos recorren las páginas solos y funcionan tal cual.
let
// Mejor como parámetro: Inicio › Administrar parámetros › Nuevo parámetro «ClaveKostoa»
Clave = "kst_1a2b3c4d5e6f_su_clave_completa",
Conjunto = "ventas",
LeerPagina = (n as number) =>
Json.Document(
Web.Contents("https://kontanex.com", [
RelativePath = "api/datos/v1/" & Conjunto,
Query = [pagina = Text.From(n), limite = "5000"],
Headers = [#"X-Api-Key" = Clave]
])
),
// Recorre todas las páginas hasta que hay_mas sea false
Paginas = List.Generate(
() => [n = 1, r = LeerPagina(1)],
each [r] <> null,
each if [r][hay_mas] then [n = [n] + 1, r = LeerPagina([n] + 1)] else [n = [n], r = null],
each [r][datos]
),
Tabla = Table.FromRecords(List.Combine(Paginas), null, MissingField.UseNull)
in
Tablalightbulb Use Web.Contents con la URL base fija y RelativePath: así el servicio de Power BI permite la actualización programada.
También funciona con
Cualquier herramienta que haga una petición HTTPS GET con un encabezado sirve: en n8n o Make use el nodo HTTP con autenticación por encabezado; en Airbyte, el conector HTTP genérico.
Abrir los datos de una empresa a internet exige más que una contraseña. Esto es lo que protege cada consulta, hoy, en producción:
Solo GET, y cada consulta corre en una transacción READ ONLY de la base: aunque alguien lo intentara, PostgreSQL rechaza cualquier escritura.
Kontanex guarda solo su huella HMAC-SHA256 con una pimienta que vive fuera de la base. Ni nosotros podemos verla: se muestra una sola vez.
Generada con SecureRandom. Adivinarla tomaría más tiempo que la edad del universo, y además 20 intentos fallidos bloquean la IP.
Empieza con kst_: los escáneres de secretos de GitHub y GitLab la reconocen si alguien la sube a un repositorio por error.
La empresa la decide la clave, nunca un parámetro. No hay forma de pedir datos de otra empresa.
Elija qué puede leer cada clave: la de ventas no ve bancos, la del contador no ve clientes.
Toda clave vence (máximo un año). Las claves eternas son las que terminan filtradas.
Limite la clave a la IP o red (CIDR, IPv4 o IPv6) del servidor del integrador.
Un clic y la clave deja de responder en ese mismo segundo.
Si la clave llega como parámetro de la URL, se rechaza: las URL quedan en historiales, proxies y registros.
Consultas por minuto según el plan, 10.000 filas por página y tiempo máximo por consulta.
Fecha, conjunto, IP, respuesta, filas y milisegundos, visibles por 180 días en Sistema › API de datos.
El API no responde a páginas web de otros dominios: la clave vive en un servidor o en Power BI, nunca en un navegador.
Se publican vistas diseñadas para análisis: nada de contraseñas, configuraciones internas ni cuentas bancarias completas.
Nadie dentro ni fuera de su empresa puede fabricar una clave: la emite Kontanex al contratar el servicio. Su administrador la revoca cuando quiera.
Todo viaja cifrado con TLS y HSTS; el tráfico en HTTP se redirige.
Más sobre cómo cuidamos sus datos en Seguridad.
Cada respuesta trae X-RateLimit-Limit y X-RateLimit-Remaining. Los errores responden JSON con un código y un mensaje en español que dice qué hacer.
| HTTP | Error | Qué pasó y qué hacer |
|---|---|---|
| 400 | clave_en_url / parámetros | La clave llegó en la URL (revóquela) o un parámetro no es válido. |
| 401 | clave_invalida | Falta la clave o está mal escrita, vencida o revocada. |
| 403 | ip_no_permitida / sin acceso | La IP no está en la lista de la clave o el conjunto no está incluido. |
| 404 | conjunto inexistente | El conjunto no existe. GET /api/datos/v1 lista los disponibles. |
| 405 | solo_lectura | Solo se admite GET: el API nunca escribe. |
| 429 | limite_por_minuto / demasiados_fallos | Pasó el tope por minuto de su plan (60, 300 o 1.000), o su IP acumuló 20 claves inválidas. Espere lo que indica Retry-After. |
Es un complemento mensual de Kontanex: Conector BI US$ 29, Integración US$ 79 y Empresarial a medida. Sin cobro por consulta ni por fila: el plan fija cuántas consultas por minuto admite cada clave.
Pídala desde Sistema › API de datos (Solicitar el API de datos) o desde Contacto. Kontanex la emite con los conjuntos, el vencimiento y las IP que usted indique, y se la entrega por un canal seguro.
Sí. No es una copia nocturna: cada consulta lee los datos de Kontanex en ese momento. Un comprobante guardado hace un minuto ya aparece.
No. Este API es de solo lectura a propósito: así una clave filtrada nunca puede alterar su contabilidad. Para cargar datos use las importaciones de Kontanex.
Sí. Use Web.Contents con RelativePath (como en el ejemplo) y, en el servicio, configure la credencial del origen como Anónima: la clave viaja en el encabezado X-Api-Key.
Sí: los parámetros RangeStart y RangeEnd se traducen a desde y hasta. Power BI avisará que no puede confirmar el plegado de consultas; aun así filtra en el servidor porque las fechas viajan en la URL.
Nadie puede: Kontanex solo guarda su huella. Revóquela en Sistema › API de datos y le emitimos otra sin costo.
Nada para usted. El API publica vistas versionadas (v1): si algo cambia por dentro, la vista sigue entregando las mismas columnas. Un cambio incompatible sería una v2, con aviso previo.
En una variable de entorno o un gestor de secretos (Azure Key Vault, AWS Secrets Manager, Propiedades del script en Google). Nunca en el repositorio ni en una página web.
Escríbanos desde Contacto: los conjuntos nuevos se agregan a la v1 sin romper los existentes.
Si ya usa Kontanex, pida su clave en Sistema › API de datos y conecte Power BI hoy mismo. Si todavía no, vea cómo trabaja con una empresa de demostración.
© 2026 Kontanex · Ecuador