Ga naar inhoud

Accounts

Account-endpoints zijn niet beschikbaar via OAuth — accountbeheer vereist een sessie- of API-sleutel-credential.

Alle accounts opvragen

Dit is niet accountgescoped en geeft ALLE accounts terug waartoe deze gebruiker toegang heeft.

GET /api/accounts

Teruggegeven params
  • accounts: Array
    • id: String
    • name: String
    • reseller: Boolean
    • is_trial: Boolean
    • trial_start: DateTime
    • trial_end: DateTime
    • parent_account: Object | alleen bij sub-accounts — zie de waarschuwing hieronder
      • id: String
      • name: String
    • reseller_billing_plan: Object | alleen bij sub-accounts met een reseller-facturatieplan — zie de waarschuwing hieronder
      • id: String
      • name: String
    • nameservers: Array
    • created_at
    • updated_at

Heeft een account geen bovenliggend account, dan ontbreken parent_account en reseller_billing_plan in de JSON in plaats van null te zijn — controleer op de aanwezigheid van de sleutel. De lijst bevat geen account_roles; die haal je op met Account bekijken of Accountrollen opvragen.


Account bekijken

GET /api/accounts/:id

Geeft één account-object terug met alle velden van een list-item plus account_roles, dat de lijst niet teruggeeft, en, zolang die bestaat, move. Elk item in account_roles heeft dezelfde structuur als een item in Accountrollen opvragen.

Teruggegeven params (aanvullend)
  • account: Object
    • move: Object | alleen zolang een workspace-verplaatsing waarvan de facturatie meeverhuist openstaat, of tot 30 dagen nadat die is mislukt of terugbetaald. Anders ontbreekt de sleutel; hij is niet null
      • guid: String
      • status: String | charging, requires_action, awaiting_payment, applying, payment_failed, refunded of refund_failed
      • cancelable: Boolean | of je de verplaatsing nu mag annuleren met Een workspace-verplaatsing annuleren
Fouten
  • 401 forbidden | de gebruiker van het token mag het account niet bekijken
  • 404 | dat account bestaat niet of is niet van jou; geen body

Account aanmaken

Twee modi:

  • Top-level account — laat X-Auth-Account weg. Vereist een admin-gebruiker.
  • Sub-account — stel X-Auth-Account in op het Account-ID van het bovenliggende account. Vereist een admin-rol op het bovenliggende account en het bovenliggende account moet een reseller zijn.

POST /api/accounts

Params
  • account: Object
    • name: String (required)

Alleen-admin-params

Admin-aanroepers kunnen daarnaast is_trial, trial_start, trial_end, reseller, reseller_bill_trial, billing_plan_id en parent_account_guid instellen.

Een sub-account krijgt het merk van de workspace in X-Auth-Account, net als gebruikers die je aanmaakt via POST /api/users.

Geeft bij succes 201 terug met het account.

Fouten
  • 401 forbidden | je bent geen admin van de workspace in X-Auth-Account, of het is geen reseller (zonder de header: je bent geen admin)
  • 422 account_invalid | het account is niet geldig, ook bij een onbekende parent_account_guid

Account bijwerken

PATCH /api/accounts/:id

Vereist bewerkrechten. Niet-admin-aanroepers kunnen alleen name bijwerken. Admin-aanroepers kunnen daarnaast is_trial, trial_start, trial_end, reseller, reseller_bill_trial en billing_plan_id instellen. Geeft 202 terug met het account.

Als je parent_account_guid meestuurt, wordt de workspace verplaatst; zie hieronder.

Params
  • account: Object
    • name: String
    • parent_account_guid: String | optioneel. Het nieuwe bovenliggende account; een lege string maakt de workspace los
  • confirm_preview_digest: String | de preview_digest die je kreeg, om een verplaatsing te bevestigen
  • keep_access: Boolean | optioneel, standaard false. Behoud je eigen toegang; zie hieronder
  • confirm_total_cents: Integer | optioneel: de billing_quote.charge_total_cents die je hebt bekeken
Fouten
  • 401 forbidden | je mag dit account niet bewerken
  • 404 | dat account bestaat niet of is niet van jou; geen body
  • 422 account_invalid | het account is niet geldig

Een workspace verplaatsen

Je hebt een admin-rol nodig op het huidige bovenliggende account van de workspace (of op de workspace zelf als die er geen heeft) en op het nieuwe bovenliggende account. Onder een niet-reseller wordt de workspace gefactureerd via dat bovenliggende account; losgemaakt betaalt hij zelf, op het standaardplan. Een geweigerde verplaatsing wijzigt niets.

Bevestigen. Een verplaatsing die het facturatieplan of het merk wijzigt, of die iemand de toegang ontneemt (access_lost), moet worden bevestigd:

  1. Stuur het verzoek. Het antwoord is 422 requires_confirmation met een preview en een preview_digest.
  2. Stuur het opnieuw met confirm_preview_digest. Is de verplaatsing intussen veranderd, dan is het antwoord preview_stale met een nieuwe preview en digest.

Je toegang behouden. Iedereen wiens rol is geërfd van een workspace die de verplaatsing verlaat, verliest de toegang. Geldt dat ook voor jou, stuur dan keep_access: true mee voor een directe rol op de workspace (de rol die je nu hebt op de dichtstbijzijnde workspace die hij verlaat).

Verplaatsingen die veranderen wie betaalt. Lopende abonnementen gaan mee met de workspace: de nieuwe betaler wordt belast voor de rest van de lopende periode (via zijn standaardbetaalmethode), de oude betaler krijgt een tegoed, en de workspace wordt verplaatst zodra de betaling is geslaagd. Dan geldt:

  • de preview bevat billing_quote, en bevestigen vereist altijd de digest;
  • de bevestiging antwoordt 202 met { "move": { "guid": "…", "status": "…" } } in plaats van het account;
  • volg de verplaatsing via move bij Account bekijken, of annuleer hem met Een workspace-verplaatsing annuleren;
  • stuur confirm_total_cents mee om de verplaatsing te laten weigeren (drift) als het totaal met meer dan 50 cent is veranderd.

Met een admin-sleutel stuur je een verplaatsing zonder andere attributen (alleen parent_account_guid, confirm_preview_digest, keep_access), anders wordt die geweigerd met move_must_be_submitted_alone.

Preview (in requires_confirmation- en preview_stale-bodies)
  • preview: Object
    • parent_before: Object | { id, name }, of afwezig
    • parent_after: Object | { id, name }, of afwezig
    • payer_before: Object | { id, name }
    • payer_after: Object | { id, name }
    • billing_plan_before: Object | { id, name }, of afwezig
    • billing_plan_after: Object | { id, name }, of afwezig
    • brand_before: Object | { id, name }, of afwezig
    • brand_after: Object | { id, name }, of afwezig
    • inherit_billing: Boolean
    • billing: String | none of required
    • billing_quote: Object | alleen als billing required is
      • currency: String
      • charge_subtotal_cents: Integer
      • tax_cents: Integer | null als de btw nog niet bekend is
      • charge_total_cents: Integer
      • seats: Array | één item per verplaatst abonnement, met de bedragen voor kosten en tegoed en de factuurperiode
    • access_lost: Array | leeg als niemand toegang verliest
      • user: Object | id, name, email
      • role: Object | id, name, label
  • preview_digest: String
Verplaatsingsfouten
  • 400 no_default_payment_method | de nieuwe betaler heeft geen standaardbetaalmethode of factuuradres
  • 401 forbidden | je bent geen admin van het huidige of het nieuwe bovenliggende account
  • 422 unknown_parent | parent_account_guid noemt geen workspace van jou
  • 422 invalid_parent | de workspace kan daar niet naartoe (zichzelf, een van zijn subworkspaces, een verwijderde workspace, of zijn huidige bovenliggende account)
  • 422 brand_locked | de verplaatsing zou het merk van de workspace wijzigen of verwijderen; alleen een beheerder van de workspace die dat merk bezit mag dat doen
  • 422 requires_confirmation | bekijk preview en bevestig daarna
  • 422 preview_stale | de verplaatsing is veranderd; bevestig met de nieuwe digest
  • 422 drift | het totaal is met meer dan 50 cent veranderd ten opzichte van confirm_total_cents
  • 422 move_in_progress | deze workspace wordt al verplaatst
  • 422 move_must_be_submitted_alone | admin-sleutel: stuur de verplaatsing zonder andere attributen
  • 422 billing_migration_unsupported, payer_not_billable, payer_in_dunning, subscription_suspended, billing_in_progress, domain_renewal_due, billing_needs_reconciliation | de facturatie kan nu niet mee; het bericht geeft de reden
  • 422 payer_invoice_open | de oude of de nieuwe betaler heeft een onbetaalde factuur. Betaal die en probeer het opnieuw
  • 422 uninvoiced_ledger_entries | een van beide betalers heeft verbruik dat nog niet is gefactureerd. Probeer het opnieuw zodra het is gefactureerd en betaald
  • 422 payment_failed | de betaling is mislukt; er is niets gewijzigd
  • 422 payment_requires_action | de bank wil dat de betaling wordt bevestigd; bevestig de verplaatsing in het dashboard
  • 503 billing_unavailable | het facturatiesysteem was niet bereikbaar

Foutbodies zijn { "errors": ["…"], "code": "…" }; de weigeringen met een preview bevatten ook preview en preview_digest.


Een workspace-verplaatsing annuleren

DELETE /api/accounts/:account_id/move

Annuleert de openstaande verplaatsing van de workspace zolang move.cancelable bij Account bekijken true is. De afschrijving wordt geannuleerd, er wordt niets verplaatst en de verplaatsing eindigt als payment_failed. Vereist een admin-rol op zowel de workspace die de verplaatsing verlaat als die ze binnenkomt. Geeft 200 terug.

Teruggegeven params
  • move: Object
    • guid: String
    • status: String | payment_failed
Fouten
  • 401 forbidden | je mag deze verplaatsing niet uitvoeren
  • 404 no_open_move | de workspace heeft geen openstaande verplaatsing
  • 404 | dat account bestaat niet of is niet van jou; geen body
  • 422 move_still_confirming | de betaling wordt nog bevestigd; probeer het over een paar minuten opnieuw
  • 422 move_not_cancelable | de verplaatsing wordt doorgevoerd, of een bankincasso wordt geïnd
  • 422 payment_went_through | de betaling is geslaagd; de workspace wordt verplaatst
  • 503 billing_unavailable | de betaalprovider was niet bereikbaar; er is niets geannuleerd. Probeer het opnieuw

Account verwijderen

DELETE /api/accounts/:id

Verwijdert een lege workspace. Facturen en de auditgeschiedenis blijven bewaard. Een verwijderde workspace kan alleen worden hersteld via contact met support. Sites, cPanel-accounts en mailspaces die al op verwijdering wachten, blokkeren niet. Vereist een admin-rol op de workspace. Geeft 202 terug, zonder body.

Fouten
  • 401 forbidden | je bent geen admin van dit account
  • 401 last_workspace | het is je enige account
  • 404 | dat account bestaat niet of is niet van jou; geen body
  • 422 workspace_not_empty | verwijder eerst wat in blockers staat
  • 422 move_in_progress | een workspace-verplaatsing waarbij hij betrokken is, staat nog open
  • 422 already_archived | hij is al verwijderd; wordt alleen teruggegeven aan CloudPress-medewerkers
workspace_not_empty-body
  • blockers: Array<Object>
    • code: String | sub_workspaces, sites, cpanel_accounts, mailspaces, domain_registrations, dns_zones, domains, subscriptions, invoices, dunning_cases, disputes, cart_checkouts, managed_users, tasks of reseller_billing_plan
    • count: Integer

Accountrollen

Beheer welke gebruikers toegang hebben tot een account, en met welke rol. Vereist een admin-rol op het account. Niet beschikbaar via OAuth.

Accountrollen opvragen

GET /api/accounts/:account_id/roles

Teruggegeven params
  • account_roles: Array<Object>
    • inherited_from: String | account-ID, of null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

De rol van een gebruiker bekijken

GET /api/accounts/:account_id/roles/:user_id

Geeft één item terug, verpakt in één account_role-object in plaats van de array account_roles die de lijst teruggeeft.

Teruggegeven params
  • account_role: Object
    • inherited_from: String | account-ID, of null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

Een gebruiker uitnodigen

Nodig een bestaande gebruiker per e-mail uit voor het account. Geeft 202 terug.

POST /api/accounts/:account_id/roles

Params
  • email: String
  • user_role_id: Integer | zie User Roles

De rol van een gebruiker wijzigen

PATCH /api/accounts/:account_id/roles/:user_id

Params
  • account_role: Object
    • user_role_id: Integer

Geeft de bijgewerkte rol terug in dezelfde structuur als GET /api/accounts/:account_id/roles/:user_id.

Teruggegeven params
  • account_role: Object
    • inherited_from: String | account-ID, of null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

Een gebruiker verwijderen

DELETE /api/accounts/:account_id/roles/:user_id

Geeft 202 terug.

Overgeërfde rollen

Een rol die is overgeërfd van een bovenliggend account kan niet op het onderliggende niveau worden verwijderd — dit geeft 422 {"errors":["Unable to remove an inherited role."]} terug. Wijzig de rol op het bovenliggende account om alle onderliggende accounts bij te werken.


Gebruikersrollen

Vraag de beschikbare roldefinities op. Gebruik de teruggegeven id bij het uitnodigen of bijwerken van gebruikers op een account.

GET /api/user_roles

Teruggegeven params
  • user_roles: Array<Object>
    • id: Integer
    • name: String
    • label: String
    • is_admin: Boolean
    • can_edit: Boolean
    • can_create: Boolean
    • can_destroy: Boolean
    • billing: Boolean
    • wp_login: Boolean