Skip to main content

1. Order Submission​

Initial transaction submission containing all financial details. This stage registers the financial components known as extracts (accepted types: COMISSION, SHIP, RETURN_COMISSION, RETURN_SHIP, and SALE), which will be reconciled at a later stage.

2. Reconciliation Creation​

Logical grouping of multiple orders for batch processing. This defines the financial period and prepares the system to receive the financial releases.

3. Financial Release Execution​

Full Submission Required

All financial components of an order must be submitted within a single request. It is not possible to add partial or supplemental releases after the initial submission.

Fundamental Rule: Financial entries (releases) must exactly match the values and types previously registered in the order (extracts), maintaining the unique identifier (marketplaceCode).

Supported Release Types​

The supported release types are detailed in the Complete List of Release Types. The primary types include:

  • SALE: Gross sales value (always positive).
  • COMISSION: Commission fees (always negative).
  • SHIP: Shipping costs (positive or negative).
  • RETURN_COMISSION: Commission reversals (always positive).

Full Workflow: Order → Reconciliation → Releases​

1. Order Submission​

The order contains the complete financial structure through the extracts array. Each item represents a distinct financial component:

Order
{
  "marketplaceCode": "701-2798273-4005859",
  "channelName": "CHANNEL_NAME",
  "accountId": "19055",
  "status": "PAID_WAITING_DELIVERY",
  "createdDate": "2025-05-09T12:00:00Z",
  "approvedDate": "2025-05-09T12:00:00Z",
  "sendDate": "2025-05-09T12:00:00Z",
  "estimatedDeliveryDate": "2025-05-15T12:00:00Z",
  "deliveryDate": "2025-05-15T12:00:00Z",
  "cancelDate": null,
  "totalGrossValue": 203.63,
  // ... (other fields omitted)
  "extracts": [
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SALE",          // Gross sale
      "value": 203.63,         // Always positive
      "expectedDate": "2025-06-05T12:00:00Z"
    },
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "COMISSION",     // Commission fee
      "value": -24.44,         // Always negative
      "percentage": 12         // 12% commission
    },
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SHIP",          // Shipping cost
      "value": -27.95          // Negative (cost)
    }
  ]
}

2. Reconciliation Creation​

The reconciliation groups orders for batch processing. The releasesQtd field must exactly match the total number of financial releases across all included orders:

Reconciliation
{
  "channelName": "CHANNEL_NAME",
  "accountId": 19055,
  "periodInitDate": "2024-02-14T01:00:01Z",   // Period start
  "periodEndDate": "2024-02-15T01:00:01Z",    // Period end
  "releasesQtd": 3,                           // Total number of financial releases included
  "totalNetValue": 203.63                     // Total net value of the reconciliation
}

The reconciliation creation should return a JSON similar to this:

Creation Response
{
    "id": 237    // Unique reconciliation ID
}
Important

The releasesQtd must reflect the number of financial releases sent at once.

  • The returned reconciliationId is mandatory for all releases.
  • The period must cover all releasedDate values of the submitted releases.
  • The releasesQtd must be the exact sum of all releases that will be sent.

3. Financial Release Submission​

Financial Releases
{
  "reconciliationId": 237,
  "channelName": "CHANNEL_NAME",
  "accountId": 19055,
  "marketplaceCode": "701-2798273-4005859",
  "status": "CONCLUDED",
  "createdDate": "2024-02-10T12:12:12Z",
  "releasedDate": "2024-02-10T13:13:13Z",
  "releaseType": "IN_CASH",
  "installment": 1,
  "installmentQuantity": 1,
  "releases": [
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SALE",
      "value": 203.63
    },
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "COMISSION",
      "value": -24.44
    },
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SHIP",
      "value": -27.95
    }
  ]
}

Financial Release Resubmission Principle​

  1. Exact Type Matching: The types in releases must be identical to those registered in extracts.
  2. Value Consistency: Values must be identical to the pre-registration data.
  3. Quantity Match: The number of items in releases must equal the number of items in extracts.
  4. Consistent marketplaceCode: The unique identifier must be maintained across all levels.

Common Error Validation​

Automated Validations​

Malformed fields in the payload of any request within the aforementioned processes will be reported in the response, featuring specific error messages and an HTTP 400 (Bad Request) status.

Implementation Best Practices​

  1. Preserve Source Values: Avoid any value recalculation. Ensure the values perfectly match the original order data to maintain financial integrity.

  2. Maintain Sequence Consistency: Keep the same sequence of financial releases between the order and the reconciliation to facilitate auditability.

  3. Pre-submission Validation: Always verify supported marketplace release types prior to submission to prevent processing errors.

  4. Period Alignment: Ensure all financial release dates strictly fall within the defined reconciliation period.