API de Astrobit
API REST sobre JSON. Crear órdenes, consultar el catálogo y el stock, emitir documentos tributarios y leer los reportes desde tu propio sistema.
Esta página es el índice de lo que existe: qué endpoints hay y qué hace cada uno, para que puedas evaluar si la API te sirve antes de hablar con nadie.
La referencia campo por campo —cuerpos de petición, respuestas y ejemplos de cada endpoint— se entrega directamente al equipo que va a integrar. Escríbenos contando qué necesitas conectar y te la hacemos llegar.
Empezar
# 1. Login — guarda las cookies de sesión
curl -c cookies.txt -X POST https://<tu-host>/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"usuario@empresa.cl","password":"..."}'
# 2. Llamadas siguientes — reenvía las cookies
curl -b cookies.txt "https://<tu-host>/api/product?search=polera&page=1"Sin sesión válida la API responde 401. Con sesión pero sin permiso para esa ruta, 403.
Autenticación
La API usa sesión por cookies con tokens JWT. Inicias sesión una vez y reenvías las cookies en cada llamada. Las cookies son HttpOnly, así que un cliente que no sea navegador tiene que capturarlas de la respuesta del login.
/api/auth/loginRecibe correo y contraseña. Deja las cookies de sesión y de refresco.
/api/auth/logoutInvalida la sesión y limpia las cookies.
Órdenes
Crear ventas, listarlas con filtros y editarlas. La creación acepta una clave de idempotencia: un reintento con la misma clave devuelve la orden ya creada en vez de duplicarla.
/api/orderCrea una venta con sus productos, sus pagos y, si lo pides, emite el documento tributario. Admite la cabecera X-Idempotency-Key.
/api/orderLista órdenes paginadas. Filtra por canal, estado de preparación, pendientes de facturación o etiqueta, rango de fechas, cliente, courier, logística y tipo de documento.
/api/order/{id}Devuelve una orden con su detalle.
/api/order/{id}Actualiza campos simples de la orden.
/api/order/{id}Edita la orden: productos, devoluciones y pagos.
Productos y stock
Consultar el catálogo, el stock por bodega y los packs con sus componentes.
/api/productLista productos. Busca por SKU, nombre o código de barras; filtra por canal, por si es pack, o por datos incompletos (sin costo, sin campos obligatorios). Devuelve el stock por bodega cuando lo pides.
/api/product/{id}Devuelve un producto con su detalle.
Documentos tributarios
Emitir DTE y consultar los recibidos. Los tipos soportados son factura afecta (T33), factura exenta (T34), boleta (T39), factura de compra (T46), guía de despacho (T52) y nota de crédito (T61).
/api/dteEmite uno o varios DTE. Se puede emitir contra una orden existente, contra un documento de gasto extranjero, o suelto con los datos del receptor en el cuerpo. La nota de crédito se pide enviando el identificador de la devolución.
/api/dte/purchases/syncTrae desde el SII los documentos recibidos de un período y los guarda. Reejecutar el mismo período no duplica nada.
/api/dte/purchasesLista los documentos recibidos, con su estado, su vencimiento y a qué orden de compra están conciliados.
Reportes
Los mismos números que ves en la aplicación, disponibles por API. Cada endpoint devuelve el cálculo hecho en el servidor, no una tabla cruda para que la sumes tú.
/api/order/statsSerie de ingresos por período y por canal.
/api/order/stats/incomeResumen de ingresos por la dimensión que pidas.
/api/order/stats/costsCostos por día.
/api/commissionListado de comisiones cobradas por los canales.
/api/reports/dte-statsEstadística de documentos tributarios emitidos y recibidos.
/api/product/statsTops de productos.
/api/stock/statsValorización actual del inventario.
/api/stock/predictCobertura de stock y sugerencia de reposición.
/api/alerts/stocksAlertas de stock bajo.
/api/client/statsIndicadores de clientes.
/api/reports/preparation/statsIndicadores de preparación de pedidos.
/api/reports/providersCompras por proveedor.
Convenciones
- Los montos son enteros en pesos. Los precios de venta se guardan brutos, con IVA incluido, salvo que la lista de precios sea de tipo neto.
- Los resultados se acotan automáticamente a los contribuyentes que tu sesión puede ver. Un parámetro de contribuyente solo puede acotar ese alcance, nunca ampliarlo.
- Las fechas de rango se envían como timestamp Unix.
- POST /api/order acepta X-Idempotency-Key: un reintento con la misma clave responde 409 con el identificador de la orden ya creada.
- La emisión de un DTE contra una orden con muchas líneas puede generar más de un documento; la respuesta trae el primero y el resto queda guardado.
- No hay límite de tasa propio de la API. Los reintentos por límite de tasa que sí existen son contra los marketplaces, y los maneja Astrobit.
Preguntas frecuentes
¿Cómo me autentico contra la API?
Con POST /api/auth/login enviando correo y contraseña. La respuesta deja las cookies de sesión, que se reenvían en cada llamada siguiente. Las cookies son HttpOnly, así que desde curl o desde un servidor hay que capturarlas de las cabeceras del login y reenviarlas.
¿Hay tokens de API o solo login con usuario?
Hoy la API se consume con la sesión de un usuario. No se emiten claves de máquina para terceros. Existen secretos de servicio y firmas HMAC, pero están reservados a rutas internas concretas (tareas programadas, marketing, checkout, alta de cuentas), no a la API general de órdenes, productos y reportes. Si vas a integrar un sistema propio, hoy corre con un usuario dedicado y sus permisos.
¿Qué permisos necesita cada endpoint?
Cada llamada se autoriza contra los permisos de la sesión. Sin sesión válida responde 401; con sesión pero sin permiso para esa ruta, 403. Además hay un filtro por contribuyente: los resultados se acotan a los contribuyentes que tu sesión puede ver, y un parámetro de contribuyente solo puede acotar ese alcance, nunca ampliarlo.
¿Cómo evito duplicar una orden si se corta la conexión?
Enviando la cabecera X-Idempotency-Key en POST /api/order. Un reintento con la misma clave responde 409 con el identificador de la orden que ya se creó, en vez de crear una segunda.
¿En qué unidad vienen los montos?
En pesos enteros. Los precios de venta se guardan brutos, con IVA incluido, salvo que la lista de precios sea de tipo neto.
¿Hay límite de llamadas?
La API no aplica un límite de tasa propio. Lo que sí existe son los límites de los marketplaces cuando una operación tuya termina llamándolos: en esos casos Astrobit reintenta respetando el tiempo de espera que el canal indica, sin que tú tengas que manejarlo.
Si lo que necesitas es que un asistente de IA consulte tus datos en vez de escribir código, eso es el servidor MCP, que es de solo lectura.
¿Vas a integrar contra la API?
Agenda una reunión con el equipo técnico y revisamos tu caso, los permisos que necesitas y la referencia completa de los endpoints.