Este post faz parte de uma séries de posts que vou fazer sobre os WebServices do Magento, tanto em SOAP quanto em REST. Espero realmente que curtam este conteúdo e o que está por vir.
A API SOAP v1 do Magento proporciona a possibilidade de gerenciar suas lojas e-commerce fazendo chamadas para trabalhar com os resources do Magento como clientes, produtos e pedidos de vendas. Ele também permite gerenciar os carrinhos de compras e o estoque de cada loja. A API SOAP versão v2 está disponível no Magento desde sua versão 1.3 e uma versão do WS-I compliant está disponível desde sua versão 1.6. Supported Types A API do Magento suporta SOAP e XML-RPC, aonde SOAP é o protocolo padrão. SOAP Para se conectar ao Web Services do Magento via SOAP, carregue o arquivo WSDL em seu cliente SOAP de alguma dessas duas URLs:
http://magentohost/api/?wsdl
http://magentohost/api/soap/?wsdl
Aonde magentohost é o domínio para sua loja Magento. A partir da versão 1.3 você deve usar a URL abaixo para acessar a API v2 do Magento, o qual teve uma melhoria de compatibilidade com Java e .NET:
http://magentohost/api/v2_soap?wsdl=1
O exemplo PHP abaixo mostra como fazer uma chamada SOAP na API v1 do Magento:
[code language=”php”]
$client = new SoapClient(‘http://magentohost/soap/api/?wsdl’);
// If somestuff requires api authentification,
// then get a session token
$session = $client->login(‘apiUser’, ‘apiKey’);
$result = $client->call($session, ‘somestuff.method’);
$result = $client->call($session, ‘somestuff.method’, ‘arg1’);
$result = $client->call($session, ‘somestuff.method’, array(‘arg1’, ‘arg2’, ‘arg3’));
$result = $client->multiCall($session, array(
array(‘somestuff.method’),
array(‘somestuff.method’, ‘arg1’),
array(‘somestuff.method’, array(‘arg1’, ‘arg2’))
));
// If you don’t need the session anymore
$client->endSession($session);
[/code]
XML-RPC
Para utilizar o XML-RPC, carregue a seguinte URL em seu cliente XML-RPC:
http://magentohost/api/xmlrpc/
Aonde magentohost é o domínio para sua loja Magento.
O seguinte exemplo PHP mostra como fazer chamadas XML-RPC:
[code language=”php”]
$client = new Zend_XmlRpc_Client(‘http://magentohost/api/xmlrpc/’);
// If somestuff requires api authentification,
// we should get session token
$session = $client->call(‘login’, array(‘apiUser’, ‘apiKey’));
$client->call(‘call’, array($session, ‘somestuff.method’, array(‘arg1’, ‘arg2’, ‘arg3’)));
$client->call(‘call’, array($session, ‘somestuff.method’, ‘arg1’));
$client->call(‘call’, array($session, ‘somestuff.method’));
$client->call(‘multiCall’, array($session,
array(
array(‘somestuff.method’, ‘arg1’),
array(‘somestuff.method’, array(‘arg1’, ‘arg2’)),
array(‘somestuff.method’)
)
));
// If you don’t need the session anymore
$client->call(‘endSession’, array($session));
[/code]
O XML-RPC suporta apenas a versão 1 da API do Magento.
Métodos da API
A tabela seguinte contem os métodos da API que podem ser chamados de seu cliente SOAP ou XML-RPC na API v1 do Magento.
| Method | Description | Return Value |
|---|---|---|
| startSession() | Start the API session and return session ID. | string |
| endSession(sessionId) | End the API session. | boolean |
| login(apiUser, apiKey) | Start the API session, return the session ID, and authorize the API user. | string |
| call(sessionId, resourcePath,array arguments) | Call the API resource that is allowed in the current session. See Note below. | mixed |
| multiCall(sessionId, array calls,array options) | Call the API resource’s methods that are allowed for current session. See Notes below. | array |
| resources(sessionId) | Return a list of available API resources and methods allowed for the current session. | array |
| globalFaults(sessionId) | Return a list of fault messages and their codes that do not depend on any resource. | array |
| resourceFaults(sessionId, resourceName) | Return a list of the specified resource fault messages, if this resource is allowed in the current session. | array |
Nota: para chamadas e multiplas chamadas, se nenhuma sessão for especificada, você pode chamar apenas resources que não são protegidos nas chamadas.
Nota: Para múltiplas chamadas, se a opção “break” for especificada, a múltipla chamada para no primeiro erro.
A API v2 do Magento não suporta os métodos call() e multicall(), em vez disso ele fornece um método separado para cada resource da API.
Erros Globais da API
A seguinte tabela contem os códigos dos erros que são aplicados para todas as chamadas SOAP/XML-RPC.
| Fault Code | Fault Message |
|---|---|
| 0 | Unknown Error |
| 1 | Internal Error. Please see log for details. |
| 2 | Access denied. |
| 3 | Invalid api path. |
| 4 | Resource path is not callable. |
API SOAP Versão v2
Desde a versão 1.3 do Magento, a versão v2 do API do SOAP está disponível. A principal diferença entre v1 e v2 é que ao invés de utilizar os métodos call e multicall, ele separa os métodos para cada ação.
Por exemplo, considere o seguinte código PHP utilizando a v1 do SOAP:
[code language=”php”]
$params = array(array(
‘status’=>array(‘eq’=>’pending’),
‘customer_is_guest’=>array(‘eq’=>’1’))
));
$result = $client->call($sessionId, ‘sales_order.list’, $params);
[/code]
Com o SOAP v2, o seguinte código seria equivalente:
[code language=”php”]
$params = array(‘filter’ => array(
array(‘key’ => ‘status’, ‘value’ => ‘pending’),
array(‘key’ => ‘customer_is_guest’, ‘value’ => ‘1’)
));
$result = $client->salesOrderList($sessionId, $params);
[/code]
Note que o WSDL para a v1 e v2 do SOAP são diferentes. No SOAP v1, customizar a API não envolve a alteração do WSDL. No SOAP v2, as alterações no WSDL são necessárias.
Você pode configurar o SOAP v2 para ser compatível com o WS-I no menu de configurações do sistema. Para fazer a alteração navegue até Services > Magento Core API > WS-I Compliance e altere seu valor para Yes.
Também perceba que o WSDL para o SOAP v1 e v2 são diferentes quando estão em modo compatível com WS-I.
Utilizando a compatibilidade WS-I para o WSDL da API do SOAP v2, fica fácil gerar automaticamente as classes do cliente para Java, .NET e outras linguagens que utilizem bibliotecas padrão.
Um abraço e até a próxima!
Tiago Sampaio
