AstrhorusDocumentación

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, agotado u off, 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.