Introduction

Nota (PT-BR): documentação técnica em inglês (fiel ao magento/devdocs-m1); instruções e comentários em português.

Introduction

The Magento SOAP v1 API provides you with the ability to manage your eCommerce stores by providing calls for working with resources such as customers, categories, products, and sales orders. It also allows you to manage shopping carts and inventory.

A SOAP v2 API version has been available since Magento 1.3, and a WS-I compliant version has been available since Magento 1.6.

Supported Types

The Magento API supports SOAP and XML-RPC, where SOAP is the default protocol.

SOAP

Load the WSDL into your SOAP client from either of these URLs:

• http://magentohost/api/?wsdl
• http://magentohost/api/soap/?wsdl

As of Magento 1.3, access the SOAP v2 API at:

• http://magentohost/api/v2_soap?wsdl=1

XML-RPC

Load the following URL into your XML-RPC client:

• http://magentohost/api/xmlrpc/

XML-RPC only supports version 1 of the Magento API.

Placeholder magentohost

Nota (PT-BR): em todos os exemplos da referência, magentohost é um placeholder. Substitua pelo domínio da sua loja Mageshop (ex.: https://sualoja.mageshop.com.br) antes de executar. Sempre use HTTPS em produção.

Global API Methods (v1) & session_token

Todos os badges session_token nos cards dos endpoints apontam para esta seção. O sessionId é obtido via login() e deve ser passado como primeiro argumento em todas as chamadas autenticadas. Ele expira ao ser encerrado com endSession() ou após o timeout da sessão do servidor (normalmente 1h).

• startSession() — Start the API session and return session ID
• endSession(sessionId) — End the API session
• login(apiUser, apiKey) — Start the session and authorize the user
• call(sessionId, resourcePath, array arguments) — Call an API resource
• multiCall(sessionId, array calls, array options) — Call multiple resource methods
• resources(sessionId) — List allowed resources and methods
• globalFaults(sessionId) — List global fault messages
• resourceFaults(sessionId, resourceName) — List fault messages of a resource

SOAP API v2 does not support call() / multiCall(). It exposes a separate method for each API resource (ex.: customerCustomerList()).

Global API Faults

• 0 — Unknown Error
• 1 — Internal Error. Please see log for details.
• 2 — Access denied.
• 3 — Invalid API path.
• 4 — Resource path is not callable.

WS-I Compliance (v2)

Em System > Configuration > Services > Magento Core API > WS-I Compliance = Yes. Com WS-I habilitado, namespaces XML são usados e o WSDL fica consumível por geradores de Java/.NET. Os exemplos marcados como SOAP V2 (WS-I Compliance Mode) assumem este modo.

Rate limits & sandbox (Mageshop SaaS)

Nota (PT-BR): a API oficial do Magento 1 não define rate limit por endpoint. No ambiente SaaS Mageshop recomendamos, por padrão conservador:

• Máximo de 1 requisição a cada 5 segundos por conta de API para cargas contínuas (importações, sincronizações).
• Para operações em lote, prefira multiCall() (SOAP v1) em vez de várias chamadas simples.
• Timeout de sessão: 1 hora. Renove via login() quando receber fault 5 (sessão expirada).
• Ambiente de teste: abra chamado para o time de integrações obter credenciais de sandbox isoladas do ambiente produtivo.

Esses limites são recomendações operacionais, não limites de hard-block. Cargas mais pesadas podem ser acordadas com o time de operações.

Changelog

• 2026-04-18 — Paridade total da referência com magento/devdocs-m1 no módulo Mage_Customer (piloto): tabelas tipadas, entity schemas, exemplos V1/V2/WS-I e response dumps verbatim.