Reference

API Endpoints

The exhaustive list of all REST API endpoints available across the V-Ledger microservices ecosystem.

Auth Service

Handles OAuth, deterministic wallets, and API Keys.

POST/v1/auth/login
Email/Password login.
Example Request Body▼
{
  "email": "[email protected]",
  "password": "SuperSecurePassword123!"
}
Example Response▼
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTIsImVtYWlsIjoiYnJhbmRAdi1sZWRnZXIuY29tIn0...",
  "user": {
    "id": 12,
    "email": "[email protected]",
    "companyName": "V-Ledger Precision Labs"
  }
}
POST/v1/auth/register
Account registration.
Example Request Body▼
{
  "email": "[email protected]",
  "password": "SuperSecurePassword123!",
  "companyName": "V-Ledger Precision Labs"
}
Example Response▼
{
  "success": true,
  "message": "User registered successfully! Please confirm your email address.",
  "userId": 12
}
POST/v1/auth/oauth/token
OAuth 2.0 Client Credentials flow for ERPs.
Example Request Body▼
{
  "grant_type": "client_credentials",
  "client_id": "vledger_cli_892b1a9f",
  "client_secret": "vledger_sec_fa8c71b1209bfa9f81d726b"
}
Example Response▼
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6InZsZWRnZXJfY2xpXzg5MmIxYTlmIn0...",
  "token_type": "Bearer",
  "expires_in": 3600
}
GET/v1/auth/api-keys
List available API Keys for the active environment.
Example Response▼
{
  "success": true,
  "apiKeys": [
    {
      "id": "key_7b1a2c",
      "name": "Production ERP Sync",
      "prefix": "vl_live_7b1a...",
      "createdAt": "2026-05-01T12:00:00.000Z"
    }
  ]
}

Passkeys (WebAuthn)

POST/v1/auth/passkey/register/challenge
Generates a unique cryptographic FIDO2/WebAuthn challenge for registering a new Passkey.
Example Request Body▼
{
  "email": "[email protected]"
}
Example Response▼
{
  "challenge": "4u7m9_S_b90Xo811d7f6_xab71bA",
  "rp": {
    "name": "V-Ledger Ecosystem",
    "id": "dashboard.v-ledger.com"
  },
  "user": {
    "id": "12",
    "name": "[email protected]",
    "displayName": "[email protected]"
  },
  "pubKeyCredParams": [
    { "type": "public-key", "alg": -7 },
    { "type": "public-key", "alg": -257 }
  ]
}
POST/v1/auth/passkey/register/verify
Verifies the registration assertion and registers the new biometric / hardware key.
Example Request Body▼
{
  "id": "AR8d1bfa98...",
  "rawId": "AR8d1bfa98...",
  "type": "public-key",
  "response": {
    "clientDataJSON": "eyJjaGFsbGVuZ2UiOiI0dTdtOV9TX2I5MFhvODExZDdmNl94YWI3MWJBIiwib3JpZ2luIjoiaHR0cHM6Ly9kYXNoYm9hcmQudi1sZWRnZXIuY29tIiwidHlwZSI6IndlYmF1dGhuLmNyZWF0ZSJ9",
    "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGNhdXRoRGF0YVg..."
  }
}
Example Response▼
{
  "success": true,
  "message": "Biometric hardware Passkey registered successfully!"
}
POST/v1/auth/passkey/login/challenge
Generates a unique cryptographic challenge to authenticate a user via Passkey.
Example Request Body▼
{
  "email": "[email protected]"
}
Example Response▼
{
  "challenge": "8b91a_xO77b102Fa781a9fd_9B8C",
  "allowCredentials": [
    { "type": "public-key", "id": "AR8d1bfa98..." }
  ]
}
POST/v1/auth/passkey/login/verify
Verifies the biometric signature assertion and issues a secure JWT.
Example Request Body▼
{
  "id": "AR8d1bfa98...",
  "rawId": "AR8d1bfa98...",
  "type": "public-key",
  "response": {
    "clientDataJSON": "eyJjaGFsbGVuZ2UiOiI4YjkxYV94Tzc3YjEwMkZhNzgxYTlmZF85QjhDIiwib3JpZ2luIjoiaHR0cHM6Ly9kYXNoYm9hcmQudi1sZWRnZXIuY29tIiwidHlwZSI6IndlYmF1dGhuLmdldCJ9",
    "authenticatorData": "SZYN5YgOjGh0NBcP5169a...",
    "signature": "MEQCIH3b1a9f1bc20a..."
  }
}
Example Response▼
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTIsImVtYWlsIjoiYnJhbmRAdi1sZWRnZXIuY29tIn0...",
  "user": {
    "id": 12,
    "email": "[email protected]",
    "companyName": "V-Ledger Precision Labs"
  }
}

Crypto Service (Core DPP)

Handles blockchain interaction, NFC validation, and Industry 4.0 resolving.

Core Operations

POST/v1/dpp/enroll
Registers a physical NTAG chip into initial inventory storage. Automatically triggered by the Toolbox Mobile App.
Example Request Body▼
{
  "chipUid": "04A1B2C3D4E5F6",
  "productId": null
}
Example Response▼
{
  "success": true,
  "message": "Chip registered and ready.",
  "data": {
    "id": 8921,
    "status": "INACTIVE"
  }
}
POST/v1/dpp/verify-chip
Validates the authenticity of an NTAG 424 DNA SUN signature.
Example Request Body▼
{
  "chipUid": "04B84542152390",
  "piccData": "93D47B697065490EF296ABEBCD9BFB22",
  "cmac": "AFEAEBC91A841FFAnc=XXtest"
}
Example Response▼
{
  "success": true,
  "authentic": true,
  "counter": 3,
  "chipType": "NXP NTAG 424 DNA"
}
POST/v1/dpp/mint
Mints a new V3 DPP. Requires validated NFC SUN payload.
Example Request Body▼
{
  "gtin": "04200000000001",
  "chipUid": "04B84542152390",
  "material": "V-Ledger Demo Batterie",
  "customDppData": {
    "hsCode": "85076000",
    "category": "battery",
    "originCountry": "CN"
  }
}
Example Response▼
{
  "success": true,
  "tokenId": "1328507507778448",
  "txHash": "0x784496e3199dbbc68696a217d1c41e1bb60c4ddf79313e0af249af51a9f16422",
  "message": "Digital Product Passport successfully minted on-chain!"
}
GET/v1/dpp/inventory
Returns all assets managed by the requesting brand.
Example Response▼
{
  "success": true,
  "inventory": [
    {
      "tokenId": "1328507507778448",
      "chipUid": "04B84542152390",
      "material": "V-Ledger Demo Batterie",
      "status": "ACTIVE"
    }
  ]
}
POST/v1/dpp/release
Initiates resale process. Calls authorizeClaim to delegate to platform admin, and returns a 94/5/1 split Stripe payment session QR-Code URL.
Example Response▼
{
  "success": true,
  "txHash": "0x4b72f10...22a",
  "stripeCheckoutUrl": "https://checkout.stripe.com/pay/cs_test_mock_x98b712",
  "message": "Asset successfully released for resale! Stripe payment QR-Code session generated."
}
POST/v1/dpp/claim
Authenticates physical ownership by executing claimOwnership on-chain, matching token ID and physical chip UID (Web NFC scan).
Example Response▼
{
  "success": true,
  "txHash": "0x39bf822...11b",
  "ownerWallet": "0x89D9F52c461F8a3B6208969fD663cB61f420",
  "message": "Ownership claimed successfully!"
}

ERP Integration

POST/v1/erp/provision
Reserves a Digital Twin in V-Ledger (Internal ID generation).
Example Request Body▼
{
  "sap_metadata": {
    "material_number": "MAT-GTIN-001",
    "order_id": "PROD-XYZ-2026"
  }
}
Example Response▼
{
  "success": true,
  "vledger_internal_id": "vledger_prov_7b8c1a",
  "status": "INACTIVE"
}
POST/v1/erp/provision/bulk
Bulk provisioning for high-volume manufacturing lines.
Example Request Body▼
{
  "items": [
    { "sap_metadata": { "material_number": "GTIN_A", "order_id": "OR_1" } },
    { "sap_metadata": { "material_number": "GTIN_A", "order_id": "OR_2" } }
  ]
}
Example Response▼
{
  "success": true,
  "count": 2,
  "items": [
    { "material_number": "GTIN_A", "vledger_internal_id": "b9a2f1..." }
  ]
}
POST/v1/factory/bind
Binds a physical chip UID to a provisioned vledger_internal_id.
Example Request Body▼
{
  "vledger_internal_id": "vledger_prov_7b8c1a",
  "hardware": {
    "chip_uid": "04B84542152390"
  }
}
Example Response▼
{
  "success": true,
  "message": "Binding successful. Product is now ACTIVE.",
  "vledger_internal_id": "vledger_prov_7b8c1a",
  "chip_uid": "04B84542152390"
}
GET/v1/aas/resolve/:id
Returns a full Asset Administration Shell (JSON) for the twin.
Example Response▼
{
  "id": "https://api.v-ledger.com/aas/01/04200000000001/21/04B84542152390",
  "idType": "IRI",
  "modelType": "AssetAdministrationShell"
}

Supply Chain (IaaS)

POST/v1/iaas/log-event
Logs a supply chain event (Location, Status, Condition).
Example Request Body▼
{
  "tokenId": "1328507507778448",
  "action": "IMPORT_CLEARED",
  "locationName": "Import Hub",
  "latitude": 48.137,
  "longitude": 11.575,
  "metadata": {
    "temperature_celsius": 21.5
  }
}
Example Response▼
{
  "success": true,
  "eventId": 60,
  "message": "Supply chain event logged successfully on-chain."
}
POST/v1/iaas/log-recycle
Marks product as recycled and releases circular deposits.
Example Request Body▼
{
  "tokenId": "1328507507778448",
  "locationName": "Recycling Hub",
  "latitude": 51.5,
  "longitude": 7.4
}
Example Response▼
{
  "success": true,
  "recycled": true,
  "releasedDeposit": "50.00 EURC",
  "message": "Circular recycling event logged, deposit released to consumer Connect account."
}

GS1 Digital Link & Discovery

GET/01/:gtin/21/:tokenId
GS1 Digital Link Resolver. Redirects browser requests directly to customer frontend.
Example Response▼
{
  "redirect": "https://dashboard.v-ledger.com/verify/01/04200000000001/21/04B84542152390",
  "statusCode": 307,
  "message": "Redirecting to Web NFC verification page."
}
GET/verify/01/:gtin/21/:tokenId
Consumer Verification Page (Customer Frontend).
Example Response▼
<!-- Renders customer-frontend with verification animations and real-time on-chain provenance timeline -->
GET/01/:gtin/21/:tokenId?format=vc
Returns the W3C Verifiable Credential (or via Accept: application/ld+json).
Example Response▼
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/status/v1",
    "https://vocabulary.uncefact.org/untp/v1",
    {
      "schema": "http://schema.org/",
      "dpp": "https://ec.europa.eu/espr/dpp/v1#",
      "idpp": "https://v-ledger.com/voc/",
      "provenance": "idpp:provenance"
    }
  ],
  "id": "urn:dpp:gtin:04200000000001:serial:04B84542152390:v1",
  "type": [
    "VerifiableCredential",
    "DigitalProductPassport"
  ],
  "issuer": "did:web:dashboard.v-ledger.com",
  "validFrom": "2026-05-09T15:41:27.792Z",
  "credentialStatus": {
    "id": "https://api.v-ledger.com/credentials/status/1#04B84542152390",
    "type": "BitstringStatusListEntry",
    "statusPurpose": "revocation",
    "statusListIndex": "0",
    "statusListCredential": "https://api.v-ledger.com/credentials/status/1"
  },
  "credentialSubject": {
    "id": "https://api.v-ledger.com/01/04200000000001/21/04B84542152390",
    "type": "Product",
    "dpp:upi": "https://api.v-ledger.com/01/04200000000001/21/04B84542152390",
    "dpp:modelIdentifier": "04200000000001",
    "dpp:instanceIdentifier": "04B84542152390",
    "schema:name": "V-Ledger Demo Batterie",
    "dpp:hsCode": "85076000",
    "dpp:originCountry": "CN",
    "dpp:materialComposition": [
      { "type": "MaterialComponent", "schema:name": "Kobalt", "dpp:percentage": 30 },
      { "type": "MaterialComponent", "schema:name": "Mangan", "dpp:percentage": 20 },
      { "type": "MaterialComponent", "schema:name": "Nickel", "dpp:percentage": 40 },
      { "type": "MaterialComponent", "schema:name": "Lithium", "dpp:percentage": 10 }
    ],
    "idpp:hardware": {
      "chipType": "NXP NTAG 424 DNA",
      "status": "AUTHENTIC",
      "verificationCount": 3
    },
    "dpp:conformity": {
      "type": "ConformityAssessment",
      "dpp:complianceStatus": "compliant",
      "dpp:declarationOfConformity": "https://v-ledger.com/compliance/doc"
    },
    "dpp:economicOperator": {
      "type": "Manufacturer",
      "schema:name": "V-Ledger Precision Labs",
      "schema:address": "Friedrichstraße 100, 10117 Berlin, Germany",
      "idpp:gln": "4012345000001"
    },
    "provenance": [
      {
        "action": "MINT",
        "location": "V-Ledger Factory",
        "actor": "did:vledger:actor:e8f18cc71a8cf19a",
        "latitude": 0,
        "longitude": 0,
        "timestamp": "2026-05-01T01:02:28.000Z",
        "tx": "0x784496e3199dbbc68696a217d1c41e1bb60c4ddf79313e0af249af51a9f16422"
      },
      {
        "action": "QC_PASSED",
        "location": "Quality Control",
        "actor": "did:vledger:actor:fbf60f75ed43d95e",
        "latitude": 0,
        "longitude": 0,
        "timestamp": "2026-05-03T22:48:32.000Z",
        "tx": "0x9ec1aa2ec62a1fa632866b9c9f201f45bf3e1a0ed1a48ded8f528c67d07ac032"
      },
      {
        "action": "EXPORT_CLEARED",
        "location": "Export Port",
        "actor": "did:vledger:actor:fbf60f75ed43d95e",
        "latitude": 0,
        "longitude": 0,
        "timestamp": "2026-05-03T22:48:36.000Z",
        "tx": "0xca2dddf8fff0d26777a481f2891f8e4de301566d20e22f168ed16b490cc2518d"
      },
      {
        "action": "IMPORT_CLEARED",
        "location": "Import Hub",
        "actor": "did:vledger:actor:fbf60f75ed43d95e",
        "latitude": 0,
        "longitude": 0,
        "timestamp": "2026-05-03T22:48:40.000Z",
        "tx": "0x52e2535e36521d5f5a8944825c27ca39fc818adb24081cfc00263be20cc5e6d1"
      },
      {
        "action": "INITIAL_SALE",
        "location": "Retail Arrival",
        "actor": "did:vledger:actor:fbf60f75ed43d95e",
        "latitude": 0,
        "longitude": 0,
        "timestamp": "2026-05-03T22:48:44.000Z",
        "tx": "0xb88e9a580eefaedb29bbf9f9f41d7dc85beb3408abe47f76adf5235337bdc254"
      },
      {
        "action": "AUTHORIZE_CLAIM",
        "location": "Brand Headquarters",
        "actor": "did:vledger:actor:e8f18cc71a8cf19a",
        "latitude": 48.137,
        "longitude": 11.575,
        "timestamp": "2026-05-03T22:48:48.000Z",
        "tx": "0xb79514247c0f79c53f7b6aecb1206f7d0b163ef86f026bf034544a9c74db939f"
      },
      {
        "action": "CLAIM_OWNERSHIP",
        "location": "Consumer Wallet",
        "actor": "did:vledger:actor:3dd563f673fa8b35",
        "latitude": 48.137,
        "longitude": 11.575,
        "timestamp": "2026-05-03T22:48:52.000Z",
        "tx": "0xeeddf81e342103675912f819cc10e5db8bc772440e94dbcc5a14ce718470eddb"
      },
      {
        "action": "RECYCLE_TRANSFER",
        "location": "Recycling Hub",
        "actor": "did:vledger:actor:60d46980fdac1ec3",
        "latitude": 51.5,
        "longitude": 7.4,
        "timestamp": "2026-05-03T22:48:56.000Z",
        "tx": "0x581f1fcfd6a72c9da79b39c0aab5ffce848a1138f82b0106372fd9b01b98c317"
      }
    ],
    "dpp:batchNumber": "BATCH-2026-A1",
    "dpp:emissionsScorecard": {
      "type": "EmissionsData",
      "dpp:carbonFootprint": {
        "type": "Measurement",
        "value": 1.2,
        "unit": "KGM",
        "metricName": "GHG emissions"
      }
    },
    "dpp:circularityScorecard": {
      "type": "CircularityData",
      "dpp:recycledContent": {
        "type": "Measurement",
        "value": 38,
        "unit": "P1"
      },
      "dpp:repairabilityScore": {
        "type": "Measurement",
        "value": 9.2,
        "unit": "SCORE"
      },
      "dpp:expectedLifeSpan": {
        "type": "Measurement",
        "value": 15,
        "unit": "ANN"
      }
    }
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "created": "2026-05-09T15:41:27.792Z",
    "verificationMethod": "did:web:dashboard.v-ledger.com#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "znxgoNEYmmeyZDF3zyoBQ9QAgF2FdvycyPzsNpV6tonLtSPKDx3FmgFspap6jEby2aWq1L4rKg1uqz5XTHjLCJRG"
  }
}
GET/01/:gtin/21/:tokenId?format=aas
Returns the full Asset Administration Shell (AAS) JSON.
Example Response▼
{
  "id": "https://api.v-ledger.com/aas/01/04200000000001/21/04B84542152390",
  "idType": "IRI",
  "modelType": "AssetAdministrationShell",
  "assetInformation": {
    "assetKind": "Instance",
    "globalAssetId": "https://api.v-ledger.com/01/04200000000001/21/04B84542152390",
    "specificAssetIds": [
      {
        "name": "GTIN",
        "value": "04200000000001",
        "semanticId": {
          "type": "ExternalReference",
          "keys": [
            {
              "type": "GlobalReference",
              "value": "0173-1#02-BAA120#008"
            }
          ]
        }
      },
      {
        "name": "SerialNumber",
        "value": "04B84542152390",
        "semanticId": {
          "type": "ExternalReference",
          "keys": [
            {
              "type": "GlobalReference",
              "value": "0173-1#02-AAO034#002"
            }
          ]
        }
      }
    ]
  },
  "submodels": [
    {
      "idShort": "DigitalNameplate",
      "id": "https://api.v-ledger.com/aas/submodels/nameplate/04B84542152390",
      "modelType": "Submodel",
      "semanticId": {
        "type": "ExternalReference",
        "keys": [
          {
            "type": "GlobalReference",
            "value": "https://admin-shell.io/zvei/nameplate/2/0/Nameplate"
          }
        ]
      },
      "submodelElements": [
        {
          "idShort": "ManufacturerName",
          "modelType": "Property",
          "valueType": "xs:string",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "0173-1#02-AAO677#002"
              }
            ]
          },
          "value": "V-Ledger Precision Labs"
        },
        {
          "idShort": "SerialNumber",
          "modelType": "Property",
          "valueType": "xs:string",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "0173-1#02-AAO034#002"
              }
            ]
          },
          "value": "04B84542152390"
        },
        {
          "idShort": "BatteryModel",
          "modelType": "Property",
          "valueType": "xs:string",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "0173-1#02-BAA120#008"
              }
            ]
          },
          "value": "BAT-LITHIUM-PRO-X"
        }
      ]
    },
    {
      "idShort": "SustainabilityData",
      "id": "https://api.v-ledger.com/aas/submodels/sustainability/04B84542152390",
      "modelType": "Submodel",
      "semanticId": {
        "type": "ExternalReference",
        "keys": [
          {
            "type": "GlobalReference",
            "value": "https://admin-shell.io/idta/CarbonFootprint/1/0"
          }
        ]
      },
      "submodelElements": [
        {
          "idShort": "CarbonFootprint",
          "modelType": "Property",
          "valueType": "xs:string",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "0173-1#02-ADF012#001"
              }
            ]
          },
          "value": "1.2 kg CO2e"
        },
        {
          "idShort": "RecycledContent",
          "modelType": "Property",
          "valueType": "xs:string",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "0173-1#02-BAA489#005"
              }
            ]
          },
          "value": "38%"
        },
        {
          "idShort": "StateOfHealth",
          "modelType": "Property",
          "valueType": "xs:string",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "https://admin-shell.io/idta/BatteryPass/Submodel/02003-1-2/SoH"
              }
            ]
          },
          "value": "100%"
        }
      ]
    },
    {
      "idShort": "Security",
      "id": "https://api.v-ledger.com/aas/submodels/security/04B84542152390",
      "modelType": "Submodel",
      "semanticId": {
        "type": "ExternalReference",
        "keys": [
          {
            "type": "GlobalReference",
            "value": "https://v-ledger.com/aas/Security/1/0"
          }
        ]
      },
      "submodelElements": [
        {
          "idShort": "ChipType",
          "modelType": "Property",
          "valueType": "xs:string",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "https://v-ledger.com/semantic/ChipType"
              }
            ]
          },
          "value": "NXP NTAG 424 DNA"
        },
        {
          "idShort": "CryptographicStatus",
          "modelType": "Property",
          "valueType": "xs:string",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "https://v-ledger.com/semantic/CryptoStatus"
              }
            ]
          },
          "value": "AUTHENTIC"
        },
        {
          "idShort": "SunCounter",
          "modelType": "Property",
          "valueType": "xs:integer",
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "https://v-ledger.com/semantic/SunCounter"
              }
            ]
          },
          "value": 3
        }
      ]
    }
  ],
  "extensions": [
    {
      "name": "eclassVersion",
      "valueType": "xs:string",
      "value": "12.0"
    }
  ]
}
GET/01/:gtin/21/:tokenId?format=public
Returns the basic public metadata of the Asset Twin.
Example Response▼
{
  "@context": [
    "https://ref.gs1.org/contexts/gs1-context.jsonld",
    { "schema": "http://schema.org/", "idpp": "https://v-ledger.com/voc/" }
  ],
  "@type": "gs1:Product",
  "@id": "https://api.v-ledger.com/01/04200000000001/21/041C4D42152390",
  "name": "V-Ledger Demo Batterie",
  "gs1:gtin": "04200000000001",
  "gs1:serialNumber": "041C4D42152390",
  "status": "ACTIVE",
  "smartContract": "0x2523822b6182f3c9705bd928f3481b61b182d61e",
  "idpp:hardware": {
    "chipType": "NXP NTAG 424 DNA",
    "status": "AUTHENTIC",
    "verificationCount": 8
  }
}
GET/01/:gtin/21/:tokenId?format=erp
Returns the ERP-specific metadata for SAP/Oracle systems.
Example Response▼
{
  "context": "SAP/Oracle Enterprise Sync",
  "integrationInfo": {
    "systemSource": "V-Ledger IaaS",
    "dataIntegrity": "BLOCKCHAIN_VERIFIED"
  },
  "productData": {
    "id": 14,
    "tokenId": "1328507507778448",
    "chipUid": "04B84542152390",
    "productId": "CERT-04B84542152390",
    "ownerWallet": "0x24954DA952B9590d7726DEDd1C1ccD4bB130F9b8",
    "material": "V-Ledger Demo Batterie",
    "warrantyExpiry": null,
    "metadataUrl": "ipfs://QmR8qpMFWqLrdn8N3nNAxR7RR1yGfzvAS5tJBFtomtag1Q",
    "sapMaterialId": null,
    "sapSerial": null,
    "sapOrderId": null,
    "vledgerUid": "2b130671-a603-4037-ab2b-4ea0ed56ed3d",
    "parentUid": null,
    "transactionHash": "0x784496e3199dbbc68696a217d1c41e1bb60c4ddf79313e0af249af51a9f16422",
    "mintBlock": 40914530,
    "mintTimestamp": "2026-05-01T01:02:27.000Z",
    "lockedDeposit": "1.62",
    "metadataCache": {
      "name": "V-Ledger Demo Batterie",
      "image": "ipfs://QmazCNumbt2RCVWMALkcxcSSpdHexTxJjtNG1z7PUeXPmZ",
      "chipUid": "04B84542152390",
      "nfcData": {
        "cmac": "AFEAEBC91A841FFAnc=XXtest",
        "urlPath": "https://dashboard.v-ledger.com/verify/01/04200000000001/21/04B84542152390",
        "piccData": "93D47B697065490EF296ABEBCD9BFB22"
      },
      "attributes": [
        { "value": 2026, "trait_type": "Herstellungsjahr", "display_type": "number" },
        { "value": "Batterie Fabrik China (Shenzhen, CN)", "trait_type": "Herkunft" },
        { "value": "BATTERY", "trait_type": "Kategorie" },
        { "value": "1.2 kg CO2e", "trait_type": "CO2-Fußabdruck" },
        { "value": "CERT-04B84542152390", "trait_type": "Echtheits-ID" },
        { "value": "V-Ledger Precision Labs", "trait_type": "Hersteller" },
        { "value": "BATCH-2026-A1", "trait_type": "Charge" },
        { "value": "Konform", "trait_type": "REACH Konformität" },
        { "value": "85 kWh", "trait_type": "Kapazität" },
        { "value": "NMC (Nickel-Mangan-Kobalt)", "trait_type": "Chemie" }
      ],
      "description": "V-Ledger Demo Batterie",
      "external_url": "",
      "custom_dpp_data": {
        "gtin": "04200000000001",
        "hsCode": "85076000",
        "category": "battery",
        "svhc_exists": false,
        "batch_number": "BATCH-2026-A1",
        "originCountry": "CN",
        "conformity_url": "https://v-ledger.com/compliance/doc",
        "manufacturer_gln": "4012345678901",
        "manufacturer_name": "V-Ledger Precision Labs",
        "manufacturingDate": "2026-04-26",
        "manufacturer_address": "Friedrichstraße 100, 10117 Berlin, Germany",
        "material_composition": { "Kobalt": 30, "Mangan": 20, "Nickel": 40, "Lithium": 10 }
      }
    },
    "contractAddress": "0x6e3e71841bda1b4a82ef86a961842f3e89928752",
    "environment": "test",
    "status": "ACTIVE",
    "createdAt": "2026-05-01T01:02:27.000Z",
    "updatedAt": "2026-05-01T01:02:28.000Z"
  },
  "chainOfCustody": {
    "totalEvents": 8,
    "firstSeen": "2026-05-01T01:02:28.000Z",
    "lastSeen": "2026-05-03T22:48:56.000Z",
    "integrityHash": "304a2b32099904ee1ea8fb9be273bf0f9e872e5aad52669d275150186e83c274"
  },
  "events": [
    {
      "id": 57,
      "tokenId": "1328507507778448",
      "action": "MINT",
      "actor": "brand***@v-ledger-demo.com",
      "locationName": "V-Ledger Factory",
      "latitude": 0,
      "longitude": 0,
      "metadata": { "gtin": "04200000000001" },
      "transactionHash": "0x784496e3199dbbc68696a217d1c41e1bb60c4ddf79313e0af249af51a9f16422",
      "blockNumber": 40914530,
      "contractAddress": null,
      "environment": "test",
      "timestamp": "2026-05-01T01:02:28.000Z",
      "createdAt": "2026-05-01T01:02:28.000Z",
      "updatedAt": "2026-05-01T01:02:28.000Z",
      "actorEmail": "brand***@v-ledger-demo.com"
    },
    {
      "id": 58,
      "tokenId": "1328507507778448",
      "action": "QC_PASSED",
      "actor": "fac***@shenzhen-assembly.com",
      "locationName": "Quality Control",
      "latitude": 0,
      "longitude": 0,
      "metadata": { "inspector": "QC-DE-07", "status": "APPROVED" },
      "transactionHash": "0x9ec1aa2ec62a1fa632866b9c9f201f45bf3e1a0ed1a48ded8f528c67d07ac032",
      "blockNumber": 40918542,
      "contractAddress": null,
      "environment": "live",
      "timestamp": "2026-05-03T22:48:32.000Z",
      "createdAt": "2026-05-03T22:48:32.000Z",
      "updatedAt": "2026-05-03T22:48:32.000Z",
      "actorEmail": "fac***@shenzhen-assembly.com"
    },
    {
      "id": 59,
      "tokenId": "1328507507778448",
      "action": "EXPORT_CLEARED",
      "actor": "fac***@shenzhen-assembly.com",
      "locationName": "Export Port",
      "latitude": 0,
      "longitude": 0,
      "metadata": { "originPort": "Shenzhen CN", "carrier": "G-Logistic" },
      "transactionHash": "0xca2dddf8fff0d26777a481f2891f8e4de301566d20e22f168ed16b490cc2518d",
      "blockNumber": 40918560,
      "contractAddress": null,
      "environment": "live",
      "timestamp": "2026-05-03T22:48:36.000Z",
      "createdAt": "2026-05-03T22:48:36.000Z",
      "updatedAt": "2026-05-03T22:48:36.000Z",
      "actorEmail": "fac***@shenzhen-assembly.com"
    },
    {
      "id": 60,
      "tokenId": "1328507507778448",
      "action": "IMPORT_CLEARED",
      "actor": "fac***@shenzhen-assembly.com",
      "locationName": "Import Hub",
      "latitude": 0,
      "longitude": 0,
      "metadata": { "destinationPort": "Hamburg DE", "temperature_celsius": 21.5 },
      "transactionHash": "0x52e2535e36521d5f5a8944825c27ca39fc818adb24081cfc00263be20cc5e6d1",
      "blockNumber": 40918578,
      "contractAddress": null,
      "environment": "live",
      "timestamp": "2026-05-03T22:48:40.000Z",
      "createdAt": "2026-05-03T22:48:40.000Z",
      "updatedAt": "2026-05-03T22:48:40.000Z",
      "actorEmail": "fac***@shenzhen-assembly.com"
    },
    {
      "id": 61,
      "tokenId": "1328507507778448",
      "action": "INITIAL_SALE",
      "actor": "fac***@shenzhen-assembly.com",
      "locationName": "Retail Arrival",
      "latitude": 0,
      "longitude": 0,
      "metadata": { "storeId": "ST-BERLIN-01", "channel": "POS" },
      "transactionHash": "0xb88e9a580eefaedb29bbf9f9f41d7dc85beb3408abe47f76adf5235337bdc254",
      "blockNumber": 40918596,
      "contractAddress": null,
      "environment": "live",
      "timestamp": "2026-05-03T22:48:44.000Z",
      "createdAt": "2026-05-03T22:48:44.000Z",
      "updatedAt": "2026-05-03T22:48:44.000Z",
      "actorEmail": "fac***@shenzhen-assembly.com"
    },
    {
      "id": 62,
      "tokenId": "1328507507778448",
      "action": "AUTHORIZE_CLAIM",
      "actor": "brand***@v-ledger-demo.com",
      "locationName": "Brand Headquarters",
      "latitude": 48.137,
      "longitude": 11.575,
      "metadata": { "authorizedAccount": "0x8b4FeAb0aaA199724e57A4b01d9aFa66dA9C1735" },
      "transactionHash": "0xb79514247c0f79c53f7b6aecb1206f7d0b163ef86f026bf034544a9c74db939f",
      "blockNumber": 40918614,
      "contractAddress": null,
      "environment": "live",
      "timestamp": "2026-05-03T22:48:48.000Z",
      "createdAt": "2026-05-03T22:48:48.000Z",
      "updatedAt": "2026-05-03T22:48:48.000Z",
      "actorEmail": "brand***@v-ledger-demo.com"
    },
    {
      "id": 63,
      "tokenId": "1328507507778448",
      "action": "CLAIM_OWNERSHIP",
      "actor": "consumer***@v-ledger-demo.com",
      "locationName": "Consumer Wallet",
      "latitude": 48.137,
      "longitude": 11.575,
      "metadata": { "newOwner": "0x8b4FeAb0aaA199724e57A4b01d9aFa66dA9C1735" },
      "transactionHash": "0xeeddf81e342103675912f819cc10e5db8bc772440e94dbcc5a14ce718470eddb",
      "blockNumber": 40918632,
      "contractAddress": null,
      "environment": "live",
      "timestamp": "2026-05-03T22:48:52.000Z",
      "createdAt": "2026-05-03T22:48:52.000Z",
      "updatedAt": "2026-05-03T22:48:52.000Z",
      "actorEmail": "consumer***@v-ledger-demo.com"
    },
    {
      "id": 64,
      "tokenId": "1328507507778448",
      "action": "RECYCLE_TRANSFER",
      "actor": "int***@remondis-recycling.com",
      "locationName": "Recycling Hub",
      "latitude": 51.5,
      "longitude": 7.4,
      "metadata": {
        "from": "0x8b4FeAb0aaA199724e57A4b01d9aFa66dA9C1735",
        "to": "0xf01BAdDCAC6aacD04cBdf3Bf2aEDFb074c8C791b"
      },
      "transactionHash": "0x581f1fcfd6a72c9da79b39c0aab5ffce848a1138f82b0106372fd9b01b98c317",
      "blockNumber": 40918650,
      "contractAddress": null,
      "environment": "live",
      "timestamp": "2026-05-03T22:48:56.000Z",
      "createdAt": "2026-05-03T22:48:56.000Z",
      "updatedAt": "2026-05-03T22:48:56.000Z",
      "actorEmail": "int***@remondis-recycling.com"
    }
  ],
  "hardware": {
    "chipUid": "04B84542152390",
    "chipType": "NXP NTAG 424 DNA",
    "status": "AUTHENTIC",
    "verified": true,
    "counter": 3
  }
}
GET/01/:gtin/21/:tokenId?format=linkset
Returns the GS1 linkset response (or via Accept: application/linkset+json).

Payment Service

Handles Stripe subscriptions and metered billing for API usage.

GET/v1/billing/status
Returns the current subscription plan and status of the Brand.
GET/v1/billing/usage
Returns the current meter for Pay-per-Mint usage.
POST/v1/billing/checkout
Initiates a new Stripe Checkout process for an Essential/Pro subscription.
POST/v1/billing/portal
Generates a Stripe Customer Portal link.

Compliance (KYB) Service

Handles Stripe Connect onboarding, company validation, and legal document uploads.

GET/v1/kyb/status
Returns the current compliance verification state, any currently outstanding legal requirements, and the Stripe Connect ID.
Example Response▼
{
  "status": "pending",
  "verified": false,
  "requirements": [
    "company.tax_id",
    "representative.document"
  ],
  "connectId": "acct_1TUwqJDba8oM1U1X"
}
POST/v1/kyb/submit
Initiates the B2B verification process. Creates a Custom Connected Account and submits company, tax, representative, and TOS details.
Example Response▼
{
  "success": true,
  "message": "KYB onboarding details submitted successfully.",
  "connectId": "acct_1TUwqJDba8oM1U1X"
}
POST/v1/kyb/upload-document
Uploads a base64-encoded PDF or image directly to Stripe's secure identity vault for official verification of registry extracts or personal IDs.
Example Response▼
{
  "success": true,
  "message": "Verification document uploaded and linked successfully.",
  "fileId": "fil_1TUwrFDHKVPsMXCW123456"
}

Compliance (KYC) Service

Handles consumer-level KYC (Know Your Customer) onboarding, individual banking details (IBAN), and passport/ID validation for secondary sellers and deposit payouts.

GET/v1/kyc/status
Returns the current KYC verification state, outstanding verification requirements, and the Stripe Connect ID for an individual customer.
Example Response▼
{
  "status": "pending",
  "verified": false,
  "requirements": [
    "individual.verification.document"
  ],
  "connectId": "acct_1TUwqJDba8oM1U1X"
}
POST/v1/kyc/submit
Initiates consumer KYC onboarding. Submits the representative's individual details, birthdate, address, and payout IBAN to Stripe.
Example Response▼
{
  "success": true,
  "message": "KYC onboarding details submitted successfully.",
  "connectId": "acct_1TUwqJDba8oM1U1X"
}
POST/v1/kyc/upload-document
Uploads base64 passport/ID scans directly to Stripe's secure document vault on behalf of individual sellers.
Example Response▼
{
  "success": true,
  "message": "Verification document uploaded and linked successfully.",
  "fileId": "fil_1TUwrFDHKVPsMXCW123456"
}