Tukang.com: SteelSolution Partner API (1.0.0)

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, at any depth. Send only the fields each endpoint declares.

Each field is validated against the type, format and any range shown in its schema below.

preferred_slot on the match endpoint and job_time on the create endpoint are both validated against the same rule. A time is accepted when all of these hold:

• at least 3 hours from now, because the vendor has to prepare and travel;
• between 08:00 and 22:00 Jakarta time inclusive, so 22:00 is a valid start and 22:01 is not;
• no more than 14 days ahead.

The first two combine rather than applying separately. The earliest bookable time is whichever is later, three hours from now or the next time the window opens. A customer ordering at 19:01 cannot book at all that day, because three hours later is 22:01, past the window; the earliest is 08:00 the next morning.

Both endpoints apply this, so an unusable time is refused at /match rather than after the customer has chosen a vendor and paid. A rejected time returns 400 VALIDATION_ERROR with a message saying which of the three rules was broken.

Every date-time must carry an explicit UTC offset, for example 2026-09-10T09:00:00+07:00, or Z. A value without one is rejected with 400 VALIDATION_ERROR.

2026-09-10T09:00:00 has no offset. We would read it as UTC, which is 16:00 in Jakarta. The booking would then be checked against the wrong time, and the vendor would arrive seven hours late.

Times we send back always carry +07:00.

Request bodies must be smaller than 8 KB. Normal requests are much smaller than this.

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.

The webhook and this API use the same words, so a push and a status check made at the same moment agree.

What each one means:

• scheduled - created, vendor assigned, work not started.

• in_progress - the vendor has started the site visit, or the project is running, or it is in its retention period.

• visit_complete - the vendor finished the job during the site visit and no cost estimate follows. Final state for those jobs.

• estimate_ready - the cost estimate has been sent and is waiting on the customer's decision.

• retention_started - every RAB line item is complete, before final sign-off.

• install_complete - the job is finished.

• closed - the customer rejected the cost estimate. The visit itself completed; the work did not proceed.

There is no push for scheduled, because nothing has happened yet, or for closed, because you sent us that decision yourself.

One limitation worth designing around. On jobs that need a cost estimate, our records do not distinguish a finished site visit from one still under way until the estimate is sent. So between the visit_complete push and the estimate_ready push, a status check answers in_progress. Treat the push as the reliable signal for that window. A status check does return visit_complete for jobs the vendor completes during the visit, where no estimate follows and it is the final state.

Each value's meaning is listed with the status field on the endpoints below.

Tukang.com calls a single webhook on SteelSolution's CMS whenever a site visit's status changes.

The payload carries the site visit id and the webhook status at the top level, then the full record under site_visit. That record is the same shape as the GET /site-visits/{id} response below, with fields that do not apply to the current status set to null.

{
  "site_visit_id": "7501130001",
  "status": "estimate_ready",
  "site_visit": {
    "site_visit_id": "7501130001",
    "status": "estimate_ready",
    "vendor": { "id": "VND0001122", "name": "Budi Konstruksi" },
    "job_time": "2026-07-10T09:00:00+07:00",
    "rab": { }
  }
}

The status at the top level and the one inside site_visit carry the same value, because both directions use one set of words. The single exception is the visit_complete push on a job that needs a cost estimate: the record reads in_progress there, for the reason given under "Status values" above. On a job the vendor completes during the visit, both read visit_complete.

Because the whole record travels with the push, you do not need to call GET /site-visits/{id} after receiving one. That endpoint stays available for reconciliation and for checking an order at any time.

Webhook 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 the sku from your product catalogue), 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. This fires before install_complete below, not at the same time.

• install_complete - installation work is fully finished.

Failed outbound pushes are retried automatically with backoff, so your receiver must be idempotent. If you miss a push, the status check endpoint below can be called at any time and returns the current state.