Quien vende en Kaufland acaba encontrándose con la Seller API. A veces porque quiere automatizar algo por su cuenta; más a menudo porque un programa le pide sus claves. En los dos casos conviene saber qué permiten esas claves, dónde se generan y qué pasa si las pierde.
Todo lo técnico de este artículo sale de la documentación de la API de Kaufland, consultada el 30 de septiembre de 2026. Esa documentación está en inglés; aquí va lo esencial en español.
Qué es la Seller API
La Marketplace Seller API de Kaufland es una API REST. Su programa envía peticiones HTTPS cifradas a una dirección fija (en los ejemplos de Kaufland, https://sellerapi.kaufland.com/v2/) y recibe datos o ejecuta una acción: descargar pedidos, cambiar precios y stock, marcar un envío, contestar tickets o gestionar devoluciones y cupones, entre otras cosas.
Kaufland describe la autenticación como basada en contraseña y HMAC. Es decir: tiene dos claves y cada petición lleva una firma calculada con la clave secreta. La clave secreta no viaja en la petición. No hay acceso anónimo.
La Seller University lo resume así: Kaufland está integrado con muchas soluciones de gestión de ventas, sistemas de gestión de inventario y tiendas online y quien prefiera un desarrollo propio tiene la API REST documentada.
Las dos claves
- Client key: 32 caracteres. Identifica su cuenta en cada petición.
- Secret key: 64 caracteres. Con ella se firma cada petición. Quien la tiene puede trabajar con la API en su nombre.
Las claves se generan en el Portal del vendedor, en la página de ajustes de API (sellerportal.kaufland.de/settings/api). Kaufland advierte: no pierda sus claves, porque por seguridad no se pueden recuperar. Solo puede generar otras nuevas.
Esto tiene una consecuencia que se olvida con facilidad. Si genera claves nuevas, tendrá que introducirlas de nuevo en todo lo que se conecta a su cuenta: sus propios scripts y también cualquier programa que tenga conectado.
Cómo es una petición
Cada petición necesita cinco cabeceras. Según la documentación:
| Cabecera | Contenido |
|---|---|
| Accept | Siempre application/json. |
| Shop-Client-Key | Su client key. |
| Shop-Timestamp | El momento de la petición en tiempo Unix (segundos), con un margen de 5 minutos respecto a la hora del servidor de Kaufland. |
| Shop-Signature | La firma, calculada con su secret key. |
| User-Agent | El nombre de su programa o, si la conexión es un desarrollo propio, «Inhouse_development». |
En las peticiones POST y PATCH se añade Content-Type: application/json. La firma es un HMAC SHA-256 sobre cuatro datos separados por saltos de línea: el método (GET, POST…), la URI completa, el cuerpo y el timestamp. Si falla un solo carácter, la firma no coincide y la petición no se ejecuta. Kaufland ofrece una calculadora de firmas (Signature Calculator) para comprobar sus cálculos.
El margen de 5 minutos es una trampa conocida. Un servidor con el reloj adelantado o atrasado produce errores que parecen de clave incorrecta. Antes de dudar de sus claves, compruebe que el servidor sincroniza la hora automáticamente.
El límite: 111 peticiones por segundo
Kaufland aplica un límite de 111 peticiones por segundo por vendedor, sumando todos los endpoints. Si lo supera, la API responde con el código HTTP 429 y no procesa las peticiones.
Para un script es mucho margen. Se queda corto cuando varios programas trabajan a la vez con la misma cuenta, porque todos cuentan en el mismo contador. Por ejemplo, un script de stock que recorre todo el catálogo cada minuto y otro programa que descarga pedidos a la vez pueden estorbarse sin que ninguno haga nada mal.
Si desarrolla usted, gestione el 429: espere un momento y reintente, en lugar de volver a lanzar todas las peticiones de golpe.
Para qué usan los vendedores la API
Hay dos caminos:
- Desarrollo propio. Un script que, por ejemplo, pasa el stock de su sistema de almacén a Kaufland o descarga los pedidos para su contabilidad. La firma, los límites y los errores corren de su cuenta.
- Conectar un programa. Introduce su client key y su secret key en un programa que ya habla con la API. El programa hace el trabajo y usted decide quién tiene sus claves.
Sellgrip es del segundo tipo. Se conecta mediante la Seller API de Kaufland: usted introduce sus dos claves y Sellgrip las guarda cifradas. A partir de ahí lee sus pedidos y sus productos, entre otras cosas y le envía alertas cuando hay dinero o un plazo en juego. Todas las herramientas están en Funciones.
Cómo proteger sus claves
La secret key es una contraseña con todos los permisos. Trátela como tal.
- Nunca por correo ni por chat. Una clave que está en un buzón seguirá ahí dentro de tres años.
- Nunca en código compartido. Guárdela en un archivo de configuración o en una variable de entorno, fuera del control de versiones.
- Una lista de quién la tiene. Anote cada programa y cada persona que usa sus claves; así cambiarlas es sencillo.
- Cámbielas si hay dudas. Si se va un empleado o deja de usar un programa, genere claves nuevas y vuelva a conectar solo lo que quiera mantener.
Dónde está la documentación
Kaufland publica la documentación en sellerapi.kaufland.com, con la lista de endpoints y una página sobre los límites, en inglés. Para marcar envíos por API se usan los códigos de transportista que Kaufland publica allí; entre ellos están Correos, Seur, GLS, DHL, DPD y UPS.
