Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CodexaCP/DG_BACK/llms.txt

Use this file to discover all available pages before exploring further.

When Dragon Guard posts results back to an ERP (for example, after a GrupoMAS Native receipt execution), the outbound delivery is decoupled from the handheld request using a persistent acknowledgment queue. The handheld receives a local acceptance response immediately, while the actual HTTP call to the ERP is made asynchronously by a background dispatcher. This design ensures that temporary ERP outages or network interruptions never block the warehouse operator — Dragon Guard retries the delivery automatically and preserves the exact original payload for replay.

​
Delivery Flow

1

Handheld posts result

The operator submits a result (e.g. POST /api/v1/integration/grupomas-native/receipt-results). Dragon Guard persists the operational execution log in core.OperationalExecutionLogs.
2

Acknowledgment record created

Within the same operation, Dragon Guard creates an OutboundAcknowledgment record containing the exact payload to be sent to the ERP. Initial status: PENDING.
3

API responds with local acceptance

Dragon Guard returns 200 OK to the handheld with status: "ERP_PENDING", outboundAcknowledgmentId, and outboundAcknowledgmentStatus: "PENDING". The handheld does not wait for ERP confirmation.
4

Background dispatcher delivers

A hosted service evaluates due acknowledgments every 1 minute and attempts delivery to the ERP endpoint. On HTTP 2xx from the ERP, the status becomes SENT.
5

Retry on failure

On a retryable failure (transport error, 5xx), status becomes FAILED and nextRetryAt is scheduled using exponential backoff.
6

Dead-letter after exhaustion

After 5 failed attempts, or on a non-retryable rejection, the acknowledgment moves to DEAD_LETTER. Manual retry remains available via the admin endpoint.

​
Retry Schedule

The durable dispatcher uses exponential backoff between delivery attempts:
AttemptDelay after previous failure
1st retry1 minute
2nd retry5 minutes
3rd retry15 minutes
4th retry30 minutes
5th retry60 minutes
After the 5th failure the record is moved to DEAD_LETTER. Use the manual retry endpoint to re-queue dead-lettered records after resolving the underlying issue.
The durable retry dispatcher replays the original queued payload stored in PayloadJson. The handheld never needs to resubmit. This is safe because the ERP call is idempotent by design — Grupo Mas ERP applies the same result only once when the eventId and idempotencyKey match.

​
Status Values

The status field on an OutboundAcknowledgment record uses the following values.
StatusMeaning
PENDINGAccepted locally, queued for first delivery attempt.
SENTERP confirmed receipt with an HTTP 2xx response.
FAILEDPrevious delivery attempt failed with a retryable error; next attempt is scheduled via nextAttemptAt.
SKIPPEDTenant is not integrated or has no callbackUrl configured. No delivery will be attempted.
DEAD_LETTERAll retry attempts exhausted, or the ERP returned a non-retryable rejection. Manual intervention required.
The OperationalExecutionLog.RetryStatus field — visible in GrupoMAS Native posting-result responses as result.retryStatus — uses a separate value set: OUTBOUND_QUEUED, OUTBOUND_RETRY_REQUIRED, OUTBOUND_COMPLETED, OUTBOUND_DEAD_LETTER, OUTBOUND_NOT_CONFIGURED. Those values track the retry lifecycle inside the execution log, not the OutboundAcknowledgment entity itself.

​
API Endpoints

​
List Acknowledgments

GET /api/outbound-acknowledgments Returns a paged list of outbound acknowledgment records for the active company.
​
companyId
string (Guid)
Company filter. Defaults to the authenticated user’s active company.
​
status
string
Filter by status value (e.g. DEAD_LETTER, PENDING, FAILED).
​
eventType
string
Filter by event type (e.g. GRUPOMAS_RECEIPT_RESULT).
​
search
string
Text search across sourceDocumentNo, postedDocumentNo, and eventType.
​
pageNumber
integer
Page number, 1-based. Defaults to 1.
​
pageSize
integer
Results per page. Defaults to 20, maximum 100.
Example 
curl -X GET "https://api.dragonguard.io/api/outbound-acknowledgments?status=DEAD_LETTER&pageSize=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Get Single Acknowledgment

GET /api/outbound-acknowledgments/{id} Returns full detail for a single acknowledgment record, including the payloadJson field that contains the exact outbound payload that was (or will be) sent to the ERP.
​
id
string (Guid)
required
Acknowledgment record ID. Returned as outboundAcknowledgmentId in posting-result responses.

​
Manually Trigger Retry

POST /api/outbound-acknowledgments/{id}/retry Immediately re-queues the specified acknowledgment for delivery, bypassing the scheduled nextRetryAt window. Useful for resolving dead-lettered records after fixing an ERP connectivity or configuration issue.
​
id
string (Guid)
required
Acknowledgment record ID.
Calling retry on a record with status SENT (i.e., already successfully delivered) returns 409 Conflict to prevent accidental duplicate delivery to the ERP.

​
OutboundAcknowledgmentDto Fields

​
id
string (Guid)
Unique identifier for this acknowledgment record.
​
companyId
string (Guid)
Tenant company ID.
​
companyCode
string
Tenant company code.
​
providerName
string
Integration provider that owns this acknowledgment (e.g. GrupoMASNative).
​
eventType
string
Event type classification. Supported values: RECEIPT_POSTED, SHIPMENT_POSTED, GRUPOMAS_RECEIPT_RESULT, GRUPOMAS_SHIPMENT_RESULT, GRUPOMAS_COUNT_RESULT, GRUPOMAS_TRANSFER_RESULT.
​
sourceDocumentType
string
Type of the originating Dragon Guard document.
​
sourceDocumentId
string (Guid)
ID of the originating document in Dragon Guard.
​
sourceDocumentNo
string
Document number of the originating document.
​
postedDocumentType
string
Type of the posted result document.
​
postedDocumentNo
string
Posted document number.
​
status
string
Current delivery status. One of PENDING, SENT, FAILED, SKIPPED, DEAD_LETTER. See Status Values above.
​
callbackUrl
string
ERP endpoint URL that Dragon Guard is posting to. null for OUTBOUND_NOT_CONFIGURED records.
​
attemptCount
integer
Number of delivery attempts made so far.
​
lastResponseStatusCode
integer
HTTP status code returned by the ERP on the last attempt.
​
lastResponseBody
string
Response body from the ERP on the last attempt (truncated if large).
​
lastError
string
Error message from the last failed attempt.
​
lastAttemptAt
string (UTC datetime)
Timestamp of the most recent delivery attempt.
​
nextAttemptAt
string (UTC datetime)
Scheduled time for the next retry. null for completed or dead-lettered records.
​
sentAt
string (UTC datetime)
Timestamp when the ERP successfully acknowledged the delivery.
​
deadLetteredAt
string (UTC datetime)
Timestamp when the record was moved to dead-letter status.
​
deadLetterReason
string
Explanation of why the record was dead-lettered (e.g. retry exhaustion, non-retryable ERP rejection).
​
correlationId
string
Correlation ID from the original inbound handheld request. Preserved through the local audit log and forwarded to the ERP in the X-Correlation-Id header.
​
createdAt
string (UTC datetime)
Timestamp when the acknowledgment record was created.
​
payloadJson
string
The exact JSON payload that Dragon Guard sends (or sent) to the ERP. Only included in single-record GET responses, not in list pages.

​
Correlation Tracing

The X-Correlation-Id header from the original inbound handheld request is preserved across the entire delivery chain:
  1. Inbound request — Dragon Guard reads X-Correlation-Id from the handheld POST.
  2. Local audit — The correlation ID is persisted in core.OperationalExecutionLogs and in the OutboundAcknowledgment record.
  3. Outbound ERP call — Dragon Guard forwards the same X-Correlation-Id header to the ERP on every delivery attempt (including retries).
This means the same correlation ID can be used to trace a single warehouse operation from the handheld scan all the way through to the ERP audit log.

​
Event Types

Event typeTrigger
GRUPOMAS_RECEIPT_RESULTPOST /api/v1/integration/grupomas-native/receipt-results
GRUPOMAS_SHIPMENT_RESULTPOST /api/v1/integration/grupomas-native/shipment-results
GRUPOMAS_COUNT_RESULTPOST /api/v1/integration/grupomas-native/count-results
GRUPOMAS_TRANSFER_RESULTPOST /api/v1/integration/grupomas-native/transfer-results
RECEIPT_POSTEDGeneric API receipt posting
SHIPMENT_POSTEDGeneric API shipment posting

​
Example: Checking a Dead-Lettered Record

# Find dead-lettered records
curl -X GET "https://api.dragonguard.io/api/outbound-acknowledgments?status=DEAD_LETTER" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get full detail including payload
curl -X GET "https://api.dragonguard.io/api/outbound-acknowledgments/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# After fixing the ERP connectivity issue, manually trigger retry
curl -X POST "https://api.dragonguard.io/api/outbound-acknowledgments/7c9e6679-7425-40de-944b-e07fc1f90ae7/retry" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Current limitations: there is no bulk dead-letter replay endpoint. Replay must be triggered record by record. HMAC signing and advanced callback authentication for outbound requests are not yet implemented in this release.

Build docs developers (and LLMs) love

Get started for freeTalk to us