.png)
Descartes Integration Guide
Connect Descartes logistics, transportation, visibility, customs, and delivery services with enterprise systems through product-specific APIs, callbacks, files, and orchestrated workflows.
Descartes integration options at a glance
Descartes integration capabilities depend on the selected product, tenant, region, and customer subscription. REST APIs are the primary documented mechanism for accessing logistics, transportation, shipment visibility, routing, customs, and delivery services. Selected products may also provide webhook-style notifications, outbound callbacks, batch or asynchronous operations, and file or EDI exchange. Authentication may use product-specific API credentials, Basic Authentication, OAuth 2.0, or another token model. Martini can consume the relevant Descartes API, receive supported callbacks, process files, poll for incremental changes, transform JSON, XML, CSV, or EDI data, and route results to enterprise applications.
| Integration point | Supported by Descartes? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Access product-specific Descartes resources for Orders, Shipments, Carriers, Locations, Tracking Events, or Customs Declarations. Operations and schemas depend on the selected Descartes service. | Martini can consume the Descartes REST API from workflows, map responses, apply business rules, and expose a separate Martini API for normalized enterprise access. |
| Webhooks and outbound callbacks | Limited | Selected transportation or shipment-visibility products may provide notifications for selected milestones, status changes, or exceptions. Coverage is not uniform across the portfolio. | Martini can receive supported HTTP callbacks, validate and transform the payload, route events, and record identifiers for duplicate prevention. Polling can supplement incomplete event coverage. |
| Bulk, asynchronous, and batch APIs | Limited | Selected services may support large-volume shipment, order, routing, or customs exchanges through batch or asynchronous operations. | Martini can submit or retrieve batch work, track asynchronous results where the product exposes that capability, transform records, and control throughput. |
| File and EDI exchange | Limited | Logistics deployments may exchange shipment tenders, status messages, delivery confirmations, customs documents, or other EDI and file-based payloads. | Martini can orchestrate file ingestion, parsing, validation, transformation, API calls, and delivery to downstream systems when the format and transport are provisioned. |
| Authentication | Limited | Authentication is product- and API-specific and may use API credentials, API keys, Basic Authentication, OAuth 2.0, or another token model with tenant or account permissions. | Martini can store credentials and tokens in environment configuration or secrets and use the confirmed authentication flow when consuming the selected API. |
| Scheduled synchronization | Yes | Polling can synchronize changed Shipments, Orders, Tracking Events, Carrier data, or Customs Declarations when callbacks are unavailable or incomplete. | Martini workflows can run on schedules, use product-specific filters or checkpoints, paginate through results, and persist synchronization state. |
| SOAP APIs | Not confirmed | Older or partner interfaces may exist within the broad Descartes portfolio, but current vendor-wide SOAP support was not confirmed. | Martini can consume SOAP services when the selected Descartes product documentation confirms such an interface, but SOAP should not be assumed for a new integration. |
| Database access | Not confirmed | Direct access to Descartes-managed production databases is not confirmed. Customer-owned reporting databases or exports are separate integration sources. | Martini should use supported APIs, callbacks, files, EDI, or customer-provided exports rather than depending on direct application-database access. |
How Descartes exposes data and business events
Descartes REST APIs
Descartes provides API access for its logistics, transportation, shipment visibility, routing, customs, and delivery products. The available resources, operations, models, environments, rate limits, and authentication requirements are product-specific rather than uniform across the portfolio.
Martini implementation pattern
Martini implementation pattern: Martini consumes the selected Descartes REST API from a workflow, authenticates using the provisioned product-specific mechanism, retrieves or submits data, maps the response into a canonical or downstream model, and persists identifiers and checkpoints for reliable synchronization.
Implementation sequence
Descartes callbacks and event notifications
Selected Descartes products may provide outbound callbacks or webhook-style notifications for particular shipment milestones, status changes, or exceptions. Event coverage and delivery guarantees must be confirmed for the selected service.
Martini implementation pattern
Martini implementation pattern: Martini exposes an HTTP entry point or receives the configured callback, validates available authenticity information, records the event identifier, retrieves the current Descartes resource when necessary, and routes a normalized Tracking Event to downstream systems. Scheduled reconciliation can cover missing or late events.
Implementation sequence
Descartes files and EDI exchanges
Descartes logistics deployments may support file or EDI exchanges for shipment tenders, status messages, delivery confirmations, customs documents, or related processes. Formats, transports, and document types vary by product and customer deployment.
Martini implementation pattern
Martini implementation pattern: Martini workflows ingest the provisioned file or message, parse JSON, XML, CSV, or EDI content as applicable, validate required logistics or customs fields, transform it into the target model, and deliver the result through an API, file, or other supported endpoint.
Implementation sequence
Common Descartes integration patterns
Pattern 1: Synchronize orders to Descartes shipments
When to use this pattern
Use this pattern when an ERP, commerce platform, or order-management application creates Orders that must become Descartes Shipments or transportation requests. The workflow validates addresses, dates, package details, and carrier requirements before submission, then stores the returned Descartes identifier so retries do not create duplicates.
Integration direction
Example Mapping
| Descartes Field | Canonical Field | Target Field |
|---|---|---|
| Order.number | externalOrderId | Order reference |
| Order.shipTo | deliveryLocation | Location |
| Order.lines | packages or shipment contents | Shipment contents |
| Order.requestedDeliveryDate | requestedDeliveryDate | Delivery date |
Martini implementation pattern
A scheduled Martini workflow retrieves new or changed Orders, validates required logistics data, maps the source structure to the product-specific Descartes Shipment request, submits the request, and persists the response identifier and status. Transient failures use controlled retries, while validation failures are routed for correction.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- validation
- business rules
- idempotency handling
- error handling
Pattern 2: Route shipment visibility events to operational systems
When to use this pattern
Use this pattern when a Descartes visibility or transportation product exposes callbacks for selected Tracking Events, or when polling is required because event coverage is limited. The pattern supports delivery milestones, delays, exceptions, and proof-of-delivery information reaching CRM, service management, portals, or analytics systems.
Integration direction
Example Mapping
| Descartes Field | Canonical Field | Target Field |
|---|---|---|
| TrackingEvent.shipmentId | shipmentId | related shipment reference |
| TrackingEvent.status | normalizedShipmentStatus | case status or event status |
| TrackingEvent.eventTime | occurredAt | event timestamp |
| TrackingEvent.exception | exceptionReason | case description |
Martini implementation pattern
Martini receives a supported callback or retrieves changed Tracking Events, validates and deduplicates the event, enriches it with Shipment and customer context when required, maps Descartes statuses to a canonical model, and creates or updates the target record. Events are reconciled by scheduled polling when callbacks are incomplete or unavailable.
Martini capabilities used
- API endpoints
- webhook consumption
- scheduled workflows
- data mapping
- status normalization
- duplicate prevention
- monitoring
Pattern 3: Exchange customs declarations and documents
When to use this pattern
Use this pattern for a Descartes customs or trade-compliance product that exchanges declaration, classification, filing, or clearance data with an ERP, commerce platform, document repository, or compliance process. Validation is important because missing item, classification, country, or shipment information can cause business rejection rather than a retryable transport failure.
Integration direction
Example Mapping
| Descartes Field | Canonical Field | Target Field |
|---|---|---|
| CustomsDeclaration.reference | declarationReference | declaration number |
| CustomsDeclaration.items | declaredItems | line items |
| CustomsDeclaration.classification | commodityClassification | HS or tariff classification |
| CustomsDeclaration.status | clearanceStatus | filing status |
Martini implementation pattern
Martini receives or retrieves declaration data, parses the provisioned JSON, XML, CSV, or EDI format, validates mandatory customs fields, applies country and classification rules, submits the supported Descartes request or file, and routes filing results. Retryable endpoint failures are separated from rejected declarations requiring human correction.
Martini capabilities used
- workflow orchestration
- file processing
- JSON and XML transformation
- data validation
- business rules
- API consumption
- error routing
Pattern 4: Load incremental Descartes data into analytics
When to use this pattern
Use this pattern when operational teams need Shipment, Carrier, Location, or Tracking Event data in an analytics platform such as Snowflake. It is appropriate where the selected Descartes API provides timestamps, cursors, page markers, or other incremental retrieval controls and where direct database access is not available.
Integration direction
Example Mapping
| Descartes Field | Canonical Field | Target Field |
|---|---|---|
| Shipment.id | descartesShipmentId | shipment_id |
| Shipment.updatedAt | lastModifiedAt | updated_at |
| Carrier.code | carrierCode | carrier_code |
| TrackingEvent.status | eventStatus | event_status |
Martini implementation pattern
A scheduled Martini workflow retrieves changed objects using the product-supported filter, cursor, page, or date mechanism, transforms product-specific structures into stable analytics records, writes batches to Snowflake through the available target interface, and advances the checkpoint only after successful delivery. Throttling and replay handling protect against rate limits and partial failures.
Martini capabilities used
- scheduled workflows
- pagination and checkpointing
- API consumption
- data transformation
- batch processing
- retry handling
- monitoring
Applications commonly integrated with Descartes
Descartes integrations commonly connect logistics and transportation processes with enterprise applications that manage orders, customers, commerce, operations, or analytics. The exact interface and object model must be confirmed for the selected Descartes product.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| SAP S/4HANA | Exchange sales orders, deliveries, shipment information, carrier data, transportation status, and exceptions. | SAP S/4HANA → Martini → Descartes | Martini retrieves or receives eligible SAP business documents, validates addresses and logistics data, maps them to the selected Descartes API model, and stores returned identifiers. Status and exception updates can flow back through a separate workflow with retry and duplicate protection. |
| Oracle NetSuite | Synchronize orders, fulfillment details, shipment tracking, and delivery status for distribution and commerce operations. | Oracle NetSuite → Martini → Descartes | A scheduled or API-triggered Martini workflow reads changed NetSuite orders, transforms fulfillment and package data into the product-specific Descartes request, records the Descartes identifier, and returns tracking updates to NetSuite when supported. |
| Microsoft Dynamics 365 | Connect sales, warehouse, transportation, delivery, and shipment-visibility processes. | Microsoft Dynamics 365 → Martini → Descartes | Martini orchestrates order and shipment synchronization, applies address and carrier validation, translates statuses between the two models, and routes transient API failures through controlled retries. |
| Salesforce | Provide shipment milestones, delivery exceptions, and customer-facing logistics information to CRM users. | Descartes → Martini → Salesforce | Martini receives supported Descartes callbacks or polls shipment status, normalizes Tracking Event values, enriches them with customer references, and updates Salesforce while recording event identifiers for idempotency. |
| Shopify | Exchange fulfilled order and package information and return tracking or delivery status to the commerce platform. | Shopify → Martini → Descartes | Martini receives eligible Shopify order or fulfillment data, maps packages and delivery locations to the selected Descartes service, and sends status changes back to Shopify after validating references and avoiding duplicate updates. |
| Amazon | Exchange marketplace order, fulfillment, shipment, and tracking information where the customer’s Descartes product and Amazon program support the required process. | Amazon → Martini → Descartes | Martini transforms marketplace order and fulfillment messages into the applicable Descartes request model, coordinates asynchronous or file-based exchanges where provisioned, and reconciles tracking results using stable external references. |
| ServiceNow | Create operational incidents or cases for shipment exceptions, customs issues, carrier failures, or delivery delays. | Descartes → Martini → ServiceNow | Martini consumes Descartes status or exception data, applies severity and routing rules, creates or updates ServiceNow records, and prevents duplicate cases using shipment and event identifiers. |
| Snowflake | Consolidate shipment, route, carrier, and tracking data for operational reporting and supply-chain analytics. | Descartes → Martini → Snowflake | Martini retrieves incremental Descartes data or processes customer-provided exports, normalizes product-specific objects into analytics-ready structures, and writes batches to Snowflake without assuming direct access to Descartes-managed databases. |
How to build a Descartes integration in Martini
Objective
Identify the exact Descartes product and configure the authentication model it requires. Keep credentials, tokens, tenant details, and environment-specific values outside workflow payloads.
Instructions in Martini
- Confirm the Descartes product, tenant, region, API version, and environment
- Obtain the product-specific API specification and authentication instructions
- Store API credentials, Basic Authentication values, OAuth tokens, or other secrets in Martini environment configuration
- Test access against the appropriate sandbox or production endpoint
Objective
Select an event-driven, scheduled, file-based, or API-led entry point based on the interfaces actually provisioned by Descartes.
Instructions in Martini
- Use a Descartes callback when the selected product exposes the required event
- Use a scheduler for polling and incremental synchronization when callbacks are unavailable or incomplete
- Use a file or EDI trigger when the deployment exchanges documents
- Use a Martini API when internal systems need a controlled normalized logistics endpoint
Objective
Receive or retrieve the relevant Descartes object and preserve enough context for correlation, pagination, and replay.
Instructions in Martini
- Receive the callback, file, or source application request
- Call the relevant Descartes REST resource when the notification is incomplete
- Retrieve related Shipment, Order, Carrier, Location, Tracking Event, or Customs Declaration data as needed
- Persist page markers, cursors, timestamps, event identifiers, and external references
Objective
Coordinate calls, transformations, validation, target writes, and exception paths in a maintainable Martini workflow.
Instructions in Martini
- Separate transport operations from business validation and target delivery
- Use reusable workflow logic for common authentication, correlation, and status handling
- Branch validation failures, retryable failures, and permanent business rejections into appropriate paths
- Preserve correlation IDs and sanitized request context for troubleshooting
Objective
Translate product-specific Descartes structures into a canonical model or the target application’s data model.
Instructions in Martini
- Map actual Descartes object names and identifiers explicitly
- Normalize statuses, timestamps, time zones, units, addresses, carrier codes, and service levels
- Transform JSON, XML, CSV, or EDI content where the deployment requires it
- Keep optional fields distinct from fields that must be explicitly cleared
Objective
Apply logistics, routing, customs, eligibility, deduplication, and exception rules before committing changes.
Instructions in Martini
- Validate addresses, dates, package details, customs fields, and required references
- Select eligible carriers or route exceptions according to business rules
- Use stable Order or Shipment references and idempotency features where provided
- Reject incomplete business data without repeatedly retrying it
Common Descartes data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Shipment | Represents a shipment or movement being planned, tendered, monitored, or delivered. | SAP S/4HANA, Oracle NetSuite, Microsoft Dynamics 365, Salesforce, Snowflake | Martini validates references, addresses, packages, dates, and carrier requirements, then creates, updates, retrieves, or normalizes the product-specific Shipment representation. |
| Order | Represents a transportation, delivery, fulfillment, or logistics order that may lead to shipment activity. | SAP S/4HANA, Oracle NetSuite, Microsoft Dynamics 365, Shopify, Amazon | Martini retrieves changed Orders or receives them from an upstream system, applies validation and business rules, maps them to the selected Descartes request model, and stores synchronization identifiers. |
| Carrier | Represents a transportation provider, carrier account, or logistics partner. | ERP systems, transportation applications, warehouse systems, Snowflake | Martini maps carrier codes and service levels, validates eligibility rules, and synchronizes changes when the selected Descartes API exposes the object. |
| Location | Represents a shipper, consignee, warehouse, terminal, port, stop, or delivery location. | SAP S/4HANA, Microsoft Dynamics 365, Shopify, warehouse applications | Martini validates addresses, location codes, time zones, and required fields, then maps internal location identifiers to Descartes identifiers. |
| Tracking Event | Represents a shipment milestone, status update, location update, exception, or proof-of-delivery event. | Salesforce, ServiceNow, customer portals, Snowflake, ERP systems | Martini receives supported callbacks or polls for changes, normalizes event types and timestamps, applies routing rules, and records event identifiers to prevent duplicate processing. |
| Customs Declaration | Represents import, export, classification, filing, or trade-compliance information in a relevant Descartes customs product. | SAP S/4HANA, Oracle NetSuite, document repositories, compliance applications | Martini validates required customs fields, transforms JSON, XML, CSV, or EDI payloads, submits supported requests, and routes filing or clearance results and exceptions. |
Authentication and security considerations
Product-specific authentication
Descartes authentication is provisioned by product and API. Confirm whether the selected service uses API credentials, API keys, Basic Authentication, OAuth 2.0, or another token model, along with tenant and account permissions.
Credential protection
- Store credentials and tokens in Martini environment configuration or secrets management.
- Do not place authorization headers, credentials, customs documents, or unnecessary personal information in logs or workflow payloads.
- Restrict access to shipment, customer, carrier, and trade-compliance data according to the integration’s responsibilities.
Inbound event security
Where Descartes provides callbacks, validate any available signature, token, source restriction, or correlation requirement before processing the event.
Operational considerations for Descartes integrations
API limits and pagination
Confirm product-specific quotas, burst limits, concurrency restrictions, pagination style, and incremental filtering. Use checkpoints, date filters, cursors, or page markers and avoid repeatedly retrieving unchanged Shipments.
Retries and idempotency
Apply controlled backoff for transient failures such as HTTP 429 and 5xx responses. Use stable Order and Shipment references, returned Descartes identifiers, and event IDs to distinguish safe retries from duplicate creation risks.
Events and reconciliation
Do not assume every Descartes status is emitted as an event. Reconcile callbacks with scheduled polling when event delivery or coverage is limited, and account for late-arriving Tracking Events.
Schema and testing
Confirm the selected product’s API version and test status values, carrier codes, addresses, customs fields, file formats, and error responses. Keep mappings versioned and monitor product-specific release information.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Descartes is a portfolio of products with different APIs, objects, authentication models, and event capabilities. Martini centralizes those differences in maintainable workflows rather than scattering them across scripts and point-to-point integrations.
Reliable data movement
Martini can coordinate API calls, callbacks, polling, files, transformations, validation, business rules, retries, checkpoints, and downstream delivery in one observable integration flow.
Reusable enterprise interfaces
Martini can expose normalized APIs and reusable workflow logic so internal applications do not need to understand every product-specific Descartes model or authentication detail.
Operational control
- Separate retryable transport failures from business validation errors.
- Preserve correlation IDs, external identifiers, checkpoints, and sanitized failure details.
- Change mappings and routing rules without rewriting every consuming application.
Frequently asked questions
Descartes can be integrated through product-specific REST APIs, selected webhook-style notifications or outbound callbacks, scheduled polling, and file or EDI exchanges where those interfaces are provisioned. The exact resources, authentication, data model, and event coverage depend on the selected Descartes product and customer subscription.
Yes. Martini can consume the relevant Descartes REST API, receive supported callbacks, poll for incremental Shipment or Tracking Event changes, process provisioned files or EDI exchanges, transform data, and route it to enterprise applications. A native Martini connector is not confirmed in the supplied product context.
No. A dedicated Descartes connector is not required. Martini can integrate using Descartes’ confirmed native mechanisms, including product-specific REST APIs, supported callbacks, scheduled polling, files, EDI, and the authentication method documented for the selected service.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Descartes. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Descartes, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
REST APIs are the primary documented mechanism for new integrations, but the exact API depends on the product, tenant, region, and subscription. Selected products may also provide callbacks, batch operations, files, or EDI. GraphQL is not confirmed as a vendor-wide Descartes capability, and SOAP should be treated as product-specific or legacy unless customer documentation confirms it.
Only when the selected Descartes product provides outbound callbacks or webhook-style notifications for the required event types. Coverage may be limited to selected milestones or exceptions. When callbacks are unavailable or incomplete, Martini can use scheduled polling and incremental synchronization.
Martini can use product-supported pagination, cursors, date filters, event identifiers, or updated timestamps and persist checkpoints between workflow executions. Stable Order or Shipment references, returned Descartes identifiers, idempotency keys, or upsert operations where available help prevent duplicate creation and processing.
Yes. Martini can expose a controlled REST API that presents a normalized logistics interface to internal or external applications, then orchestrate calls to the selected Descartes API. This can isolate product-specific models, authentication details, validation rules, and downstream routing from consuming applications.
Related Martini documentation
Workflows
Connect Descartes with your enterprise systems
Use Martini to orchestrate product-specific Descartes APIs, callbacks, files, and synchronization workflows with the validation, mapping, security, and operational controls required for reliable logistics integration.