API de HandyLay
HandyLay publica una única dirección HTTP que planifica el despiece de azulejos o suelo laminado en la habitación que describas. Devuelve cuántas piezas necesita el despiece, separadas en enteras y cortadas, qué parte del material acaba como recorte, un plano a escala y un enlace que abre el plano terminado en el planificador. Sin clave y sin cuenta.
Toda la API es una dirección
La petición es un GET normal, así que se puede pegar en el navegador o dársela a un asistente capaz de descargar una página. La dirección de abajo planifica una pieza de 60 × 60 cm con junta de 2 mm en una habitación de 420 × 360 cm.
GET https://handylay.app/api/plan?outline=E420 S360 W420 N360&pattern=squares&tileSize=600&joint=2Una habitación con un entrante o una hornacina se escribe igual, con un recorrido más largo. Este ejemplo es una planta en L con un pilar de 40 × 40 cm en el centro, en espiga con lamas de 90 × 600 mm.
GET https://handylay.app/api/plan?outline=E500 S300 W200 S200 W300 N500&subtract=200,150,40,40&pattern=herringbone&tileWidth=90&tileHeight=600Los mismos campos se aceptan como cuerpo JSON en POST, si resulta más cómodo llamarla desde código.
POST /api/planHabitaciones en centímetros, piezas en milímetros
Las medidas de la habitación y el punto de inicio van en centímetros; el tamaño de las piezas y el ancho de junta, en milímetros. La división sigue el origen de cada número: las paredes se miden con cinta y la pieza se lee en la ficha del fabricante.
Equivocarse de unidad no produce ningún aviso, porque una pieza de 20 mm es tan válida como una de 200 mm. Cuando un resultado parece absurdo, suele ser lo primero que conviene revisar.
La habitación se describe recorriendo sus paredes
El parámetro outline enumera las paredes en el orden en que se recorren. Cada pared es una dirección y una longitud en centímetros: E a la derecha, S hacia abajo, W a la izquierda, N hacia arriba. Un rectángulo de 420 × 360 cm se escribe E420 S360 W420 N360.
El recorrido tiene que volver al punto de partida, y si no lo hace la respuesta dice por cuánto falla. Una planta en L es E500 S300 W200 S200 W300 N500, y cualquier otra forma de paredes rectas se construye añadiendo tramos. Una pared en ángulo se escribe como A rumbo dos puntos longitud, donde el rumbo son grados en sentido horario desde el este.
Pilares, patinillos y otros huecos se restan con rectángulos en el parámetro subtract. Una habitación que ningún recorrido describe se pasa directamente como lista de vértices en el parámetro polygon.
Salvo la descripción de la habitación, todo es opcional
Los nombres que no aparecen abajo se pasan al despiece como parámetros suyos, por ejemplo tileWidth para la espiga. De dónde sacar esa lista se explica en la sección de despieces.
| Nombre | Significado |
|---|---|
outline | Las paredes de la habitación en orden de recorrido, p. ej. E420 S360 W420 N360. |
polygon | Vértices del contorno como pares x,y separados por espacios. Alternativa a outline. |
holes | Huecos en el suelo, escritos como polygon; los anillos se separan con punto y coma. |
subtract | Huecos rectangulares como x,y,ancho,alto en centímetros, separados por punto y coma. |
pattern | El despiece a colocar. Por defecto squares. |
joint | Ancho de junta en milímetros. Por defecto el propio del despiece. |
color | Un color hexadecimal para todas las piezas del motivo. |
gapColor | Color de la junta, en hexadecimal. |
start | Punto de inicio como x,y en centímetros. Es el parámetro que decide cómo caen los cortes junto a las paredes. |
width | Ancho del plano en píxeles. |
walls | Dibuja la banda de pared y las longitudes alrededor de la habitación. Activo por defecto. |
format | json devuelve los números, svg el plano. |
inlineSvg | Añade el plano a la respuesta JSON. |
credit | La firma handylay.app en el margen del plano. Activa por defecto. |
link | Crea el enlace al planificador. Desactívalo mientras comparas opciones. |
lang | Idioma de los nombres de despiece y del enlace al planificador: en, pl, es o zh. |
La respuesta trae números, no solo una imagen
Por defecto devuelve JSON. El plano aparece como dirección y no como contenido, para poder leer la respuesta sin pasar por varios kilobytes de marcado. El parámetro inlineSvg lo incrusta y format=svg devuelve solo la imagen desde la misma dirección.
El campo warnings es lo que conviene atender antes de enseñar el plano a nadie. Avisa de tiras inservibles junto a las paredes o de un desperdicio alto. Mover start media pieza y volver a preguntar suele resolverlo.
| Nombre | Significado |
|---|---|
surface.areaM2 | Superficie del suelo una vez restados los huecos, en metros cuadrados. |
surface.perimeterM | Perímetro de la habitación en metros. |
surface.wallsCm | Longitud de cada pared en centímetros, en orden. |
pattern.parameters | Los parámetros del despiece realmente usados, incluidos los de defecto. |
pattern.jointMm | Ancho de junta en milímetros. |
pattern.startCm | Punto de inicio del despiece en centímetros. |
tiles.total | Piezas que hay que comprar para este despiece. |
tiles.whole | De esas, colocadas enteras. |
tiles.cut | De esas, que requieren corte. |
tiles.wastePercent | Parte del material comprado que acaba como recorte. |
tiles.narrowestCutMm | Lado más corto de cualquier pieza cortada. Un número pequeño indica una tira. |
tiles.sliverCount | Cortes que salen por debajo de una décima parte de una pieza entera. |
warnings | Qué falla en este despiece y qué suele arreglarlo. |
svgUrl | El mismo plano en una dirección propia. |
plannerUrl | Abre el plano terminado en el planificador, donde se puede arrastrar el punto de inicio. |
GET https://handylay.app/api/plan?outline=E420 S360 W420 N360&pattern=bricks&format=svgCada despiece describe sus propios parámetros
Cada despiece tiene sus parámetros: la espiga acepta tileWidth, tileHeight y direction. En lugar de adivinar un nombre, se piden a una dirección aparte que lista todos los despieces con sus rangos, valores por defecto y etiquetas traducidas.
GET /api/plan/patternsDespieces disponibles ahora mismo:
squares-patternbricks-patternvertical-bricks-patternhexagons-patternflat-top-hexagons-patterndiamonds-patternrhombus-patternisometric-cubes-patternherringbone-patternchevron-pattern
Sin clave, pero con límites
El punto de acceso está abierto porque un asistente que sigue un enlace no tiene dónde guardar una clave. El coste lo acotan los límites de entrada: como mucho 20.000 piezas por plano, 64 paredes en un recorrido, 32 huecos y un tope de superficie. Superar cualquiera devuelve un mensaje que dice qué enviar en su lugar.
Las peticiones desde una misma dirección están limitadas a treinta por minuto. Al comparar varios puntos de inicio conviene añadir link=false, porque cada petición que devuelve un enlace al planificador guarda un proyecto. El enlace se toma de la llamada cuyo plano se entrega.
Dos direcciones llevan la descripción legible por máquina
La descripción OpenAPI es a lo que apuntar un asistente o tu propio código para conectar el punto de acceso como herramienta. El archivo llms.txt resume qué es HandyLay y qué hace esta API, en un formato pensado para que lo lea un modelo.