PT EN

Primeiros passos

URL base: $CONSUMER_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"
}

Obter o progresso de um percurso inicial

Registos

GET /first-run/progress

Returns the durable progress of the signed-in resident for one journey (resident_link, resident_connection): 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 an authenticated resident.

Parâmetros

journeystring · consulta · obrigatório

Journey ID

um de resident_link, resident_connection

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 "$CONSUMER_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 an authenticated resident.

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 "$CONSUMER_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. Requires an authenticated resident and a run token issued to them or the anonymous resident entry token.

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 "$CONSUMER_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