5.3Webservices, API REST e intercambios
Lo esencial en 30 segundos
- Las API REST son el estándar de intercambio: Yacine consume la API de un proveedor para los precios y expone un servicio para los pedidos del sitio de comercio electrónico, en JSON sobre HTTP.
- El vocabulario REST se domina: URL, métodos GET/POST/PUT/DELETE, token de autenticación nunca codificado en duro y códigos de retorno tratados sistemáticamente.
- La robustez prima: no confiar nunca en los datos recibidos, prever tiempos de espera, reintentos, cola de espera, idempotencia y registro de los intercambios.
Mini-caso hilado — Yacine conecta su gestión con las API asociadas
Yacine desarrolla la aplicación de gestión de una pyme de venta de material eléctrico en Orán. Para evitar volver a introducir los precios, consulta la API REST de un proveedor: un GET devuelve el precio y las existencias de un producto en formato JSON. Para el sitio de comercio electrónico del distribuidor, expone él mismo una API que recibe los pedidos en POST y devuelve su estado. El token de autenticación no está escrito en el código: se lee desde un parámetro seguro. Cada respuesta se valida antes de registrarse, porque un precio a cero o un código de producto desconocido no deben entrar nunca en la base. Cuando el proveedor no está disponible, la petición pasa a una cola de espera y se reproducirá con un identificador único para evitar duplicados. Yacine registra cada llamada: fecha, sentido, servicio, código de retorno y datos resumidos.
Caso autónomo de esta sección: reaparece en el curso, el esquema, el código y el reto 48 h de la sección 5.3.
1. Consumir y exponer
Una aplicación de gestión rara vez vive aislada: intercambia con la contabilidad, un ERP, un sitio de comercio electrónico, un banco o un proveedor. Los webservices y API REST son el estándar moderno. Consumir una API consiste en llamar a un servicio remoto para obtener o enviar datos; exponer una API consiste en publicar la propia para que otras aplicaciones la llamen. Los intercambios se hacen casi siempre en JSON sobre HTTP. Los archivos de intercambio (CSV, XML, JSON, Excel) siguen siendo útiles para las importaciones y exportaciones por lotes, y el acceso directo a otra base todavía existe, pero la API REST es el modo privilegiado para el tiempo real.
2. El vocabulario REST
Para llamar a una API, Yacine identifica la URL del servicio y el método: GET para leer, POST para crear, PUT para modificar, DELETE para suprimir. La autenticación suele basarse en una clave o un token: esos secretos nunca deben escribirse en duro en el código ni exponerse en el lado cliente. El formato de los datos (JSON casi siempre) debe analizarse y convertirse en objetos de negocio. Por último, los códigos de retorno indican el éxito, un error de autenticación, un recurso no encontrado o un error de servidor: se tratan sistemáticamente. Un código 200 no garantiza que los datos sean correctos, y un código 500 no es razón para abandonar sin rastro.
3. Robustez y trazabilidad
Un servicio remoto estará indisponible, lento o incoherente algún día. Yacine parte de ese principio y prevé un tiempo de espera, reintentos espaciados, una cola de espera para no perder nada y un tratamiento asíncrono para no bloquear al usuario. La idempotencia evita los duplicados cuando un envío se repite: un identificador único de operación permite al servidor reconocer una petición ya tratada. Todos los datos recibidos se validan antes de registrarse. Por último, los intercambios se registran: fecha, sentido, servicio, código de retorno, datos resumidos e identificador de negocio. Es la única prueba explotable en caso de litigio con un socio, y la mejor herramienta para diagnosticar una avería intermitente.
🔎 Ejemplo concreto — 🔎 Ejemplo concreto — Consumir la API de precios del proveedor
Yacine recupera un precio y rechaza cualquier valor incoherente:
// Consommation de l'API prix fournisseur
sURL est une chaîne = "https://api.fournisseur.dz/articles/" + SAI_CodeArticle
sReponse est une chaîne = RESTEnvoie(sURL, "GET", gsJetonFournisseur)
SI sReponse = "" ALORS
Erreur("Service fournisseur indisponible")
RENVOYER Faux
FIN
oArticle est un dynamic ArticleAPI
JSONVersObjet(sReponse, oArticle)
SI oArticle.PrixHT <= 0 ALORS
Erreur("Prix reçu invalide")
RENVOYER Faux
FIN
RENVOYER VraiResultado: ningún precio nulo o negativo entra en la base de Yacine.
Reflejo: el token viene de un parámetro seguro, nunca del código fuente.
Vocabulario de la sección
- API REST
- Servicio web que expone recursos mediante URL y métodos HTTP, a menudo en JSON.
Ejemplo sencillo: Yacine consulta la API del proveedor para los precios y las existencias.
Lo que no es: copiar a mano las tarifas en la aplicación.
Reflejo: API REST = intercambio estandarizado en tiempo real.
- Métodos HTTP
- Verbos del protocolo HTTP: GET (leer), POST (crear), PUT (modificar), DELETE (suprimir).
Ejemplo sencillo: Yacine utiliza GET para consultar y POST para recibir un pedido.
Lo que no es: hacerlo todo con un solo verbo sin distinguir la acción.
Reflejo: el método describe la intención del intercambio.
- Token de API
- Secreto de autenticación presentado en cada llamada para demostrar la identidad de la aplicación.
Ejemplo sencillo: Yacine lee su token en un parámetro seguro.
Lo que no es: escribir el token en claro en el código o en una página.
Reflejo: un secreto nunca se codifica en duro.
- Idempotencia
- Propiedad de un intercambio que, repetido con el mismo identificador, no crea un duplicado.
Ejemplo sencillo: Yacine adjunta un identificador de operación único a cada pedido.
Lo que no es: reenviar el mismo pedido tras un corte de red.
Reflejo: idempotencia = reintento sin duplicado.
- Registro de intercambios
- Traza con marca temporal de las llamadas: sentido, servicio, datos resumidos, código de retorno e identificador de negocio.
Ejemplo sencillo: Yacine consulta el registro para diagnosticar un precio rechazado.
Lo que no es: no registrar ningún intercambio y suponer que todo va bien.
Reflejo: el registro es la prueba y la herramienta de diagnóstico.
En la práctica — En la práctica — Intercambiar con otros sistemas
- Identifique el modo adecuado: API REST para el tiempo real, archivos CSV/XML/JSON para los lotes, acceso directo a otra base como último recurso.
- Para consumir una API, localice la URL, el método (GET/POST/PUT/DELETE), la autenticación y el formato JSON, sin codificar nunca el secreto en duro.
- Trate sistemáticamente los códigos de retorno y las averías (servicio no disponible, tiempo de espera superado) con reintento, cola de espera e idempotencia.
- Valide todos los datos recibidos, registre los intercambios y verifique sus obligaciones sobre los datos personales transmitidos.
Guion paso a paso — registrar un intercambio (10 min)
Yacine traza cada respuesta del proveedor para poder diagnosticar y probar.
Se registra un resumen si los datos son voluminosos, pero siempre el identificador de negocio que vincula el intercambio con el pedido.
Plantilla para copiar y pegar — mi ficha de intercambio API
// Fiche d'échange — Yacine
// Service : API fournisseur matériel électrique
// URL : https://api.fournisseur.dz/articles/{code}
// Méthode : GET
// Authentification : jeton lu dans ParametreSecurise("API_FOURNISSEUR")
// Format : JSON (ArticleAPI)
// Codes traités : 200, 401, 404, 429, 500
// Robustesse : délai 10 s, 3 reprises espacées, file d'attente
// Idempotence : NumeroOperation unique
// Journal : date, sens, service, code, données résuméesPrecios del proveedor
Yacine consume la API de un proveedor para actualizar los precios y las existencias.
Pedido de comercio electrónico
Yacine expone una API POST que recibe los pedidos del sitio asociado.
Exportación contable
Yacine genera un archivo CSV para la contabilidad cuando la API no está disponible.
Recuperación tras una avería
Yacine pone los envíos en cola de espera y los reproduce con un identificador único.
✓ Buenas prácticas
- Proteger los tokens y claves de API fuera del código fuente.
- Validar todos los datos recibidos antes de registrarlos.
- Prever reintentos, cola de espera y registro desde el primer intercambio.
✗ Errores frecuentes
- Codificar un secreto en duro en la aplicación o en una página.
- Confiar en el código 200 sin verificar los datos.
- Reenviar una petición sin identificador de operación y crear un duplicado.
Puntos clave
- Las API REST intercambian en JSON sobre HTTP, tanto al consumir como al exponer.
- URL, métodos, autenticación y códigos de retorno forman el vocabulario REST.
- Los secretos nunca se codifican en duro y los datos recibidos se validan.
- Tiempos de espera, reintentos, cola de espera, idempotencia y registro hacen robustos los intercambios.
Reto 48 h — aplícalo mañana
Como Yacine, llame a una API pública en GET desde un pequeño proyecto WinDev, analice el JSON y valide un campo antes de registrarlo. Añada un registro de intercambio (fecha, servicio, código de retorno, datos resumidos) y simule una avería cortando la red. Verifique que la petición pasa a la cola de espera y que un reenvío no crea un duplicado.
- Puedo explicar la diferencia entre consumir y exponer una API.
- Sé nombrar los métodos HTTP y proteger un token.
- Sé hacer un intercambio robusto y registrado.
Preguntas frecuentes
¿Por qué hay que registrar los intercambios con sistemas externos?
Porque, en caso de problema, el registro es la única prueba de lo que se envió y se recibió, y en qué momento. Permite diagnosticar un dato falso, una avería intermitente o un cambio no anunciado en el socio. También sirve para recuperarse tras un incidente sabiendo con precisión qué ha pasado, y para responder a un litigio o a una auditoría. Yacine registra la fecha, el sentido, el servicio, el código de retorno, un resumen de los datos y el identificador de negocio (número de pedido o de factura). Sin ese identificador, el registro es difícil de vincular a la operación real.
¿Cómo hacer robustos los intercambios que dependen de un servicio externo?
Partiendo del principio de que el servicio estará algún día indisponible, lento o incoherente. Hacen falta un tiempo de espera para no bloquear indefinidamente, reintentos espaciados y limitados, una cola de espera para conservar las peticiones no enviadas, un tratamiento asíncrono para no bloquear al usuario y un identificador de operación único para hacer idempotente el envío. Todas las respuestas se validan antes de registrarse, y cada intercambio se registra. Yacine prevé también una información clara al usuario cuando el intercambio se difiere.
¿Qué hacer con los datos recibidos de una API de proveedor antes de registrarlos?