PT EN

Primeiros passos

URL base: $BUSINESS_API

O objecto

journey_idstring · obrigatório

um de platform_setup, utility_test, utility_real, resident_link, resident_connection, staff_field_reader, staff_cashier, staff_finance

subjectobject · obrigatório

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
tenant_idstring · obrigatório · anulável

The utility for utility and staff journeys; null for the platform journey

updated_atstring (date-time) · obrigatório
stepsarray of FirstRunStep · obrigatório
Mostrar atributos filhos
idstring · obrigatório
statestring · obrigatório

um de todo, done, skipped, blocked

can_skipboolean · obrigatório
allowed_skip_reasonsarray of string · obrigatório
reasonstring · opcional

Skip reason code

changed_atstring (date-time) · opcional
changed_byobject · opcional

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
completion_sourcestring · opcional

The qualifying domain action that completed the step

completed_atstring (date-time) · opcional
responsibilitystring · opcional

Who does the step on a checklist the platform sets up on a utility's behalf

um de platform, utility

completed_byobject · opcional

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
run_tokenstring · opcional

Opaque funnel run token; absent once the journey is complete

O objecto
{
  "journey_id": "platform_setup",
  "subject": {
    "type": "utility_staff",
    "id": "usr_01"
  },
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "updated_at": "2026-11-19T09:30:00Z",
  "steps": [
    {
      "id": "customer_import",
      "state": "todo",
      "can_skip": true,
      "allowed_skip_reasons": [
        "not_needed"
      ],
      "reason": "Leitura confirmada no local.",
      "changed_at": "2026-11-19T09:30:00Z",
      "changed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      },
      "completion_source": "service_area.created",
      "completed_at": "2026-11-19T09:30:00Z",
      "responsibility": "platform",
      "completed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      }
    }
  ],
  "run_token": "run token"
}

Verificar a ligação de pagamentos

Registos

POST /first-run/payment-check

A payment connection check: asks the utility's payment connectors, through the payment service, which payment methods are operational right now, and succeeds when at least one connector method is. Nothing is charged. Success in the real account (not the test account) completes the utility_real connect_payments step. Codes: payments_inactive, no_payment_connector, connector_unavailable. Requires business:onboarding:write and a role that may read the utility's payment methods.

Devolve

200 The check outcome

Mostrar atributos
outcomestring · obrigatório

um de succeeded, failed

codestring · opcional

um de payments_inactive, no_payment_connector, connector_unavailable

checked_atstring (date-time) · obrigatório
retryableboolean · obrigatório
connectorsarray of string · opcional

Names of the connectors with an operational method

Erros 401 · 403

curl -X POST "$BUSINESS_API/first-run/payment-check" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "outcome": "succeeded",
  "code": "payments_inactive",
  "checked_at": "2026-11-19T09:30:00Z",
  "retryable": true,
  "connectors": [
    "connector"
  ]
}

Obter o progresso de um percurso inicial

Registos

GET /first-run/progress

Returns the durable progress of the signed-in utility user and their tenant for one journey (utility_test, utility_real, staff_field_reader, staff_cashier, staff_finance): every step by stable ID in server order, its state (todo, done, skipped or blocked with a reason), whether and why it can be skipped, who changed it and when, and the qualifying action that completed it. A journey with no record returns its steps as todo. The response also carries an opaque run token the client sends back in the X-First-Run-Token header so funnel events join without storing who ran them. Requires business:onboarding:read for the utility journeys. A staff member reads only their own role journey with the entitlement of their own first-run action: business:reading-assignments:read for staff_field_reader, and business:onboarding:read or cashier:write (staff_cashier) or billing_runs:read (staff_finance); no subject or tenant selector is accepted. From a test (sandbox) account, utility_test is the owning real account's tour (the record the tour's actions credit, also for skips and resumes) and utility_real answers 404.

Parâmetros

journeystring · consulta · obrigatório

Journey ID

um de utility_test, utility_real, staff_field_reader, staff_cashier, staff_finance

X-First-Run-Tokenstring · cabeçalho · opcional

Opaque run token from an earlier progress or next-steps response. It joins this request's first-use events to one run and carries no identity.

Devolve

200 Journey progress

Mostrar atributos
journey_idstring · obrigatório

um de platform_setup, utility_test, utility_real, resident_link, resident_connection, staff_field_reader, staff_cashier, staff_finance

subjectobject · obrigatório

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
tenant_idstring · obrigatório · anulável

The utility for utility and staff journeys; null for the platform journey

updated_atstring (date-time) · obrigatório
stepsarray of FirstRunStep · obrigatório
Mostrar atributos filhos
idstring · obrigatório
statestring · obrigatório

um de todo, done, skipped, blocked

can_skipboolean · obrigatório
allowed_skip_reasonsarray of string · obrigatório
reasonstring · opcional

Skip reason code

changed_atstring (date-time) · opcional
changed_byobject · opcional

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
completion_sourcestring · opcional

The qualifying domain action that completed the step

completed_atstring (date-time) · opcional
responsibilitystring · opcional

Who does the step on a checklist the platform sets up on a utility's behalf

um de platform, utility

completed_byobject · opcional

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
run_tokenstring · opcional

Opaque funnel run token; absent once the journey is complete

Erros 401 · 403 · 404

curl -X GET "$BUSINESS_API/first-run/progress" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "journey_id": "platform_setup",
  "subject": {
    "type": "utility_staff",
    "id": "usr_01"
  },
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "updated_at": "2026-11-19T09:30:00Z",
  "steps": [
    {
      "id": "customer_import",
      "state": "todo",
      "can_skip": true,
      "allowed_skip_reasons": [
        "not_needed"
      ],
      "reason": "Leitura confirmada no local.",
      "changed_at": "2026-11-19T09:30:00Z",
      "changed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      },
      "completion_source": "service_area.created",
      "completed_at": "2026-11-19T09:30:00Z",
      "responsibility": "platform",
      "completed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      }
    }
  ],
  "run_token": "run token"
}

Saltar ou retomar um passo inicial

Registos

PATCH /first-run/progress/{journey}/{step}

Records an explicit skip (state skipped with a reason_code from the step's allowed_skip_reasons) or resumes a skipped step (state todo). A client can never write done or blocked: domain actions complete steps and prerequisites block them. A done step cannot be reopened (409). Security, identity and legal steps and the moment-of-value steps have no skip reasons. Requires business:onboarding:write. Staff journeys are completed only by their actions and cannot be patched (403).

Parâmetros

journeystring · caminho · obrigatório

Journey ID

stepstring · caminho · obrigatório

Step ID

X-First-Run-Tokenstring · cabeçalho · opcional

Opaque run token from an earlier progress or next-steps response. It joins this request's first-use events to one run and carries no identity.

Corpo application/json

statestring · obrigatório

um de skipped, todo

reason_codestring · opcional

Required for skipped; one of the step's allowed_skip_reasons

Devolve

200 Updated journey progress

Mostrar atributos
journey_idstring · obrigatório

um de platform_setup, utility_test, utility_real, resident_link, resident_connection, staff_field_reader, staff_cashier, staff_finance

subjectobject · obrigatório

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
tenant_idstring · obrigatório · anulável

The utility for utility and staff journeys; null for the platform journey

updated_atstring (date-time) · obrigatório
stepsarray of FirstRunStep · obrigatório
Mostrar atributos filhos
idstring · obrigatório
statestring · obrigatório

um de todo, done, skipped, blocked

can_skipboolean · obrigatório
allowed_skip_reasonsarray of string · obrigatório
reasonstring · opcional

Skip reason code

changed_atstring (date-time) · opcional
changed_byobject · opcional

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
completion_sourcestring · opcional

The qualifying domain action that completed the step

completed_atstring (date-time) · opcional
responsibilitystring · opcional

Who does the step on a checklist the platform sets up on a utility's behalf

um de platform, utility

completed_byobject · opcional

Who changed a step, by actor type and stable user ID

Mostrar atributos filhos
typestring · obrigatório
idstring · obrigatório
run_tokenstring · opcional

Opaque funnel run token; absent once the journey is complete

Erros 400 · 401 · 403 · 404 · 409

curl -X PATCH "$BUSINESS_API/first-run/progress/{journey}/{step}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "state": "skipped",
  "reason_code": "later"
}'
Resposta 200
{
  "journey_id": "platform_setup",
  "subject": {
    "type": "utility_staff",
    "id": "usr_01"
  },
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "updated_at": "2026-11-19T09:30:00Z",
  "steps": [
    {
      "id": "customer_import",
      "state": "todo",
      "can_skip": true,
      "allowed_skip_reasons": [
        "not_needed"
      ],
      "reason": "Leitura confirmada no local.",
      "changed_at": "2026-11-19T09:30:00Z",
      "changed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      },
      "completion_source": "service_area.created",
      "completed_at": "2026-11-19T09:30:00Z",
      "responsibility": "platform",
      "completed_by": {
        "type": "utility_staff",
        "id": "usr_01"
      }
    }
  ],
  "run_token": "run token"
}

Registar a saída de um percurso inicial

Registos

POST /first-run/abandon

Records that the user explicitly exited or cancelled the journey at the given step. It is sent only after an explicit exit; closing a tab, losing the network or inactivity are never recorded. The body carries only the opaque run token and the stable step ID: no reason text or identity. Repeats are idempotent. Utility journeys require business:onboarding:write. Staff journeys require only a valid run token issued to the same principal for their role journey plus the entitlement of their own role action; this records the exit and grants no other onboarding access.

Corpo application/json

run_tokenstring · obrigatório

Opaque run token

step_idstring · obrigatório
journey_idstring · opcional

Only for the public route

Devolve

204 Exit recorded

Erros 400 · 401 · 403 · 409

curl -X POST "$BUSINESS_API/first-run/abandon" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "run_token": "run token",
  "step_id": "open_todays_route",
  "journey_id": "resident_link"
}'
Resposta 204

Exit recorded