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
| Campo | Tipo | Descripció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
| HTTP | error | Descripción |
|---|---|---|
400 | invalid_json | El cuerpo no es un JSON legible. |
401 | unauthorized | Token ausente, no válido o revocado. |
403 | suspended | El vendedor está suspendido en el marketplace: su token deja de publicar hasta su reintegración. |
403 | closed | La API no está abierta en este marketplace. |
404 | not_found | Ningún anuncio de este vendedor lleva esta referencia. |
422 | invalid_payload | Cuerpo no válido: sin lista, lista vacía, demasiados artículos, o janus y dry_run juntos. |
429 | rate_limited | Demasiadas llamadas: vuelva a intentarlo tras el plazo del encabezado Retry-After. |
503 | rate_limiter_unavailable | El 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.