#Orientações de Integração — SOAP API Magento 1

Leitura em lote de preço e estoque (módulo MageShop_BatchProductInfo)

Documento de referência para integrações ERP ↔ Magento 1 que precisam coletar preço e estoque de muitos produtos em poucas chamadas. Expõe um método SOAP v2 customizado que substitui o par clássico catalogProductInfo + cataloginventoryStockItemList.

#1. Contexto

Em integrações ERP ↔ Magento 1, é comum coletar preço e estoque de centenas ou milhares de SKUs para conferência, reconciliação ou sincronização periódica. O caminho ingênuo — uma chamada por SKU em catalogProductInfo + outra em cataloginventoryStockItemList — gera 2N requisições, cada uma com seu custo de hidratação de model, round-trip SOAP e parsing XML.

Este módulo expõe um único método SOAP que retorna preço, estoque e dados básicos de catálogo de uma lista arbitrária de SKUs em uma única chamada, lendo direto dos índices catalog_product_index_price e cataloginventory_stock_item via PDO — sem hidratar models Magento.

#2. Convenções e Autenticação

#2.1. Convenções

• Endpoint WSDL (SOAP v2): https://<dominio>/api/v2_soap/?wsdl
• Endpoint WSDL (SOAP v1 RPC encoded): https://<dominio>/api/?wsdl
• Login obrigatório: toda chamada ao método exige um sessionId obtido previamente via login(API_USER, API_KEY).
• Numéricos retornados como string — price, qty, special_price vêm como string no XML; converter no consumidor (floatval / Decimal).

#2.2. Autenticação

#ACL exigida

#Configuração do role da API

1. Admin → System → Web Services → SOAP/XML-RPC - Roles.
2. Editar (ou criar) o role que o usuário da API utiliza.
3. Em Role Resources, marcar Batch Product Info → Info → Get Info.
4. Salvar e vincular ao usuário da API em System → Web Services → SOAP/XML-RPC - Users.

#3. Endpoint — mageshopBatchProductInfoGetInfo

#3.1. Identificação

#3.2. Parâmetros

#Notas sobre os parâmetros

• identifiers — sem limite declarado pelo módulo. Há dedupe automático (valores repetidos contam uma vez na resposta). A ordem do input é preservada na resposta.
• filterBy = sku busca pela coluna sku da tabela catalog_product_entity. filterBy = entity_id busca pela coluna entity_id.
• store afeta price, status, visibility, special_price e suas datas — todos campos com override por store no Magento. Se omitido, usa a default store view. Estoque é global no Magento 1 e não depende da store.

#3.3. Exemplo de request — SOAP v1 RPC encoded

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:urn="urn:OpenMage"
                  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:mageshopBatchProductInfoGetInfo soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <sessionId xsi:type="xsd:string">{token}</sessionId>
         <identifiers xsi:type="urn:mageshopBatchProductInfoIdentifierArray" soapenc:arrayType="xsd:string[3]">
            <item xsi:type="xsd:string">SKU-001</item>
            <item xsi:type="xsd:string">SKU-002</item>
            <item xsi:type="xsd:string">SKU-INEXISTENTE</item>
         </identifiers>
         <filterBy xsi:type="xsd:string">sku</filterBy>
         <store xsi:type="xsd:string"></store>
      </urn:mageshopBatchProductInfoGetInfo>
   </soapenv:Body>
</soapenv:Envelope>

#Variações

Buscando por entity_id:

<identifiers xsi:type="urn:mageshopBatchProductInfoIdentifierArray" soapenc:arrayType="xsd:string[3]">
   <item xsi:type="xsd:string">4521</item>
   <item xsi:type="xsd:string">4522</item>
   <item xsi:type="xsd:string">999999</item>
</identifiers>
<filterBy xsi:type="xsd:string">entity_id</filterBy>

Para store específica:

<store xsi:type="xsd:string">default</store>

#4. Resposta

#4.1. Exemplo

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:ns1="urn:OpenMage"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <ns1:mageshopBatchProductInfoGetInfoResponse>
         <result xsi:type="ns1:mageshopBatchProductInfoEntityArray" SOAP-ENC:arrayType="ns1:mageshopBatchProductInfoEntity[3]">
            <item xsi:type="ns1:mageshopBatchProductInfoEntity">
               <found xsi:type="xsd:int">1</found>
               <sku xsi:type="xsd:string">SKU-001</sku>
               <product_id xsi:type="xsd:string">4521</product_id>
               <type_id xsi:type="xsd:string">simple</type_id>
               <status xsi:type="xsd:int">1</status>
               <visibility xsi:type="xsd:int">4</visibility>
               <price xsi:type="xsd:string">199.9000</price>
               <special_price xsi:type="xsd:string">159.9000</special_price>
               <special_from_date xsi:type="xsd:string">2026-05-01 00:00:00</special_from_date>
               <special_to_date xsi:type="xsd:string">2026-05-31 23:59:59</special_to_date>
               <qty xsi:type="xsd:string">42.0000</qty>
               <is_in_stock xsi:type="xsd:int">1</is_in_stock>
               <manage_stock xsi:type="xsd:int">1</manage_stock>
            </item>
            <item xsi:type="ns1:mageshopBatchProductInfoEntity">
               <found xsi:type="xsd:int">1</found>
               <sku xsi:type="xsd:string">SKU-002</sku>
               <product_id xsi:type="xsd:string">4522</product_id>
               <type_id xsi:type="xsd:string">simple</type_id>
               <status xsi:type="xsd:int">1</status>
               <visibility xsi:type="xsd:int">4</visibility>
               <price xsi:type="xsd:string">89.9000</price>
               <qty xsi:type="xsd:string">0.0000</qty>
               <is_in_stock xsi:type="xsd:int">0</is_in_stock>
               <manage_stock xsi:type="xsd:int">1</manage_stock>
            </item>
            <item xsi:type="ns1:mageshopBatchProductInfoEntity">
               <found xsi:type="xsd:int">0</found>
               <sku xsi:type="xsd:string">SKU-INEXISTENTE</sku>
            </item>
         </result>
      </ns1:mageshopBatchProductInfoGetInfoResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

#4.2. Campos da resposta

Cada item retornado segue a estrutura abaixo. Campos com valor nulo ou não aplicável podem ser omitidos do XML — o consumidor deve tratar a ausência do nó como "campo não informado".

#4.3. Pontos importantes

• Ordem da resposta — segue a ordem dos identifiers no request (depois do dedupe). Isso facilita correlação direta com o pedido sem precisar indexar por SKU no consumidor.
• Itens não encontrados — vêm com found=0 e apenas sku preenchido (ou product_id, se o filtro era entity_id). É echo do valor do request, para correlação. Não gera fault SOAP, é resposta normal.

• Special price cru — special_price traz o valor cadastrado mesmo se a data atual estiver fora do período special_from_date → special_to_date. Cabe ao consumidor decidir se o aplica como ativo ou não, comparando com a data corrente.

• Estoque global no Magento 1 — não há MSI no M1. Os campos qty, is_in_stock e manage_stock não dependem da store informada. O parâmetro store afeta apenas preço, status e visibility.

#5. Erros — Faults SOAP

#6. Receita prática — cliente PHP

$client = new SoapClient('https://sualoja.com.br/api/v2_soap/?wsdl', [
    'trace'      => true,
    'cache_wsdl' => WSDL_CACHE_NONE,
]);

$session = $client->login('API_USER', 'API_KEY');

$result = $client->mageshopBatchProductInfoGetInfo(
    $session,
    ['SKU-001', 'SKU-002', 'SKU-INEXISTENTE'],
    'sku',
    null
);

foreach ($result as $item) {
    if ($item->found) {
        echo "{$item->sku}: R\$ {$item->price} | estoque: {$item->qty}\n";
    } else {
        echo "{$item->sku}: não encontrado\n";
    }
}

#7. Características técnicas

Para o time de N2 entender por que este endpoint é mais barato que o caminho ingênuo:

• 1 única query SQL com LEFT JOIN em tabelas indexadas (catalog_product_entity, catalog_product_index_price, cataloginventory_stock_item, EAV de status/visibility/special_price). Mesmo com milhares de SKUs, é 1 round-trip ao banco.
• Sem hidratação de model — usa core_read PDO direto. Não há custo de Mage::getModel('catalog/product')->load() por item, que sozinho instanciaria objetos completos e dispararia events.
• Preço lido do índice — catalog_product_index_price já contém o preço com regras de catálogo aplicadas no reindex. Não recalcula nada na hora da chamada.
• Estoque lido do índice — cataloginventory_stock_item direto.
• Sem cache de resposta — preço e estoque mudam com frequência alta; cachear a resposta poderia entregar dado defasado ao ERP. O cache fica por conta do consumidor, com janela curta se for o caso.

#8. Boas práticas e resultado esperado

#Recomendações

• Use este endpoint sempre que precisar de mais de 1 SKU. Para um único SKU, catalogProductInfo continua adequado — mas a partir de ~5 SKUs, este método já compensa pelo overhead reduzido.
• Dedupe do lado do cliente é dispensável — o módulo já deduplica identifiers internamente. Não precisa pré-processar.
• Inspecione found por item — não basta verificar que a chamada retornou sem fault. Cada item pode ter found=0 mesmo quando a chamada como um todo deu certo.
• Reaproveite o sessionId — o login SOAP tem custo. Manter uma sessão viva e renovar só quando vier fault 5 (sessão expirada) é mais eficiente que logar a cada batch.
• Replique a lógica de janela de promoção no ERP — special_price vem cru. Se o ERP precisa do preço efetivo do dia, comparar now com special_from_date / special_to_date.

#Resultado esperado da adoção

• Redução significativa do número total de chamadas SOAP (de 2N para 1 por lote).
• Menor consumo de CPU e banco de dados na aplicação Magento — uma query única indexada substitui N hidratações de model.
• Sincronizações de catálogo mais rápidas e previsíveis.
• Menor risco de timeouts em ERPs que sincronizam catálogos grandes.

Em caso de dúvidas sobre a implementação ou sobre limites adequados de tamanho de lote para o ambiente, fica à disposição o time de integração.