Documentación

La API: tu primera solicitud en cinco minutos.

REST, JSON, una sola clave. Cada endpoint de abajo está activo y los ejemplos muestran la forma real de la respuesta.

¿Por qué controles pasa una llamada?el orden real en src/app.ts

Los controles se ejecutan en este orden: una solicitud cuya identidad no puede resolverse nunca toca la cuota, y una solicitud sin cuota suficiente nunca llega a la validación. No hay resultado parcial — un trabajo de 100 artículos con 40 restantes se rechaza por completo; devolver medio resultado como si fuera completo sería lo peor.

1 · Consigue una clave

Inicia sesión en el panel y genérala desde la pantalla API Anahtarları genérala. La clave en bruto se muestra una sola vez ; la base de datos solo guarda el hash SHA-256, y si se pierde se genera una nueva.

Generar una clave administrador requiere permisos de administrador. No se puede generar una clave nueva con una clave API — para que una sola clave filtrada no se convierta en un número infinito de claves permanentes.

2 · Autenticación

Envía la clave con uno de dos encabezados.

HTTPEncabezado de solicitud

x-api-key: gtin_live_XXXXXXXXXXXX
— o —
Authorization: Bearer gtin_live_XXXXXXXXXXXX

Una solicitud sin clave devuelve 401. Las solicitudes desde el panel usan la cookie de sesión; no se necesita clave.

3 · Número individual

La respuesta separa la validación matemática del estado de la fuente del producto.

GET/api/v1/gtins/{gtin}

{
  "valid": true,
  "status": "UNVERIFIED",
  "type": "GTIN-13",
  "gtin14": "04006381333931",
  "checkDigit": "1",
  "expectedCheckDigit": "1",
  "product": null
}

Las atribuciones de organización y país no se publican sin aprobación de licencia. UNVERIFIED significa que la comprobación matemática pasó sin coincidencia de producto.

4 · Validación por lotes

Una lista JSON o un cuerpo CSV directo. Hasta 10.000 números por trabajo.

POST/api/v1/batches

Content-Type: application/json

{ "gtins": ["4006381333931", "8690504045618"] }

— o un cuerpo CSV (text/csv): la columna GTIN se detecta automáticamente —

Endpoint	Qué hace
`POST /api/v1/batches`	Inicia el trabajo, `202` y devuelve un id de trabajo.
`GET /api/v1/batches`	Lista los trabajos recientes.
`GET /api/v1/batches/{id}`	Estado y progreso.
`GET /api/v1/batches/{id}/results`	Resultados; `offset` y `limit` paginados.
`GET /api/v1/batches/{id}/result.csv`	Descarga todo en CSV.

Resultados persistente — sobreviven incluso a un reinicio del servicio. Se conservan 60 minutos.

5 · Tu propio catálogo

Los campos que subes se devuelven en product en cada consulta. Subir un catálogo no descuenta de la cuota.

CSVColumnas esperadas

gtin,urun_adi,marka,kategori,gorsel_url
4006381333931,STABILO BOSS Fosforlu Kalem,STABILO,Kırtasiye,https://...
8690504045618,Çikolatalı Gofret 36 g,Örnek Marka,Gıda,

Columna	Obligatorio	Nota
`gtin`	sí	Cualquier formato GTIN; se normaliza a 14 dígitos.
`urun_adi`	no	Como máximo 300 caracteres.
`marka`	no
`kategori`	no	Texto libre.
`gorsel_url`	no	Solo `https` se acepta.

6 · Uso y cuota

GET/api/v1/usage

{ "requests": 128, "items": 4210 }

GET /api/v1/usage/daily da el desglose diario. Una solicitud difiere de un artículo: un lote de 100 números es 1 solicitud pero 100 artículos; se factura por artículo.

Códigos de respuesta

Seis códigos. Todos llegan con una clave error en el cuerpo; ninguno devuelve en silencio un resultado vacío.

¿Qué código y cuándo?un número inválido también es 200

El punto que confunde: un número inválido no es un error. La llamada tiene éxito, la respuesta dice valid: false. 400 solo se devuelve cuando la solicitud no coincide con el esquema de la API.

Lee tu cuota en la respuesta

No hace falta preguntar; cada respuesta lleva tu cupo restante. No tienes que enterarte del agotamiento de la cuota por un 402.

Encabezados devueltos en cada respuestapara que no haya cortes por sorpresa

7 · Límites y errores

Código	Cuándo	Qué hacer
`400`	No se pudo leer el cuerpo o el CSV.	Comprueba los nombres de campo y el formato.
`401`	Clave ausente, incorrecta o revocada.	Genera una clave nueva desde el panel.
`403`	Permisos insuficientes (p. ej. un miembro no puede generar claves).	Se requieren permisos de administrador.
`413`	El lote superó los 10.000 artículos.	Divide la lista.
`429`	Se superó el límite por minuto de solicitudes o artículos.	`retry-after` espera el tiempo que indica el encabezado.
`kota_doldu`	Tu cupo mensual de artículos está agotado.	Mejora el plan o espera al inicio del periodo.
`503`	Demasiados lotes abiertos a la vez.	Vuelve a intentarlo en breve.

Los encabezados de respuesta llevan tu cupo restante: x-ratelimit-remaining, x-item-ratelimit-remaining.

Consigue tu clave

Inicia sesión en el panel y genérala desde la pantalla Claves API. Si no tienes cuenta, tu administrador de organización abre una.

Iniciar sesión en el panel