API Documentation

API de Conversión de Formatos de Datos#

Los endpoints de Formatos de Datos convierten archivos de datos estructurados entre JSON, XML, YAML, CSV y TOML, además de renderizar Markdown a HTML completamente estilizado. Cada conversión es una única solicitud POST con una carga de archivo multipart/form-data: envías tu archivo y recibes el resultado convertido como bytes en bruto, o solicitas en su lugar una URL de descarga prefirmada. Los once endpoints siguen la misma forma de solicitud, autenticación y modelo de errores, por lo que integrar un segundo formato después del primero toma minutos.

Conversiones admitidas#

Conversión Endpoint Descripción
JSON a XML POST /v1/convert/json-to-xml Convierte JSON a XML con los objetos como hijos de <root>, los arrays envueltos en elementos <item> y los escalares en <value>.
XML a JSON POST /v1/convert/xml-to-json Convierte XML a JSON, asignando los atributos a claves con prefijo @, el contenido de texto a #text y los elementos hermanos repetidos a arrays.
JSON a YAML POST /v1/convert/json-to-yaml Asignación directa a YAML en estilo de bloque, legible por humanos, preservando el orden de las claves y el unicode.
YAML a JSON POST /v1/convert/yaml-to-json Analiza de forma segura archivos .yaml o .yml (sin ejecución de código arbitrario) en JSON formateado (pretty-printed) con sangría de 2 espacios.
JSON a CSV POST /v1/convert/json-to-csv Convierte un array JSON de objetos a CSV delimitado por comas, con encabezados tomados de las claves del primer objeto.
CSV a JSON POST /v1/convert/csv-to-json Convierte CSV a un array JSON donde la fila de encabezados se convierte en las claves y todos los valores permanecen como strings (sin inferencia de tipos).
JSON a TOML POST /v1/convert/json-to-toml Convierte JSON a TOML, envolviendo los arrays bajo una clave items y los escalares bajo value; los valores null se rechazan con un 400.
TOML a JSON POST /v1/convert/toml-to-json Convierte tablas y arrays de TOML a JSON formateado (pretty-printed), serializando los valores de fecha y hora como strings ISO-8601.
CSV a XML POST /v1/convert/csv-to-xml Convierte CSV a XML con los encabezados de columna como nombres de etiqueta de elemento y cada fila como un <item> dentro de <root>.
XML a CSV POST /v1/convert/xml-to-csv Aplana XML tabular (elementos hermanos repetidos con campos consistentes) en filas CSV delimitadas por comas.
Markdown a HTML POST /v1/convert/markdown-to-html Renderiza archivos .md o .markdown en una página HTML completa y autocontenida, con CSS incrustado, tablas, bloques de código, soporte de tabla de contenidos (TOC) y modo oscuro.

Convenciones compartidas#

  • Autenticación: todos los endpoints aceptan una clave de API privada mediante la cabecera X-API-Key o un token JWT Authorization: Bearer obtenido a partir de una clave pública. Consulta Autenticación.
  • Forma de la solicitud: todas las conversiones son POSTs síncronos multipart/form-data con un campo file obligatorio, además de los parámetros opcionales output_filename y direct_download. Consulta Trabajos síncronos y asíncronos.
  • Respuestas: por defecto (direct_download=true) el archivo convertido se devuelve como bytes en bruto; con direct_download=false recibes metadatos JSON que contienen presigned_url, object_key, filename, file_size y conversion_time_seconds.
  • Requisitos de entrada: todas las entradas deben estar codificadas en UTF-8 y coincidir con la extensión de archivo esperada; el tamaño máximo de archivo depende del plan (plan Founding: 5 MB).
  • Errores: los archivos inválidos o las conversiones fallidas devuelven 400, las credenciales faltantes o inválidas 401, los límites de plan excedidos 402, y los archivos demasiado grandes 413. Consulta Códigos de Error.

Preguntas frecuentes#

¿Cómo autentico las solicitudes a los endpoints de conversión de formatos de datos?#

Los once endpoints aceptan una clave de API privada en la cabecera X-API-Key o un token JWT Authorization: Bearer obtenido a partir de una clave pública. Las mismas credenciales funcionan en todas las conversiones. Consulta Autenticación para más detalles.

¿Puedo obtener una URL de descarga en lugar de los bytes del archivo convertido?#

Sí. Todos los endpoints devuelven el archivo convertido como bytes en bruto por defecto; establece direct_download=false para recibir en su lugar metadatos JSON con presigned_url, object_key, filename, file_size y conversion_time_seconds.

¿Qué límites de tamaño de archivo y de entrada se aplican a las conversiones de formatos de datos?#

El tamaño máximo de archivo depende del plan (plan Founding: 5 MB), y los archivos que superan el límite de tu plan devuelven 413 Payload Too Large. Todas las entradas deben estar codificadas en UTF-8, y los recuentos mensuales de conversión también dependen del plan: superarlos devuelve 402 Payment Required.

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