# webcl.dkh: HTTP y correo SMTP `webcl.dkh` permite a un programa DKL **llamar** a otros servidores: consultar una API REST, enviar un formulario, descargar o subir un archivo, y mandar correos por SMTP. Sus funciones están en `Devkron.WebClient.dll`. Para **atender** peticiones (leer lo que llega a su servicio y armar la respuesta) y para un cliente JSON más completo (Basic/Bearer, peticiones en paralelo, códigos de estado) use la biblioteca estándar [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md). ```dkl #include "dkli.dkh" #! program "cliente" { #include "functions.dkh" #include "serialize.dkh" #include "webcl.dkh" // ... } ``` ## Funciones HTTP | Función | Devuelve | Qué hace | |---|---|---| | `http.get(url)` | Cadena | Hace un `GET` y devuelve el cuerpo de la respuesta | | `http.post(url, registro)` | Cadena | Hace un `POST` codificado como `application/x-www-form-urlencoded` con los campos del registro; devuelve el cuerpo. Con `@null` no envía nada y devuelve `""` | | `http.request(url, método, encabezados, cuerpo)` | Cadena | Petición con cualquier método (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`…), encabezados propios (registro o `@null`) y cuerpo de texto (se envía en UTF-8 solo con `POST`, `PUT` y `PATCH`) | | `http.download(url, archivo)` | — | Descarga la URL y la guarda en `archivo` | | `http.upload(archivo, url, campo)` | Cadena | Sube un archivo por `POST` `multipart/form-data` con el nombre de campo indicado | | `http.upf(archivo, url, campo, encabezados)` | Cadena | Igual que `http.upload`; si `campo` es `""` usa `files`. `encabezados` (registro o `@null`) se agregan a la parte `multipart` | | `http.mpost(url, registro, asíncrono)` | Cadena | La función base de `http.post`. Con `asíncrono` = `@true` envía en segundo plano y devuelve un identificador en lugar de la respuesta (sin forma de leerla desde DKL); use `http.post` | ### Encabezados de http.request Los campos del registro de encabezados se envían como encabezados HTTP (`Content-Type`, `Accept`, `Authorization`, `X-Api-Key`…). Dos campos especiales **no** se envían, configuran la petición: | Campo | Qué hace | |---|---| | `__timeout` | Tiempo máximo de espera en milisegundos (por omisión 100000) | | `__securityprotocol` | Fuerza el protocolo: `tls`, `tls11` o `tls12` (`ssl3` da error). Normalmente no hace falta: Devkron 2.0 negocia TLS 1.2 o 1.3 | > La documentación 1.x llamaba `__protocol` a este campo; el nombre que reconoce el código es **`__securityprotocol`**. Cuando el servidor responde con un código de error (4xx o 5xx), `http.request` lanza una excepción cuyo mensaje es **el cuerpo de la respuesta** (útil para APIs que explican el error en JSON). `http.get`, `http.post` y `http.download` lanzan la excepción de .NET (`The remote server returned an error: (401) Unauthorized.`). Si no hay respuesta HTTP (tiempo agotado, servidor caído), `http.request` lanza `Object reference not set to an instance of an object.` ## Ejemplo Contra un servidor de pruebas local que devuelve en JSON lo que recibió: ```dkl #include "dkli.dkh" #! program "http" { #include "functions.dkh" #include "serialize.dkh" #include "webcl.dkh" base = "http://127.0.0.1:8089" do print(http.get(base + "/clientes?estado=activo")) new datos { @"usuario": "mi_usuario" @"comentario": "Pago con tarjeta & efectivo" } do print(http.post(base + "/formulario", datos)) new enc { @"Content-Type": "application/json" @"Accept": "application/json" @"X-Api-Key": "clave-de-ejemplo" @"__timeout": 15000 } new pedido { @"folio": "A-100" @"total": 300.5 } resp = http.request(base + "/api/pedidos", "POST", enc, to.json(pedido)) ref r = from.json(resp) do print(field.str(r, "metodo") + " " + field.str(r, "content_type") + " " + field.str(r, "x_api_key")) do print(field.str(r, "cuerpo")) do print(field.str(from.json(http.request(base + "/api/pedidos/A-100", "DELETE", @null, "")), "metodo")) do print(field.str(from.json(http.request(base + "/api/pedidos/A-100", "PATCH", enc, "{\"total\":1}")), "cuerpo")) do http.request(base + "/error", "GET", @null, "") exception { do print(last_error()) do clear_exceptions() } do http.download(base + "/archivo.txt", "/tmp/dkdoc/descargado.txt") do print(file.rtext("/tmp/dkdoc/descargado.txt")) do file.wtext("/tmp/dkdoc/cfdi.xml", "") do print(http.upload("/tmp/dkdoc/cfdi.xml", base + "/subir", "xml")) new encs { @"X-Token": "abc123" } do print(http.upf("/tmp/dkdoc/cfdi.xml", base + "/subir", "", encs)) do file.delete("/tmp/dkdoc/cfdi.xml") do file.delete("/tmp/dkdoc/descargado.txt") do http.get("http://127.0.0.1:1/") exception { do print(last_error()) do clear_exceptions() } } ``` ```text {"metodo": "GET", "ruta": "/clientes?estado=activo", "content_type": "", "accept": null, "x_api_key": null, "cuerpo": ""} {"metodo": "POST", "ruta": "/formulario", "content_type": "application/x-www-form-urlencoded", "accept": null, "x_api_key": null, "cuerpo": "usuario=mi_usuario&comentario=Pago+con+tarjeta+%26+efectivo"} POST application/json clave-de-ejemplo {"folio":"A-100","total":300.5} DELETE {"total":1} {1} Error en 'http.request. ({"error": "no autorizado"}Exception has been thrown by the target of an invocation.) [http.dkl][Ln= 34] contenido del archivo {"metodo": "POST", "multipart": true, "campo": "xml", "archivo": "cfdi.xml", "bytes": 181, "x_token": null} {"metodo": "POST", "multipart": true, "campo": "files", "archivo": "cfdi.xml", "bytes": 183, "x_token": "abc123"} {1} Error en 'http.get. (Connection refused 127.0.0.1:1 (127.0.0.1:1)Exception has been thrown by the target of an invocation.) [http.dkl][Ln= 51] ``` Para llamar una API JSON real con autenticación, el patrón es: ```dkl new enc { @"Content-Type": "application/json" @"Accept": "application/json" @"Authorization": "Bearer " + token } ref r = from.json(http.request("https://api.ejemplo.com/v1/pedidos", "POST", enc, to.json(pedido))) exception { error_api = last_error() do clear_exceptions() } ``` ## Correo: smtp.send `smtp.send(mensaje)` envía un correo con los campos del registro `mensaje`: | Campo | Obligatorio | Contenido | |---|---|---| | `server` | Sí | Nombre o IP del servidor SMTP | | `port` | No | Puerto (por omisión 25; normalmente 587 o 465) | | `protocol` | No | `"ssl"` habilita el cifrado (STARTTLS); omítalo si el servidor no lo usa | | `user`, `password` | Según el servidor | Credenciales SMTP | | `from` | Sí | Remitente: `"Nombre "` o solo la dirección | | `to` | Sí | Destinatarios, separados por `;` o `,`; cada uno con o sin nombre | | `cc` | No | Copia | | `cco` | No | Copia oculta | | `repply` | No | Dirección de respuesta (*Reply-To*). Se escribe **`repply`**, con doble `p` | | `subject` | No | Asunto | | `body` | No | Cuerpo en HTML | | `onlytext` | No | `@true` envía el cuerpo como texto plano en lugar de HTML | | `attatchments` | No | Lista de cadenas con las rutas de los archivos adjuntos. El campo se escribe **`attatchments`** | > En la 1.x el campo `repply` se describía como "dirección a copiar el mensaje"; en realidad es la dirección de respuesta. La copia es `cc`. El ejemplo 1.x agregaba los adjuntos con `mail:archivos`; el nombre correcto del campo es `attatchments` y la lista se asigna con `mail<"attatchments*">: lista`. ```dkl #include "dkli.dkh" #! program "correo" { #include "functions.dkh" #include "webcl.dkh" do file.wtext("/tmp/dkdoc/factura.xml", "") ref adjuntos = list.create() do list.addstr(adjuntos, "/tmp/dkdoc/factura.xml") new mail { @"server": "127.0.0.1" @"port": 2525 @"user": "mi_usuario" @"password": "MiClave#2026" @"from": "Facturación " @"to": "Cliente Uno ; cliente2@ejemplo.com" @"cc": "contabilidad@ejemplo.com" @"cco": "archivo@ejemplo.com" @"repply": "soporte@ejemplo.com" @"subject": "Su factura A-100" @"body": "

Adjuntamos su factura A-100.

" } mail<"attatchments*">: adjuntos do smtp.send(mail) do print("enviado") mail<"to">: "sin-arroba" do smtp.send(mail) exception { do print(last_error()) do clear_exceptions() } do file.delete("/tmp/dkdoc/factura.xml") } ``` ```text enviado {1} Error en 'smtp.send. ('sin-arroba' No define una dirección de correo válidaException has been thrown by the target of an invocation.) [correo.dkl][Ln= 28] ``` Así llegó el mensaje al servidor SMTP de pruebas (extracto): ```text MAIL FROM: RCPT TO: RCPT TO: RCPT TO: RCPT TO: From: =?utf-8?Q?Facturaci=C3=B3n?= To: "Cliente Uno" , "cliente2" Cc: "contabilidad" Reply-To: "soporte" Subject: Su factura A-100 Content-Type: text/html; charset=us-ascii

Adjuntamos su factura A-100.

Content-Type: application/octet-stream; name=factura.xml Content-Disposition: attachment ``` Con proveedores como Microsoft 365 o Gmail use el puerto 587, `protocol` = `"ssl"` y una contraseña de aplicación. No guarde la contraseña en el código: léala de un archivo de configuración fuera del sitio. ## Errores típicos | Mensaje | Causa | Solución | |---|---|---| | `Connection refused …` | El servidor no escucha en esa dirección o puerto | Revise la URL y el firewall | | El mensaje de la excepción es un JSON (`{"error": …}`) | `http.request` recibió 4xx/5xx | Lea `last_error()` y trate el código de error | | `The remote server returned an error: (401) Unauthorized.` (u otro código) | `http.get`/`http.post`/`http.download` con error HTTP | Revise la URL; use `http.request` para leer el cuerpo del error | | `Object reference not set to an instance of an object.` en `http.request` | Falla de red sin respuesta HTTP (tiempo agotado por `__timeout`, servidor que no contesta, DNS). `http.request` no puede leer un cuerpo de error y da este mensaje genérico | Revise la conexión con el servidor; aumente `__timeout` si es lento | | `Los encabezados de una solicitud HTTP deben ser un Record` | Se pasó algo que no es registro | Use un registro o `@null` | | `'x' No define una dirección de correo válida` | Una dirección de `from`, `to`, `cc`… sin `@` | Corrija la dirección | | `Failure sending mail.` / `Authentication failed` | Servidor, puerto, `protocol` o credenciales incorrectos | Pruebe la cuenta con otro cliente de correo | ## Relación con la documentación 1.x | Página 1.x | En esta página | |---|---| | [webcl.dkh](/es/devkron/Bibliotecas-de-funciones/webcl/webcl.md) | Toda la página | | [http.get](/es/devkron/Bibliotecas-de-funciones/webcl/http/http.get.md), [http.post](/es/devkron/Bibliotecas-de-funciones/webcl/http/http.post.md), [http.request](/es/devkron/Bibliotecas-de-funciones/webcl/http/http.request.md), [http.download](/es/devkron/Bibliotecas-de-funciones/webcl/http/http.download.md), [http.upload](/es/devkron/Bibliotecas-de-funciones/webcl/http/http.upload.md), [http.upf](/es/devkron/Bibliotecas-de-funciones/webcl/http/http.upf.md) | Funciones HTTP | | [smtp.send](/es/devkron/Bibliotecas-de-funciones/webcl/smtp/smtp.send.md) | Correo: smtp.send | En 2.0 `webcl` conserva el mismo comportamiento que 1.x (mismas cabeceras y redirecciones). [Regresar a Bibliotecas del motor](/es/devkron/2.0/bibliotecas/motor/)