API de HCC2D

Autenticación

Envíe la clave en la cabecera Authorization:

Authorization: Bearer hcc2d_<64 hex chars>

Las solicitudes sin una clave válida se rechazan con HTTP 401.

URL base

https://hcc2d.com/api/v1

Endpoints

POST /api/v1/generate

Codifique un contenido en un símbolo HCC2D o QR y reciba una imagen PNG.

Cuerpo de la solicitud (JSON)

Campo	Tipo	Obligatorio	Descripción
payloadBase64	string	sí	Bytes del contenido codificados en base64
inputName	string	no	Nombre de archivo almacenado dentro del contenedor HCC2DF (por ejemplo payload.txt o data.pdf). El valor por defecto es payload.bin. Se ignora cuando structured: false.
structured	boolean	no	Envuelve el contenido en el contenedor HCC2DF (nombre de archivo + compresión zlib). El valor por defecto es true. Use false para guardar bytes sin contenedor. Conviene usar false para URL y vCard, de modo que el decodificador reconozca el contenido directamente. Consulte la referencia del formato HCC2DF.
mode	string	no	Tipo de símbolo: qr, hcc2d4 (4 colores), hcc2d8 (8 colores, por defecto)
ec	string	no	Nivel de corrección de errores: L, M, Q, H (por defecto M)
version	integer	no	Versión del símbolo (1–40). Use 0 para selección automática.
scale	integer	no	Píxeles por módulo (1–64, por defecto 12)
quietZone	integer	no	Anchura de la zona de silencio en módulos (0–64, por defecto 4)

Solicitud de ejemplo

curl -X POST https://hcc2d.com/api/v1/generate   -H "Authorization: Bearer hcc2d_<your-key>"   -H "Content-Type: application/json"   -d '{
    "payloadBase64": "SGVsbG8sIFdvcmxkIQ==",
    "inputName": "payload.txt",
    "structured": true,
    "mode": "hcc2d8",
    "ec": "M",
    "version": 0,
    "scale": 4,
    "quietZone": 4
  }' --output code.png

Respuesta correcta (200)

{
  "ok": true,
  "imageUrl": "/generated/<uuid>.png",
  "message": "Code generated successfully — Version 1"
}

Respuesta de error

{
  "ok": false,
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

Códigos de error

HTTP	Código	Significado
400	missing_payload	payloadBase64 no existe o está vacío
400	invalid_base64	payloadBase64 no es base64 válido
400	empty_payload	El contenido decodificado tiene cero bytes
400	payload_over_max	El contenido supera el límite previo a la codificación del servidor
400	too_large_settings	El contenido cabe en general, pero no con la combinación solicitada de versión, EC y modo
400	too_large_absolute	El contenido supera la capacidad absoluta de cualquier símbolo. Reduzca el tamaño.
400	encoder_failed	El codificador rechazó la entrada por un motivo distinto de la capacidad
400	invalid_mode / invalid_ec / invalid_version / invalid_scale / invalid_quiet_zone	Un parámetro está fuera del rango permitido
401	auth_required	La clave API falta, es inválida o ha sido revocada
413	body_too_large	El cuerpo HTTP supera el límite del parser
415	unsupported_media_type	Content-Type no es application/json
429	rate_limited	Se alcanzó el límite por clave o por IP
429	too_many_jobs	El servidor alcanzó el límite de trabajos concurrentes
500	internal_error	Fallo interno inesperado
502	missing_output	El codificador terminó sin producir imagen
503	encoder_unavailable	El binario del codificador no está disponible
504	encoder_timeout	El proceso de codificación superó el tiempo límite

Límites de tasa

Límite	Valor
Por clave API	30 solicitudes / minuto
Por IP (con clave)	60 solicitudes / minuto
Bloqueo por fuerza bruta	10 fallos de autenticación / 15 min bloquean la IP durante 15 min

Cuando se alcanza un límite, el servidor devuelve 429 con la cabecera Retry-After.

¿Necesita límites más altos? Escriba a info@hcc2d.com.

Límites del tamaño de carga

Capa	Límite	Aplicado por
Parser del cuerpo	~86 KB	Servidor, antes de analizar el JSON — devuelve body_too_large
Control previo	65.536 bytes (64 KB)	Servidor, tras decodificar base64 — devuelve payload_over_max
Máximo absoluto del código	~8.859 bytes	Codificador — devuelve too_large_absolute
Límite según ajustes	Depende de la versión y del nivel EC	Codificador — devuelve too_large_settings

Por defecto, el servidor aplica compresión zlib mediante el contenedor HCC2DF antes de codificar, por lo que entradas de hasta 64 KB a menudo pueden caber. Pase structured: false para omitir el contenedor y codificar bytes sin procesar.

La interfaz web aplica además un límite de 64 KB para cargas desde el navegador, alineado con la validación del servidor.

Recuperación de imágenes

Los PNG generados se sirven en https://hcc2d.com<imageUrl> y se conservan durante 1 hora. Descárguelos poco después de generarlos.

Obtener una clave API

Solicite una clave API mediante el formulario oficial.

Más información

Referencia del formato HCC2DF — diseño binario campo por campo del contenedor estructurado.

Ejemplos de código — fragmentos listos para usar en JavaScript, Python, Java y PHP.