📘 Documentação: Integração via API para Sellers – Plataforma Soulmkt

Tabela de conteúdos (TOC)

Objetivo
🧩 Como funciona a plataforma Soulmkt
🔧 Sobre a API Soulmkt
📚 Material de Apoio
🔐 1. Autenticação - Geração do Session ID
🛒 2. Selecionar Produto para Venda (catalogProductCreate)
📦 3. Atualizar Estoque (catalogInventoryStockItemUpdate)
📋 4. Listar Pedidos Pagos (salesOrderList)
🔄 5. Atualizar Pedido para “Aguardando Nota Fiscal” (salesOrderAddComment)
🧾 6. Emitir Nota Fiscal (salesOrderNFCreate)
🚚 7. Criar Remessa (salesOrderShipmentCreate)
📦 8. Atualizar Pedido para “Aguardando Confirmação” ou “Completo” (salesOrderAddComment)
🛠️ Suporte

Objetivo #

Este guia tem como objetivo detalhar o fluxo de integração via API entre vendedores (sellers) e a plataforma Soulmkt, permitindo a seleção de produtos, atualização de estoque, controle de pedidos, emissão de nota fiscal e remessa — tudo via requisições HTTP padronizadas.

🧩 Como funciona a plataforma Soulmkt #

A plataforma Soulmkt adota um modelo centralizado de catálogo de produtos. Isso significa que o administrador da loja é responsável por cadastrar os produtos na plataforma, incluindo todas as informações padrão, como:

Nome do produto
Descrição e características técnicas
Dimensões e peso
Categoria
Imagens e informações complementares

O papel do seller (vendedor) é apenas selecionar quais desses produtos ele deseja revender, sem precisar criar um novo item do zero. Ao selecionar o produto, o seller poderá definir dados específicos de sua operação:

Preço de venda (respeitando os limites mínimo e máximo definidos pelo administrador)
Status do produto
Disponibilidade de estoque
Estoque disponível
Etc…

Todo o restante das informações do produto permanece conforme definido originalmente pelo administrador da loja. Dessa forma, garante-se padronização no catálogo e maior controle da qualidade da informação exibida aos clientes.

🔧 Sobre a API Soulmkt #

A plataforma Soulmkt disponibiliza sua API via protocolo SOAP, com suporte às versões v1 e v2. Todos os métodos descritos nesta documentação utilizam essa interface.

Os exemplos de XML que serão inseridos ao longo deste documento foram testados e validados utilizando o Postman, ferramenta recomendada para testes, simulações e validação de integrações com a API da Soulmkt.

🧪 Ferramenta recomendada: Postman

📚 Material de Apoio #

Para facilitar a compreensão e aplicação prática da integração via API, disponibilizamos os seguintes materiais de apoio:

🧪 Collection Postman com exemplos XML:
Arquivo contendo todas as requisições utilizadas nesta documentação para testes e validações no Postman.

Collection-Soulmkt.postman_collection Baixar

🎥 Tutorial em vídeo (Loom):
Acesse a explicação completa do fluxo de integração no link:
https://www.loom.com/share/0bef231bd7554d46a21be455ae6294d0

🔐 1. Autenticação – Geração do `Session ID` #

O que faz: #

Realiza o login do seller na API e retorna um Session ID temporário (válido por aproximadamente 1 hora), necessário para autenticar todas as outras chamadas da API.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:OpenMage"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:login>
			<username xsi:type="xsd:string">login_api</username>
			<apiKey xsi:type="xsd:string">senha_api</apiKey>
		</ns1:login>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parâmetros: #

usuario_api: nome de usuário do seller
senha_api: senha associada ao usuário

Retorno: #

sessionId: Token de sessão

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:OpenMage" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <ns1:loginResponse>
            <loginReturn xsi:type="xsd:string">[session_id_gerado]</loginReturn>
        </ns1:loginResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

🛒 2. Selecionar Produto para Venda (`catalogProductCreate`) #

O que faz: #

Permite que o seller associe um produto já cadastrado pela loja à sua vitrine, passando a revender esse item.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:OpenMage"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:catalogProductCreate>
			<sessionId xsi:type="xsd:string">session_id</sessionId>
			<type xsi:type="xsd:string">simple</type>
			<set xsi:type="xsd:string">4</set>
			<sku xsi:type="xsd:string">pampasul07</sku>
			<productData xsi:type="ns1:catalogProductCreateEntity">
				<status xsi:type="xsd:string">1</status>
				<price xsi:type="xsd:string">170</price>
			</productData>
			<storeView xsi:nil="true"/>
            <identifierType xsi:type="xsd:string">sku</identifierType>
		</ns1:catalogProductCreate>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parâmetros: #

sessionId
type_id: Ex: simple
attribute_set_id: Ex: 4
sku: SKU do produto
productData:
- status: 1 (1: habilitado, 0: desabilitado)
- price: dentro da faixa permitida

❗ Respeite o preço mínimo e máximo definidos pela loja.

📦 3. Atualizar Estoque (`catalogInventoryStockItemUpdate`) #

O que faz: #

Informa a quantidade de unidades em estoque do produto selecionado, ativando a sua exibição na loja.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:OpenMage"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:catalogInventoryStockItemUpdate>
			<sessionId xsi:type="xsd:string">session_id</sessionId>
			<product xsi:type="xsd:string">sku_do_produto</product>
			<data xsi:type="ns1:catalogInventoryStockItemUpdateEntity">
				<qty xsi:type="xsd:string">49</qty>
				<is_in_stock xsi:type="xsd:int">1</is_in_stock>
			</data>
            <identifierType xsi:type="xsd:string">sku</identifierType>
		</ns1:catalogInventoryStockItemUpdate>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parâmetros: #

sessionId
product_id: sku do produto
data:
- qty: quantidade disponível
- is_in_stock: 1 (ativo) ou 0 (inativo)

📋 4. Listar Pedidos Pagos (`salesOrderList`) #

O que faz: #

Lista pedidos com status processing, indicando que foram pagos e estão aguardando ações do seller.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:OpenMage"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:salesOrderList>
			<sessionId xsi:type="xsd:string">session_id</sessionId>
			<filters xsi:type="ns1:filters">
				<filter SOAP-ENC:arrayType="ns1:associativeEntity[1]" xsi:type="SOAP-ENC:Array">
					<item xsi:type="ns1:associativeEntity">
						<key xsi:type="xsd:string">status</key>
						<value xsi:type="xsd:string">processing</value>
					</item>
				</filter>
			</filters>
		</ns1:salesOrderList>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parâmetros: #

sessionId
filters:
- status: processing

Retorno em XML com os pedidos encontrados.

🔄 5. Atualizar Pedido para “Aguardando Nota Fiscal” (`salesOrderAddComment`) #

O que faz: #

Atualiza o status do pedido para aguardando_nota_fiscal, permitindo que a nota fiscal seja emitida.

⚠️ Se o pedido não exige nota fiscal, este passo pode ser ignorado e o fluxo pode seguir diretamente para o passo 7 – Criar Remessa.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:OpenMage"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:salesOrderAddComment>
			<sessionId xsi:type="xsd:string">session_id</sessionId>
			<orderIncrementId xsi:type="xsd:string">id_do_pedido</orderIncrementId>
			<status xsi:type="xsd:string">aguardando_nota_fiscal</status>
			<comment xsi:nil="true"/>
			<notify xsi:nil="true"/>
		</ns1:salesOrderAddComment>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parâmetros: #

sessionId
order_id
status: aguardando_nota_fiscal

🧾 6. Emitir Nota Fiscal (`salesOrderNFCreate`) #

O que faz: #

Gera e associa uma nota fiscal ao pedido, incluindo os dados obrigatórios e os itens comprados.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:Store"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:ns2="urn:OpenMage"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:salesOrderNfCreate>
			<sessionId xsi:type="xsd:string">session_id</sessionId>
			<orderIncrementId xsi:type="xsd:string">id_do_pedido</orderIncrementId>
			<chave_nf xsi:type="xsd:string">45454545464545446555654544646546565644444444</chave_nf>
			<link_nf xsi:type="xsd:string">https://www.nfe.fazenda.gov.br/portal/consultaRecaptcha.aspx</link_nf>
			<numero_nf xsi:type="xsd:int">174</numero_nf>
			<serie_nf xsi:type="xsd:int">1</serie_nf>
			<data_nf xsi:type="xsd:string">2023-01-01</data_nf>
			<hora_nf xsi:type="xsd:string">12:47</hora_nf>
			<items SOAP-ENC:arrayType="ns2:orderNfItem[1]" xsi:type="SOAP-ENC:Array">
				<item xsi:type="ns2:orderNfItem">
					<item_id xsi:type="xsd:string">id_do_produto</item_id>
					<sku_marketplace xsi:type="xsd:string">sku_do_produto</sku_marketplace>
				</item>
			</items>
		</ns1:salesOrderNfCreate>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parâmetros: #

sessionId
order_id
Dados da nota:
- chave, numero, serie, data_emissao, hora, link_xml
Itens:
- product_id
- sku

🚚 7. Criar Remessa (`salesOrderShipmentCreate`) #

O que faz: #

Gera uma remessa para o pedido, registrando o envio dos produtos.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:OpenMage"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:salesOrderShipmentCreate>
			<sessionId xsi:type="xsd:string">session_id</sessionId>
			<orderIncrementId xsi:type="xsd:string">id_do_pedido</orderIncrementId>
			<itemsQty SOAP-ENC:arrayType="ns1:orderItemIdQty[2]" xsi:type="SOAP-ENC:Array">
				<item xsi:type="ns1:orderItemIdQty"/>
				<item xsi:type="ns1:orderItemIdQty"/>
			</itemsQty>
			<comment xsi:nil="true"/>
			<email xsi:nil="true"/>
			<includeComment xsi:nil="true"/>
		</ns1:salesOrderShipmentCreate>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parâmetros: #

sessionId
order_id
(opcional) items: item_id, qty

📦 8. Atualizar Pedido para “Aguardando Confirmação” ou “Completo” (`salesOrderAddComment`) #

O que faz: #

Finaliza o pedido com base na política configurada pelo administrador da loja. Existem dois fluxos possíveis:

🔄 Fluxo com confirmação manual (aguardando confirmação) #

Se o administrador da loja optar por utilizar o processo de confirmação por parte do cliente, o pedido deve ser atualizado para o status aguardando_confirmacao. Esse processo funciona da seguinte forma:

Após a criação da remessa, o seller atualiza o pedido com o status aguardando_confirmacao.
A plataforma envia automaticamente uma notificação para o cliente no painel da loja, solicitando que ele confirme o recebimento do produto.
O cliente pode então clicar para confirmar a entrega.
Uma vez confirmado, o pedido será automaticamente atualizado para o status complete.

⏱️ Se o cliente não realizar a confirmação em até 7 dias, o sistema atualizará o status para complete automaticamente.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:OpenMage"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:salesOrderAddComment>
			<sessionId xsi:type="xsd:string">session_id</sessionId>
			<orderIncrementId xsi:type="xsd:string">id_do_pedido</orderIncrementId>
			<status xsi:type="xsd:string">aguardando_confirmacao</status>
			<comment xsi:nil="true"/>
			<notify xsi:nil="true"/>
		</ns1:salesOrderAddComment>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

✔️ Fluxo direto (finalização imediata) #

Se o administrador não utilizar o processo de confirmação de entrega, o seller pode atualizar o pedido diretamente para o status complete, finalizando-o imediatamente após a remessa.

XML: #

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:ns1="urn:OpenMage"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<SOAP-ENV:Body>
		<ns1:salesOrderAddComment>
			<sessionId xsi:type="xsd:string">session_id</sessionId>
			<orderIncrementId xsi:type="xsd:string">id_do_pedido</orderIncrementId>
			<status xsi:type="xsd:string">complete</status>
			<comment xsi:nil="true"/>
			<notify xsi:nil="true"/>
		</ns1:salesOrderAddComment>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parâmetros: #

sessionId
order_id
status: aguardando_confirmacao ou complete

🛠️ Suporte #

Para suporte técnico e dúvidas sobre a API, entre em contato com a equipe Soulmkt através dos canais oficiais.

Objetivo #

🧩 Como funciona a plataforma Soulmkt #

🔧 Sobre a API Soulmkt #

📚 Material de Apoio #

🔐 1. Autenticação – Geração do Session ID #

O que faz: #

XML: #

Parâmetros: #

Retorno: #

🛒 2. Selecionar Produto para Venda (catalogProductCreate) #

O que faz: #

XML: #

Parâmetros: #

📦 3. Atualizar Estoque (catalogInventoryStockItemUpdate) #

O que faz: #

XML: #

Parâmetros: #

📋 4. Listar Pedidos Pagos (salesOrderList) #

O que faz: #

XML: #

Parâmetros: #

🔄 5. Atualizar Pedido para “Aguardando Nota Fiscal” (salesOrderAddComment) #

O que faz: #

XML: #

Parâmetros: #

🧾 6. Emitir Nota Fiscal (salesOrderNFCreate) #

O que faz: #

XML: #

Parâmetros: #

🚚 7. Criar Remessa (salesOrderShipmentCreate) #

O que faz: #

XML: #

Parâmetros: #

📦 8. Atualizar Pedido para “Aguardando Confirmação” ou “Completo” (salesOrderAddComment) #

O que faz: #

🔄 Fluxo com confirmação manual (aguardando confirmação) #

XML: #

✔️ Fluxo direto (finalização imediata) #

XML: #

Parâmetros: #

🛠️ Suporte #

🔐 1. Autenticação – Geração do `Session ID` #

🛒 2. Selecionar Produto para Venda (`catalogProductCreate`) #

📦 3. Atualizar Estoque (`catalogInventoryStockItemUpdate`) #

📋 4. Listar Pedidos Pagos (`salesOrderList`) #

🔄 5. Atualizar Pedido para “Aguardando Nota Fiscal” (`salesOrderAddComment`) #

🧾 6. Emitir Nota Fiscal (`salesOrderNFCreate`) #

🚚 7. Criar Remessa (`salesOrderShipmentCreate`) #

📦 8. Atualizar Pedido para “Aguardando Confirmação” ou “Completo” (`salesOrderAddComment`) #