API HCC2D

Autenticazione

Passa la chiave nell'header Authorization:

Authorization: Bearer hcc2d_<64 hex chars>

Le richieste senza una chiave valida vengono rifiutate con HTTP 401.

URL base

https://hcc2d.com/api/v1

Endpoint

POST /api/v1/generate

Codifica un payload in un simbolo HCC2D o QR e ricevi un'immagine PNG.

Corpo della richiesta (JSON)

Campo	Tipo	Obbligatorio	Descrizione
payloadBase64	string	sì	Byte del payload codificati in base64
inputName	string	no	Nome file memorizzato nel contenitore HCC2DF (ad esempio payload.txt o data.pdf). Il valore predefinito è payload.bin. Ignorato quando structured: false.
structured	boolean	no	Avvolge il payload nel contenitore HCC2DF (nome file + compressione zlib). Il valore predefinito è true. Imposta false per salvare byte grezzi senza contenitore. È consigliato per URL e vCard, così il decoder riconosce direttamente il contenuto. Vedi la referenza del formato HCC2DF.
mode	string	no	Tipo di simbolo: qr, hcc2d4 (4 colori), hcc2d8 (8 colori, predefinito)
ec	string	no	Livello di correzione d'errore: L, M, Q, H (predefinito M)
version	integer	no	Versione del simbolo (1–40). Usa 0 per la selezione automatica.
scale	integer	no	Pixel per modulo (1–64, predefinito 12)
quietZone	integer	no	Ampiezza della quiet zone in moduli (0–64, predefinito 4)

Richiesta di esempio

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

Risposta di successo (200)

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

Risposta di errore

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

Codici di errore

HTTP	Codice	Significato
400	missing_payload	payloadBase64 manca o è vuoto
400	invalid_base64	payloadBase64 non è base64 valido
400	empty_payload	Il payload decodificato è vuoto
400	payload_over_max	Il payload supera il limite del server prima della codifica
400	too_large_settings	Il payload rientra nel limite assoluto ma non con la combinazione richiesta di versione, EC e modalità
400	too_large_absolute	Il payload supera la capacità assoluta di qualsiasi simbolo. Riduci la dimensione.
400	encoder_failed	L'encoder ha rifiutato l'input per un motivo diverso dalla capacità
400	invalid_mode / invalid_ec / invalid_version / invalid_scale / invalid_quiet_zone	Un parametro della richiesta è fuori intervallo
401	auth_required	Chiave API mancante, non valida o revocata
413	body_too_large	Il corpo HTTP supera il limite del parser
415	unsupported_media_type	Content-Type non è application/json
429	rate_limited	Raggiunto il limite di richieste per chiave o per IP
429	too_many_jobs	Il server ha raggiunto il limite di job concorrenti
500	internal_error	Errore interno imprevisto
502	missing_output	L'encoder è terminato senza produrre un'immagine
503	encoder_unavailable	Il binario dell'encoder non è disponibile
504	encoder_timeout	Il processo ha superato il timeout

Limiti di frequenza

Limite	Valore
Per chiave API	30 richieste / minuto
Per IP (con chiave)	60 richieste / minuto
Blocco anti brute-force	10 tentativi falliti / 15 min bloccano l'IP per 15 min

Quando viene raggiunto un limite, il server restituisce 429 con header Retry-After.

Hai bisogno di limiti più alti? Scrivi a info@hcc2d.com.

Limiti di dimensione del payload

Livello	Limite	Applicato da
Parser del body	~86 KB	Server, prima del parsing JSON — restituisce body_too_large
Controllo preliminare	65.536 byte (64 KB)	Server, dopo la decodifica base64 — restituisce payload_over_max
Massimo assoluto del codice	~8.859 byte	Encoder — restituisce too_large_absolute
Limite specifico delle impostazioni	Dipende da versione ed EC	Encoder — restituisce too_large_settings

Per impostazione predefinita, il server applica la compressione zlib tramite il contenitore HCC2DF prima della codifica, quindi input grezzi fino a 64 KB possono spesso ancora entrare. Passa structured: false per saltare il contenitore e codificare byte grezzi.

L'interfaccia web applica inoltre un limite client-side di 64 KB per gli upload, allineato al controllo del server.

Recupero immagini

I PNG generati sono serviti su https://hcc2d.com<imageUrl> e restano disponibili per 1 ora. Scaricali subito dopo la generazione.

Ottieni una chiave API

Richiedi una chiave API tramite il modulo ufficiale.

Approfondimenti

Riferimento del formato HCC2DF — layout binario campo per campo del contenitore strutturato.

Esempi di codice — snippet pronti in JavaScript, Python, Java e PHP.