Curl Testing

Examples of curl commands to test the credex-core API endpoints directly. Login and onboard routes are the only that do not require a token.

⚠️ Important Notes

Always check the API code before testing to ensure you're using the correct field names and values.
Tokens expire after a few minutes, so you may need to login again if you encounter authentication errors. If you see a "Token expired" error with "Token activity timeout" reason, you'll need to login again to get a fresh token.
This document separates verified commands (✅) from untested commands (❌) to help guide your testing.
The CLIENT_API_KEY environment variable is set in this dev environment.

Verified Basic API Endpoints ✅

Login

curl -X POST http://localhost:3000/login -H "Content-Type: application/json" -H "x-client-api-key: $CLIENT_API_KEY" -d '{"phone": "1234567890"}'

Alternative: You can also use the test script to login, which will display the token and member information:

npm test login [phone_number]

# Example:
npm test login 19023332786

Onboard Member

curl -X POST http://localhost:3000/onboardMember -H "Content-Type: application/json" -H "x-client-api-key: $CLIENT_API_KEY" -d '{"firstname": "Fortunate", "lastname": "Vendor", "phone": "1234567890", "defaultDenom": "USD"}'

Create Trust Account

curl -X POST http://localhost:3000/createTrustAccount -H "Content-Type: application/json" -H "Authorization: Bearer token" -H "x-client-api-key: $CLIENT_API_KEY" -d '{
  "accountName": "Test USD Trust",
  "accountHandle": "TEST_USD_TRUST",
  "subtype": "BANK",
  "denomination": "USD",
  "bankFields": {
    "jurisdiction": "ZW",
    "accountNumber": "12345678",
    "branchCode": "001",
    "bankCode": "42"
  }
}'

Testing the Vimbiso Market API Flow

This guide demonstrates how to test the complete Vimbiso Market API flow using curl commands. We'll set up accounts, fund them, and test both seller and purchaser functionalities.

Step 1: Environment Setup

First, set up environment variables to make the curl commands more readable and reusable. Replace placeholder values with actual values as you proceed through the testing.

# Set the API key (should be available in your environment)
# export CLIENT_API_KEY="your_client_api_key"

# Base URL for local testing
export API_URL="http://localhost:3000"

# Store tokens and IDs as we obtain them
export ADMIN_TOKEN=""
export SELLER_TOKEN=""
export BUYER_TOKEN=""

export ADMIN_MEMBER_ID=""
export SELLER_MEMBER_ID=""
export BUYER_MEMBER_ID=""

export TRUST_ACCOUNT_ID=""
export SELLER_PERSONAL_ACCOUNT_ID=""
export BUYER_PERSONAL_ACCOUNT_ID=""
export PRODUCT_ACCOUNT_ID=""
export INVOICE_ID=""

Step 2: Account Setup ✅

2.1 Login as Admin (Account with Trust Creation Capability) ✅

# Login as admin (263778177125)
curl -X POST "$API_URL/login" \
  -H "Content-Type: application/json" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{"phone": "263778177125"}'

# Store the token
export ADMIN_TOKEN="token_from_response"

# Store the member ID
export ADMIN_MEMBER_ID="member_id_from_response"

2.2 Create a USD Trust Account ✅

# Create a USD trust account for the admin
curl -X POST "$API_URL/createTrustAccount" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "accountName": "Test USD Trust",
    "accountHandle": "TEST_USD_TRUST",
    "subtype": "BANK",
    "denomination": "USD",
    "bankFields": {
      "jurisdiction": "ZW",
      "accountNumber": "12345678",
      "branchCode": "001",
      "bankCode": "42"
    }
  }'

# Store the trust account ID
export TRUST_ACCOUNT_ID="account_id_from_response"

2.3 Create Seller Account ✅

# Onboard a new member as seller
curl -X POST "$API_URL/onboardMember" \
  -H "Content-Type: application/json" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "firstname": "Test",
    "lastname": "Seller",
    "phone": "1111111111",
    "defaultDenom": "USD"
  }'

# Login as the seller
curl -X POST "$API_URL/login" \
  -H "Content-Type: application/json" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{"phone": "1111111111"}'

# Store the seller token
export SELLER_TOKEN="token_from_response"

# Store the seller member ID
export SELLER_MEMBER_ID="member_id_from_response"

# Store the seller's personal account ID
export SELLER_PERSONAL_ACCOUNT_ID="personal_account_id_from_response"

2.4 Create Buyer Account ✅

# Onboard a new member as buyer
curl -X POST "$API_URL/onboardMember" \
  -H "Content-Type: application/json" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "firstname": "Test",
    "lastname": "Buyer",
    "phone": "2222222222",
    "defaultDenom": "USD"
  }'

# Login as the buyer
curl -X POST "$API_URL/login" \
  -H "Content-Type: application/json" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{"phone": "2222222222"}'

# Store the buyer token
export BUYER_TOKEN="token_from_response"

# Store the buyer member ID
export BUYER_MEMBER_ID="member_id_from_response"

# Store the buyer's personal account ID
export BUYER_PERSONAL_ACCOUNT_ID="personal_account_id_from_response"

Step 3: Fund Accounts ✅

Note: The following commands have been updated to match the API requirements.

3.1 Send Credex from Trust Account to Seller ✅

# Create a credex from trust account to seller's personal account
curl -X POST "$API_URL/createCredex" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "issuerAccountID": "'$TRUST_ACCOUNT_ID'",
    "receiverAccountID": "'$SELLER_PERSONAL_ACCOUNT_ID'",
    "Denomination": "USD",
    "InitialAmount": 99.00,
    "credexType": "PURCHASE",
    "OFFERSorREQUESTS": "OFFERS",
    "securedCredex": true
  }'

# Store the credex ID
export SELLER_CREDEX_ID="credex_id_from_response"

3.2 Accept Credex as Seller ✅

# Accept the credex
curl -X POST "$API_URL/acceptCredex" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "credexID": "'$SELLER_CREDEX_ID'"
  }'

3.3 Send Credex from Trust Account to Buyer ✅

# Create a credex from trust account to buyer's personal account
curl -X POST "$API_URL/createCredex" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "issuerAccountID": "'$TRUST_ACCOUNT_ID'",
    "receiverAccountID": "'$BUYER_PERSONAL_ACCOUNT_ID'",
    "Denomination": "USD",
    "InitialAmount": 99.00,
    "credexType": "PURCHASE",
    "OFFERSorREQUESTS": "OFFERS",
    "securedCredex": true
  }'

# Store the credex ID
export BUYER_CREDEX_ID="credex_id_from_response"

3.4 Accept Credex as Buyer ✅

# Accept the credex
curl -X POST "$API_URL/acceptCredex" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "credexID": "'$BUYER_CREDEX_ID'"
  }'

Step 4: Seller Setup

Note: The following commands have been updated to match the API requirements.

4.1 Enable Vendor Functionality ✅

# Enable seller to sell in the market
curl -X POST "$API_URL/sellInMarket" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "vendor": true,
    "storeAccountName": "Test Seller Store",
    "storeAccountHandle": "TEST_SELLER_STORE"
  }'

# Store the onboarded assets account ID and profile pictures account ID
export ONBOARDED_ASSETS_ACCOUNT_ID="onboarded_assets_account_id_from_response"
export PROFILE_PICTURES_ACCOUNT_ID="profile_pictures_account_id_from_response"

4.2 Edit Member Profile ✅

# Update seller's profile information
curl -X POST "$API_URL/editMember" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "firstname": "Test",
    "lastname": "Seller",
    "memberHandle": "test_seller",
    "vendorBio": "I am a test seller offering fresh produce."
  }'

4.3 Create Product Account ✅

# Create a product account for fresh tomatoes
curl -X POST "$API_URL/createAccountInternal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "accountName": "Fresh Tomatoes",
    "accountType": "PHYSICAL_ASSET",
    "accountDescription": "Fresh, organic tomatoes grown locally."
  }'

# Store the product account ID
export PRODUCT_ACCOUNT_ID="product_account_id_from_response"

Note: To create a product and associate it with a store in one step, include the storeAccountID parameter:

# Create a product and associate it with a store
curl -X POST "http://localhost:3000/createAccountInternal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "accountName": "Premium Winter Tires",
    "accountType": "PHYSICAL_ASSET",
    "accountDescription": "High-quality winter tires with excellent snow and ice traction.",
    "storeAccountID": "18a4569f-9da2-4f3f-ab82-723923ce98b0"
  }'

4.4 Upload Product Image ✅

Note: Directly including large base64-encoded images in curl commands can result in an "Argument list too long" error. The solution is to create a temporary JSON file with the image data and use that file as input to curl.

# Create a script to handle the image upload
cat > upload-image.sh << 'EOF'
#!/bin/bash

# Set variables
CLIENT_API_KEY="$CLIENT_API_KEY"
SELLER_TOKEN="$1"
PROFILE_PICTURES_ACCOUNT_ID="$2"
ONBOARDED_ASSETS_ACCOUNT_ID="$3"
IMAGE_PATH="$4"

# Convert image to base64
BASE64_IMAGE=$(base64 -w 0 "$IMAGE_PATH")

# Create JSON payload file
cat > image-payload.json << EOF_JSON
{
  "jpg": "$BASE64_IMAGE",
  "name": "test_image",
  "drAccountID": "$PROFILE_PICTURES_ACCOUNT_ID",
  "crAccountID": "$ONBOARDED_ASSETS_ACCOUNT_ID"
}
EOF_JSON

# Upload image using the JSON file
curl -X POST "http://localhost:3000/uploadAndOptimizeJpg" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d @image-payload.json
EOF

chmod +x upload-image.sh

# Run the script with the appropriate parameters
./upload-image.sh "$SELLER_TOKEN" "$PROFILE_PICTURES_ACCOUNT_ID" "$ONBOARDED_ASSETS_ACCOUNT_ID" "/path/to/image.jpg"

# From the response, store the image asset IDs
export ORIGINAL_ASSET_ID="original_asset_id_from_response"
export THUMBNAIL_ASSET_ID="thumbnail_asset_id_from_response"
export ASSET_200_ID="asset_200_id_from_response"
export ASSET_600_ID="asset_600_id_from_response"

4.5 Update Profile Pictures ✅

# Connect the uploaded images to the product account
curl -X POST "$API_URL/updateProfilePics" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "sourceID": "'$PRODUCT_ACCOUNT_ID'",
    "originalAssetID": "'$ORIGINAL_ASSET_ID'",
    "thumbnailAssetID": "'$THUMBNAIL_ASSET_ID'",
    "asset200ID": "'$ASSET_200_ID'",
    "asset600ID": "'$ASSET_600_ID'"
  }'

4.6 Edit Product Account ✅

# Update product account details
curl -X POST "$API_URL/editAccountInternal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "accountID": "'$PRODUCT_ACCOUNT_ID'",
    "accountName": "Fresh Organic Tomatoes",
    "accountDescription": "Fresh, organic tomatoes grown locally. Available year-round with peak harvest in summer months."
  }'

4.7 Set Store Status and Location ✅

# Open the store and set location
curl -X POST "$API_URL/storeStatus/$PRODUCT_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "storeOpen": true,
    "location": {
      "latitude": 17.8252,
      "longitude": 31.0335
    }
  }'

4.8 Generate Invoice ✅

# Generate an invoice for tomatoes
curl -X POST "$API_URL/generateInvoice" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "paymentAccountID": "'$SELLER_PERSONAL_ACCOUNT_ID'",
    "InvoiceData": {
      "items": [
        {
          "accountID": "'$PRODUCT_ACCOUNT_ID'",
          "amount": 6
        }
      ],
      "total": 6,
      "denomination": "USD",
      "notes": "Fresh Organic Tomatoes - 2kg at $3/kg"
    }
  }'

# Store the invoice ID
export INVOICE_ID="invoice_id_from_response"

Step 5: Buyer Actions

Note: The following commands have been updated to match the API requirements. The sellInMarket endpoint now requires storeAccountName and storeAccountHandle parameters to ensure an OPERATIONS account is created.

5.1 Search for Products ✅

# Search for tomatoes near a specific location
curl -X GET "$API_URL/searchProducts?keyword=tomatoes&latitude=17.8252&longitude=31.0335&radius=10" \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

Example: Search for "tire" products in Halifax, Nova Scotia:

curl -X GET "http://localhost:3000/searchProducts?keyword=tire&latitude=44.6484848&longitude=-63.6053617&radius=10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

The search response includes detailed product information, store details, and vendor information:

{
  "message": "Products found",
  "data": {
    "action": {
      "id": null,
      "type": "PRODUCTS_SEARCHED",
      "timestamp": "2025-04-01T13:36:45.887Z",
      "actor": "41f1057a-b463-4a58-b4f0-6a3af34b62c1",
      "details": {
        "keyword": "tire",
        "latitude": 44.6484848,
        "longitude": -63.6053617,
        "radius": 10,
        "resultsCount": 1
      }
    },
    "dashboard": {
      "products": [
        {
          "productID": "2b241ba3-6fa3-4486-83b5-33682b2ff4d6",
          "productName": "Premium Winter Tires",
          "productDescription": "High-quality winter tires with excellent snow and ice traction.",
          "productHandle": "",
          "thumbnailPicUrl": null,
          "store": {
            "storeName": "Test Seller Store",
            "storeHandle": "TEST_SELLER_STORE",
            "storeDescription": "",
            "location": {
              "latitude": 44.6484848,
              "longitude": -63.6053617
            },
            "distance": 0,
            "thumbnailPicUrl": null
          },
          "vendor": {
            "memberID": "41f1057a-b463-4a58-b4f0-6a3af34b62c1",
            "firstname": "Tony",
            "lastname": "Stark",
            "memberHandle": "19023332786",
            "vendorBio": "",
            "thumbnailPicUrl": null
          }
        }
      ],
      "searchParams": {
        "keyword": "tire",
        "latitude": 44.6484848,
        "longitude": -63.6053617,
        "radius": 10
      }
    }
  }
}

5.2 Get Product Information ✅

# Get detailed information about the tomatoes product
curl -X GET "$API_URL/getProduct/$PRODUCT_ACCOUNT_ID" \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

5.3 Get Member Information ✅

# Get information about the seller
curl -X GET "$API_URL/getMember/$SELLER_MEMBER_ID" \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

5.4 Get Account Internal Data ✅

# Get detailed account information for the product
curl -X GET "$API_URL/getAccountInternalData/$PRODUCT_ACCOUNT_ID" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

5.5 Get Invoice ❌

# Get the invoice details
curl -X GET "$API_URL/getInvoice/$INVOICE_ID" \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

5.6 Process Payment ❌

# Create a credex to pay for the invoice
curl -X POST "$API_URL/createCredex" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "issuerAccountID": "'$BUYER_PERSONAL_ACCOUNT_ID'",
    "credexType": "PURCHASE",
    "OFFERSorREQUESTS": "OFFERS",
    "securedCredex": true,
    "invoiceID": "'$INVOICE_ID'"
  }'

Step 6: Verification ✅

Note: The getAccountDashboard endpoint has been implemented and tested. The enhanced GetAccountDashboardFullService now returns products (AccountInternal entities) with AVAILABLE_IN relationship to the store account.

6.1 Verify Seller Account Balance ✅

# Get the seller's account dashboard
curl -X GET "$API_URL/getAccountDashboard/$SELLER_PERSONAL_ACCOUNT_ID" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

6.2 Verify Buyer Account Balance ✅

# Get the buyer's account dashboard
curl -X GET "$API_URL/getAccountDashboard/$BUYER_PERSONAL_ACCOUNT_ID" \
  -H "Authorization: Bearer $BUYER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

6.3 Verify Store Account ✅

# Get the seller's store account dashboard
curl -X GET "$API_URL/getAccountDashboard/$SELLER_STORE_ACCOUNT_ID" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

Note: The response now includes a "products" array in the dashboard data, containing all AccountInternal entities with an AVAILABLE_IN relationship to the store account. Each product includes accountID, accountName, accountType, and profilePictureThumbnail (if available).

# Example response (truncated):
{
  "message": "Account dashboard information retrieved successfully",
  "data": {
    "dashboard": {
      "accountID": "9a3d8d77-b7f0-4f9c-8900-45add7ba5bad",
      "accountName": "Updated Seller Store",
      "accountHandle": "UPDATED_SELLER_STORE",
      "accountType": "OPERATIONS",
      "defaultDenom": "USD",
      "isOwnedAccount": true,
      "balanceData": { ... },
      "pendingInData": [],
      "pendingOutData": [],
      "products": [
        {
          "accountID": "dcdea6f1-39f8-4081-b443-64f8da5d73e2",
          "accountName": "Fresh Apples",
          "accountType": "PHYSICAL_ASSET",
          "profilePictureThumbnail": "https://example.com/thumbnail.jpg"
        }
      ]
    }
  }
}

6.4 Edit Account ✅

# Update account details
curl -X POST "$API_URL/editAccount" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "accountID": "'$SELLER_STORE_ACCOUNT_ID'", 
    "accountName": "Updated Seller Store", 
    "accountHandle": "UPDATED_SELLER_STORE", 
    "defaultDenom": "USD"
  }'

6.5 Verify Invoice Status ❌

# Check the invoice status after payment
curl -X GET "$API_URL/getInvoice/$INVOICE_ID" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY"

6.6 Create Product with Store Relationship ✅

# Create a product with an AVAILABLE_IN relationship to a store
curl -X POST "$API_URL/createAccountInternal" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELLER_TOKEN" \
  -H "x-client-api-key: $CLIENT_API_KEY" \
  -d '{
    "accountName": "Fresh Apples",
    "accountType": "PHYSICAL_ASSET",
    "accountDescription": "Fresh, organic apples grown locally.",
    "storeAccountID": "'$SELLER_STORE_ACCOUNT_ID'"
  }'

# The product will now appear in the store's dashboard products array

Important: Note the use of single quotes around the variable in the JSON payload. This ensures proper variable substitution in the shell. For example: "storeAccountID": "'$SELLER_STORE_ACCOUNT_ID'"