# How API Integration Works on the Lume NDR & CSR Portal

> This is a public, non-sensitive guide. It explains the expected integration workflow without publishing private endpoints, credentials, infrastructure, database details, or security configuration.

## 1. Integration purpose

An integration connects an authorized courier, 3PL, store, or customer system to the Lume return-management workflow. Its purpose is to bring relevant shipment updates into the correct company workspace and keep those records current as their delivery status changes.

The integration layer is designed to:

- Identify the authorized company and data source.
- Receive or request shipment updates.
- Validate and standardize the available fields.
- Select only return-related or action-required records.
- Prevent duplicate cases.
- Keep merchant information when the source supplies it.
- Update the portal when the courier status changes later.

## 2. Simple data flow

1. The courier or customer system makes shipment data available.
2. Lume receives a push update or requests updates on a schedule.
3. The integration validates the source and identifies the workspace.
4. Provider fields and statuses are converted into a consistent portal format.
5. Relevant return or pending cases are created or updated.
6. Administrators assign cases to agents.
7. Agents call customers and record remarks.
8. Later updates show whether a shipment returned again or was recovered.

## 3. Push updates

With a push integration, the provider sends Lume a notification when a shipment changes. This method can make new returns visible quickly because the portal does not have to wait for the next scheduled check.

A production push connection normally includes source verification, event validation, duplicate-event protection, and retry handling. The exact method depends on the provider's supported API.

## 4. Scheduled pull updates

With a pull integration, Lume periodically asks the provider for new or changed shipments. The integration may use a date, page number, or provider cursor so it can continue from the last successful check.

Pulling is useful when a courier does not provide push notifications. The schedule and volume depend on provider limits, customer plan, and operational requirements.

## 5. Hybrid updates

A hybrid connection combines fast push events with occasional scheduled checks. The scheduled check acts as reconciliation if an event is delayed or missed. Hybrid operation is available only when the provider supports the required functions.

## 6. Custom APIs

A custom API can connect a store, courier, or 3PL system that does not use a predefined connector. During onboarding, Lume and the customer agree on:

- How the source is authenticated.
- Whether data is pushed, pulled, or both.
- Which shipment fields are available.
- Which statuses should enter the return queue.
- How merchant identities are supplied and matched.
- How updates, pagination, rate limits, and errors are handled.

Custom work begins only after technical review and authorization from the data owner.

## 7. Information that may be imported

The fields available depend entirely on the source. A shipment may include:

- Tracking or consignment number.
- Courier name and provider status.
- Merchant identifier and merchant name.
- Customer or consignee name.
- Customer phone number.
- Delivery address.
- Product, order, or parcel description.
- Cash-on-delivery amount.
- Booking, queue, update, and delivery dates.
- Provider reference information needed to reconcile later updates.

Lume does not create missing courier information. If a provider omits a field, that field may remain unavailable in the portal.

## 8. Selecting return-relevant records

The portal is intended to import records that need return-recovery attention rather than every successful delivery. During setup, provider statuses are reviewed and mapped into operational groups such as:

- Return or return in transit.
- Return to origin.
- Pending, held, or undelivered.
- Shipper advice or action required.
- Delivered after a previously tracked return.

The exact wording differs between providers. Lume uses the agreed mapping for that integration and keeps the original courier status available when useful.

## 9. Status normalization

Different couriers may describe the same event differently. Normalization gives portal users a consistent working view while preserving the source status for reference.

- A relevant new return becomes a return-queue case.
- A non-final action state can appear as pending.
- A later repeated return can be marked return again.
- A previously tracked return that later becomes delivered can be counted as recovered.

Status mapping is tested with customer-provided examples before a connection is treated as production-ready.

## 10. Duplicate protection

Providers can resend an event, and scheduled pulls can include records seen earlier. The integration uses stable shipment and source references to create a case once and update it afterward instead of creating repeated copies.

If a provider reuses tracking numbers or supplies an unstable identifier, additional matching rules may be required during onboarding.

## 11. Merchant identification

When a custom API or 3PL source includes merchant information, Lume can associate each case with the matching merchant inside the workspace. A stable merchant ID is preferred because business names can be spelled differently over time.

If no merchant is provided, the record can only be associated with the configured account or a pre-agreed default. Merchant information is never guessed from unrelated customer data.

## 12. Later shipment updates

An imported case remains linked to its source reference. When a new provider update arrives, the integration can update the courier status and identify operational outcomes such as return again or recovered delivery.

Agent remarks are separate from courier status. Calling activity does not change the provider's delivery record, and a courier update does not erase the agent's work history.

## 13. Errors and retries

Temporary provider downtime, expired authorization, changed response formats, rate limits, and invalid records can interrupt a sync. A production integration should distinguish temporary errors from configuration problems, retry safely, and notify authorized workspace users when attention is required.

One failed record should not silently convert or corrupt other valid shipment records. Unclear fields or statuses should be reviewed before mapping changes are applied.

## 14. Security and privacy principles

Production integrations follow these public principles:

- Access is limited to the authorized customer workspace.
- Credentials are not displayed as ordinary shipment data.
- Connections use encrypted transport where supported and required.
- The source is validated before records are accepted.
- Customers should provide only the fields needed for return operations.
- Operational data is not sold or used for third-party advertising.
- Access can be suspended or removed when authorization ends.

For security reasons, private endpoint addresses, signing procedures, internal logs, infrastructure, and credential-storage methods are provided only through an approved technical onboarding channel.

## 15. Customer responsibilities

The customer must have permission to access and process the shipment and personal data it connects. The customer is responsible for the accuracy of source records, lawful customer contact, approved courier credentials, internal user access, and timely notice when authorization should be removed.

Credentials should never be sent through public documents, screenshots, or unapproved messages.

## 16. Integration onboarding

1. Confirm the company, provider, account owner, and business purpose.
2. Review provider documentation and confirm API availability.
3. Agree on required fields, merchant rules, and return statuses.
4. Exchange credentials through an approved protected method.
5. Test with non-sensitive or controlled sample records.
6. Verify duplicate handling and later status updates.
7. Confirm the workspace queue and reports with the customer.
8. Approve and monitor the production connection.

## 17. Availability notice

The portal may display supported-provider setup choices before a production adapter is enabled for a particular customer. A provider logo or name is not a guarantee of immediate connectivity.

Live integration depends on provider cooperation, valid account access, documentation quality, API limits, testing, and the customer's selected service. Contact Lume to confirm a specific courier or custom API before relying on it operationally.

## 18. Contact

To discuss a courier or custom API connection:

- **WhatsApp:** +971 50 454 1256
- **Email:** contact@lumecourier.com