Tukang.com: SteelSolution Partner API (1.0.0-draft)

Every request needs X-API-Key and X-Signature headers - see the Authorization panel on each endpoint below for how to compute X-Signature.

Every error looks like this: { "message": "Vendor not found", "error_code": "VENDOR_NOT_FOUND" } Clients should branch on error_code. The message field is intended for human readers and its wording may change. Each endpoint documents the codes it returns. Two additional codes may be returned by any endpoint: NOT_FOUND (404) when the path or method does not exist, and PAYLOAD_TOO_LARGE (413) when the request body exceeds the size limit below. Note that a request body which is not valid JSON returns 400 VALIDATION_ERROR even when credentials are absent or incorrect. The body is parsed before credentials are verified. A 400 where a 401 was expected therefore indicates a malformed body.

Requests are validated strictly. A field that is not listed in the schema is rejected with 400 VALIDATION_ERROR rather than ignored, and every string and numeric field has a documented length or range. Send only the fields each endpoint declares. This applies to nested objects as well as the top level.

Request bodies must be smaller than 8 KB. Normal requests are considerably smaller, so this limit is unlikely to be reached in regular use. Requests exceeding it are rejected by a web application firewall before they reach this API. The firewall responds with 403 and an HTML body rather than the JSON error format above, and no record of the request is retained on our side. The firewall may also reject requests for other reasons, such as an unrecognised User-Agent. An HTML response therefore indicates a firewall rejection rather than an API error. Please report the source IP address so that it can be added to the allow list.

Tukang.com calls a single webhook on SteelSolution's CMS whenever a site visit's status changes. Every call carries a status value plus the same record shape as the GET /site-visits/{id} response below - fields not relevant to the current status are null. Status values, in the order they can occur:

• in_progress - vendor has started the site visit.

• visit_complete - the site visit itself has ended. rab is not yet populated at this point, whether or not this job will need one.

• estimate_ready - fires separately, later: can be hours to days after visit_complete, not the same call. rab is now populated, including a materials list (each item carrying a Magento-recognizable internal_id), a total service amount, and a RAB PDF URL. Only fires for jobs that need an estimate; jobs that do not require one stop after visit_complete.

• retention_started - every RAB line item has been marked complete by the vendor, before final install sign-off. A distinct, earlier signal from install_complete below, not the same moment.

• install_complete - installation work is fully finished.

Failed outbound pushes are retried automatically with backoff, so your receiver must be idempotent. If you ever see a gap, the job status check endpoint below is callable anytime and reflects current state.