Organizações e workspaces

Workspace = evento, na prática — o nome no código é workspace, mas tudo que se aplica a "evento" no resto desta documentação (participante, PDV, caixa) se refere a um workspace criado aqui.

Organizações

Endpoint	O que faz
GET /v1/management/organizations	Lista organizações onde o gestor autenticado tem papel ativo.
POST /v1/management/organizations	Cria uma organização; quem cria vira owner. slug é opcional — se omitido, a API gera um a partir do nome.
PATCH /v1/management/organizations/{organizationId}	Só owner altera nome. Slug e papel do gestor são somente leitura.
DELETE /v1/management/organizations/{organizationId}	Só owner. Encerra a organização e arquiva todos os workspaces dela.

Regiões disponíveis

Endpoint	O que faz
GET /v1/management/regions	Lista os códigos de região com pelo menos um cluster ativo — é a lista que alimenta o seletor de região na criação de workspace.

Workspaces (eventos)

Endpoint	O que faz
GET /v1/management/organizations/{organizationId}/workspaces	Lista workspaces da organização.
POST /v1/management/organizations/{organizationId}/workspaces	Cria e provisiona um workspace numa região. owner/admin apenas.
PATCH /v1/management/organizations/{organizationId}/workspaces/{workspaceId}	Atualiza nome, timezone, startsAt/endsAt. Região e moeda são imutáveis após criação.
POST /v1/management/organizations/{organizationId}/workspaces/{workspaceId}/provisioning/retry	Tenta de novo o provisionamento regional quando ele falhou (status=failed).
DELETE /v1/management/organizations/{organizationId}/workspaces/{workspaceId}	Arquiva o workspace (terminal — não existe "reativar").

Exemplo: criar um workspace

curl

curl -X POST http://127.0.0.1:8787/v1/management/organizations/{organizationId}/workspaces \
  -H "Authorization: Bearer <accessToken do gestor>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Festival de Verão",
    "homeRegion": "br-east-1",
    "timezone": "America/Sao_Paulo",
    "currencyCode": "BRL"
  }'

JavaScript

const response = await fetch(
  `http://127.0.0.1:8787/v1/management/organizations/${organizationId}/workspaces`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Festival de Verão",
      homeRegion: "br-east-1",
      timezone: "America/Sao_Paulo",
      currencyCode: "BRL",
    }),
  },
);
const workspace = await response.json();

Python

import requests

response = requests.post(
    f"http://127.0.0.1:8787/v1/management/organizations/{organization_id}/workspaces",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "name": "Festival de Verão",
        "homeRegion": "br-east-1",
        "timezone": "America/Sao_Paulo",
        "currencyCode": "BRL",
    },
)
workspace = response.json()

Provisionamento é assíncrono, mas a resposta já reflete o resultado

POST .../workspaces chama a wallet-api da região escolhida de forma síncrona, dentro do mesmo request — o cliente já recebe status: "active" ou status: "failed" na resposta, sem precisar dar polling. Se falhar (região momentaneamente indisponível, por exemplo), o registro global e o slug já existem; use o endpoint de retry, não crie de novo.

eventCode — o código curto do evento

Toda resposta de workspace inclui eventCode, no formato AXY-9898 (3 letras sem I/O, 4 dígitos sem 0/1 — evita confusão visual). Esse é o código que o participante digita ou lê via QR pra encontrar o evento e ativar a própria wallet nele — veja Encontrar evento e ativar wallet. Ele é gerado automaticamente na criação do workspace; não há como escolher ou editar.