Formatos de mensajes de solicitud y respuesta

Formatos de mensajes de solicitud y respuesta

La solicitud

    <?xml version='1.0' encoding='UTF-8'?>
    <call method="exportData" callerName="a string that identifies your client application">
       <credentials login="sample@company.com" password="my_pwd"/>              
       method specific data goes here
    </call>

Esta línea indica que los datos posteriores están codificados en XML en UTF-8.
La etiqueta <call> indica a qué método de API se llama mediante su atributo de método. En este ejemplo, el método de API es exportData. Además, callerName es un atributo obligatorio en la etiqueta <call>. Identifica su aplicación cliente en el sistema y se utiliza con fines de identificación para la resolución de problemas y el registro.
Cada método API debe autenticar al usuario que realiza la llamada. Esto suele hacerse proporcionando un nombre de inicio de sesión y una contraseña. Aquí se pueden especificar otros atributos. Consulte la documentación de cada función de API para obtener más detalles sobre las credenciales.
Algunos métodos de API requieren datos adicionales en la solicitud. Por ejemplo, el método exportData requiere algunos criterios que describan qué periodos, cuentas, niveles, etc., se deben utilizar al recuperar sus datos. Esta parte de la solicitud variará de un método a otro.
Esta es la etiqueta de cierre de la etiqueta de llamada en la línea 2.

La respuesta

     <?xml version='1.0' encoding='UTF-8'?>
     <response success="true">
       <messages>
          <message key="modeled-import-success">Personnel import successful. Rows imported: 100</message>
       </messages>
       <output>
         ... method output ...
       </output>
     </response>

De forma similar a la solicitud, esta línea indica que los datos posteriores tienen formato XML y están codificados en UTF-8.
Cada respuesta se incluye en una etiqueta <response>. Si la solicitud se ha realizado correctamente, el atributo de éxito de la etiqueta de respuesta se establece en verdadero. Si la solicitud no se ha realizado correctamente, el atributo de éxito se establece en falso.
Muchas llamadas a la API devolverán este bloque opcional <messages> que contiene una lista de mensajes generados por el servidor. Es posible que este bloque no aparezca si el servidor no tiene mensajes que devolver en respuesta a la llamada. Los mensajes de error siempre aparecerán en el bloque de mensajes.
Cada mensaje del bloque de mensajes tiene un atributo clave que identifica el tipo de mensaje que se transmite. La etiqueta de mensaje también contiene el texto del mensaje del servidor, incluidos los valores devueltos, los valores de estado u otros metadatos independientes sobre el éxito o el error de la solicitud. Una respuesta puede contener un número ilimitado de etiquetas de mensaje.
La etiqueta de mensajes de cierre.
El resultado real de la llamada al método API, si se devuelve alguno, se incluye en una etiqueta <output>.
El resultado real de la llamada al método API aparecerá aquí. Esta salida varía en función del método al que se haya llamado.
La etiqueta de resultado de cierre.
La etiqueta de respuesta de cierre.