AlugSol (2.0)

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.

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.

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
• SCHEDULED and RESCHEDULED
  • installation_scheduled_date
  • installation_scheduled_shift (optional)
• INSTALLATION
  • installation_start_date
• INSTALLATION_COMPLETED
  • installation_end_date
• INSTALLATION_RESCHEDULED
  • installation_scheduled_date
  • installation_scheduled_shift (optional)
• 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, ELECTRICAL_INFRASTRUCTURE_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

Five rules that are easy to miss:

1. status_change_reasons sent with a status that does not allow it is a 400 - it is not silently ignored.
2. 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.
3. 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.
4. Scheduling the installation is gated by the contract's current status, the same way the AlugSol Backoffice is. SCHEDULED is accepted only while the contract sits on CARRIER_DELIVERY_DATE; RESCHEDULED only while it sits on SCHEDULING_CANCELED, SCHEDULED, RESCHEDULED or INSTALLATION_RESCHEDULED. Anything else is a 409 and nothing is written. Both also refuse an installation_scheduled_date whose day, in São Paulo time, is already past (400). INSTALLATION_RESCHEDULED keeps working from any status, as before.
5. A lost contract, or one being terminated, accepts no report. Once AlugSol marks a contract as lost (CLOSED_LOST) or opens a friendly termination for it (TERMINATION_IN_PROGRESS), every PATCH is a 409 DEAL_PHASE_LOCKED, whatever the status and even for a replay. Nothing is written. The check runs after the contract is found and the body schema is validated, before the conditional rules above. AlugSol is notified of each attempt, so do not retry: contact AlugSol.

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. This holds for SCHEDULED too: the same date and shift again is a no-op, while a different date or shift on an already scheduled contract must come as RESCHEDULED.
• SCHEDULED and RESCHEDULED e-mail the client the same installation-scheduled confirmation the AlugSol flows send. Nothing is sent back to the partner.

Updates contract status at the scheduling/installation stage

Retrieve a contract's data by id