Integraciones: API
Sincronizar su inventario desde un endpoint GET de su tienda, con referencia completa y ejemplos.
El conector de API trae su catálogo desde un endpoint GET que usted ya tiene (la API de su tienda, su ERP o un servicio propio) y lo mantiene sincronizado con su inventario.
Nota
Por defecto es una copia periódica: si un precio cambia a las 3:05 y sincroniza cada hora, el asistente puede decir el precio anterior hasta la siguiente sincronización. Si su API puede entregar un producto a la vez, active la consulta en vivo y el asistente verificará el precio y el stock en el momento de responder.
Qué necesita su endpoint
| Requisito | Detalle |
|---|---|
| Método | GET (no se usa POST ni cuerpo de la petición) |
| Dirección | https:// pública. No se aceptan direcciones internas ni de red privada |
| Respuesta | JSON, de hasta 5 MB y 5.000 productos |
| Redirecciones | No se siguen: ponga la dirección final |
| Paginación | No se pagina: haga una sola petición. Si su API pagina, use un límite grande (?limit=500) |
Los filtros van dentro de la misma dirección: https://api.mitienda.cl/productos?categoria=herramientas&limit=500.
Autenticación
| Tipo | Cómo se envía |
|---|---|
| Ninguna | Sin credenciales |
| Bearer | Authorization: Bearer <su clave> |
| Cabecera propia | El nombre lo elige usted (por ejemplo X-API-Key) y el valor es su clave |
La clave se guarda cifrada y no se vuelve a mostrar. Si deja el campo vacío al editar, se conserva la guardada.
curl -H "Accept: application/json" \
-H "Authorization: Bearer su_clave_secreta" \
"https://api.mitienda.cl/productos?limit=500"
Formato de la respuesta
Puede ser directamente una lista:
[
{
"id": "BK-3500",
"nombre": "Generador Bauker 3500W",
"precio": 189990,
"stock": 2,
"categoria": "Generadores",
"url": "https://mitienda.cl/generador-bauker-3500w",
"foto": "https://mitienda.cl/fotos/bauker-3500.jpg"
}
]
O envuelta en un objeto. En ese caso indica dónde está la lista con una ruta con puntos (data.items):
{
"data": {
"items": [
{
"sku": "BK-650",
"title": "Taladro percutor Bauker 650W",
"price": { "value": 39990, "currency": "CLP" },
"inventory": { "available": 5 }
}
]
}
}
El mapeo
Usted indica la ruta de cada dato dentro de cada producto. Las rutas usan puntos para entrar en objetos (price.value) y números para listas (variants.0.stock).
| Dato | Obligatorio | Ruta en el primer ejemplo | Ruta en el segundo |
|---|---|---|---|
| Identificador | Sí | id |
sku |
| Nombre | Sí | nombre |
title |
| Precio | No | precio |
price.value |
| Stock | No | stock |
inventory.available |
| Categoría | No | categoria |
|
| Enlace al producto | No | url |
|
| Foto (enlace) | No | foto |
|
| Activo | No |
Puede sumar hasta 10 características (nombre que usted elige + ruta).
Reglas del mapeo:
- El identificador debe ser único. Un repetido se informa como error de esa fila.
- Un precio o stock con texto («$14.990», «1.234,50») se interpreta con formato chileno.
- Un enlace o una foto inválidos se descartan y el producto se importa igual (sin tarjeta).
- Activo: si el campo vale
no,false,0,inactivo,oculto,agotadouoff, el producto se oculta.
Probar antes de guardar
En Integraciones → nueva conexión → API, pegue la dirección, elija la autenticación, defina el mapeo y pulse la vista previa. Verá los primeros productos ya convertidos y los errores por fila, sin guardar nada.
Los mensajes de error le dicen qué falló:
| Mensaje | Qué hacer |
|---|---|
| «La URL debe usar HTTPS» | Use https:// |
| «Tu API rechazó las credenciales (401/403)» | Revise la clave y el tipo de autenticación |
| «Tu API respondió 404» | Revise la dirección |
| «Tu API tardó demasiado en responder» | Su API debe responder en menos de 15 segundos |
«No encontramos la lista de productos en data.items» |
Corrija la ruta de la lista |
| «La respuesta de tu API supera los 5 MB» | Reduzca los campos o pida menos productos |
| «Tu API devolvió más de 5000 productos» | Filtre por categoría o cree varias conexiones |
Ejemplo: un endpoint mínimo
Si todavía no tiene una API, este es un endpoint de ejemplo que cumple todo lo anterior.
import express from "express";
const app = express();
const PRODUCTS = [
{ id: "BK-3500", nombre: "Generador Bauker 3500W", precio: 189990, stock: 2,
url: "https://mitienda.cl/generador-bauker-3500w" },
];
app.get("/productos", (req, res) => {
if (req.get("authorization") !== `Bearer ${process.env.CATALOG_TOKEN}`) {
return res.status(401).json({ error: "no autorizado" });
}
res.json(PRODUCTS);
});
app.listen(3000);
import os
from fastapi import FastAPI, Header, HTTPException
app = FastAPI()
PRODUCTS = [
{"id": "BK-3500", "nombre": "Generador Bauker 3500W", "precio": 189990, "stock": 2,
"url": "https://mitienda.cl/generador-bauker-3500w"},
]
@app.get("/productos")
def productos(authorization: str = Header(default="")):
if authorization != f"Bearer {os.environ['CATALOG_TOKEN']}":
raise HTTPException(status_code=401, detail="no autorizado")
return PRODUCTS
<?php
header('Content-Type: application/json');
$esperado = 'Bearer ' . getenv('CATALOG_TOKEN');
if (($_SERVER['HTTP_AUTHORIZATION'] ?? '') !== $esperado) {
http_response_code(401);
echo json_encode(['error' => 'no autorizado']);
exit;
}
echo json_encode([
['id' => 'BK-3500', 'nombre' => 'Generador Bauker 3500W', 'precio' => 189990, 'stock' => 2],
]);
Frecuencia y resultado
Elija cada cuánto sincronizar: 5, 15, 30 minutos, cada hora, cada 6 horas o una vez al día. Después de cada sincronización, la conexión muestra un resumen (creados, actualizados, ocultados, errores por fila). Detalles de cómo se tratan los productos en Inventario.
Consulta en vivo (opcional)
Con la copia, el asistente responde con lo último que sincronizó. Con la consulta en vivo, cuando un cliente pregunta por un producto, Astrhorus le pregunta a su API el precio y el stock de ese producto en ese instante.
En el segundo paso de la conexión encontrará Consulta en vivo (opcional):
| Campo | Qué poner |
|---|---|
| Dirección para consultar un producto | Una URL https://… con {id} (el identificador del producto en su sistema) o {sku}. Por ejemplo https://api.mitienda.cl/productos/{id} |
| Dónde está el producto en la respuesta | La ruta del producto dentro del JSON, por ejemplo data. Vacío si la respuesta es el producto mismo |
El precio y el stock se leen con el mismo mapeo que ya definió. Use Probar consulta con un producto real: le muestra lo que su API respondió, sin guardar nada.
GET https://api.mitienda.cl/productos/BK-3500
{ "data": { "id": "BK-3500", "precio": 189990, "stock": 2 } }
Cómo se comporta:
- Solo se consultan los productos de los que se está hablando (hasta 4 por pregunta), nunca todo el catálogo.
- Una misma respuesta se reutiliza 30 segundos, para no saturar su API si varios clientes preguntan por lo mismo.
- Si su API tarda más de unos segundos o falla, el asistente usa la copia y se lo dice al cliente («según nuestro último registro…»).
- Si la respuesta no trae el precio o el stock, ese dato se queda con el valor de la copia (nunca se convierte en 0).
- Usa la misma autenticación de la conexión.
Consejo
Mantenga la sincronización periódica aunque active la consulta en vivo: la copia es lo que permite encontrar los productos y es el respaldo cuando su API no responde.
Eliminar la conexión
Al eliminar una conexión, sus productos se quedan en su inventario como productos manuales y dejan de actualizarse. Si prefiere que se vayan con ella, marque Borrar también los productos que trajo esta conexión: se eliminan solo los que trajo esa conexión, nunca los que cargó a mano.
Seguridad
- Astrhorus hace las peticiones desde sus servidores y valida que la dirección sea pública (sin acceso a redes internas).
- La dirección de la consulta en vivo debe usar HTTPS y su servidor no puede depender del producto:
{id}y{sku}solo van en la ruta o en los parámetros, y se codifican. - Su clave se guarda cifrada; no se muestra ni se incluye en los registros.
- Cree una clave solo de lectura para este uso y dele permiso únicamente al endpoint del catálogo.
Lo que este conector no hace
- No consulta toda la lista en vivo: la consulta en vivo trae solo un producto a la vez; el catálogo completo sigue siendo una copia periódica.
- No usa
POST, ni paginación, ni OAuth. - Un endpoint por conexión. Puede crear varias conexiones si tiene varias listas.