Documentação - Documentação

post https://console.iugu.com/api/workspaces

Provision a batch of workspaces.

Creates one workspace per item and stores the billing information so the customer can be created in the Billing app.

Requires an application authenticated with the client_credentials grant that holds the workspace_provisioner entitlement. The entitlement is granted by iugu only.

The batch is best effort per item: as long as the request itself is well formed the response is 200 and every item reports its own outcome, so only the failed ones need to be sent again. Every item carries an external_id that is unique per calling application, so on any non-2xx response retry the whole batch — items that were already processed answer replayed and create nothing.

Ownership. Every provisioned workspace is owned by a single iugu service account, which exists only to hold administrator permissions. No user is created per workspace and no invitation is sent, so the calling application owns onboarding. The address supplied in owner.email is recorded against the provisioning for reference only — it is not sent to Billing, which uses billing.email.

Setup and billing are asynchronous. The response returns as soon as the workspace row exists; setup_status reaches all_set shortly after, and billing_status reaches synced when install_requesting_app asked for a subscription, or skipped when it did not.

Sem ações implementadas definidas

Request

Body Required

Content Type: application/json

install_requesting_app

Boolean

Applies to every item in the request. When true, the calling application is installed into each new workspace, and a Billing customer and subscription are created for it. Because a subscription cannot be created for an incomplete customer, `billing.document` and `billing.email` are **required** on every item when this is set. When false, no Billing record is created at all: the customer is registered only as part of creating a subscription, so it waits for the first application install. The whole `billing` object is then optional and is not stored.

workspaces

Required

Array of objects [1..100] items

external_id

Required

String

Your identifier for this workspace. Unique per calling application, and the key that makes retries safe — sending the same one again returns the original result instead of creating a second workspace.

Ex: crm-8842

name

Required

String

The name of the workspace.

Ex: Acme Ltda

alias

String

A short label for the workspace, used as the publisher name in the app store.

Ex: acme

time_zone

String

Defaults to America/Sao_Paulo. Also sent to Billing as the customer time zone.

Ex: America/Sao_Paulo

owner

Object

Optional. Contact for the workspace. No user account is created from this — the workspace is owned by the iugu service account — and the address is not sent to Billing either; it is recorded against the provisioning for your own reference.

String

Ex: [email protected]

billing

Forwarded to the Billing app to create the customer alongside the subscription. Used only when `install_requesting_app` is true, and ignored otherwise — so the object is required only in that case, along with `document` and `email` inside it.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "install_requesting_app": "<INSTALL_REQUESTING_APP>",
  "workspaces": [
    {
      "external_id": "crm-8842",
      "name": "Acme Ltda",
      "alias": "acme",
      "time_zone": "America/Sao_Paulo",
      "owner": {
        "email": "[email protected]"
      },
      "billing": "<BILLING>"
    }
  ]
}

Response

200

Batch processed. Check each item for its outcome.

items

Array of objects

external_id

String

Echoed on every item, so results do not have to be matched by position.

Ex: crm-8842

status

String
Enum: `created`, `replayed`, `updated`, `failed`

`created` — the workspace was provisioned by this request. `replayed` — this external_id was already provisioned; nothing was created. `updated` — the billing data was corrected and a new attempt was queued. `failed` — the item was rejected; see `error`.

workspace_id

String = 22 characters ^[0-9a-f]{22}$

The unique identifier of the resource

Ex: abcd1234efgh5678ijkl

user_id

String = 22 characters ^[0-9a-f]{22}$

The unique identifier of the resource

Ex: abcd1234efgh5678ijkl

setup_status

String
Enum: `pending_setup`, `all_set`

Setup runs in the background. The workspace is usable once it reaches `all_set`.

billing_status

String
Enum: `pending`, `synced`, `failed`, `skipped`

Whether the Billing records have been created yet. `synced` covers the customer and the subscription together — they are created in one call. `skipped` is terminal and means the request did not set `install_requesting_app`, so there was no Billing work to do. `failed` means Billing rejected the data; send it again through `PATCH /api/workspaces`.

app_installed

Boolean

Whether the calling application has been installed into the workspace. Only ever true when the request set `install_requesting_app`, and it becomes true asynchronously.

error

Object

code

String
Enum: `forbidden`, `invalid_request`, `invalid_batch`, `empty_batch`, `too_many_items`, `missing_external_id`, `missing_workspace_name`, `missing_document`, `missing_billing_email`, `validation_failed`, `service_user_missing`, `internal_error`, `provisioning_not_found`, `billing_already_synced`, `activation_in_progress`, `billing_not_applicable`, `workspace_discarded`

A stable, machine-readable code. Branch on this — `message` is localized and its wording is not part of the contract.

Ex: missing_document

message

String

Human-readable description, localized by the Accept-Language header.

Ex: billing.document is required

details Object Present for validation_failed. Maps attribute names to error identifiers. Ex: {"name"=>[{"error"=>"blank"}]}

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "items": [
    {
      "external_id": "crm-8842",
      "status": "<STATUS>",
      "workspace_id": "abcd1234efgh5678ijkl",
      "user_id": "abcd1234efgh5678ijkl",
      "setup_status": "<SETUP_STATUS>",
      "billing_status": "<BILLING_STATUS>",
      "app_installed": "<APP_INSTALLED>",
      "error": {
        "code": "missing_document",
        "message": "billing.document is required",
        "details": {
          "name": [
            {
              "error": "blank"
            }
          ]
        }
      }
    }
  ]
}

401

Unauthorized

error

String

Error type.

Ex: JWT::ExpiredSignature

error_description

String

Error description.

Ex: Signature has expired

Example

1
2
3
4
{
  "error": "JWT::ExpiredSignature",
  "error_description": "Signature has expired"
}

403

The application may not provision workspaces.

error

Object

code

A stable, machine-readable code. Branch on this — `message` is localized and its wording is not part of the contract.

Ex: missing_document

message

String

Human-readable description, localized by the Accept-Language header.

Ex: billing.document is required

details Object Present for validation_failed. Maps attribute names to error identifiers. Ex: {"name"=>[{"error"=>"blank"}]}

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "error": {
    "code": "missing_document",
    "message": "billing.document is required",
    "details": {
      "name": [
        {
          "error": "blank"
        }
      ]
    }
  }
}

422

The batch itself is invalid (missing, empty or too large).

error

Object

code

A stable, machine-readable code. Branch on this — `message` is localized and its wording is not part of the contract.

Ex: missing_document

message

String

Human-readable description, localized by the Accept-Language header.

Ex: billing.document is required

details Object Present for validation_failed. Maps attribute names to error identifiers. Ex: {"name"=>[{"error"=>"blank"}]}

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "error": {
    "code": "missing_document",
    "message": "billing.document is required",
    "details": {
      "name": [
        {
          "error": "blank"
        }
      ]
    }
  }
}

Back

List user workspaces.

Forward

Correct the billing data of a batch of provisionings.