PT EN

Convites de empresas

URL base: $PUBLIC_API

O objecto

utility_namestring · opcional
country_codestring · opcional
setup_modestring · opcional

um de invite, platform_managed

owner_contact_maskedstring · opcional
contact_kindstring · opcional

um de email, phone

expires_atstring (date-time) · opcional
O objecto
{
  "utility_name": "Ana Matsinhe",
  "country_code": "MZ",
  "setup_mode": "invite",
  "owner_contact_masked": "owner contact masked",
  "contact_kind": "email",
  "expires_at": "2026-11-19T09:30:00Z"
}

Abrir um convite

Registos

POST /utility-invitations/open

Resolves the one-time token from the invitation landing page and records the invitation as opened. Returns the utility name, country, setup mode, masked owner contact and expiry so the page can be prefilled. Expired, revoked or used tokens return 410 without saying whether any account exists.

Corpo application/json

tokenstring · obrigatório

One-time token from the invitation link

Devolve

200 Invitation preview

Mostrar atributos
utility_namestring · opcional
country_codestring · opcional
setup_modestring · opcional

um de invite, platform_managed

owner_contact_maskedstring · opcional
contact_kindstring · opcional

um de email, phone

expires_atstring (date-time) · opcional

Erros 400 · 410

curl -X POST "$PUBLIC_API/utility-invitations/open" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "token"
}'
Resposta 200
{
  "utility_name": "Ana Matsinhe",
  "country_code": "MZ",
  "setup_mode": "invite",
  "owner_contact_masked": "owner contact masked",
  "contact_kind": "email",
  "expires_at": "2026-11-19T09:30:00Z"
}

Aceitar um convite e criar as credenciais do titular

Registos

POST /utility-invitations/accept

Consumes a valid token once, with the owner's display name (for a new account) and chosen password. For an invitation the utility name, country and plan come from the record and the response's session is the owner's normal utility session. For an on-behalf invitation the owner becomes a member but the utility stays closed until they accept the handover: the response carries handover.state pending_owner_acceptance and the handover summary, and the same session can call only the handover routes. An existing person must give their current password. Replays, expired and revoked tokens return 410.

Corpo application/json

tokenstring · obrigatório
full_namestring · opcional

Required for a new account

passwordstring (password) · obrigatório

Devolve

200 Accepted

Mostrar atributos
invitation_statestring · obrigatório

um de accepted

setup_modestring · obrigatório

um de invite, platform_managed

handoverobject · obrigatório
Mostrar atributos filhos
statestring · opcional

um de not_required, pending_owner_acceptance, accepted

handover_summaryobject · opcional
Mostrar atributos filhos
invitation_idstring · obrigatório
tenant_idstring · obrigatório
utility_namestring · obrigatório
handoverobject · obrigatório
Mostrar atributos filhos
statestring · opcional

um de not_required, pending_owner_acceptance, accepted

accepted_atstring (date-time) · opcional
completedarray of object · obrigatório
Mostrar atributos filhos
step_idstring · opcional
responsibilitystring · opcional

um de platform, utility

completed_by_namestring · opcional
completed_atstring (date-time) · opcional
outstandingarray of string · obrigatório
sessionobject · obrigatório

The owner's own session

Erros 400 · 409 · 410

curl -X POST "$PUBLIC_API/utility-invitations/accept" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "token",
  "full_name": "Ana Matsinhe",
  "password": "password"
}'
Resposta 200
{
  "invitation_state": "accepted",
  "setup_mode": "invite",
  "handover": {
    "state": "not_required"
  },
  "handover_summary": {
    "invitation_id": "ivt_2pf2g1TgOrLQ0HT6IxvyElNWgBz",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "utility_name": "Ana Matsinhe",
    "handover": {
      "state": "not_required",
      "accepted_at": "2026-11-19T09:30:00Z"
    },
    "completed": [
      {
        "step_id": "service_areas",
        "responsibility": "platform",
        "completed_by_name": "Ana Matsinhe",
        "completed_at": "2026-11-19T09:30:00Z"
      }
    ],
    "outstanding": [
      "company_details",
      "documents"
    ]
  },
  "session": {}
}