agentleFS
ankitjh4ankitjh4/indic-ai-skills/skills/ondc-buyer/SKILL.md

ondc-buyer

Skill65 starsChanged 7 months agoMITView on GitHub

Deploy and manage ONDC buyer applications. Set up buyer reference apps with product discovery, cart management, checkout flows, and order tracking. Handle payment integration, delivery tracking, and ONDC protocol compliance for consumer-facing applications.

  • Reads credentials
  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Product Discovery: Search and browse products across ONDC network

    line 18
  2. Distinctive:

    Before using this skill, ensure you have:

    line 37
  3. Distinctive:

    Create account at https://dashboard.juspay.in

    line 235
  4. Distinctive:

    Update the payment service to match your gateway's API.

    line 250
  5. Very specific:

    After deployment, visit https://yourdomain.com/bugzilla/admin

    line 271
  6. Very specific:

    Add BUGZILLA_API_KEY to environment variables

    line 275
  7. Distinctive:

    Verify protocol layer is running

    line 297
  8. Distinctive:

    Check ONDC registry connectivity

    line 298
  9. Distinctive:

    Ensure catalog service is indexed

    line 300
  10. Distinctive:

    Test with Juspay sandbox first

    line 307
  11. Distinctive:

    Check GPS coordinate format

    line 312
  12. Very specific:

    Verify /track endpoint responses

    line 313
  13. Very specific:

    Never commit .env files or credentials to version control

    line 319
  14. Distinctive:

    Use HTTPS for all endpoints

    line 320
  15. Distinctive:

    Use this skill when you need to:

    line 377

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ONDC Buyer Skill

This skill helps you deploy and manage ONDC (Open Network for Digital Commerce) buyer applications. ONDC is India's digital commerce network enabling buyers to discover and purchase from sellers across multiple platforms.

What This Skill Does

  • Deploy ONDC Buyer Apps: Set up the complete buyer reference application
  • Product Discovery: Search and browse products across ONDC network
  • Shopping Cart: Manage cart, apply customizations, and handle variants
  • Checkout Flow: Handle select, init, confirm, and payment flows
  • Order Tracking: Track orders in real-time with GPS/URL-based tracking
  • Returns & Cancellations: Process returns, cancellations, and refunds
  • IGM Support: File and track issues/complaints with sellers

Architecture Overview

The ONDC Buyer App uses microservice architecture:

  • biap-client-node-js: Node.js backend API layer
  • biap-app-ui-front: React web application (served via nginx)
  • py-ondc-protocol: Python protocol layer for ONDC communication
  • biap-igm-node-js: Node.js IGM service for issue management
  • biap-bugzilla-service: Bugzilla integration for ticket management
  • catalog-service: Catalog indexing and search service

Prerequisites

Before using this skill, ensure you have:

  1. Docker & Docker Compose installed
  2. Git with submodule support
  3. Domain name or ngrok for public endpoint
  4. Required service accounts:
    • Firebase (authentication)
    • Juspay or other payment gateway
    • Map My India (location services)
  5. MongoDB (included in docker-compose)
  6. ONDC Registry Access (for production deployment)

Quick Start

1. Clone and Initialize

cd /home/workspace
git clone https://github.com/ONDC-Official/ondc-sdk.git ondc-buyer-app
cd ondc-buyer-app
git submodule init
git submodule update

2. Generate Cryptographic Keys

bun /home/workspace/Skills/ondc-buyer/scripts/generate-keys.ts

This creates signing and encryption keys required for ONDC registration.

3. Configure Environment

bun /home/workspace/Skills/ondc-buyer/scripts/setup-env.ts \
  --domain "https://buyerapp.example.com" \
  --firebase-key "YOUR_KEY" \
  --juspay-merchant-id "MERCHANT_ID" \
  --mmi-client-id "MMI_CLIENT"

4. Deploy Locally (Development)

cd /home/workspace/ondc-buyer-app
docker-compose -f docker-compose-for-local.yaml --env-file .env-local up -d

Access the app at http://localhost (or your configured domain).

5. Register with ONDC

Once deployed, use the registration helper:

bun /home/workspace/Skills/ondc-buyer/scripts/register.ts \
  --subscriber-url "https://buyerapp.example.com" \
  --signing-key "path/to/signing_public.pem" \
  --crypto-key "path/to/crypto_public.pem"

Common Operations

Check Application Status

bun /home/workspace/Skills/ondc-buyer/scripts/check-status.ts

Shows the status of all services (client, frontend, protocol, IGM, catalog).

Search Products

# Search across ONDC network
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --query "smartphones" --city "Bangalore"

# Search by category
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --category "Grocery" --location "110001"

# Get provider details
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --provider-id "PROVIDER123"

Manage Orders

# List user orders
bun /home/workspace/Skills/ondc-buyer/scripts/view-orders.ts --user-id "USER123" --limit 10

# Get order details and tracking
bun /home/workspace/Skills/ondc-buyer/scripts/view-orders.ts --order-id "ORDER456"

# Track order status
bun /home/workspace/Skills/ondc-buyer/scripts/track-order.ts --order-id "ORDER456"

Handle Returns & Cancellations

# Initiate cancellation
bun /home/workspace/Skills/ondc-buyer/scripts/cancel-order.ts --order-id "ORDER789" --reason "Changed mind"

# Request return
bun /home/workspace/Skills/ondc-buyer/scripts/return-order.ts --order-id "ORDER789" --items "ITEM1,ITEM2"

# Check cancellation status
bun /home/workspace/Skills/ondc-buyer/scripts/check-cancellation.ts --order-id "ORDER789"

Manage IGM Issues

# List user issues
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action list --user-id "USER123"

# File new issue
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action create \
  --order-id "ORDER123" \
  --type "PRODUCT_QUALITY" \
  --description "Product damaged"

# Track issue status
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action track --issue-id "IGM456"

Environment Variables

Key environment variables required (store in Settings > Advanced):

# ONDC Registry
BAP_URL="https://buyerapp.example.com"
BAP_ID="buyerapp.example.com"
BAP_PRIVATE_KEY="signing_private_key"
BAP_PUBLIC_KEY="signing_public_key"
BAP_UNIQUE_KEY_ID="unique_key_id_from_registry"

# Firebase Auth
FIREBASE_ADMIN_SERVICE_ACCOUNT="/path/to/firebase-service-account.json"
REACT_APP_FIREBASE_API_KEY="firebase_api_key"
REACT_APP_FIREBASE_AUTH_DOMAIN="buyerapp.example.com"

# Juspay Payment Gateway
JUSPAY_SECRET_KEY_PATH="/path/to/juspay-creds.pem"
JUSPAY_BASE_URL="https://sandbox.juspay.in"
JUSPAY_MERCHANT_ID="merchant_id"
JUSPAY_API_KEY="access_key"
JUSPAY_WEBHOOK_USERNAME="webhook_user"
JUSPAY_WEBHOOK_PASSWORD="webhook_pass"

# Web App Payment Config
REACT_APP_JUSTPAY_CLIENT_AND_MERCHANT_KEY="merchant_id"
REACT_APP_MERCHANT_KEY_ID="merchant_id"
REACT_APP_PAYMENT_SDK_ENV="sandbox"
REACT_APP_PAYMENT_SERVICE_URL="https://api.juspay.in"

# Map My India
MMI_CLIENT_SECRET="mmi_secret"
MMI_CLIENT_ID="mmi_client_id"
MMI_ADVANCE_API_KEY="mmi_api_key"

# MongoDB
MONGO_DB_URL="mongodb://mongo:27017/ondc"

Feature Support Matrix

The ONDC Buyer App implements ONDC Retail v1.2 specification:

FeatureStatus
Incremental catalog refresh✅ Available
Full catalog refresh✅ Available
Product search & discovery✅ Available
Shopping cart management✅ Available
Checkout flow (select/init/confirm)✅ Available
Payment integration (Juspay)✅ Available
Order tracking (GPS-based)✅ Available
Live order tracking✅ Available
Customization (selection)✅ Available
Variants support✅ Available
Return with liquidation✅ Available
Cancellation flows✅ Available
RTO (Return to Origin)✅ Available
IGM issue management✅ Available
Order history✅ Available
Multi-store cart✅ Available
Address management✅ Available
Customization (free text)📅 Future scope
Subscription orders📅 Future scope
Offers & discounts📅 Future scope

Payment Gateway Integration

Juspay Setup

  1. Create account at https://dashboard.juspay.in
  2. Generate API credentials from console
  3. Download merchant certificate (.pem file)
  4. Configure environment variables
  5. Set up webhook endpoints for payment callbacks

Alternative Payment Gateways

To integrate other payment gateways (Razorpay, Paytm, etc.):

# Modify payment service integration
vim /home/workspace/ondc-buyer-app/biap-client-node-js/src/payment/

Update the payment service to match your gateway's API.

Map My India Integration

MMI provides:

  • Address autocomplete
  • PIN code lookup
  • State/city detection
  • Geocoding (lat/long from address)

Required APIs:

  • https://outpost.mapmyindia.com/api - Authentication
  • https://atlas.mapmyindia.com/api/places/search/json - Search
  • https://explore.mappls.com - Explore places
  • https://apis.mapmyindia.com/advancedmaps/v1 - Advanced mapping
  • https://atlas.mappls.com/api/places/geocode - Geocoding

Bugzilla Setup (Optional)

For IGM ticket management:

  1. After deployment, visit https://yourdomain.com/bugzilla/admin
  2. Login with username admin and password password
  3. Configure SMTP settings for email notifications
  4. Generate API key from dashboard
  5. Add BUGZILLA_API_KEY to environment variables
  6. Restart bugzilla container

Note: Bugzilla is optional but recommended for full IGM functionality.

Troubleshooting

Services Not Starting

# Check logs
docker logs ondc-buyer-client
docker logs ondc-buyer-frontend
docker logs ondc-buyer-protocol
docker logs ondc-catalog-service

# Restart specific service
docker-compose restart biap-client-node-js

Search Not Working

  • Verify protocol layer is running
  • Check ONDC registry connectivity
  • Review /search request/response logs
  • Ensure catalog service is indexed

Payment Failures

  • Verify Juspay credentials
  • Check webhook configuration
  • Review payment service logs
  • Test with Juspay sandbox first

Order Tracking Issues

  • Confirm seller provides tracking URLs
  • Check GPS coordinate format
  • Verify /track endpoint responses
  • Review order status updates

Security Notes

  • Store all secrets in Zo's Settings > Advanced
  • Never commit .env files or credentials to version control
  • Use HTTPS for all endpoints
  • Implement rate limiting on public APIs
  • Validate payment webhook signatures
  • Sanitize user inputs
  • Regular security audits

Deployment Options

Local Development (with ngrok)

# Install ngrok
brew install --cask ngrok

# Start tunnel
ngrok http 5555

# Use ngrok URL in BAP_URL and PROTOCOL_BASE_URL

Production Deployment (with SSL)

# Use docker-compose with SSL
docker-compose -f docker-compose.yaml --env-file .env-prod up -d

# Initialize Let's Encrypt
./init-letsencrypt.sh

Ansible Deployment

cd deploying_ansible
ansible-playbook -i ansible_hosts buyer-app-install-for-ssl.yaml
ansible-playbook -i ansible_hosts buyer-app-run.yaml

References

See the references/ folder for:

  • ONDC API Contract v1.2 documentation
  • Buyer app user manual
  • Feature implementation guide
  • Integration requirements
  • Payment gateway setup guides

Support

When to Use This Skill

Use this skill when you need to:

  • Deploy an ONDC-compliant buyer application
  • Build a consumer-facing shopping experience on ONDC
  • Integrate payment gateways with ONDC flows
  • Implement product search and discovery
  • Handle end-to-end order management
  • Process returns and cancellations
  • File and track customer issues (IGM)
  • Scale buyer operations across India

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.