Usar la API de SOAP

Si ha navegado por los estrechos de alguna otra API basada en SOAP, ya sabe que el archivo WSDL (lenguaje de descripción de servicios web) es básicamente su mapa para comprender cómo se debe usar la API. Contiene los enlaces, protocolos y objetos necesarios para ejecutar llamadas de API.

Salesforce proporciona dos WSDL de API de SOAP para dos casos de uso distintos. El WSDL para compañías se ha optimizado para una única organización de Salesforce. Está tipificado de forma estricta y refleja la configuración específica de su organización, lo que significa que dos archivos WSDL para compañías generados en dos organizaciones distintas contienen información diferente.

Ahora que ya tenemos nuestro archivo WSDL, necesitamos un método para extraer la información y empezar a procesar solicitudes de API de SOAP. En el lenguaje del entorno web, este proceso se llama consumo de WSDL. Del mismo modo que un kraken devora un barco lleno de desventurados marineros, algunas herramientas como Web Services Connector (WSC) consumen el archivo WSDL. A continuación, las herramientas crean clases que le permiten procesar solicitudes con la API de SOAP mediante lenguajes de programación de uso frecuente.

En esta unidad, vamos a usar una herramienta de terceros llamada SoapUI para el consumo de nuestro archivo WSDL de compañía. SoapUI es una aplicación gratuita y de código abierto para probar los servicios web. Para empezar, descargue e instale SoapUI OpenSource desde el sitio web de SoapUI. Instale tan solo el componente SoapUI.

Después de instalar e iniciar SoapUI, en el menú File (Archivo), seleccione New SOAP Project (Nuevo proyecto de SOAP). Para nombre del proyecto, ingrese Exploring Salesforce SOAP API. En el caso del WSDL inicial, vaya a la ubicación en la que ha guardado el archivo WSDL de compañía y selecciónelo. No cambie ninguna otra opción. Su ventana de SoapUI debe ser similar a esta.

Haga clic en Aceptar. Después del procesamiento durante unos segundos, la carpeta Exploring Salesforce SOAP API se muestra en el panel del navegador en la parte izquierda de la pantalla. Debajo de esta carpeta, se incluye una entrada llamada SoapBinding que contiene varias operaciones.

¿Qué es lo que vemos aquí? Cada operación se corresponde con una solicitud de API de SOAP que podemos procesar. Las propiedades de cada operación se extraen de la información del archivo WSDL. Además, cada operación contiene una solicitud XML de ejemplo que incluye el extremo HTTPS de la operación y un mensaje de SOAP completado previamente.

Una cosa más: Salesforce requiere que todas las conexiones utilicen TLS 1.2 o versiones posteriores. Y si está utilizando SoapUI con Java 7, TLS 1.2 no está activado de forma predeterminada. Si intenta conectar con Salesforce con una versión antigua de TLS, recibirá un mensaje de error. Las buenas noticias es que la solución es bastante sencilla. Consulte esta útil publicación de blog para obtener más información.

Ya estamos preparados para empezar a procesar solicitudes de API de SOAP. ¡A toda vela, capitán!

En SoapUI, desplácese hasta la operación login. Expándala y, a continuación, haga doble clic en Request 1 (Solicitud 1). Se muestra un ejemplo de solicitud de inicio de sesión de SOAP.

Dado que no vamos a usar paquetes gestionados para este ejemplo, podemos eliminar el número de la versión del paquete del final del URI. Adelante, hágalo ahora.

El mensaje de SOAP (2) contiene todo lo que cabe esperar en un mensaje de SOAP: un sobre, un encabezado y un cuerpo.

Las propiedades incluidas en el elemento LoginScopeHeader están relacionadas con la autenticación de los usuarios de portales de clientes y autoservicio. Puesto que no es necesario detenernos en estos valores para nuestros fines, elimine el elemento <urn:LoginScopeHeader> completo (todo desde <urn: LoginScopeHeader> a </urn:LoginScopeHeader>). Resalte el texto en la ventana y pulse la tecla Supr.

A continuación, examine el elemento <urn:login> del cuerpo del mensaje. Este elemento es el meollo de la solicitud de inicio de sesión. Aquí especificamos nuestras credenciales de usuario. Sustituya los caracteres ? por su nombre de usuario y contraseña en su Trailhead Playground.

Dado que va a enviar una solicitud de API desde una dirección IP desconocida a Salesforce, debe anexar su token de seguridad al final de su contraseña. Por ejemplo, si su contraseña es mypassword y su token de seguridad es XXXXXXXXXX, ingrese mypasswordXXXXXXXXXX en el elemento <urn:password>.

Para obtener su token de seguridad, vaya a su configuración personal y luego vaya a la página Restablecer mi token de seguridad bajo Mi información personal. Haga clic en Restablecer token de seguridad para enviar un email a la dirección de email asociada con su Trailhead Playground con su token.

Su mensaje de SOAP debe ser similar al siguiente.

Haga clic en el botón de reproducción (triángulo verde) en la parte superior izquierda de la ventana de la solicitud. Este botón le permite enviar la solicitud y lanzar al mar su mensaje de SOAP en una botella. Esta es la apariencia que tiene cuando ampliamos la respuesta.

Felicitaciones, capitán. Ha iniciado sesión correctamente. La respuesta contiene información diversa sobre su organización y usuario. Sin embargo, lo más importante es que contiene el nombre de Mi dominio de su organización y un identificador de sesión que usaremos para futuras solicitudes, los cuales aparecen resaltados aquí.

Copie la instancia y el Id. de sesión en un archivo de texto. Los utilizaremos en un minuto.

Dado que es probable que la instancia de su organización cambie, no codifique las referencias a la instancia cuando empiece a desarrollar integraciones. En lugar de eso, use la URL de inicio de sesión de Mi dominio de su organización. Con Mi dominio, debe configurar un dominio específico de cliente para su organización de Salesforce. Mi dominio no solo elimina el inconveniente de cambiar los nombres de instancias, sino que también es útil para destacar su marca, aumentar la seguridad de su organización y personalizar su página de inicio de sesión.