This tutorial shows how to retrieve the racking bill of materials using Sync API.

How It Works

On design completion, a racking partner app embedded in Aurora posts racking line items to the bill of materials in Aurora and a file in PDF format with a human-readable bill of materials. You can retrieve both via Sync API.

Getting Started

To complete this tutorial, you will need:

your Aurora tenant to be on the Custom or Business plan,
your Aurora tenant to have a racking design app enabled,
your Aurora tenant to use the API version 2022.09 or higher,
your Aurora bearer token,
your Aurora tenant_id,
URL to deliver Aurora webhooks to.

You or any Administrator for your Aurora tenant can retrieve the token and tenant id from the API Settings page.

Step 1. Subscribe to asset_created webhook event.

Subscribe to asset_created webhook event with the “Racking Bill of Materials” filter, pointing webhooks to your application that will process them. See Webhooks for more details.

Step 2. When a racking partner app posts the bill of materials, Aurora will send you a webhook.

When an Aurora user completes the racking design in the embedded partner app, the app will upload a machine- and human-readable copies of the bill of materials. On human-readable bill of materials upload completion, Aurora will send you a webhook.

//Webhook query string payload
?design_id=2v52d42f-7b03-40f4-94be-e393ed8c5386&asset_id=3fa85f64-5717-4562-b3fc-2c963f66afa6

Step 3. Retrieve the machine-readable bill of materials.

On the webhook receipt, use design_id to retrieve the bill of materials JSON by using Retrieve Design Summary API. Note that racking items are listed with the component_type of racking_components.

//GET <https://api-sandbox.aurorasolar.com/tenants/{tenant_id}/designs/{design_id}/summary

//HTTP 200 response
{
  "design": {
    "bill_of_materials": [
      {
                "id": "7b95b2d5-61a1-4543-aed1-19f1c861190f",
                "component_type": "modules",
                "sku": null,
                "name": "DNA-144-MF26-430W",
                "manufacturer_name": "Aptos Solar Technology",
                "quantity": 27
            },
            {
                "id": null,
                "component_type": "racking_components",
                "sku": "ABC-123",
                "name": "Your Racking Manufacturer - Black 84\"",
                "manufacturer_name": "Your Racking Manufacturer",
                "quantity": 54
            },
            {
                "id": null,
                "component_type": "racking_components",
                "sku": "ZYZ-789",
                "name": "Your Racking Manufacturer - Bonded Structural Splice",
                "manufacturer_name": "Your Racking Manufacturer",
                "quantity": 34
            },
						...

Step 4. Retrieve the human-readable bill of materials.

On the webhook receipt, use asset_id to look up the url field using Retrieve Design Asset API. The field points to the URL where the human-readable bill of materials binary file (often in PDF format) is available.

//GET <https://api-sandbox.aurorasolar.com/tenants/{tenant_id}/assets/{asset_i}/

//HTTP 200 response
{
  "asset": {
    "url": "http://some-host.com/some-path/file2.png",
    "asset_type": "Racking Bill of Materials"
  }
}

Considerations

Note that the URL returned by Retrieve Design Assets API expires after 24 hours.
Consider using a webhook test site like https://webhook.site to verify that your webhook subscription is live.