Integración del catálogo por API

1Cómo funciona

Doopy consulta una dirección web del proveedor (endpoint) y recibe en cada consulta su catálogo completo en JSON. El proveedor no envía nada: solo expone el endpoint.

La respuesta representa todo lo que el proveedor tiene para vender en ese momento. Doopy la compara con lo que ya tiene publicado de ese proveedor:

• los productos nuevos se dan de alta;
• los que ya existen se actualizan (nombre, precio y stock);
• los que dejaron de venir se dan de baja en la tienda.

2Requisitos del endpoint

3Campos de cada producto

Cada elemento de la lista es un producto con estas claves. Los nombres de las claves tienen que ser exactamente estos, respetando mayúsculas y minúsculas.

4Ejemplo de respuesta

Una respuesta mínima válida con dos productos, uno en dólares y otro en guaraníes:

[
  {
    "codigo_barra": "7891234567890",
    "nombre": "Notebook Lenovo IdeaPad 3 15.6\" Core i5 8GB 512GB SSD",
    "seccionTxt": "NOTEBOOKS",
    "precio_venta": 650.00,
    "moneda_txt": "USD",
    "stock": 12
  },
  {
    "codigo_barra": "PLOL-00017",
    "nombre": "Cable HDMI 2.1 8K 2 metros",
    "seccionTxt": "CABLES",
    "precio_venta": 45000,
    "moneda_txt": "PYG",
    "stock": 0
  }
]

Una consulta de ejemplo, como la que hace Doopy:

curl -X GET "https://api.su-empresa.com.py/doopy/catalogo" \
     -H "Authorization: Bearer SU_TOKEN" \
     --max-time 60

5Qué hace Doopy con cada producto

Buenas prácticas

• No reutilice códigos. Un código nuevo es un producto nuevo para Doopy, y si cambia el código de un producto existente, ese producto se da de baja y se crea otro.
• Use un prefijo propio si sus códigos son internos y no códigos de barras reales. Por ejemplo, PLOL-00017. Así no coinciden con los de otro proveedor de Doopy. El prefijo se acuerda en el alta.
• Mantenga estables los nombres. Cambiar un nombre a cada rato cambia la URL del producto y afecta su posicionamiento en buscadores.
• Use siempre los mismos nombres de categoría. NOTEBOOKS y Notebook son dos categorías distintas.

6Errores y bajas

La regla principal es que una lista vacía significa "no tengo ningún producto".

Cómo dar de baja un producto

Deje de incluirlo en la respuesta. En la siguiente actualización deja de mostrarse en la tienda. Si vuelve a incluirlo con el mismo código, se reactiva. Para un faltante temporal, en cambio, conviene mantenerlo con "stock": 0: sigue publicado como "Sin stock" y vuelve a venderse cuando llega stock.

7Frecuencia de actualización

Doopy consulta el endpoint de forma automática, a partir de una hora fija (hora de Paraguay), con una de estas frecuencias:

La hora y la frecuencia se acuerdan en el alta. Elija una hora de poca carga para su servidor. Doopy también puede lanzar una actualización a mano, por ejemplo después de un cambio de precios importante.

8Cotización del dólar Opcional

Si sus precios están en dólares y su sistema maneja una cotización propia, puede exponer un segundo endpoint con ella. Doopy lo usa para actualizar su cotización y recalcular sus precios en guaraníes.

• Método: POST, sin cuerpo.
• Autenticación: este endpoint se consulta sin headers. Si necesita protegerlo, incluya el token en la propia URL, por ejemplo ?token=....
• Respuesta: una lista con un elemento cuya descripcion sea "USD" y cuyo campo venta sea la cantidad de guaraníes por dólar.

[
  { "descripcion": "USD", "venta": 7300 }
]

Sin este endpoint, la cotización se actualiza desde el panel de proveedor o a pedido, con el equipo de Doopy.

9Imágenes y contenido

La API transmite datos comerciales: código, nombre, precio, moneda, categoría y stock. El contenido de la ficha se carga en Doopy aparte:

• Imágenes: envíe a Doopy las fotos de cada producto, identificadas con su codigo_barra (por ejemplo, 7891234567890.jpg, 7891234567890-2.jpg). Sin imagen, el producto no se muestra en la tienda.
• Descripción y ficha técnica: el equipo de Doopy las arma con la información del fabricante. Si tiene fichas propias, inclúyalas en el mismo envío.
• Marca: indíquela en el nombre del producto (ver nombres).

Los requisitos de las fotos están en Panel de proveedor › Imágenes.

10Validador

Pegue la respuesta de su endpoint para comprobar el formato antes de pasarla a Doopy. La validación se hace en su navegador: los datos no se envían a ningún lado.

11Antes de pasar a producción

Antes de activar la actualización automática, verifique que su endpoint cumpla esto:

• Responde por HTTPS con un certificado válido.
• Devuelve una lista JSON en el primer nivel, en UTF-8, en menos de 60 segundos.
• Incluye el catálogo completo en cada respuesta.
• Cada producto trae codigo_barra, nombre, precio_venta y moneda_txt, y en lo posible seccionTxt y stock.
• Los códigos son únicos y estables, con un prefijo propio si son internos.
• Ante un error responde con un código HTTP de error, nunca con 200 y una lista vacía.
• Pasa el validador sin errores.
• Ya envió a Doopy la URL, el método, los headers de autenticación y las imágenes de los productos.

Con eso, Doopy hace una primera importación de prueba, la revisa con usted y después activa la actualización automática. El proceso completo está en Alta y contacto.