Documentação - Documentação

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

Correct the billing data of a batch of provisionings.

Replaces the billing data of provisionings whose `billing_status` is `failed` and queues a new attempt. This is the way out of a rejected document or email — because `external_id` is an idempotency key, resending the batch to `POST` only answers `replayed`. Authentication and batch semantics are identical to `POST`: same entitlement, same item cap, `200` with a per-item outcome as long as the request is well formed. **Only billing data is correctable.** Items are matched by `external_id` and every other field is ignored, including `install_requesting_app` — the workspace and the install intent are already settled. To rename a workspace, use the workspace endpoints. The `billing` object **replaces** the rejected one rather than merging into it, so send it complete: any field you leave out is cleared. Corrected items come back as `pending` and reach `synced` asynchronously, or `failed` again if Billing rejects the new data too. Only `failed` is correctable. `synced` is already accepted, `pending` is still being processed, and `skipped` never had billing data — each answers with its own error code.

Sem ações implementadas definidas

Request

Body Required

Content Type: application/json

workspaces

Required

Array of objects [1..100] items

external_id

Required

String

Identifies the provisioning to correct, scoped to the calling application. Unknown values answer `provisioning_not_found`.

Ex: crm-8842

billing

Required

Replaces the rejected billing data entirely — send it complete, as omitted fields are cleared. `document` and `email` are always required.

Example

1
2
3
4
5
6
7
8
{
  "workspaces": [
    {
      "external_id": "crm-8842",
      "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

Provision a batch of workspaces.

Forward

List installed apps with the requested features.