> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agribackup.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Link Batch to Shipment Async | AgriBackup EUDR
> Invoke the Hedera smart contract to cryptographically lock a compliant EUDR batch to a logistics shipment. Returns 202 Accepted with a jobId.
Invokes the AgriBackup Hedera smart contract to cryptographically lock a verified, compliant EUDR batch to a logistics shipment reference. This creates an immutable on-chain record binding the batch's supply-chain provenance to a specific Bill of Lading or shipment tracking ID. Because Hedera consensus takes time, this endpoint returns `202 Accepted` immediately with a `jobId`. Poll `GET /api/v1/enterprise/eudr/jobs/{jobId}` or listen for the `shipment.linked` webhook to confirm that the smart contract lock has been executed.
Only batches with a `consolidatedRiskState` of `COMPLIANT` or `LOW` may be linked to a shipment. Attempting to link a `HIGH_RISK` batch returns `409 Conflict`.
## Request Headers
| Header | Required | Description |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `X-API-Key` | ✅ | Your live API key, e.g. `sk_live_...`. |
| `Idempotency-Key` | ✅ | A UUID v4 string. Replaying the same key within 24 hours returns the original response without re-invoking the smart contract. |
## Request Body
| Field | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------ |
| `batchId` | string | ✅ | The UUID of the EUDR batch to link. |
| `shipmentId` | string | ✅ | The shipment reference or logistics tracking ID (e.g. `SHIP-OOCL-9988`). |
| `billOfLading` | string | ☐ | Optional Bill of Lading document number (e.g. `BOL-77665544`). |
| `vesselName` | string | ☐ | Optional shipping vessel name (e.g. `MSC Gulsun`). |
```json theme={null}
{
"batchId": "uuid-1234",
"shipmentId": "SHIP-OOCL-9988",
"billOfLading": "BOL-77665544",
"vesselName": "MSC Gulsun"
}
```
## Response — 202 Accepted
| Field | Type | Description |
| ---------------------- | ----------------- | ------------------------------------------------------------------------------ |
| `jobId` | string | Use this ID to poll job status via `GET /api/v1/enterprise/eudr/jobs/{jobId}`. |
| `status` | string | Always `PENDING` on acceptance. |
| `estimatedDurationSec` | integer | Estimated seconds until Hedera consensus completes. |
| `createdAt` | string (ISO-8601) | Timestamp when the job was accepted. |
The response also includes a `Location` header pointing to the job status endpoint.
```json theme={null}
{
"jobId": "job_998877",
"status": "PENDING",
"estimatedDurationSec": 3,
"createdAt": "2026-06-15T12:00:00Z"
}
```
## Error Responses
| Status | Meaning |
| ------ | ------------------------------------------------------------------------------------------------------- |
| `400` | Invalid `batchId`, invalid `shipmentId`, or malformed request body. |
| `401` | Missing or invalid `X-API-Key`. |
| `403` | Your API key does not have permission to link this batch. |
| `409` | The batch is already linked to a shipment, or a double-spend attempt was detected on the Hedera ledger. |
| `423` | The batch is currently being processed by another thread. Wait briefly and retry. |
| `429` | Rate limit exceeded. |
## Async Completion — `shipment.linked` Webhook
When the Hedera smart contract lock is confirmed, AgriBackup fires a `shipment.linked` event to your registered webhook URL. The payload is signed with `X-AgriBackup-Signature` (HMAC-SHA256). After receiving this event, the batch is cryptographically immutable and ready for Due Diligence Statement generation.
## Code Examples
```python Python theme={null}
import agribackup
from agribackup.rest import ApiException
import uuid
configuration = agribackup.Configuration(host="https://live.agribackup.com/api/v1")
configuration.api_key['ApiKeyAuth'] = 'sk_live_YOUR_API_KEY'
with agribackup.ApiClient(configuration) as api_client:
try:
api_instance = agribackup.EnterpriseLogisticsApi(api_client)
request = agribackup.ShipmentLinkRequest(
batch_id='uuid-1234',
shipment_id='SHIP-OOCL-9988',
bill_of_lading='BOL-77665544',
vessel_name='MSC Gulsun'
)
response = api_instance.link_batch_to_shipment(
idempotency_key=str(uuid.uuid4()),
shipment_link_request=request
)
print("Job accepted:", response.job_id)
except ApiException as e:
print("Error:", e)
```
```javascript Node.js theme={null}
import { AgriBackupClient } from '@agribackup/sdk';
import { v4 as uuidv4 } from 'uuid';
const client = new AgriBackupClient({
apiKey: 'sk_live_YOUR_API_KEY',
baseUrl: 'https://live.agribackup.com/api/v1'
});
async function linkShipment() {
try {
const response = await client.logistics.linkBatchToShipment({
idempotencyKey: uuidv4(),
batchId: 'uuid-1234',
shipmentId: 'SHIP-OOCL-9988',
billOfLading: 'BOL-77665544',
vesselName: 'MSC Gulsun'
});
console.log('Job accepted:', response.jobId);
} catch (error) {
console.error('Error:', error.message);
}
}
```
```bash cURL theme={null}
curl -X POST https://live.agribackup.com/api/v1/enterprise/eudr/shipments/link \
-H "X-API-Key: sk_live_YOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"batchId": "uuid-1234",
"shipmentId": "SHIP-OOCL-9988",
"billOfLading": "BOL-77665544",
"vesselName": "MSC Gulsun"
}'
```
## OpenAPI
````yaml post /api/v1/enterprise/eudr/shipments/link
openapi: 3.0.1
info:
title: AgriBackup Enterprise EUDR API
description: >-
# Introduction
AgriBackup is the cryptographic compliance engine for EU-bound commodity
imports. Built on Deterministic Logic, Immutable Evidence, and
High-Throughput Ingestion, our API provides Tier-1 enterprise routing for EU
Deforestation Regulation (EUDR).
## The Integration Vector
To integrate this Digital Trust Layer into your ERP, you must execute the
following sequence:
1. **Authentication:** Generate your `X-API-Key` from the client dashboard.
2. **Telemetry:** Register your webhook URLs via `POST /webhooks`.
3. **Ingestion:** Push your GeoJSON polygons via `POST /polygons`.
4. **Logistics:** Lock the batch to a shipment via `POST /shipments/link`.
## Asynchronous Architecture
Because satellite deforestation screening and Hedera DLT anchoring take
time, ingestion endpoints return a `202 Accepted`. You must listen for the
corresponding Webhook to confirm cryptographic execution.
## Base URLs
* **Production:** `https://live.agribackup.com`
* **Sandbox:** `https://sandbox.agribackup.com`
contact:
name: AgriBackup Architecture Team
url: https://agribackup.com
email: contact@agribackup.com
license:
name: Proprietary
url: https://agribackup.com/terms
version: v1.0
servers:
- url: https://live.agribackup.com
description: Production (Mainnet)
- url: https://sandbox.agribackup.com
description: Sandbox (Testnet)
security: []
tags:
- name: Enterprise Risk Management
- name: Enterprise Clearance Webhooks
description: Asynchronous status receivers for TRACES NT
- name: Enterprise Jobs
description: Query status and metrics of asynchronous compliance jobs
- name: Enterprise Suppliers
- name: Enterprise Diagnostics
description: Monitor API health, consensus ledger, and satellite systems availability
- name: Enterprise Suppliers
description: Map internal ERP vendor IDs to EU Operator UUIDs
- name: Enterprise Webhooks
description: Register endpoints for asynchronous compliance events
- name: Enterprise Archival
description: Endpoints for bulk compliance archiving and auditor extensibility
- name: Enterprise Logistics
description: Smart contract linking of batches to logistics shipments
- name: Enterprise Declarations
description: DDS generation with legal land tenure proofs
- name: Enterprise Batches
- name: Enterprise API Keys
- name: Enterprise Diagnostics
- name: Enterprise Logistics
- name: Enterprise Jobs
- name: Enterprise Evidence
description: Cryptographic evidence ledger anchored on Hedera Hashgraph
- name: Enterprise Declarations
- name: Enterprise Credentials
- name: Enterprise Evidence
- name: Enterprise Risk Management
description: Pre-assessment of country risk and satellite deforestation probabilities
- name: Enterprise Batches
description: Programmatic batch ingestion and management
- name: Enterprise Polygons
- name: Introduction
- name: Enterprise Polygons
description: Programmatic polygon ingestion and verification
- name: Enterprise Archival
- name: Enterprise Credentials
description: Programmatic ingestion of vault-secured enterprise secrets
- name: Enterprise API Keys
description: Endpoints for managing B2B API Keys (Requires standard JWT login)
- name: Enterprise Webhooks
paths:
/api/v1/enterprise/eudr/shipments/link:
post:
tags:
- Enterprise Logistics
summary: Cryptographically link a batch to a shipment (Async)
description: >-
Invokes the [BATCH_SHIPMENT_GATEKEEPER] Hedera Smart Contract to lock a
verified batch to a logistics shipment. Emits a 'shipment.linked'
webhook upon blockchain consensus.
operationId: linkBatchToShipment
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentLinkRequest'
required: true
responses:
'202':
description: Smart contract lock initiated asynchronously
headers:
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
format: int32
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets in UTC
epoch seconds.
schema:
type: integer
format: int32
X-RateLimit-Limit:
description: >-
The maximum number of requests you're permitted to make per
hour.
schema:
type: integer
format: int32
X-Trace-Id:
description: Unique request trace identifier
style: simple
schema:
type: string
Location:
description: >-
The relative URI path to track the lifecycle phase and final
cryptographic consensus receipts for this job.
style: simple
schema:
type: string
example: /api/v1/enterprise/eudr/jobs/job_998877
content:
application/json:
schema:
$ref: '#/components/schemas/JobAcceptedResponse'
'400':
description: Bad Request (e.g., Invalid Batch ID or invalid payload structure)
headers:
X-RateLimit-Limit:
description: >-
The maximum number of requests you're permitted to make per
hour.
schema:
type: integer
format: int32
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
format: int32
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets in UTC
epoch seconds.
schema:
type: integer
format: int32
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
headers:
X-RateLimit-Limit:
description: >-
The maximum number of requests you're permitted to make per
hour.
schema:
type: integer
format: int32
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
format: int32
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets in UTC
epoch seconds.
schema:
type: integer
format: int32
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
headers:
X-RateLimit-Limit:
description: >-
The maximum number of requests you're permitted to make per
hour.
schema:
type: integer
format: int32
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
format: int32
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets in UTC
epoch seconds.
schema:
type: integer
format: int32
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'409':
description: >-
Hedera EVM State Violation (e.g., Shipment already linked,
double-spend attempt)
headers:
X-RateLimit-Limit:
description: >-
The maximum number of requests you're permitted to make per
hour.
schema:
type: integer
format: int32
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
format: int32
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets in UTC
epoch seconds.
schema:
type: integer
format: int32
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'423':
description: >-
Locked: Execution thread is currently processing the resource. Wait
and retry.
headers:
X-RateLimit-Limit:
description: >-
The maximum number of requests you're permitted to make per
hour.
schema:
type: integer
format: int32
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
format: int32
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets in UTC
epoch seconds.
schema:
type: integer
format: int32
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
description: Too Many Requests
headers:
X-RateLimit-Limit:
description: >-
The maximum number of requests you're permitted to make per
hour.
schema:
type: integer
format: int32
X-RateLimit-Remaining:
description: >-
The number of requests remaining in the current rate limit
window.
schema:
type: integer
format: int32
X-RateLimit-Reset:
description: >-
The time at which the current rate limit window resets in UTC
epoch seconds.
schema:
type: integer
format: int32
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: Python
source: >-
import agribackup
from agribackup.rest import ApiException
# Initialize Client
configuration =
agribackup.Configuration(host="https://live.agribackup.com/api/v1")
configuration.api_key['ApiKeyAuth'] = 'sk_live_YOUR_API_KEY'
with agribackup.ApiClient(configuration) as api_client:
try:
api_instance = agribackup.EnterpriseLogisticsApi(api_client)
response = api_instance.link_batch_to_shipment()
print(response)
except ApiException as e:
print("Exception when calling API: %s\n" % e)
- lang: Node.js
source: |-
import { AgriBackupClient } from '@agribackup/sdk';
// Initialize Client
const client = new AgriBackupClient({
apiKey: 'sk_live_YOUR_API_KEY',
baseUrl: 'https://live.agribackup.com/api/v1'
});
async function execute() {
try {
const response = await client.logistics.linkBatchToShipment();
console.log(response);
} catch (error) {
console.error(error);
}
}
- lang: Java
source: |-
import com.agribackup.client.*;
import com.agribackup.client.api.*;
import com.agribackup.client.model.*;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://live.agribackup.com/api/v1");
defaultClient.setApiKey("sk_live_YOUR_API_KEY");
EnterpriseLogisticsApi apiInstance = new EnterpriseLogisticsApi(defaultClient);
try {
Object result = apiInstance.linkBatchToShipment();
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling API: " + e.getResponseBody());
}
}
}
- lang: C#
source: |-
using System;
using System.Threading.Tasks;
using AgriBackup.SDK.Api;
using AgriBackup.SDK.Client;
using AgriBackup.SDK.Model;
class Program {
static async Task Main() {
Configuration config = new Configuration();
config.BasePath = "https://live.agribackup.com/api/v1";
config.AddApiKey("ApiKeyAuth", "sk_live_YOUR_API_KEY");
var apiInstance = new EnterpriseLogisticsApi(config);
try {
var result = await apiInstance.LinkBatchToShipmentAsync();
Console.WriteLine(result);
} catch (ApiException e) {
Console.WriteLine("Exception when calling API: " + e.Message);
}
}
}
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
description: >-
Unique idempotency key (UUID) to prevent duplicate operations. Safely
stored in Redis with a strict 24-hour TTL to prevent memory bloat during
saturation attacks.
required: true
schema:
type: string
format: uuid
schemas:
ShipmentLinkRequest:
required:
- batchId
- shipmentId
type: object
properties:
batchId:
type: string
description: The EUDR batch ID
example: uuid-1234
shipmentId:
type: string
description: The shipment reference or logistics tracking ID
example: SHIP-OOCL-9988
billOfLading:
type: string
description: Optional Bill of Lading document number
nullable: true
example: BOL-77665544
vesselName:
type: string
description: Optional Shipping Vessel Name
nullable: true
example: MSC Gulsun
description: Payload to link a batch to a shipment via Hedera Smart Contract
JobAcceptedResponse:
required:
- createdAt
- estimatedDurationSec
- jobId
- status
type: object
properties:
jobId:
type: string
description: The unique asynchronous tracking job ID
example: job_998877
status:
type: string
description: Current execution status invariant
example: PENDING
enum:
- PENDING
estimatedDurationSec:
type: integer
description: >-
Estimated duration in seconds before consensus or processing lock
release
format: int32
example: 3
createdAt:
type: string
description: Timestamp when the job was accepted
format: date-time
example: '2026-06-15T12:00:00Z'
description: Response payload for asynchronously accepted jobs
ApiError:
required:
- code
- details
- message
type: object
properties:
code:
type: string
description: Error code
example: VALIDATION_FAILED
message:
type: string
description: Human-readable error message
example: Invalid polygon coordinates
details:
type: array
description: Detailed list of validation errors, if applicable
items:
$ref: '#/components/schemas/ApiErrorDetail'
description: Standard error format for all Enterprise API failures
ApiErrorDetail:
required:
- code
- field
- issue
type: object
properties:
code:
type: string
description: Programmatic error code for automated branch logic
example: INVALID_COORDINATE_CLOSURE
field:
type: string
description: The field or property that caused the error
example: features[0].properties.area
issue:
type: string
description: A description of the issue with the field
example: Area must be specified in hectares and cannot be negative
description: Detailed error information for a specific field
securitySchemes:
ApiKeyAuth:
type: apiKey
description: Enterprise API Key provided via the AgriBackup developer console.
name: X-API-Key
in: header
````