Ver categorias

Documentation for Order Flow Query and Update via Soulmkt Marketplace API (V2)

Tabela de conteúdos (TOC)

This documentation aims to guide you step by step through the process of querying and updating the order flow in a Soulmkt Marketplace store using APIs V1 and V2. Even if you are not familiar with the process, this detailed explanation will help you understand how to perform the task.

1. Introduction #

The Soulmkt Marketplace offers two versions of the API (V1 and V2) to interact with the system and perform operations such as updating or querying the order flow. Both versions use the SOAP (Simple Object Access Protocol) protocol to send and receive data in XML format.

This guide will focus on how to update order flows using XML request examples that can be sent via tools such as Postman.

2. Prerequisites #

Before getting started, make sure you have:

  • Access to the Soulmkt Marketplace API: You will need credentials (username and password) to obtain a sessionId, which is necessary to authenticate requests.
  • Order Identifier: The ID of the order you want to update.
  • Request Sending Tool: We recommend using Postman or any other tool that allows sending SOAP requests.

3. Platform Order Flows #

3.1 Obtain the sessionId #

https://api.soulmkt.dev/examples.phtml

Before performing any operation via API, you must obtain a sessionId to authenticate your requests.

Example Request for Login:
<?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">seu_usuario</username>
			<apiKey xsi:type="xsd:string">sua_senha</apiKey>
		</ns1:login>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response:
If the login is successful, you will receive a sessionId.

<SOAP-ENV:Envelope>
	<SOAP-ENV:Body>
		<ns1:loginResponse>
			<result xsi:type="xsd:string">1234567890abcdef1234567890abcdef</result>
		</ns1:loginResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Save it to use in the following requests.

3.2 Query Paid Orders #

https://api.soulmkt.dev/sales_order.info.phtml

Use this method to retrieve a list of paid orders.

<SOAP-ENV:Body>
    <ns1:salesOrderList>
        <sessionId xsi:type="xsd:string">1234567890abcdef1234567890abcdef</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>

Field Explanation:

  • sessionId: Token obtained from the previous step.
  • key: Attribute used for filtering, such as status.
  • value: Desired value for filtering (e.g., processing).

Response:
If successful, the system will return the matching order data. 


    <item xsi:type="ns1:salesOrderListEntity">
      <increment_id xsi:type="xsd:string">100000048-9</increment_id>
      <store_id xsi:type="xsd:string">1</store_id>
      <created_at xsi:type="xsd:string">2020-11-12 16:58:08</created_at>
      <updated_at xsi:type="xsd:string">2020-11-12 16:59:15</updated_at>
      <customer_id xsi:type="xsd:string">18</customer_id>
      <discount_amount xsi:type="xsd:string">0.0000</discount_amount>
      <subtotal xsi:type="xsd:string">10.0000</subtotal>
      <grand_total xsi:type="xsd:string">10.0000</grand_total>
      <total_paid xsi:type="xsd:string">10.0000</total_paid>
      <total_qty_ordered xsi:type="xsd:string">1.0000</total_qty_ordered>
      <total_invoiced xsi:type="xsd:string">10.0000</total_invoiced>
      <base_discount_amount xsi:type="xsd:string">0.0000</base_discount_amount>
      <base_subtotal xsi:type="xsd:string">10.0000</base_subtotal>
      <base_grand_total xsi:type="xsd:string">10.0000</base_grand_total>
      <base_total_paid xsi:type="xsd:string">10.0000</base_total_paid>
      <base_total_invoiced xsi:type="xsd:string">10.0000</base_total_invoiced>
      <billing_address_id xsi:type="xsd:string">160</billing_address_id>
      <billing_firstname xsi:type="xsd:string">Alexsandro</billing_firstname>
      <billing_lastname xsi:type="xsd:string">Soulmkt</billing_lastname>
      <billing_name xsi:type="xsd:string">Alexsandro Soulmkt</billing_name>
      <weight xsi:type="xsd:string">0.0000</weight>
      <store_name xsi:type="xsd:string">Marketplace Marketplace PT:Português</store_name>
      <status xsi:type="xsd:string">processing</status>
      <state xsi:type="xsd:string">processing</state>
      <global_currency_code xsi:type="xsd:string">BRL</global_currency_code>
      <base_currency_code xsi:type="xsd:string">BRL</base_currency_code>
      <store_currency_code xsi:type="xsd:string">BRL</store_currency_code>
      <order_currency_code xsi:type="xsd:string">BRL</order_currency_code>
      <shipping_description xsi:type="xsd:string"></shipping_description>
      <customer_email xsi:type="xsd:string">[email protected]</customer_email>
      <customer_firstname xsi:type="xsd:string">Alexsandro</customer_firstname>
      <customer_lastname xsi:type="xsd:string">Soulmkt</customer_lastname>
      <quote_id xsi:type="xsd:string">0</quote_id>
      <is_virtual xsi:type="xsd:string">1</is_virtual>
      <customer_group_id xsi:type="xsd:string">5</customer_group_id>
      <customer_note_notify xsi:type="xsd:string">1</customer_note_notify>
      <customer_is_guest xsi:type="xsd:string">0</customer_is_guest>
      <order_id xsi:type="xsd:string">83</order_id>
      <protect_code xsi:type="xsd:string">a5b382</protect_code>
      <base_discount_invoiced xsi:type="xsd:string">0.0000</base_discount_invoiced>
      <base_shipping_invoiced xsi:type="xsd:string">0.0000</base_shipping_invoiced>
      <base_subtotal_invoiced xsi:type="xsd:string">10.0000</base_subtotal_invoiced>
      <base_tax_invoiced xsi:type="xsd:string">0.0000</base_tax_invoiced>
      <base_total_invoiced_cost xsi:type="xsd:string">0.0000</base_total_invoiced_cost>
      <discount_invoiced xsi:type="xsd:string">0.0000</discount_invoiced>
      <shipping_invoiced xsi:type="xsd:string">0.0000</shipping_invoiced>
      <subtotal_invoiced xsi:type="xsd:string">10.0000</subtotal_invoiced>
      <tax_invoiced xsi:type="xsd:string">0.0000</tax_invoiced>
      <paypal_ipn_customer_notified xsi:type="xsd:string">0</paypal_ipn_customer_notified>
      <base_subtotal_incl_tax xsi:type="xsd:string">10.0000</base_subtotal_incl_tax>
      <base_total_due xsi:type="xsd:string">0.0000</base_total_due>
      <subtotal_incl_tax xsi:type="xsd:string">10.0000</subtotal_incl_tax>
      <total_due xsi:type="xsd:string">0.0000</total_due>
      <customer_dob xsi:type="xsd:string">2000-01-01 00:00:00</customer_dob>
      <total_item_count xsi:type="xsd:string">1</total_item_count>
      <hidden_tax_invoiced xsi:type="xsd:string">0.0000</hidden_tax_invoiced>
      <base_hidden_tax_invoiced xsi:type="xsd:string">0.0000</base_hidden_tax_invoiced>
    </item>

  </result>
</ns1:salesOrderListResponse>

3.3 Change Order Status to awaiting_invoice or awating_shipping #

https://api.soulmkt.dev/sales_order.addComment.phtml

3.3.1 Order with Invoice #

Update the order status to awaiting_invoice to remove it from the pending list.


<?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">1234567890abcdef1234567890abcdef</sessionId>
      <orderIncrementId xsi:type="xsd:string">100000183-9</orderIncrementId>
      <status xsi:type="xsd:string">awaiting_invoice</status>
      <comment xsi:nil="true"/>
      <notify xsi:nil="true"/>
    </ns1:salesOrderAddComment>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Field Explanation:

  • sessionId: Authentication token.
  • orderIncrementId: Order number.
  • status: Desired status (awaiting_invoice).

Response:
If successful, you will receive a confirmation response.

<?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:salesOrderAddCommentResponse>
            <result xsi:type="xsd:boolean">true</result>
        </ns1:salesOrderAddCommentResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

3.3.2 Order without Invoice #

Update the order status to awaiting_shipping.

<?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">1234567890abcdef1234567890abcdef</sessionId>
			<orderIncrementId xsi:type="xsd:string">100000183-9</orderIncrementId>
			<status xsi:type="xsd:string">awaiting_shipping</status>
			<comment xsi:nil="true"/>
			<notify xsi:nil="true"/>
		</ns1:salesOrderAddComment>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Field Explanation:

  • sessionId: Authentication token.
  • orderIncrementId: Order number.
  • status: Desired status (awaiting_shipping).

Response:
If successful, you will receive a confirmation response. 

<?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:salesOrderAddCommentResponse>
            <result xsi:type="xsd:boolean">true</result>
        </ns1:salesOrderAddCommentResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

3.4 Add Invoice Data to the Order #

https://api.soulmkt.dev/sales_order_nf.create.phtml

⚠️ Only perform this step if the order has an invoice. Otherwise, proceed to step 3.5.

After providing invoice data for all items, the system automatically updates the order status to nf_emitida.

<?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">1234567890abcdef1234567890abcdef</sessionId>
			<orderIncrementId xsi:type="xsd:string">100000180-9</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">305</item_id>
					<sku_marketplace xsi:type="xsd:string">bombacha-001</sku_marketplace>
				</item>
			</items>
		</ns1:salesOrderNfCreate>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Field Explanation:

  • sessionId: Authentication token.
  • orderIncrementId: Order number.
  • chave_nf: Invoice key.
  • link_nf: Invoice link (URL).
  • numero_nf: Invoice number.
  • serie_nf: Invoice series.
  • data_nf: Invoice issue date (YYYY-MM-DD).
  • hora_nf: Invoice issue time (HH:MM).
  • item_id: Item identifier.
  • sku_marketplace: SKU in the marketplace.

Response:
If successful, the system will return a success response.

<?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:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <ns1:salesOrderNfCreateResponse>
            <result xsi:type="xsd:int">1</result>
        </ns1:salesOrderNfCreateResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

3.5 Add Tracking Data to the Order #

https://api.soulmkt.dev/sales_order_shipment.create.phtml

<?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">1234567890abcdef1234567890abcdef</sessionId>
			<orderIncrementId xsi:type="xsd:string">100000180-9</orderIncrementId>
			<itemsQty SOAP-ENC:arrayType="ns1:orderItemIdQty[2]" xsi:type="SOAP-ENC:Array">
                <order_item_id>1</order_item_id>
                <qty>1</qty>
			</itemsQty>
			<comment xsi:type="xsd:string">Delivery</comment>
			<email xsi:nil="true"/>
			<includeComment xsi:nil="true"/>
		</ns1:salesOrderShipmentCreate>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Field Explanation:

  • sessionId: Authentication token.
  • orderIncrementId: Order number.
  • order_item_id: Item ID being shipped.
  • qty: Quantity of the item shipped.
  • comment: Shipping comment (e.g., “Delivery”).
  • email: Whether to notify the customer.
  • includeComment: Whether to include the comment in notifications.

Response:
If successful, the system will return a shipment ID.

<?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:salesOrderShipmentCreateResponse>
            <shipmentIncrementId xsi:type="xsd:string">100000053</shipmentIncrementId>
        </ns1:salesOrderShipmentCreateResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

3.6 Update Order to complete or aguardando_confirmacao #

https://api.soulmkt.dev/sales_order.addComment.phtml

3.6.1 Order Delivery with Customer Confirmation #

If the seller has integration to track when the order reaches the customer, they can first set the status to awaiting_confirmation. Once the order is confirmed by the customer, update the status to complete.

⚠️ Make sure the confirmation process is enabled in the Marketplace. If not, proceed to 3.6.2.

<?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">1234567890abcdef1234567890abcdef</sessionId>
			<orderIncrementId xsi:type="xsd:string">100000183-9</orderIncrementId>
			<status xsi:type="xsd:string">awaiting_confirmation</status>
			<comment xsi:nil="true"/>
			<notify xsi:nil="true"/>
		</ns1:salesOrderAddComment>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Field Explanation:

  • sessionId: Authentication token.
  • orderIncrementId: Order number.
  • status: Desired status (awaiting_confirmation and later complete).

Response:
If successful, the system will confirm the update. 

<?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:salesOrderAddCommentResponse>
            <result xsi:type="xsd:boolean">true</result>
        </ns1:salesOrderAddCommentResponse>
    </SOAP-ENV:Body>

3.6.2 Order Delivery Without Customer Confirmation #

If the customer confirmation feature is not enabled, set the order directly to complete.

(XML example omitted)

Field Explanation:

  • sessionId: Authentication token.
  • orderIncrementId: Order number.
  • status: Desired status (complete).

Response:
If successful, the system will confirm the update. 

<?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">1234567890abcdef1234567890abcdef</sessionId>
			<orderIncrementId xsi:type="xsd:string">100000183-9</orderIncrementId>
			<status xsi:type="xsd:string">complete</status>
			<comment xsi:nil="true"/>
			<notify xsi:nil="true"/>
		</ns1:salesOrderAddComment>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4. Final Considerations #

  • Testing: Always test your requests in a development environment before using them in production.
  • Common Errors: Check the validity of your sessionId and product SKU. Authentication failures or incorrect SKUs are frequent issues.
  • Tools: Tools like Postman make it easier to send and view SOAP requests.

With this documentation, you’re ready to manage the order flow in the Soulmkt Marketplace using the V2 API. If you have questions, reach out to our support team.

Note: All example data is fictional and should be replaced with real values from your environment.