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 único

¿Cómo se resuelve un número?en una sola solicitud

El campo issuer en la respuesta contiene este prefijo. Atención: el prefijo no es el país de origen ; indica quién emitió el número.

¿Cómo se calcula el dígito de control?GS1 mod-10

Este cálculo de la página no se escribió a mano; se generó con la misma regla que usa el producto. Por eso, ante un número inválido, no solo decimos «inválido» sino que también indicamos el el dígito que debería ser.

GET/v1/gtins/{gtin}

{
  "input": "4006381333931",
  "compact": "4006381333931",
  "valid": true,
  "type": "GTIN-13",
  "gtin14": "04006381333931",
  "checkDigit": "1",
  "expectedCheckDigit": "1",
  "issues": [],
  "issuer": {
    "prefix": "400-440",
    "issuer": "GS1 Germany",
    "countryCode": "DE",
    "kind": "company"
  },
  "product": null
}

Campo	Qué
`valid`	Si el dígito de control cumple la regla GS1 mod-10.
`type`	`GTIN-8`, `GTIN-12`, `GTIN-13`, `GTIN-14`.
`gtin14`	El equivalente de 14 dígitos: úsalo para la correspondencia.
`expectedCheckDigit`	El dígito que debería ser si es inválido.
`issues`	Códigos de problema; un arreglo vacío si es válido.
`issuer`	La organización GS1 que emitió el número, el país y el prefijo. Para un prefijo no asignado, `null`.
`product`	Desde tu propio catálogo: nombre, marca, categoría, imagen. Si no está en tu catálogo, `null`.

4 · Validación por lotes

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

POST/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 /v1/batches`	Inicia el trabajo, `202` y devuelve un id de trabajo.
`GET /v1/batches`	Lista los trabajos recientes.
`GET /v1/batches/{id}`	Estado y progreso.
`GET /v1/batches/{id}/results`	Resultados; `offset` ve `limit` paginados.
`GET /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/v1/usage

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

GET /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 un número no puede leerse en absoluto.

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