HTMLToImage » Documentación técnica

API para convertir documentos HTML con CSS y Javascript a múltiples formatos de imagen.

Esta API permite a su aplicación realizar capturas de pantalla de sitios web o documentos HTML, y puede ser usada tanto para realizar screenshots de páginas web como para capturar elementos especificos en el DOM, permitiendo a su aplicación crear imágenes en múltiples formatos como PNG o WEBP usando tecnologías web.

Conectando a la API

Servidor y protocolos para la conexión

Conexión a la API
Servidor:	https://zpk.systems
Esquema:	HTTPS, solo conexiones seguras SSL.
Protocolo:	JSON recomendado Enviando un JSON en el body del request, y especificando una cabecera Content-Type: application/json en el request Si envia ficheros como imágenes o documentos, estos deberán estar codificados en base64. Form-Data no recomendado Formato usado en los formularios web, no recomendado. Al enviar una solicitud tipo form_data puede enviar todos los campos como parámetros POST separados. Sin embargo si la solicitud es muy grande recomendamos que envie el contenido de la peticion en un único campo de texto llamado _json (con un guión bajo). Este parametro especial sera procesado por nuestro backend como si se tratase de una solicitud JSON habitual.

El servidor dónde enviar las solicitudes es https://zpk.systems mediante una conexión HTTPS segura.

El tipo de comunicación recomendado es JSON, en cuyo caso especificaremos en la conexión un Content-Type: application/json, y enviaremos el body de la solicitud como un string JSON válido.

Convertir una pagina o elemento HTML a imagen

Endpoint y parámetros de la solicitud

Solicitud de captura

Llame al endpoint /capture especificando el documento HTML y los elementos a capturar.

POST /api/htmltoimage/capture
Parámetro	Descripción
application_id	alfanumérico requerido Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación
url	string requerido si no especificó html La URL a cargar antes de realizar la captura, esta puede incluir puerto y parámetros GET extra. Nuestros sistemas esperarán a que la página este totálmente cargada antes de iniciar la captura para que CSS, fuentes, e imágenes sean capturados correctamente. El tiempo máximo de espera para que la página sea cargada en su totalidad es de 8 segundos.
resolution_width	integer opcional y por defecto 1920 máx:3200 \| min:320 El ancho en pixels de la ventana virtual de captura, tenga en cuenta que las páginas responsivas se adaptarán a la resolución especificada. Los parámetros de resolución pueden usarse para obtener la versión de la página adaptada a diferentes dispositivos como desktop, smartphone, o tablet.
resolution_height	integer opcional y por defecto 1080 máx:3200 \| min:320 El alto en pixels de la ventana virtual de captura, tenga en cuenta que las páginas responsivas se adaptarán a la resolución especificada. Los parámetros de resolución pueden usarse para obtener la versión de la página adaptada a diferentes dispositivos como desktop, smartphone, o tablet.
injected_js	string opcional Código javascript que será ejecutado en cuanto la página sea cargada. Cuando la ejecución de este código termine, se procederá a la captura de las imágenes. Este código permite interactuar con elementos de la página antes de hacer la captura, por ejemplo para cerrar un posible aviso de cookies.
capture_list	array de elementos requerido Una lista de objetos que definen que partes del documento capturar y como debe realizarse esta captura. Consulte la siguiente tabla para ver el formato de esta lista y como configurar la captura de uno o múltiples elementos del DOM.

Formato de capture_list

Este array contiene la informción sobre que elementos de la página capturar.

Formato del array capture_list
Parámetro	Descripción
selector	alfanumérico requerido Un selector tipo CSS del elemento a capturar, ejemplos de selector: body: Todo el body del documento. #main_list:first-child .card: El primer elemento con clase 'card' en el primer hijo del elemento con id 'main_list' .card:nth-child(3): El elemento con clase 'card' que es el tercer elemento de su contenedor.
force_transparency	boleano opcional y por defecto false Establecer este parámetro a true eliminara el fondo establecido por la página en el elemento seleccionado, y en todos los elementos superiores en la jerarquía del DOM, buscando forzar que la imagen final tenga color transparente. Es importante tener en cuenta que estos cambios en el DOM no se deshacen hasta realizar una nueva solicitud a la API.
force_parent_transparency	boleano opcional y por defecto false Establecer este parámetro a true eliminara el fondo establecido por la página en el elemento padre, y en todos los elementos superiores en la jerarquía del DOM, buscando forzar que el contenedor del selector tenga color transparente, pero sin eliminar el color o la imagen de fondo del elemento apuntado por el selector. Es importante tener en cuenta que estos cambios en el DOM no se deshacen hasta realizar una nueva solicitud a la api.
output_format	alfanumérico opcional y por defecto png El formato de imágen retornado. Se soporta jpeg, webp, y png. Notese que PNG siempre tiene la misma calidad de salida, y por lo tanto el parámetro output_quality será ignorado por la API en caso de ser especificado.
output_quality	entero opcional y por defecto 80 La calidad de la imagen retornada, a mayor calidad mayor será el tamaño de la imagen. La máxima calidad es 100, por defecto 80. Este parámetro solo se aplica a formatos que soporten calidad de salida, webp y jpeg. En imágenes PNG este parámetro será ignorado.

Respuesta a captura

Respuesta con éxito

Respuesta OK

{
  "success": true,
  "results": [
    {
      "selector": "#list:first-child",
      "success": true,
      "download_url": "http://zpk.systems/api-results/html-to-image/download/SDFKJ98jjsdfDsfpaapsZWSXXX/4893.webp"
    },
    {
      "selector": "#unexisting_element_id",
      "success": false,
      "error": "NO_MATCH_FOR_SELECTOR"
    }
  ],
  "costs": {
    "base_request_cost": 0.002,
    "price_extra_pixels": 0.0003,
    "total_cost": 0.0023
  }
}

En este ejemplo se pudo capturar el primer elemento, pero el segundo elemento no pudo ser capturado debido a que no hay ningún elemento en la página que coincida con el selector.

Estructura de respuesta

Estructura de respuesta
Parámetro	Descripción
success	boleano Un boleano con valor true si se pudo procesar su solicitud. O false, en caso de errores.
results	array Un array de objetos que contiene los datos de captura de cada elemento solicitado, la url de descarga, y un código de error en caso de que se detectase algún problema. Consulte la siguiente tabla para detalles sobre los elementos de este array.
costs	array : asociativo Información detallada del coste de la solicitud enviada, donde: base_request_cost: El coste de la petición de captura 0,002 €. total_cost: El coste total de esta solicitud, que en esta API es el mismo que base_request_cost.
errors	array Uno o más errores en caso de que se hayan producido, el array de errores solo es retornado en caso de que el boleano success sea false. Cada elemento del array errors contiene: id: Un código identificador del error. on: Un indicador del elemento en los datos enviados que esta provocando el error. (solo en caso de errores provocados por un envío de datos incorrectos) message: Un texto informando de los detalles del error para poder hacer debug.

Estructura del array results

Estructura del array *results*
Parámetro	Descripción
selector	string El selector enviado para apuntar a un elemento
success	boleano Un boleando indicando si este elemento pudo ser capturado, true en caso afirmativo.
download_url	string Una dirección URL dónde descargar la imagen generada para el elemento. Esta imágen se mantiene en nuestros servidores durante un máximo de 24 horas y puede ser descargada un máximo de diez veces.
error	string Solo en caso de errores contendrá un string indicando el tipo de error Estos son los posibles errores retornados cuando no se pudo procesar la imagen. NO_MATCH_FOR_SELECTOR: No se encontró ningún elemento que coincida con el selector indicado. UNEXPECTED_ERROR: Este es un error interno que no debería suceder, contacte con ZPK

Ejemplo de respuesta con error general

Respuesta ERROR

{
  "success": false,
  "errors": [
    {
      "id": "MISSING_REQUIRED_PARAMETER",
      "message": "Parameter 'url' is required",
	  "on": "url"
    }
  ]
}

Gestión y depuración de errores

Errores generales y errores de captura

Esta API retorna dos tipos de errores, un error general si no se puede acceder a la URL del documento, y errores especificos a una captura de elemento dentro de la página.

Un error general indica que no se pudo acceder al documento, y por lo tanto impiden capturar ninguno de los elementos.

Debemos tener en cuenta que esta API no considera un error de conexión si pudo conectar efectivamente al otro extremo, aún cuando el servidor de destino retorne códigos http de error, como 404 o 500.

Esto es así para permitir realizar capturas de páginas de error en aplicaciónes de control de calidad.

Errores generales

Errores que impiden la carga de pagina, estos pueden ser los habituales de la API como falta de saldo en su cartera para realizar la petición, o un error de red al intentar cargar el recurso especificado en URL.

Depurar errores de red

Asegurese que la url introducida es válida, que no da timeouts, y que no hay bloqueos o caches que impidan que sea visitada por nuestros servidores.

Errores de captura de elemento

Son los retornados a nivel del elemento que se intentó capturar, estos errores son en la mayoría de casos por haber especificado un selector incorrecto.

Asegurese de que esta cargando la página correcta y que el selector usado es correcto.

Recuerde que puede capturar todo el documento usando document como selector.

Asegurese de que no hay factores que puedan influir en que ese elemento sea mostrado o no, por ejemplo si solo se muestra a usuarios autentificados.

Integración con PHP

ZPK-PHP es una librería de código abierto instalable mediante composer que le permitirá integrar nuestras APIs en su proyecto PHP con un mínimo esfuerzo.

Integrar HtmlToImage con el SDK en PHP

Instalando ZPK-PHP con composer

Terminal

composer require zpksystems/phpzpk

Ejemplo de request

Ejemplo SDK en PHP

<?php

$application = new zpkApplication('app_id','api_key');
$capturer = new zpkHtmlToImageCapturer($application,$url);

$capturer->addElement(['selector'=>'#example_1']);
$capturer->addElement(['selector'=>'#example_2','output_format'=>'webp','force_transparency'=>true]);

echo json_encode($imageCapturer->capture(),
 JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE);

Precio de capura

0,002 Euros por documento capturado

HtmlToImage tiene un coste por solicitud de captura de documento, el coste por petición es de 0,002 que se descontará de su crédito actual.

Regístrese para probar esta API

Regístrese para obtener crédito gratuito y probar esta y otras APIs de ZPK

Registrarse Acceder