API Integration Guide

// Example: Add "Order Services" button to tenant portal
async function orderServicesForTenant(tenant, property) {
  // 1. Get available services for property address
  const catalog = await fetchCatalog(property.zipCode);

  // 2. Let tenant select services
  const selectedServices = await showServiceSelection(catalog);

  // 3. Place orders
  const orders = await Promise.all(
    selectedServices.map((service) =>
      placeOrder({
        offerId: service.id,
        customerInfo: {
          fullName: tenant.name,
          email: tenant.email,
          phone: tenant.phone,
        },
        serviceAddress: property.address,
      })
    )
  );

  // 4. Track and notify tenant
  await trackOrders(orders);
}

// Example: Pre-close service coordination
async function coordinateServicesForClosing(property, buyer) {
  const moveInDate = property.closingDate;

  // Get services available at property
  const services = await getAvailableServices(property.zipCode);

  // Recommend essential services
  const recommended = recommendServices(services, property.type);

  // Place orders timed for move-in
  const orders = await placeOrdersWithTiming(recommended, buyer, moveInDate);

  return orders;
}

// Example: Service comparison tool
async function buildServiceComparison(zipCode, serviceType) {
  // Fetch available offers
  const offers = await fetch(
    `https://api.offergrid.io/reseller/catalog?zipCode=${zipCode}&category=${serviceType}`,
    {
      headers: {
        'x-api-key': process.env.OFFERGRID_API_KEY,
      },
    }
  );

  const services = await offers.json();

  // Build comparison table
  const comparison = services.map((s) => ({
    name: s.name,
    price: s.monthlyPrice,
    features: s.keyFeatures,
    provider: s.providerName,
  }));

  return comparison;
}

// When user selects service
async function captureLeadAndOrder(service, customerInfo) {
  // Save lead to CRM
  await saveToCRM(customerInfo);

  // Place order on Offergrid
  const order = await placeOrder({
    offerId: service.id,
    customerInfo,
    serviceAddress: customerInfo.address,
  });

  // Track order in CRM
  await updateCRMWithOrder(customerInfo.id, order.orderId);

  return order;
}

# Get all services
GET /reseller/catalog

# Filter by category
GET /reseller/catalog?category=internet

# Filter by location
GET /reseller/catalog?zipCode=94102

# Search
GET /reseller/catalog?search=fiber&minPrice=50&maxPrice=100

GET /reseller/catalog/{offerId}

POST /reseller/orders
Content-Type: application/json

{
  "items": [{ "offerId": "off-123-abc" }],
  "customerInfo": {
    "fullName": "John Doe",
    "email": "john@example.com",
    "phone": "+1-555-123-4567"
  },
  "serviceAddress": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "country": "US"
  }
}

# List all orders
GET /reseller/orders

# Get specific order
GET /reseller/orders/{orderId}

# Filter by status
GET /reseller/orders?status=scheduled

PATCH /reseller/orders/{orderId}/cancel
Content-Type: application/json

{
  "reason": "Customer no longer needs service"
}

async function safeApiCall(apiFunction, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await apiFunction();
    } catch (error) {
      if (error.status === 401) {
        throw new Error('Invalid API key');
      }

      if (error.status === 429) {
        // Rate limited - wait and retry
        await sleep(2 ** i * 1000);
        continue;
      }

      if (error.status >= 500) {
        // Server error - retry
        await sleep(2 ** i * 1000);
        continue;
      }

      // Client error - don't retry
      throw error;
    }
  }

  throw new Error('Max retries exceeded');
}

const catalogCache = {
  data: null,
  timestamp: null,
  ttl: 3600000, // 1 hour

  async get(zipCode) {
    if (this.isValid()) {
      return this.data;
    }

    this.data = await fetchCatalog(zipCode);
    this.timestamp = Date.now();
    return this.data;
  },

  isValid() {
    return this.data && Date.now() - this.timestamp < this.ttl;
  },
};

const orderCache = new Map();
const ORDER_CACHE_TTL = 300000; // 5 minutes

async function getOrderStatus(orderId) {
  const cached = orderCache.get(orderId);

  if (cached && Date.now() - cached.timestamp < ORDER_CACHE_TTL) {
    return cached.data;
  }

  const order = await fetchOrder(orderId);
  orderCache.set(orderId, {
    data: order,
    timestamp: Date.now(),
  });

  return order;
}

app.post('/webhooks/offergrid', async (req, res) => {
  const { event, orderId, status } = req.body;

  if (event === 'order.status_changed') {
    // Update your database
    await updateOrderInDatabase(orderId, status);

    // Notify customer
    await sendCustomerNotification(orderId, status);
  }

  res.sendStatus(200);
});

const RateLimiter = require('bottleneck');

const limiter = new RateLimiter({
  maxConcurrent: 5,
  minTime: 600, // 600ms between requests = 100/min
});

const rateLimitedFetch = limiter.wrap(fetch);

// Use rate-limited fetch
const response = await rateLimitedFetch(url, options);

{
  "items": [{ "offerId": "test-offer-id" }],
  "customerInfo": {
    "fullName": "Test Customer",
    "email": "test@example.com",
    "phone": "+1-555-000-0000"
  },
  "metadata": {
    "test": true
  }
}