Formatos de mensagem de solicitação e resposta

Formatos de mensagem de solicitação e resposta

A solicitação

    <?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>

Essa linha indica que os dados subsequentes são codificados em XML em UTF-8.
A etiqueta <call> indica qual método de API está sendo chamado usando seu atributo de método. Neste exemplo, o método de API é exportData. Além disso, callerName é um atributo obrigatório na etiqueta <call>. Ele identifica seu aplicativo cliente no sistema e é usado para fins de identificação na solução de problemas e no registro.
Todo método de API precisa autenticar o usuário que faz a chamada. Isso geralmente é feito fornecendo um nome de logon e uma senha. Outros atributos podem ser especificados aqui. Consulte a documentação de cada função de API para obter mais detalhes sobre credenciais.
Alguns métodos de API exigem dados adicionais na solicitação. Por exemplo, o método exportData requer alguns critérios que descrevem quais períodos, contas, níveis etc. devem ser usados na recuperação dos dados. Essa parte da solicitação varia de método para método.
Esta é a etiqueta de fechamento para a etiqueta de chamada na linha 2.

A resposta

     <?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>

Semelhante à solicitação, essa linha indica que os dados subsequentes estão formatados como XML e codificados em UTF-8.
Cada resposta é colocada em uma etiqueta <response>. Se a solicitação foi bem-sucedida, o atributo de êxito na etiqueta de resposta é definido como verdadeiro. Se a solicitação não foi bem-sucedida, o atributo de êxito é definido como falso.
Muitas chamadas à API retornam esse bloco opcional <messages> que contém uma lista de mensagens geradas pelo servidor. Esse bloco pode não aparecer se o servidor não tiver mensagens para retornar em resposta à chamada. As mensagens de erro sempre serão exibidas no bloco de mensagens.
Cada mensagem no bloco de mensagens tem um atributo de chave que identifica o tipo de mensagem que está sendo transmitida. A etiqueta de mensagem também contém o texto da mensagem do servidor, incluindo valores de retorno, valores de status ou outros metadados independentes sobre o êxito ou a falha da solicitação. Uma resposta pode conter um número ilimitado de etiquetas de mensagem.
A etiqueta das mensagens de fechamento.
A saída real da chamada de método da API, se alguma for retornada, é colocada em uma etiqueta <output>.
A saída real da chamada de método da API será exibida aqui. Essa saída varia dependendo de qual método foi chamado.
A etiqueta de saída de fechamento.
A etiqueta de resposta de fechamento.