# Consultar una API externa En esta guía consumirá desde DKL un servicio JSON con el formato `{success, data}` / `{success:false, message}`: consulta, alta y los tres tipos de error que debe atender. Usa `http.request` de `webcl.dkh`, que viene en todas las versiones de Devkron. Para lo nuevo de 2.0 (`http.get_json`, `http.post_json`, peticiones en paralelo, Bearer y Basic listos) vea [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md). El servicio que se consume es el de la guía [Servicio REST JSON](/es/devkron/2.0/guias/servicio-rest-json.md); cambie `@api_base` por la URL de la API que necesite. ## http.request ```dkl respuesta = http.request(url, método, encabezados, cuerpo) ``` | Argumento | Contenido | |---|---| | `url` | URL completa (`https://...`) | | `método` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`... | | `encabezados` | Registro con los encabezados (`Content-Type`, `Accept`, `Authorization`...). Dos llaves especiales: `__timeout` (milisegundos; predeterminado 100 000) y `__securityprotocol` (`tls12`, `tls11`, `tls`, `ssl3`) | | `cuerpo` | Texto del cuerpo; se envía en `POST`, `PUT` y `PATCH` (en los demás se ignora) | Devuelve el cuerpo de la respuesta como texto. **Si el servidor responde un estado de error (4xx o 5xx), lanza una excepción cuyo mensaje contiene el cuerpo de la respuesta.** ## El programa ```dkl #include "dkli.dkh" #! program "Consultar la API de productos" { #include "functions.dkh" #include "serialize.dkh" #include "webcl.dkh" do errordet(@false) @api_base = "http://tienda.ejemplo.com/api/v1/productos/" // Llama a la API y devuelve data, o lanza un error con el mensaje api.llamar::metodo, url, &cuerpo { new h { @"Accept": "application/json" @"Content-Type": "application/json;charset=utf-8" @"__timeout": 15000 } texto = "" if isnull(cuerpo) { texto = http.request(url, metodo, h, "") } else { texto = http.request(url, metodo, h, to.json(cuerpo)) } ref r = from.json(texto) if not(@@(r,"#success")) { do rise_error(0, @@(r,"$message")) } return @@(r,"&data") } // 1. Consulta ref p = api.llamar("GET", @api_base + "?sku=CUA-100", @null) do print("Producto: " + @@(p,"$descripcion") + " a $" + format(@@(p,"#precio"),"#,0.00")) // 2. Alta o cambio new nuevo { @"sku": "MAR-02" @"descripcion": "Marcador negro" @"precio": 18 } ref g = api.llamar("POST", @api_base, nuevo) do print("Guardado: " + @@(g,"$sku") + " = $" + format(@@(g,"#precio"),"#,0.00")) // 3. Error de negocio: la API responde 200 con success=false codeblock { do api.llamar("GET", @api_base + "?sku=NOEXISTE", @null) exception { do print("La API respondió: " + last_error()) } } // 4. Servidor que no responde codeblock { do api.llamar("GET", "http://127.0.0.1:1/", @null) exception { do print("Sin conexión: " + last_error()) } } // 5. Respuesta con estado de error (404 del servidor) codeblock { do api.llamar("GET", "http://tienda.ejemplo.com/no-existe.dkl", @null) exception { do print("Estado de error: " + substring(last_error(),0,40) + "...") } } } ``` Salida real (contra el servicio de la guía, en el mismo equipo): ```text Producto: Cuaderno profesional 100 hojas a $45.50 Guardado: MAR-02 = $18.00 La API respondió: No existe el producto NOEXISTE Sin conexión: Error en 'http.request. (Object reference not set to an instance of an object.Exception has been thrown by the target of an invocation.) [api-cliente.dkl] Estado de error: Error en 'http.request. (... ``` ## Los tres tipos de error | Caso | Qué pasa | Cómo se distingue | |---|---|---| | **Error de negocio** | La API responde 200 con `{"success":false,"message":...}` | Revise `success` después de `from.json` (como hace `api.llamar`) | | **Estado HTTP de error** (401, 404, 500...) | `http.request` lanza una excepción; el mensaje trae el cuerpo de la respuesta | `last_error()` empieza con `Error en 'http.request. (` seguido del cuerpo. Si la API manda JSON de error, extráigalo de ahí | | **Sin conexión** (DNS, puerto cerrado, tiempo agotado, certificado) | `http.request` lanza una excepción con un mensaje genérico (`Object reference not set to an instance of an object`) | No trae cuerpo. Reintente más tarde o avise | Mientras no se mejore el mensaje del tercer caso, regístrelo con la URL que falló para poder diagnosticarlo. ## Autenticación Agregue el encabezado que pida la API: ```dkl new h { @"Content-Type": "application/json;charset=utf-8" @"Authorization": "Bearer " + token } ``` Para obtener tokens con OAuth 2.0 (`client_credentials` de PayPal y otras), use [oauth.dkh](/es/devkron/2.0/bibliotecas/estandar/oauth.md); para firmar o validar JWT, [hash.dkh](/es/devkron/2.0/bibliotecas/estandar/hash.md). ## Otras funciones de webcl.dkh | Función | Uso | |---|---| | `http.get(url)` | GET simple; devuelve el cuerpo | | `http.post(url, registro)` | POST de un formulario `x-www-form-urlencoded` con los campos del registro | | `http.download(url, archivo)` | Descarga a un archivo | | `http.upload(archivo, url, nombre_campo)` | Sube un archivo como `multipart/form-data` | | `smtp.send(registro)` | Envía un correo | La referencia completa está en [webcl.dkh](/es/devkron/2.0/bibliotecas/motor/webcl/). ## Errores típicos | Síntoma | Causa y solución | |---|---| | `Could not find token at index 0` en `from.json` | La respuesta no es JSON (una página HTML de error, un proxy): imprima el texto antes de convertirlo | | La llamada tarda 100 segundos en fallar | Fije `__timeout` en los encabezados | | Sin licencia, una llamada a su propio servidor responde `Host no admitido` | Su servidor FastCGI sin licencia solo atiende hosts `*.localhost` y `127.0.0.1`: llame con ese nombre de host | | Caracteres raros en lo recibido | La API no manda UTF-8: revise su `Content-Type` |