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.