GrupoMAS Native ERP Execution Integration Guide

GrupoMAS Native connects Dragon Guard to Grupo Mas ERP using a bidirectional, contract-first HTTP adapter. In this model, Grupo Mas ERP retains authority over the item catalog, commercial documents, accounting stock, and costs. Dragon Guard acts as the physical warehouse execution layer: it queries released work, executes operations on handheld devices, maintains a local operational audit trail, and posts results back to Grupo Mas ERP through a durable outbound queue. The full document state machine is RELEASED → IN_PROGRESS → PARTIAL → POSTED → ERP_PENDING → ERP_APPLIED / ERP_FAILED.

Prerequisites

Before using the execution layer endpoints, confirm the following:

The tenant’s IntegrationMode resolves to GrupoMASNative. Call GET /api/v1/integration/capabilities and verify providerName = "GrupoMASNative" and mode = "ERP_EXECUTION".
A SUPERADMIN_SUPREMO user has configured grupoMasNativeSettings for the company in Supreme (see Configuration below).
isConfigured is true in the settings response — this requires a non-empty baseUrl, a valid Company.Code, and at least one credential (apiKey or bearerToken).

Catalog sync endpoints (/api/v1/integration/items, /stock/opening, etc.) are disabled for GrupoMASNative tenants. Calling them returns 409 Conflict. Item master and stock are owned by Grupo Mas ERP, not Dragon Guard.

Configuration

GrupoMASNative adapter settings are managed per tenant in the Supreme administration panel. PATCH /api/supreme/companies/{id}/integration/grupomas-native-settings

Tenant settings fields

baseUrl

string

required

Absolute base URL of the Grupo Mas ERP API (e.g. https://erp.grupomas.com). Must be a valid absolute URL.

apiKey

string

API key credential for outbound requests. Sent as X-Api-Key header to Grupo Mas. Pass null to leave the existing secret unchanged; set clearApiKey: true to remove it explicitly.

bearerToken

string

Bearer token credential for outbound requests. Sent as Authorization: Bearer .... Pass null to leave unchanged; set clearBearerToken: true to remove.

timeoutSeconds

integer

HTTP timeout in seconds for outbound adapter requests. Valid range: 5 – 120.

releasedWorkPath

string

Base path prefix for released-work lookups. Defaults to /api/wms.

postingResultPath

string

Base path prefix for posting-result delivery. Defaults to /api/wms.

pollingEnabled

boolean

Whether the background polling scheduler runs for this tenant.

pollingIntervalSeconds

integer

How frequently (in seconds) the scheduler polls for released work. Valid range: 30 – 3600.

pollingLocationCode

string

Default location code filter applied to scheduled polling runs.

pollingExternalDocumentNo

string

Default external document number filter applied to scheduled polling runs.

Credentials are never returned in plain text. Reading the settings exposes only hasApiKey, hasBearerToken, maskedApiKey, maskedBearerToken, authMode, isConfigured, and polling fields. Test connection POST /api/supreme/companies/{id}/integration/grupomas-native/test-connection Verifies the baseUrl and credentials are reachable without executing any released-work or posting-result flows. Returns 501 Not Implemented when settings are incomplete, or 200 OK with HTTP status details when the remote server responds.

Released Work Lookup

Dragon Guard queries Grupo Mas ERP for documents that have been released for physical warehouse execution.

Choose the operation type

Select the endpoint matching the document type you want to retrieve.

Apply optional query filters

Filter by externalDocumentNo, locationCode, date range (releasedFromUtc / releasedToUtc), and pagination (pageNumber, pageSize, default page size 100).

Receive the document list

Each document includes eventId, idempotencyKey, correlationId, externalDocumentNo, operationType, status, locationCode, releasedAtUtc, and a lines[] array.

Endpoints

All execution-layer endpoints are available under both api/v1/integration/grupomas-native/ (canonical) and the legacy alias api/integration/grupomas-native/.

Method	Path	Operation type
`GET`	`/api/v1/integration/grupomas-native/released-receipts`	`RECEIPT`
`GET`	`/api/v1/integration/grupomas-native/released-shipments`	`SHIPMENT`
`GET`	`/api/v1/integration/grupomas-native/released-counts`	`INVENTORY_COUNT`
`GET`	`/api/v1/integration/grupomas-native/released-transfers`	`TRANSFER`

Query parameters

externalDocumentNo

string

Filter to a specific ERP document number.

locationCode

string

Filter by warehouse location code.

releasedFromUtc

string

Start of the release date range (ISO 8601 UTC).

releasedToUtc

string

End of the release date range (ISO 8601 UTC).

pageNumber

integer

Page number, 1-based. Defaults to 1.

pageSize

integer

Items per page. Defaults to 100.

Example

curl -X GET "https://api.dragonguard.io/api/v1/integration/grupomas-native/released-receipts?locationCode=MAIN" \
  -H "X-Api-Key: YOUR_TENANT_API_KEY" \
  -H "X-Contract-Version: 1"

Released work document fields (GrupoMasReleasedWorkDocumentDto)

eventId

string

Unique event identifier issued by Grupo Mas for this released document.

idempotencyKey

string

Idempotency key used in the corresponding posting-result submission.

externalDocumentNo

string

Grupo Mas document number (e.g. purchase order number, shipment order number).

operationType

string

One of RECEIPT, SHIPMENT, INVENTORY_COUNT, TRANSFER.

status

string

RELEASED for documents ready for handheld execution.

locationCode

string

Warehouse location where execution should occur.

lines[].externalLineNo

string

ERP line number.

lines[].itemNo

string

Item code.

lines[].expectedQuantity

number

Quantity expected for this line.

lines[].uom

string

Unit of measure.

lines[].binCode

string

Bin code for single-bin operations (receipts, counts).

lines[].sourceBinCode

string

Source bin code for transfer/movement operations.

lines[].targetBinCode

string

Destination bin code for transfer/movement operations.

Error responses

501 Not Implemented — tenant adapter settings are incomplete or missing.
502 Bad Gateway — Grupo Mas ERP rejected the request, timed out, or returned an invalid payload.

Item and Bin Stock Lookup

These endpoints allow handhelds to query live item data and stock balances directly from Grupo Mas ERP.

Item Grid Lookup

GET /api/v1/integration/grupomas-native/items/lookup Returns a paged, flat product grid with one row per ItemNo + Location + Bin combination. Designed for the handheld item browsing screen.

string

Full-text search across item code, description, barcode, and alternate code.

itemNo

string

Exact item code filter.

locationCode

string

Filter by warehouse location.

binCode

string

Filter by bin code.

hasStockOnly

boolean

When true, only returns items with available stock greater than zero.

groupCode

string

Filter by item group code.

itemType

string

Filter by item type classification.

uom

string

Filter by unit of measure.

supplierCode

string

Filter by supplier code.

pageNumber

integer

Page number, 1-based. Defaults to 1.

pageSize

integer

Results per page. Defaults to 20, maximum 100.

When no filter is applied, totalQuantity in the response is intentionally returned as 0 to avoid forcing a tenant-wide aggregate on every open. Apply at least one filter to receive meaningful totals.

Per-Item Bin Stock

GET /api/v1/integration/grupomas-native/items/{itemNo}/stock Returns a GrupoMasItemStockDetailDto with item metadata and a flat lines[] array of bin-level stock entries for the specified item.

itemNo

string

required

Item code to query.

locationCode

string

Optional location filter.

binCode

string

Optional bin filter.

hasStockOnly

boolean

Optional — return only bins with stock.

Flat Bin Stock

GET /api/v1/integration/grupomas-native/bin-stock Returns flat stock lines for a required itemNo and optional filters.

itemNo

string

required

Item code. Required — returns 400 Bad Request if missing.

Locations

GET /api/v1/integration/grupomas-native/locations Returns the list of warehouses/locations configured in Grupo Mas for this tenant. The first available option is flagged as isDefaultSelection when the ERP response does not explicitly specify a default.

Posting Results

After physical execution is complete on the handheld, Dragon Guard posts the result back to Grupo Mas ERP. Delivery is decoupled — the handheld request is accepted locally with ERP_PENDING status, and the actual ERP call is made asynchronously by the outbound dispatcher.

Endpoints

Method	Path	Operation type
`POST`	`/api/v1/integration/grupomas-native/receipt-results`	`RECEIPT`
`POST`	`/api/v1/integration/grupomas-native/shipment-results`	`SHIPMENT`
`POST`	`/api/v1/integration/grupomas-native/count-results`	`INVENTORY_COUNT`
`POST`	`/api/v1/integration/grupomas-native/transfer-results`	`TRANSFER`

Request Body (GrupoMasPostingResultDocumentDto)

All four endpoints share the same base contract. Document-level fields

eventId

string

required

Unique event identifier for this execution event. Combined with idempotencyKey to enforce deduplication.

idempotencyKey

string

required

Idempotency key. The composite key (CompanyId, ProviderName, OperationType, ExternalDocumentNo, EventId, IdempotencyKey) is checked before processing — duplicate submissions return the existing result without re-executing.

correlationId

string

required

Trace identifier from the handheld session. Persisted in OperationalExecutionLogs and forwarded to Grupo Mas.

externalDocumentNo

string

required

Grupo Mas document number being posted.

operationType

string

required

Must match the endpoint: RECEIPT, SHIPMENT, INVENTORY_COUNT, or TRANSFER.

status

string

required

Must be POSTED. Partial execution is represented at the line level via expectedQuantity vs actualQuantity, not via a document-level PARTIAL status.

locationCode

string

required

Warehouse location where the execution occurred.

operatorId

string

Operator identifier.

operatorEmail

string

Operator email. Persisted in the execution log.

deviceId

string

Handheld device identifier.

startedAtUtc

string

required

ISO 8601 UTC timestamp when execution began on the handheld.

postedAtUtc

string

required

ISO 8601 UTC timestamp when the handheld completed the operation. Must not be earlier than startedAtUtc.

lines

array

required

At least one line is required.

Line-level fields

lines[].externalLineNo

string

required

ERP line number.

lines[].itemNo

string

required

Item code.

lines[].expectedQuantity

number

required

Quantity that was expected per the released document. Must be ≥ 0.

lines[].actualQuantity

number

required

Quantity physically handled by the operator. Must be ≥ 0.

lines[].uom

string

required

Unit of measure.

lines[].differenceReason

string

Required when actualQuantity ≠ expectedQuantity. Must be one of the day-zero catalog values:

SHORT_PICK — fewer units available or picked than expected
OVERAGE — more units received than expected
DAMAGED_UNIT — units are present but damaged
ITEM_NOT_FOUND — item could not be located in the warehouse
BIN_CHANGE — execution moved to a different bin

lines[].binCode

string

Operational bin for single-bin operations.

lines[].sourceBinCode

string

Source bin for transfer/movement operations.

lines[].targetBinCode

string

Destination bin for transfer/movement operations.

differenceReason is mandatory whenever actualQuantity differs from expectedQuantity. Omitting it causes a 400 Bad Request. Dragon Guard does not generate backorders or document splits — Grupo Mas ERP decides how to handle residual quantities.

Example request

curl -X POST https://api.dragonguard.io/api/v1/integration/grupomas-native/receipt-results \
  -H "X-Api-Key: YOUR_TENANT_API_KEY" \
  -H "X-Contract-Version: 1" \
  -H "X-Correlation-Id: handheld-session-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "evt-001",
    "idempotencyKey": "idem-001",
    "correlationId": "handheld-session-abc123",
    "externalDocumentNo": "PO-2026-0042",
    "operationType": "RECEIPT",
    "status": "POSTED",
    "locationCode": "MAIN",
    "operatorId": "OP-007",
    "operatorEmail": "[email protected]",
    "deviceId": "HH-01",
    "startedAtUtc": "2026-01-15T09:00:00Z",
    "postedAtUtc": "2026-01-15T09:18:00Z",
    "lines": [
      {
        "externalLineNo": "1",
        "itemNo": "SKU-100",
        "expectedQuantity": 20,
        "actualQuantity": 18,
        "uom": "EA",
        "differenceReason": "DAMAGED_UNIT"
      }
    ]
  }'

Success response

{
  "success": true,
  "accepted": true,
  "contractVersion": "1",
  "companyCode": "ACME",
  "providerName": "GrupoMASNative",
  "correlationId": "handheld-session-abc123",
  "outboundAcknowledgmentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "outboundAcknowledgmentStatus": "PENDING",
  "result": {
    "accepted": true,
    "externalDocumentNo": "PO-2026-0042",
    "status": "ERP_PENDING",
    "erpStatus": null,
    "retryStatus": "OUTBOUND_QUEUED",
    "attemptCount": 0,
    "nextAttemptAtUtc": "2026-01-15T09:19:00Z"
  }
}

result.status

string

ERP_PENDING — Dragon Guard accepted the result and queued the outbound delivery to Grupo Mas ERP.

outboundAcknowledgmentId

string

ID of the durable outbound acknowledgment record. Use this to track delivery status via the Outbound Acknowledgments endpoints.

outboundAcknowledgmentStatus

string

PENDING on first acceptance — the OutboundAcknowledgment entity status. See the Outbound Acknowledgments page for the full status lifecycle (PENDING → SENT / FAILED / DEAD_LETTER).

result.retryStatus

string

OUTBOUND_QUEUED on first acceptance — the OperationalExecutionLog.RetryStatus field that tracks the durable retry state of this execution record.

Idempotency When the same (CompanyId, ProviderName, OperationType, ExternalDocumentNo, EventId, IdempotencyKey) combination is received again, Dragon Guard returns the previously recorded execution result with "duplicate": true — no second provider call is made and no second execution log is created.

Background Polling

Dragon Guard includes a hosted background service that automatically fetches released work from Grupo Mas ERP for enabled tenants.

The service checks every 30 seconds for GrupoMASNative tenants with polling due.
Each tenant uses its own pollingIntervalSeconds (valid range: 30 – 3600).
On each poll, Dragon Guard fetches released receipts, shipments, counts, and transfers, applying the tenant’s pollingLocationCode and pollingExternalDocumentNo filters when configured.
Results are persisted into core.GrupoMasReleasedWorkSnapshots. Documents that no longer appear in a poll are marked IsActive = false.
Scheduler state is tracked in core.GrupoMasPollingStates.

Manual refresh POST /api/supreme/companies/{id}/integration/grupomas-native/polling/refresh Triggers an immediate released-work refresh for the specified tenant outside the regular schedule. Accepts optional locationCode and externalDocumentNo filters and returns document counts by operation type plus a correlationId.

Outbound Request Headers

Dragon Guard sends the following headers on every outbound request to Grupo Mas ERP:

Header	Value
`X-Correlation-Id`	Correlation ID from the inbound request
`X-Contract-Version`	`1`
`X-Company-Code`	`Company.Code` (= `codigo_empresa` in MAS)
`Authorization`	`Bearer <bearerToken>` when bearer token is configured
`X-Api-Key`	`<apiKey>` when API key is configured

The companyCode query parameter is also appended to every outbound URL — Grupo Mas uses this to identify the tenant.

Technical Retry Policy

The HTTP adapter uses a technical retry policy for transient connectivity failures:

Attempt	Wait
1st retry	1 second
2nd retry	2 seconds
3rd retry	4 seconds

Maximum 3 attempts per request. Retryable conditions: HTTP status 408, 429, 502, 503, 504, network timeout, or transport error. Non-retryable errors (functional rejections, contract validation failures) are not retried at the transport layer but may be re-queued by the durable outbound dispatcher.

Use GET /api/v1/integration/capabilities at startup to confirm supportsReleasedWorkLookup and requiresProviderAdapter flags before making any released-work or posting-result calls. If the adapter is not yet configured, all execution endpoints return 501 Not Implemented.

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

GrupoMAS Native ERP Execution Integration Guide

Prerequisites

Configuration

Released Work Lookup

Endpoints

Item and Bin Stock Lookup

Item Grid Lookup

Per-Item Bin Stock

Flat Bin Stock

Locations

Posting Results

Endpoints

Request Body (GrupoMasPostingResultDocumentDto)

Background Polling

Outbound Request Headers

Technical Retry Policy

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Prerequisites

​Configuration

​Released Work Lookup

​Endpoints

​Item and Bin Stock Lookup

​Item Grid Lookup

​Per-Item Bin Stock

​Flat Bin Stock

​Locations

​Posting Results

​Endpoints

​Request Body (GrupoMasPostingResultDocumentDto)

​Background Polling

​Outbound Request Headers

​Technical Retry Policy

Build docs developers (and LLMs) love

Prerequisites

Configuration

Released Work Lookup

Endpoints

Item and Bin Stock Lookup

Item Grid Lookup

Per-Item Bin Stock

Flat Bin Stock

Locations

Posting Results

Endpoints

Request Body (GrupoMasPostingResultDocumentDto)

Background Polling

Outbound Request Headers

Technical Retry Policy