Actualidad Apertura a compradores el 1 de diciembre. Vendedores, publiquen ya sus activos.

Inicio · API de ingesta

API de ingesta

La API de ingesta permite a un vendedor acreditado enviar sus anuncios y sus stocks desde su ERP. Pasa por la misma cadena que la importación de archivos: mismos controles, mismos valores por defecto.

La descripción OpenAPI de la API, para importar en Postman, Insomnia o un editor Swagger: openapi.json, openapi.yaml (OpenAPI 3.1.0)

Autenticación

Cada llamada lleva el token del vendedor en la cabecera Authorization. El token clasifica todo lo que envía bajo la empresa vendedora que lo creó.

Authorization: Bearer sqh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Los tokens se crean y se revocan en Mi Espacio, Integración, por un administrador del equipo.

Probar sin escribir nada

Añada dry_run=1 a una llamada de escritura: el lote se controla como lo sería, y la respuesta devuelve el mismo informe (creaciones, actualizaciones, rechazos detallados), pero no se escribe nada, ni anuncio, ni stock, ni paso en el registro. Cualquier token lo permite: es el token de prueba de su primera integración.

Cree un token en Mi Espacio, guarde el lote de ejemplo siguiente en lot.json y ejecute:

export SQH_TOKEN="sqh_..."
curl -X POST "https://sqhubb.com/api/v1/ingestion/listings?dry_run=1" \
  -H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
  --data @lot.json

Reglas

  • 60 llamadas por minuto y por token; más allá, respuesta 429 con la cabecera Retry-After.
  • Como máximo 500 artículos por llamada.
  • La referencia del vendedor es obligatoria. Una referencia ya conocida actualiza su anuncio: repetir una llamada nunca crea duplicados.
  • Un anuncio creado por la API nace como borrador y pasa por la moderación del marketplace antes de su publicación. Solo se modifican los campos enviados.

POST https://sqhubb.com/api/v1/ingestion/listings

Crea o actualiza anuncios, por lotes.

Un lote de ejemplo (lot.json): un anuncio completo, y luego la actualización del precio y del stock de una referencia ya conocida.

{
  "listings": [
    {
      "reference": "SKU-001",
      "title": "Réducteur SEW R97",
      "price": 1850,
      "currency": "EUR",
      "quantity": 3,
      "condition": "new_unused",
      "incoterm": "EXW",
      "brand": "SEW",
      "model": "R97",
      "origin_country": "DE",
      "pickup_country": "FR",
      "unit_weight_kg": 120,
      "certifications": [
        "CE"
      ],
      "price_tiers": [
        {
          "min_quantity": 2,
          "unit_price": 1750
        }
      ],
      "images": [
        "https://images.example.com/sku-001-face.jpg"
      ],
      "specifications": {
        "puissance": "7,5 kW",
        "hs_code": "8483.40"
      }
    },
    {
      "reference": "SKU-002",
      "price": 940,
      "quantity": 0
    }
  ]
}
curl -X POST "https://sqhubb.com/api/v1/ingestion/listings" \
  -H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
  --data @lot.json

Cuando el marketplace ha abierto Janus en importación, añada janus=1: los artículos se convierten en una importación Janus recibida (vinculación a la taxonomía, enriquecimiento), que usted lanza desde Mi Espacio tras ver su coste.

POST https://sqhubb.com/api/v1/ingestion/listings?janus=1

Campos de un artículo

CampoTipoDescripción
reference * string Su referencia, obligatoria y única en su catálogo.
title string El título del anuncio, obligatorio en la creación.
description string La descripción, en francés.
summary string Un resumen de una línea.
category string La familia: su nombre o su identificador (slug).
condition string El estado del bien (valores abajo).
price number El precio unitario sin impuestos.
reference_price number El precio de referencia (nuevo o de mercado), superior al precio.
currency string La divisa, EUR por defecto.
quantity integer La cantidad disponible.
sale_unit string La unidad de venta (unit, lot, tonne, kilogram, pallet...).
lot_size integer El tamaño del lote.
minimum_order_quantity integer La cantidad mínima de pedido.
packaging string El embalaje (pallet, wooden_crate, big_bag...).
incoterm string El Incoterm 2020 (valores abajo).
pickup_country string El país de recogida, código ISO de dos letras.
pickup_region string La región de recogida.
pickup_city string La ciudad de recogida.
pickup_postal_code string El código postal de recogida.
origin_country string El país de origen, código ISO de dos letras.
brand string La marca.
model string El modelo o la referencia del fabricante.
year_of_manufacture integer El año de fabricación.
unit_weight_kg number El peso unitario en kilogramos.
length_cm integer La longitud en centímetros.
width_cm integer La anchura en centímetros.
height_cm integer La altura en centímetros.
seo_title string El título para los motores de búsqueda.
seo_description string La descripción para los motores de búsqueda.
certifications array La lista de certificaciones y sellos, por ejemplo ["CE", "ISO 9001"].
price_tiers array Los tramos de precio por volumen sin IVA, por ejemplo [{"min_quantity": 10, "unit_price": 95}]. Un tramo igual o superior al precio base se descarta.
images array Las direcciones web de las fotos (JPEG, PNG o WebP, 10 MB como máximo), cinco como máximo. La primera se convierte en la foto principal. Se descargan después de guardar el anuncio.
specifications object Las características de la familia, como objeto clave y valor.

Estados: new_unused, new_surplus, workshop_checked, audited, good_condition, dismantled_tagged, for_parts. Incoterms: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP.

POST https://sqhubb.com/api/v1/ingestion/stocks

Actualiza la cantidad disponible, y el precio si se indica, por referencia. Una referencia desconocida se rechaza, nunca se crea.

curl -X POST "https://sqhubb.com/api/v1/ingestion/stocks" \
  -H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
  -d '{"stocks":[{"reference":"SKU-001","quantity":2},{"reference":"SKU-002","quantity":5,"price":900}]}'

GET https://sqhubb.com/api/v1/ingestion/listings/:reference

Lee un anuncio por su referencia: estado, precio, stock, traducciones.

curl "https://sqhubb.com/api/v1/ingestion/listings/SKU-001" -H "Authorization: Bearer $SQH_TOKEN"

GET https://sqhubb.com/api/v1/ingestion/runs

Las veinte últimas ejecuciones, por la API y por la sincronización diaria.

Respuesta

{"run": {"id": 42, "channel": "api", "kind": "listings", "status": "partial",
         "received": 2, "created": 1, "updated": 0, "rejected": 1,
         "rejections": [{"reference": "SKU-002", "reasons": ["…"]}]}}

En modo de prueba, la respuesta lleva también "dry_run": true, y el paso no tiene identificador: no se registra.

  • ok : todo ha pasado.
  • partial : una parte ha pasado, los rechazos se detallan.
  • failed : nada ha pasado.
  • unchanged : el flujo diario no ha cambiado, no se vuelve a procesar nada.
  • janus_received : la importación Janus está recibida, para lanzar desde Mi Espacio.

Errores

HTTPerrorDescripción
400invalid_jsonEl cuerpo no es un JSON legible.
401unauthorizedToken ausente, no válido o revocado.
403suspendedEl vendedor está suspendido en el marketplace: su token deja de publicar hasta su reintegración.
403closedLa API no está abierta en este marketplace.
404not_foundNingún anuncio de este vendedor lleva esta referencia.
422invalid_payloadCuerpo no válido: sin lista, lista vacía, demasiados artículos, o janus y dry_run juntos.
429rate_limitedDemasiadas llamadas: vuelva a intentarlo tras el plazo del encabezado Retry-After.
503rate_limiter_unavailableEl control de caudal no está disponible por el momento: reintente tras el plazo indicado.

Sincronización diaria

En lugar de llamar a la API, puede declarar en Mi Espacio la dirección HTTPS de un flujo CSV o XLSX, con las columnas de la plantilla de importación. El marketplace lo lee cada noche, no vuelve a procesar un archivo sin cambios y anota cada ejecución en el registro.