Skip to main content

Offramping Assets

Offramping of assets can only be triggered by the Sales Channel on behalf of their Trader. Assets can only be offramped if the Trader is a Puro.earth Platform Agreement signed Trader (the Trader is onboarded via a Trader Onboarding Proposal). Assets from a Sales Channel registered Trader cannot be off-ramped, any such requests will be rejected.

Prerequisites

Following roles are needed to be able to perform steps described on this page:

  • TRADER_VIEWER
  • ASSET_OFFRAMPER

See Authorization for more details about roles

info

You need a traderId of the Trader which assets are to be offramped. See Discover Assets page to fetch the traderId.

Offramping assets is an asynchronous process yielding an offramp task. Status of the offramp is observed from this task.

Registering Offramp​

Offramping is registered using POST /saleschannel-services/v1/traders/{traderId}/inventory/offramp endpoint. Start and end ids of bundles to be offramped will be given as the request payload.

Detailed payload for registering an offramp:

required
Array of objects non-empty

All assets which are involved in this offramp

{
  • "assets": [
    ]
}

Offramp assets
curl -X 'POST' "/saleschannel-services/v1/traders/{traderId}/inventory/offramp" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{ \
    "assets": [ \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_1", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_100" \
      } \
    ] \
  }'

Check the Offramping status​

Via the Get status of an offramp task endpoint​

A successful response from registering an offramp contains the id of the created offramp task which can be used to query for the offramp status.

Get status of an offramp task
curl -X 'GET' "/saleschannel-services/v1/traders/{traderId}/inventory/offramp/{taskId}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Resending the Offramp assets request​

As the offramp endpoint is idempotent with the help of the Idempotency-Key. You can request the status of the offramp by resending the exact same payload with the same Idempotency-Key used initially to register the offramp.

Response​

Both of these endpoints return the offramp task status

taskId
required
string

The ID of this task

status
required
string
Enum: "STARTED" "SUCCESS" "FAILED" "PENDING" "REJECTED"

The status of the transaction.

idempotencyKey
string <^[\w-]{1,64}$> ^[\w-]{1,64}$

Idempotency keys are client-generated strings which ensure that requests can be safely retried.

message
string

Human-readable message field describing the state of the task.

object

Details on the created offramp, if the offramp task completed successfully.

{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}
Asset bundles

The offramped start and end range of the Asset IDs cannot overlap between bundles.

For example, here the bundles do not overlap:

Offramp assets
curl -X 'POST' "/saleschannel-services/v1/traders/{traderId}/inventory/offramp" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{ \
    "assets": [ \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_1", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_50" \
      }, \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_100", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_150" \
      } \
    ] \
  }'