API Documentation

API di Conversione Formati Dati#

Gli endpoint Data Formats convertono file di dati strutturati tra JSON, XML, YAML, CSV e TOML, oltre a renderizzare Markdown in HTML completamente stilizzato. Ogni conversione è una singola richiesta POST con un upload di file multipart/form-data: invii il tuo file e ricevi indietro il risultato convertito come byte grezzi, oppure richiedi invece un URL di download presigned. Tutti e undici gli endpoint seguono la stessa forma di richiesta, autenticazione e modello di errore, quindi integrare un secondo formato dopo il primo richiede pochi minuti.

Conversioni supportate#

Conversione Endpoint Descrizione
JSON in XML POST /v1/convert/json-to-xml Converte JSON in XML con gli oggetti come figli di <root>, gli array racchiusi in elementi <item> e gli scalari in <value>.
XML in JSON POST /v1/convert/xml-to-json Converte XML in JSON, mappando gli attributi in chiavi con prefisso @, il contenuto testuale in #text e gli elementi fratelli ripetuti in array.
JSON in YAML POST /v1/convert/json-to-yaml Mappatura diretta in YAML block-style leggibile, con ordine delle chiavi e unicode preservati.
YAML in JSON POST /v1/convert/yaml-to-json Analizza in modo sicuro file .yaml o .yml (nessuna esecuzione di codice arbitrario) in JSON con indentazione a 2 spazi e formattazione leggibile.
JSON in CSV POST /v1/convert/json-to-csv Converte un array JSON di oggetti in CSV delimitato da virgole, con intestazioni prese dalle chiavi del primo oggetto.
CSV in JSON POST /v1/convert/csv-to-json Converte CSV in un array JSON in cui la riga di intestazione diventa le chiavi e ogni valore resta una stringa (nessuna inferenza di tipo).
JSON in TOML POST /v1/convert/json-to-toml Converte JSON in TOML, racchiudendo gli array sotto una chiave items e gli scalari sotto value; i valori null vengono rifiutati con un 400.
TOML in JSON POST /v1/convert/toml-to-json Converte tabelle e array TOML in JSON con formattazione leggibile, serializzando i valori datetime come stringhe ISO-8601.
CSV in XML POST /v1/convert/csv-to-xml Converte CSV in XML con le intestazioni di colonna come nomi di tag elemento e ogni riga come un <item> dentro <root>.
XML in CSV POST /v1/convert/xml-to-csv Appiattisce XML tabellare (elementi fratelli ripetuti con campi coerenti) in righe CSV delimitate da virgole.
Markdown in HTML POST /v1/convert/markdown-to-html Renderizza file .md o .markdown in una pagina HTML completa e autonoma con CSS incorporato, tabelle, blocchi di codice, supporto TOC e modalità scura.

Convenzioni condivise#

  • Autenticazione: ogni endpoint accetta sia una chiave API privata tramite l'header X-API-Key sia un token JWT Authorization: Bearer ottenuto da una chiave pubblica. Consulta Autenticazione.
  • Forma della richiesta: tutte le conversioni sono POST sincroni multipart/form-data con un campo file obbligatorio più i parametri opzionali output_filename e direct_download. Consulta Job sync e async.
  • Risposte: per impostazione predefinita (direct_download=true) il file convertito viene restituito come byte grezzi; con direct_download=false ricevi metadati JSON contenenti presigned_url, object_key, filename, file_size e conversion_time_seconds.
  • Requisiti di input: tutti gli input devono essere codificati in UTF-8 e corrispondere all'estensione di file attesa; la dimensione massima del file dipende dal piano (piano Founding: 5 MB).
  • Errori: file non validi o conversioni fallite restituiscono 400, credenziali mancanti o non valide 401, limiti di piano superati 402, e file troppo grandi 413. Consulta Codici di Errore.

Domande frequenti#

Come autentico le richieste agli endpoint di conversione dei formati dati?#

Tutti e undici gli endpoint accettano sia una chiave API privata nell'header X-API-Key sia un token JWT Authorization: Bearer ottenuto da una chiave pubblica. Le stesse credenziali funzionano per ogni conversione. Consulta Autenticazione per i dettagli.

Posso ottenere un URL di download invece dei byte del file convertito?#

Sì. Ogni endpoint restituisce per impostazione predefinita il file convertito come byte grezzi; imposta direct_download=false per ricevere invece metadati JSON con presigned_url, object_key, filename, file_size e conversion_time_seconds.

Quali limiti di dimensione file e di input si applicano alle conversioni di formati dati?#

La dimensione massima del file dipende dal piano (piano Founding: 5 MB), e i file che superano il limite del tuo piano restituiscono 413 Payload Too Large. Tutti gli input devono essere codificati in UTF-8, e anche i conteggi mensili di conversione dipendono dal piano: superarli restituisce 402 Payment Required.

← ots-to-pdf json-to-xml →