DOCSEARCHbyAlgolia
Submit Docs

OpenSolar Developer Documentation

website·Indexed 34 days ago

https://developers.opensolar.com

Developer resources for the OpenSolar platform, including the Seller API for managing product sync, pricing tiers, and quotes; the OpenSolar SDK for integrating the platform into third-party applications via React; and core API endpoints for managing projects, organizations, private files, and webhooks.

Tokens
30.5K
Snippets
152
Records
215
Agent score
57%

What's inside OpenSolar

  1. Manage Quote and Quote Activity Log webhooks

    Suppliers can subscribe to real-time webhooks for Quote (CREATE, UPDATE, DELETE) and QuoteActivityLog (CREATE, DELETE). These webhooks are configured via a dedicated distributor endpoint. Unlike general webhooks, the scope is fixed to the entire model (quote.* or quoteactivitylog.*) and triggers when the supplier's organization is the supplier on the quote.

  2. Manage Contacts via OpenSolar API

    The OpenSolar API provides a set of endpoints to manage Contacts. A Contact stores personal details for an individual Customer and may optionally be attached to an OpenSolar User Login, which enables the Customer to log in to MyEnergy.

  3. Understand OpenSolar API organization routing

    In the OpenSolar API, most resource endpoints are scoped to a specific organization and are prefixed with the path /api/orgs/:org_id/..., where :org_id is the unique identifier of the organization.

  4. Understand the OpenSolar Webhook Event payload structure

    When a webhook event is triggered in OpenSolar, the payload contains metadata about the event (such as the model, event type, and timestamp) and a fields object containing the specific details of the project-related event.
    {
  "timestamp": "1605832669",
  "model": "Event",
  "model_id": 5,
  "identifier": "6ab6a60d-1a4d-4374-88af-92f7c02e3223",
  "event": "UPDATE",
  "event_id": 1,
  "fields": {
    "action": "/api/orgs/27/actions/1/",
    "archive_for": null,
    "completion_date": "2020-01-01T12:00:00.000000Z",
    "contact": "/api/orgs/15/contacts/6/",
    "created_date": "2020-01-02T12:00:00.000000Z",
    "duration": 0,
    "end": null,
    "event_type_id": 29,
    "id": 5,
    "is_archived": false,
    "is_complete": true,
    "location_override": "",
    "modified_date": "2020-01-01T12:00:00.000000Z",
    "notes": null,
    "org": "/api/orgs/15/",
    "project": "/api/orgs/15/projects/11/",
    "project_name": "Vandelay Industries",
    "repeat": 0,
    "start": null,
    "task_status": 0,
    "team_members": [],
    "title": "Design Systems",
    "url": "/api/orgs/15/events/5/",
    "user": "/auth/users/7/",
    "who": {
      "display": "george costanza",
      "email": "george@vanderlayindustries.com",
      "portrait_image_public_url": null
    }
  }
}

  5. Understand the OpenSolar Data Schema Hierarchy

    The OpenSolar data model is centered around Organizations (Orgs), which are split into Customer Data and Configuration data.

    Customer Data Hierarchy:

    • Orgs contain Projects and Contacts.
    • Projects act as a central hub for:
      • Systems: The technical solar designs.
      • Assigned Personnel: Contacts assigned as Team Members, Site Inspectors, or Installers (via Roles).
      • Tariffs: Links to Current and Proposed Utility Tariffs.
      • Events: Project-related activities.
      • Private Files: Documents specific to that project.

    Organization Configuration:

    • Orgs maintain global settings including API Keys, Pricing Schemes, Payment Options, Costings, and Design Settings (Setbacks).
    • Component Activations: Defines which Modules, Inverters, and Batteries from the Component Database (or custom entries) are active for the Org.
    • Administrative Assets: Document Templates, Lead Capture Forms, and Public Files.

  6. Understand the Project object structure in Proposal Data

    The Project object within the OpenSolar Proposal Data API contains comprehensive details about a specific solar project, including location, customer contacts, system sales status, and technical specifications. Key fields include:

    • Identification: id (Project ID), url (API URL), and identifier.
    • Location: address, zip, state, locality, country, county, country_iso2, lat, and lon.
    • Customer & Communication: contacts (array of contact objects), language, and assigned_team_member.
    • Sales & Proposal: proposal_template_id, proposal_data (the full proposal payload), valid_until_date, and available_customer_actions (actions like checkout or sign).
    • Energy & Utility: usage_annual_or_guess (kWh), usage_normalized (detailed breakdown), utility_tariff_current, utility_tariff_proposed, and their resolved versions (utility_tariff_current_or_guess, utility_tariff_proposed_or_guess).
    • Project Status: stage (workflow milestone), priority, contract_date, and project_sold.
    • Technical/Errors: calculation_error_messages and last_calculation_error.
    • Customization: custom_data (e.g., proposal_config_v2 for Proposal V2 templates).

  7. Understand OpenSolar API throttling types

    OpenSolar enforces two types of throttling to maintain performance and prevent misuse:

    • Throttling per User: Limits the number of requests a specific user can make to an endpoint.
    • Throttling per Org: Limits the total number of requests all users within a specific organization can make to an endpoint.

  9. Follow OpenSolar API URL and Request Conventions

    The OpenSolar API follows standard Django REST Framework conventions. A critical requirement is that trailing slashes (/) are enforced on all API methods, with the exception of GET requests.

  10. Manage private files using the Private Files API

    The Private Files API allows you to list, create, retrieve, update, and delete private files for an organization. Files can be scoped to a project and filtered by project, user, and file tags.

    Permissions: The authenticated user must be a 'Pro' for the same organization. Throttling: 1000 requests per day per organization for both read and write operations.

    Endpoints

    MethodEndpointDescription
    GET/api/orgs/:org_id/private_files/List private files
    GET/api/orgs/:org_id/private_files/:file_id/Retrieve a private file
    POST/api/orgs/:org_id/private_files/Create a private file
    PATCH/api/orgs/:org_id/private_files/:file_id/Update a private file
    DELETE/api/orgs/:org_id/private_files/:file_id/Delete a private file

  11. Understand OpenSolar API Access plan pricing and limits

    Organizations with an enabled API Access plan are charged per project created. This plan includes unlimited API calls and webhook events. Throttle limits still apply. If the wallet balance is low or empty, API access continues to function, but the creation of new projects is blocked. To prevent this, users should enable auto top-up in their wallet.

  12. Quote webhook payload field reference

    The Quote webhook payload contains detailed information about a supplier quote. The primary data is contained within the fields object.
    {
  "id": "integer (Quote ID)",
  "address": "string (Delivery address)",
  "zip": "string (Postal / ZIP code)",
  "state": "string (State or region)",
  "locality": "string (City or suburb)",
  "county": "string | null (County)",
  "country": "string (ISO 3166-1 alpha-2 country code, e.g., AU, US)",
  "created_date": "datetime",
  "modified_date": "datetime",
  "status": "string (e.g., under_review, awaiting_order, ordered)",
  "quote_valid_until": "date | null",
  "estimated_delivery_date": "date | null",
  "notes": "string",
  "org_name": "string (Organization owning the quote)",
  "supplier_name": "string (Supplier organization)",
  "project_id": "integer | null",
  "pro_contact": "object | null (Contact details of the pro user)",
  "account_manager_data": "array (Assigned account managers)",
  "data": "object (Line items keyed by index. Contains: code, componentType, quantity, source, price, product_name, and optionally price_per_watt)",
  "custom_data": "object | null",
  "cost_summary": "object (Contains: subtotal, discount, shipping, tax, total)",
  "files": "array (Attached files with file_name and file_url)"
}