AlugSol (2.0)

Download OpenAPI specification:

AlugSol exposes the engineering side of a solar rental contract. The partner responsible for logistics, installation and inspection reads the contracts assigned to it and reports progress back.

Versions

Two versions are documented here. v2 (Engineering) is the current API. v1 (Contract) is the legacy n8n webhook, kept for reference while partners migrate - it reports the same statuses on a different host with a different key.

Authentication

Every v2 request carries an x-api-key header holding a key issued in the AlugSol Backoffice, always prefixed alug_v2_. Keys are per partner. The legacy v1 secret is rejected with 401.

Conventions

Every date, in requests and in responses, is ISO 8601 in UTC with the Z suffix (2025-02-10T20:34:23.777Z). A local or offset timestamp is a 400.
A contract is addressed by contract_id, the token AlugSol issued for the deal - the same value the validation payload delivers in its code field.
Every v2 error answers the same envelope. Branch on name, the machine-readable tag; resolution says what to do about it.

Engineering

Engineering and installation partner integration. Replaces the deprecated Contract operations. contract_id is always the contract token AlugSol issued for the deal - the same value the validation payload delivers in its code field.

List the contracts held by engineering

Paginated list of the contracts currently in an engineering phase. Use updated_since for incremental pulls - it filters on the updated_at field of the response objects.

Authorizations:

ApiKeyV2

query Parameters

current_page	integer Default: 1 1-based page number
items_quantity_per_page	integer Default: 50 Page size
updated_since	string <date-time> Example: updated_since=2025-02-10T20:34:23.777Z Return only contracts whose `updated_at` is newer than this ISO date. A value that cannot be parsed is a 400 (`INVALID_UPDATED_SINCE`).
phase_status	Array of strings (EngineeringPhaseStatus) Items Enum: "CONTRACT_ANALYSIS" "CONTRACT_APPROVED" "CONTRACT_CANCELED" "CONTRACT_REJECTED" "CONTRACT_REJECTED_DOCUMENTATION" "CONTRACT_REJECTED_STRUCTURAL_DOCUMENTS" "HOMOLOG_APPROVED" "HOMOLOG_REJECTED" "CARRIER_DISPATCH_DATE" "CARRIER_SCHEDULING_DATE" "CARRIER_DELIVERY_DATE" "SCHEDULED" "RESCHEDULED" "SCHEDULING_CANCELED" "INSTALLATION" "INSTALLATION_COMPLETED" "INSTALLATION_RESCHEDULED" "INSTALLATION_CANCELED" "INSPECTION" "INSPECTION_COMPLETED" Example: phase_status=INSPECTION Restrict the list to these statuses. Repeat the parameter (`?phase_status=A&phase_status=B`) or send it comma-separated (`?phase_status=A,B`) - both forms are accepted. Defaults to all 20 engineering statuses. A value outside that set is a 400 (`INVALID_PHASE_STATUS`).

Responses

Response samples

Content type

application/json

{"data": [{"id": "623b3b46f59591002100e37b",
"status": "INSPECTION",
"name": "Sunne test",
"carrier_dispatch_date": "2025-02-10T20:34:23.777Z",
"carrier_expected_delivery_date": "2025-02-10T20:34:23.777Z",
"carrier_scheduling_date": "2025-02-10T20:34:23.777Z",
"carrier_delivery_date": "2025-02-10T20:34:23.777Z",
"installation_scheduled_date": "2025-02-10T20:34:23.777Z",
"installation_start_date": "2025-02-10T20:34:23.777Z",
"installation_end_date": "2025-02-10T20:34:23.777Z",
"carrier_name": "Sunne logistics",
"carrier_order_number": "536577",
"carrier_receipt_number": "43766876",
"meter_replacement_date": "2025-02-10T20:34:23.777Z",
"power_plant_connection_date": "2025-02-10T20:34:23.777Z",
"last_status_change_at": "2025-02-10T20:34:23.777Z",
"updated_at": "2025-02-10T20:34:23.777Z",
"documents": [{"type": "ENERGY_BILL",
"url": "https://sunnesaas.s3.us-east-2.amazonaws.com/assets_saas/logo.png",
"description": "Conta de energia"
}
],
"status_history": [{"id": "65464653y658778",
"previous_status": "INSPECTION",
"new_status": "INSPECTION",
"status_change_reasons": ["PHOTOS_REJECTED"
],
"status_change_comment": "Telhado com problemas na estrutura",
"created_at": "2025-02-10T20:34:23.777Z"
}
]
}
],
"total_items": 137
}

Retrieve one contract

One contract by its contract_id. The response object is the same as an item of the list endpoint. Unlike the list, this lookup is not filtered by phase - a contract that has left the engineering phases is still returned here.

Authorizations:

ApiKeyV2

path Parameters

contract_id

required

string

Example: 623b3b46f59591002100e37b

The contract token AlugSol issued

Responses

Response samples

Content type

application/json

{"data": {"id": "623b3b46f59591002100e37b",
"status": "INSPECTION",
"name": "Sunne test",
"carrier_dispatch_date": "2025-02-10T20:34:23.777Z",
"carrier_expected_delivery_date": "2025-02-10T20:34:23.777Z",
"carrier_scheduling_date": "2025-02-10T20:34:23.777Z",
"carrier_delivery_date": "2025-02-10T20:34:23.777Z",
"installation_scheduled_date": "2025-02-10T20:34:23.777Z",
"installation_start_date": "2025-02-10T20:34:23.777Z",
"installation_end_date": "2025-02-10T20:34:23.777Z",
"carrier_name": "Sunne logistics",
"carrier_order_number": "536577",
"carrier_receipt_number": "43766876",
"meter_replacement_date": "2025-02-10T20:34:23.777Z",
"power_plant_connection_date": "2025-02-10T20:34:23.777Z",
"last_status_change_at": "2025-02-10T20:34:23.777Z",
"updated_at": "2025-02-10T20:34:23.777Z",
"documents": [{"type": "ENERGY_BILL",
"url": "https://sunnesaas.s3.us-east-2.amazonaws.com/assets_saas/logo.png",
"description": "Conta de energia"
}
],
"status_history": [{"id": "65464653y658778",
"previous_status": "INSPECTION",
"new_status": "INSPECTION",
"status_change_reasons": ["PHOTOS_REJECTED"
],
"status_change_comment": "Telhado com problemas na estrutura",
"created_at": "2025-02-10T20:34:23.777Z"
}
]
}
}

Report a contract status

Report the progress of a contract. Replaces POST /contract/updateStatus.

Only status is always required. What else the body must carry depends on it:

CARRIER_DISPATCH_DATE
- carrier_dispatch_date
- carrier_expected_delivery_date
- carrier_name
- carrier_order_number
- carrier_receipt_number
CARRIER_SCHEDULING_DATE
- carrier_scheduling_date
CARRIER_DELIVERY_DATE
- carrier_delivery_date
INSTALLATION
- installation_start_date
INSTALLATION_COMPLETED
- installation_end_date
INSTALLATION_RESCHEDULED
- installation_scheduled_date
INSPECTION_COMPLETED
- power_plant_connection_date
SCHEDULING_CANCELED and INSTALLATION_CANCELED
- observation
CONTRACT_REJECTED
- status_change_reasons or observation
- allowed reasons: DOCUMENTATION_REJECTED, PHOTOS_REJECTED
CONTRACT_CANCELED
- status_change_reasons or observation
- allowed reasons: INSTALLATION_AREA_INSUFFICIENT, INSTALLATION_AFFECTED_BY_SHADING, DOCUMENTATION_REJECTED
Any other status
- nothing beyond status

Three rules that are easy to miss:

status_change_reasons sent with a status that does not allow it is a 400 - it is not silently ignored.
Every date field must be ISO 8601 in UTC with the Z suffix (2025-02-10T20:34:23.777Z). A local or offset timestamp is a 400.
Length limits, each a 400 when exceeded: observation.description 4096; observation.attachments[].url and .description 256; carrier_name 256; carrier_order_number and carrier_receipt_number 64.

Two behaviours the response cannot show you:

The resulting phase_status may differ from the status you reported. INSTALLATION_COMPLETED auto-advances the contract to INSPECTION, and CONTRACT_REJECTED resolves to CONTRACT_REJECTED_DOCUMENTATION or CONTRACT_REJECTED_STRUCTURAL_DOCUMENTS depending on the reason. The response tells you where the contract actually landed.
Re-sending an identical report is safe. It answers 200 with the same payload and writes nothing. The body carries no event id, so this is how retries are absorbed.

Authorizations:

ApiKeyV2

path Parameters

contract_id

required

string

Example: 623b3b46f59591002100e37b

The contract token AlugSol issued

Request Body schema: application/json

status required	string Enum: "CONTRACT_ANALYSIS" "CONTRACT_APPROVED" "CONTRACT_REJECTED" "CONTRACT_CANCELED" "HOMOLOG_APPROVED" "HOMOLOG_REJECTED" "CARRIER_DISPATCH_DATE" "CARRIER_SCHEDULING_DATE" "CARRIER_DELIVERY_DATE" "SCHEDULED" "RESCHEDULED" "SCHEDULING_CANCELED" "INSTALLATION" "INSTALLATION_RESCHEDULED" "INSTALLATION_CANCELED" "INSTALLATION_COMPLETED" "INSPECTION_COMPLETED" The status being reported. It is the only always-required field; which other fields are required depends on this value - see the operation description.
status_change_reasons	Array of strings (EngineeringStatusChangeReason) Items Enum: "DOCUMENTATION_REJECTED" "PHOTOS_REJECTED" "INSTALLATION_AREA_INSUFFICIENT" "INSTALLATION_AFFECTED_BY_SHADING" Required with `CONTRACT_REJECTED` or `CONTRACT_CANCELED` unless `observation` is provided. Sending it with any other status is a 400.
carrier_dispatch_date	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z... Required when status is `CARRIER_DISPATCH_DATE`. ISO 8601 in UTC.
carrier_expected_delivery_date	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z... Required when status is `CARRIER_DISPATCH_DATE`. ISO 8601 in UTC.
carrier_scheduling_date	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z... Required when status is `CARRIER_SCHEDULING_DATE`. ISO 8601 in UTC.
carrier_delivery_date	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z... Required when status is `CARRIER_DELIVERY_DATE`. ISO 8601 in UTC.
carrier_name	string <= 256 characters Required when status is `CARRIER_DISPATCH_DATE`.
carrier_order_number	string <= 64 characters Required when status is `CARRIER_DISPATCH_DATE`.
carrier_receipt_number	string <= 64 characters Required when status is `CARRIER_DISPATCH_DATE`.
installation_start_date	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z... Required when status is `INSTALLATION`. ISO 8601 in UTC.
installation_end_date	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z... Required when status is `INSTALLATION_COMPLETED`. ISO 8601 in UTC.
installation_scheduled_date	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z... Required when status is `INSTALLATION_RESCHEDULED`. ISO 8601 in UTC.
power_plant_connection_date	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z... Required when status is `INSPECTION_COMPLETED`. ISO 8601 in UTC.
	object (Observation)

Responses

Request samples

Payload

Content type

application/json

{"status": "INSTALLATION_COMPLETED",
"status_change_reasons": ["PHOTOS_REJECTED"
],
"carrier_dispatch_date": "2025-02-10T20:34:23.777Z",
"carrier_expected_delivery_date": "2025-02-10T20:34:23.777Z",
"carrier_scheduling_date": "2025-02-10T20:34:23.777Z",
"carrier_delivery_date": "2025-02-10T20:34:23.777Z",
"carrier_name": "Sunne transportes",
"carrier_order_number": "536577",
"carrier_receipt_number": "43766876",
"installation_start_date": "2025-02-10T20:34:23.777Z",
"installation_end_date": "2025-02-10T20:34:23.777Z",
"installation_scheduled_date": "2025-02-10T20:34:23.777Z",
"power_plant_connection_date": "2025-02-10T20:34:23.777Z",
"observation": {"description": "Telhado com problemas na estrutura",
"attachments": [{"mediaType": "image/png",
"url": "https://sunnesaas.s3.us-east-2.amazonaws.com/assets_saas/logo.png",
"description": "Foto da estrutura"
}
]
}
}

Response samples

Content type

application/json

{"data": {"deal_id": "41",
"phase_status": "INSPECTION"
}
}

Contract

Legacy n8n webhook API. Superseded by the Engineering routes, which report the same statuses on a different host with a different key. Kept for reference while the migration runs.

Updates the contract's status Deprecated

Updates contract status at the scheduling/installation stage

header Parameters

s-api-key

required

string

RMTP Access token

Request Body schema: application/json

contractId required	string Contract ID
status required	string Enum: "CONTRACT_ANALYSIS" "CONTRACT_APPROVED" "CONTRACT_CANCELED" "CONTRACT_REJECTED" "HOMOLOG_APPROVED" "HOMOLOG_REJECTED" "CARRIER_DISPATCH_DATE" "CARRIER_SCHEDULING_DATE" "CARRIER_DELIVERY_DATE" "SCHEDULED" "RESCHEDULED" "SCHEDULING_CANCELED" "INSTALLATION" "INSTALLATION_RESCHEDULED" "INSTALLATION_CANCELED" "INSTALLATION_COMPLETED" "INSPECTION_COMPLETED" Provides the status of the contract. Only items on the list are accepted.
status_change_reasons	Array of strings Items Enum: "INSTALLATION_AREA_INSUFFICIENT" "INSTALLATION_AFFECTED_BY_SHADING" "DOCUMENTATION_REJECTED" "PHOTOS_REJECTED" Reasons for the status change. Required with `CONTRACT_REJECTED` or `CONTRACT_CANCELED` when no `observation` is provided.
carrier_dispatch_date	string <date-time> Order dispatch date, ISO 8601 in UTC. Required only when status is `CARRIER_DISPATCH_DATE`.
carrier_expected_delivery_date	string <date-time> Estimated delivery date, ISO 8601 in UTC. Required only when status is `CARRIER_DISPATCH_DATE`.
carrier_scheduling_date	string <date-time> Appointment date, ISO 8601 in UTC. Required only when status is `CARRIER_SCHEDULING_DATE`.
carrier_delivery_date	string <date-time> Material delivery date, ISO 8601 in UTC. Required only when status is `CARRIER_DELIVERY_DATE`.
carrier_name	string Name of the carrier company. Required only when status is `CARRIER_DISPATCH_DATE`.
carrier_order_number	string Code of the order on the carrier system. Required only when status is `CARRIER_DISPATCH_DATE`.
carrier_receipt_number	string Number of the order receipt on the carrier system. Required only when status is `CARRIER_DISPATCH_DATE`.
installation_start_date	string <date-time> Installation start date, ISO 8601 in UTC. Required only when status is `INSTALLATION`.
installation_end_date	string <date-time> Installation end date, ISO 8601 in UTC. Required only when status is `INSTALLATION_COMPLETED`.
power_plant_connection_date	string <date-time> Power plant connection date, ISO 8601 in UTC. Required only when status is `INSPECTION_COMPLETED`.
installation_scheduled_date	string <date-time> New installation date, ISO 8601 in UTC. Required only when status is `INSTALLATION_RESCHEDULED`.
	object (Observation)

Responses

Request samples

Payload

Content type

application/json

{"contractId": "623b3b46f59591002100e37b",
"status": "CARRIER_DISPATCH_DATE",
"status_change_reasons": ["INSTALLATION_AREA_INSUFFICIENT",
"DOCUMENTATION_REJECTED"
],
"carrier_dispatch_date": "2025-02-10T20:34:23.777Z",
"carrier_expected_delivery_date": "2025-02-10T20:34:23.777Z",
"carrier_scheduling_date": "2025-02-10T20:34:23.777Z",
"carrier_delivery_date": "2025-02-10T20:34:23.777Z",
"carrier_name": "Sunne transportes",
"carrier_order_number": "536577",
"carrier_receipt_number": "43766876",
"installation_start_date": "2025-02-10T20:34:23.777Z",
"installation_end_date": "2025-02-10T20:34:23.777Z",
"power_plant_connection_date": "2025-02-10T20:34:23.777Z",
"installation_scheduled_date": "2025-02-10T20:34:23.777Z",
"observation": {"description": "Telhado com problemas na estrutura",
"attachments": [{"mediaType": "image/png",
"url": "https://sunnesaas.s3.us-east-2.amazonaws.com/assets_saas/logo.png",
"description": "Foto da estrutura"
}
]
}
}

Response samples

Content type

application/json

{"id": "623b3b46f59591002100e37b",
"status": "CARRIER_DISPATCH_DATE",
"updated_at": "2025-02-10T20:34:23.777Z"
}

Retrieve a contract by id Deprecated

Retrieve a contract's data by id

header Parameters

s-api-key

required

string

RMTP Access token

Request Body schema: application/json

contractId

required

string

Contract ID

Responses

Request samples

Payload

Content type

application/json

{"contractId": "623b3b46f59591002100e37b"
}

Response samples

Content type

application/json

{"id": "623b3b46f59591002100e37b",
"status": "CARRIER_DISPATCH_DATE",
"name": "Sunne test",
"carrier_dispatch_date": "2025-02-10T20:34:23.777Z",
"carrier_expected_delivery_date": "2025-02-10T20:34:23.777Z",
"carrier_scheduling_date": "2025-02-10T20:34:23.777Z",
"carrier_delivery_date": "2025-02-10T20:34:23.777Z",
"installation_scheduled_date": "2025-02-10T20:34:23.777Z",
"carrier_order_number": "56765634",
"carrier_receipt_number": "56765634",
"installation_start_date": "2025-02-10T20:34:23.777Z",
"installation_end_date": "2025-02-10T20:34:23.777Z",
"meter_replacement_date": "2025-02-10T20:34:23.777Z",
"power_plant_connection_date": "2025-02-10T20:34:23.777Z",
"carrier_name": "Sunne logistics",
"status_history": [{"id": "65464653y658778",
"previous_status": "CARRIER_DISPATCH_DATE",
"new_status": "CARRIER_SCHEDULING_DATE",
"status_change_reasons": ["INSTALLATION_AREA_INSUFFICIENT"
],
"status_change_comment": "Contract rejected because of insufficient area",
"created_at": "2025-02-10T20:34:23.777Z"
}
]
}