> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciar tokens de conta da plataforma AceDataCloud (Account Token)

> Platform API guide - Ace Data Cloud

**O token de conta (Account Token, anteriormente chamado Platform Token)** é a "chave em nível de conta" usada por desenvolvedores para gerenciar programaticamente recursos da plataforma AceDataCloud (solicitações de serviço, credenciais de API, pedidos, registros de chamadas, saldo, arquivos etc.). Sua função é semelhante ao Token do usuário após o login no frontend e, por padrão, não possui prazo de expiração; usuários comuns só podem gerenciar seus próprios tokens, enquanto superadministradores podem gerenciar tokens de outras contas conforme suas permissões.

O token de conta acessa as interfaces da plataforma com as permissões atuais da conta à qual pertence: permissões básicas, permissões concedidas diretamente e permissões dos grupos de usuários aos quais pertence entram em vigor combinadas; após entrar ou sair de um grupo, a próxima solicitação será avaliada com base nas novas permissões. O acesso a recursos específicos, como solicitações e pedidos, ainda requer validação de pertencimento. Tokens de conta não expiram por padrão; use-os apenas em ambientes confiáveis e mantenha-os adequadamente protegidos.

> ℹ️ Esta interface pertence à **API de gerenciamento da plataforma AceDataCloud**, com o prefixo unificado `https://platform.acedata.cloud/api/v1/`. Para o índice completo de interfaces, consulte [Obter lista de documentos da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Token de conta vs credencial de API

Estes são os dois tipos de chaves que mais confundem iniciantes; observe primeiro com clareza:

| Dimensão | **Token de conta** (este documento) | **Credencial de API (Credential)** |
| - | - | - |
| Uso | Chamar interfaces de gerenciamento `https://platform.acedata.cloud/**` | Chamar interfaces de negócios `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo etc.) |
| Formato | `platform-v1-` + 64 caracteres hexadecimais (76 caracteres no total) | 32 caracteres hexadecimais |
| Uma conta | Normalmente 1–2 tokens | 1–N tokens para cada solicitação de serviço |
| Entrada de criação | [Console do Account Token](https://platform.acedata.cloud/console/platform-tokens) | [Criar credencial de API da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) |
| Condições de invalidação | Invalida imediatamente após exclusão; expira quando `expiration` não é nulo | Pode definir limite de cota, prazo de expiração e IP de origem vinculado |

Se você apenas quer usar o GPT-4.1, o que precisa é de uma **credencial de API**, não de um token de conta.
Se você quer escrever scripts de automação para gerenciar recargas, visualizar faturas mensais ou distribuir credenciais em massa para membros da equipe, então use um token de conta.

***

## Criar com um clique no console (recomendado)

1. Faça login em [https://platform.acedata.cloud](https://platform.acedata.cloud).
2. Acesse a barra lateral →「Desenvolvedor」→「[Account Token](https://platform.acedata.cloud/console/platform-tokens)」.
3. Clique no botão 「Criar」 no canto superior direito para obter imediatamente um token `platform-v1-...`; **clique no botão de copiar e salve-o no gerenciador de senhas**.

![Console do Account Token](https://cdn.acedata.cloud/6g86oz.png)

> ⚠️ Atualmente, as respostas de criação, lista e detalhes retornam o token em texto simples. Trate toda a resposta como um segredo; não a grave em logs, plataformas de análise ou persistência no frontend; os clientes também não devem depender de a lista manter o retorno em texto simples a longo prazo.

***

## Criar token de conta com a API

### Visão geral da interface

| Item | Conteúdo |
| - | - |
| Método | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Autenticação | ✅ Qualquer token de conta existente ou JWT de sessão do navegador |
| Body | `application/json` (pode enviar um objeto vazio `{}`) |

### Explicação sobre autenticação (o problema do ovo e da galinha)

> Como obter o primeiro token? A resposta é **pelo console** — após fazer login no navegador, o console chama `POST /platform-tokens/` com autenticação JWT e entrega o primeiro token a você.
> Depois disso, você pode usar qualquer token `platform-v1-...` existente para criar mais tokens.

Formato do cabeçalho da solicitação:

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
Content-Type: application/json
```

### Exemplo de solicitação

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/platform-tokens/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'
```

### Resposta (HTTP 201)

```json theme={null}
{
  "id": "3264f1aa-cbe1-4e2c-a434-95adba4f8304",
  "token": "platform-v1-<REDACTED>",
  "expiration": null,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "created_at": "2026-04-26T15:50:11.123456Z",
  "updated_at": "2026-04-26T15:50:11.123456Z",
  "used_at": null
}
```

### Descrição dos campos

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | UUID | Chave primária do token, usada ao excluir / consultar detalhes |
| `token` | string | Texto simples do token de conta. Formato `platform-v1-` + 64 caracteres hexadecimais (76 caracteres no total), deve ser tratado como segredo |
| `expiration` | int \| null | Horário de expiração (timestamp em segundos). `null` indica que não há prazo de expiração definido |
| `user_id` | UUID | ID do usuário ao qual pertence. Também é o valor do parâmetro `?user_id=` que deve ser informado em todas as interfaces de lista subsequentes |
| `created_at` | datetime (ISO8601) | Horário de criação |
| `updated_at` | datetime (ISO8601) | Horário de atualização |
| `used_at` | datetime \| null | Horário em que foi usado pela última vez para autenticação. Será `null` se nunca tiver sido usado e pode ser usado para identificar "tokens zumbis" |

***

## Obter lista de tokens de conta

### Visão geral da interface

| Item | Conteúdo |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Autenticação | ✅ Token de conta necessário |

### Parâmetro de consulta obrigatório

> ⚠️ **É obrigatório incluir `?user_id=<your_user_id>`**. Motivo: a interface de lista realiza validação de permissão **objeto por objeto** nos resultados paginados; sem `user_id`, o primeiro objeto que não pertencer a você será rejeitado, retornando `403 permission_denied`.

Como obter `user_id`:

1. Abra [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile) no navegador; o UUID completo é exibido no topo da página.
2. Ou preencha diretamente com o campo `user_id` retornado por `POST /platform-tokens/`.

### Parâmetros de consulta

| Parâmetro | Obrigatório | Tipo | Descrição |
| - | - | - | - |
| `user_id` | ✅ | UUID | ID do usuário da conta atual |
| `limit` | ❌ | int | Número de itens por página, padrão 10, máximo 100 |
| `offset` | ❌ | int | Deslocamento |
| `ordering` | ❌ | string | Campo de ordenação, padrão `-created_at` |

### Exemplo de solicitação

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b&limit=5' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

### Resposta (HTTP 200)

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "51c575a2-801c-4211-bc47-711452a8c8c9",
      "token": "platform-v1-<REDACTED>",
      "expiration": null,
      "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
      "created_at": "2026-04-26T15:41:32.761705Z",
      "updated_at": "2026-04-26T15:41:32.761726Z",
      "used_at": null
    }
  ]
}
```

> A resposta paginada desta API usa `count` + `items`. Outras APIs da plataforma podem usar estruturas diferentes; consulte a documentação correspondente e a resposta real.

***

## Obter detalhes do token da conta

| Item | Conteúdo |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**sem barra no final**） |
| Autenticação | ✅ Apenas o criador do token ou o superadministrador pode acessar |

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/51c575a2-801c-4211-bc47-711452a8c8c9' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

A estrutura retornada é igual à do elemento da lista, `HTTP 200`.

***

## Excluir token da conta

| Item | Conteúdo |
| - | - |
| Método | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**sem barra no final**） |
| Autenticação | ✅ Apenas o criador do token ou o superadministrador pode excluir |

```shell theme={null}
curl -X DELETE 'https://platform.acedata.cloud/api/v1/platform-tokens/3264f1aa-cbe1-4e2c-a434-95adba4f8304' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

* Em caso de sucesso, retorna `HTTP 204 No Content`, sem corpo de resposta.
* Após a exclusão, o token **perde a validade imediatamente**, e todos os serviços que o estão usando receberão `401` imediatamente.
* Consultar novamente esse `id` retornará `404`.

> ⚠️ A exclusão é irreversível. Se você suspeitar que o token vazou, pode **primeiro criar um novo, alternar o lado do negócio e depois excluir o antigo**.

***

## Operações não suportadas

| Operação | HTTP | Descrição |
| - | - | - |
| Modificação com `PATCH` | 405 | Após a criação, o token da conta **não suporta a modificação de nenhum campo**. Para usos como renomeação, exclua e recrie |
| Substituição com `PUT` | 405 | Mesmo acima |

***

## Referência rápida de códigos de erro

| HTTP | `code` | Motivos comuns |
| - | - | - |
| 401 | `not_authenticated` | Cabeçalho `Authorization` ausente ou token excluído |
| 403 | `permission_denied` | A API de lista não incluiu `?user_id=`, ou acesso aos detalhes do token de outra pessoa |
| 404 | `not_found` | O `id` não existe ou foi excluído |
| 405 | `method_not_allowed` | Foi enviado `PATCH`/`PUT` para a API de detalhes |

Formato unificado da resposta de erro:

```json theme={null}
{
  "detail": "You do not have permission to perform this action.",
  "code": "permission_denied",
  "trace_id": "0a88956213edf6e62b71695ee2df0eff"
}
```

Ao investigar, forneça o `trace_id` ao atendimento ao cliente ou inclua-o no ticket para localizar rapidamente os logs.

***

## Exemplo de código completo

### Python

```python theme={null}
import os
import requests

BASE = "https://platform.acedata.cloud/api/v1"
PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
USER_ID = "89518d07-5560-4b05-92c1-667f3ddf6a4b"

headers = {
    "accept": "application/json",
    "authorization": f"Bearer {PLATFORM_TOKEN}",
    "content-type": "application/json",
}

# 1. 创建新令牌
created = requests.post(f"{BASE}/platform-tokens/", headers=headers, json={}).json()
print("新令牌：", created["token"])
print("UserID：", created["user_id"])

# 2. 列表
listing = requests.get(
    f"{BASE}/platform-tokens/",
    headers=headers,
    params={"user_id": USER_ID, "limit": 50},
).json()
print(f"共 {listing['count']} 枚令牌")

# 3. 删除（注意末尾无斜杠）
resp = requests.delete(f"{BASE}/platform-tokens/{created['id']}", headers=headers)
assert resp.status_code == 204, resp.text
```

### Node.js

```javascript theme={null}
const BASE = 'https://platform.acedata.cloud/api/v1'
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const USER_ID = '89518d07-5560-4b05-92c1-667f3ddf6a4b'

const headers = {
  accept: 'application/json',
  authorization: `Bearer ${PLATFORM_TOKEN}`,
  'content-type': 'application/json',
}

// 创建
const created = await fetch(`${BASE}/platform-tokens/`, {
  method: 'POST',
  headers,
  body: '{}',
}).then((r) => r.json())

// 列表
const url = new URL(`${BASE}/platform-tokens/`)
url.searchParams.set('user_id', USER_ID)
const listing = await fetch(url, { headers }).then((r) => r.json())
console.log(`共 ${listing.count} 枚令牌`)

// 删除（末尾无斜杠）
await fetch(`${BASE}/platform-tokens/${created.id}`, { method: 'DELETE', headers })
```

***

## Usar em outras APIs da plataforma

Basta colocar `platform-v1-...` diretamente no cabeçalho `Authorization: Bearer ...` para chamar qualquer API da plataforma que exija autenticação:

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/applications/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

> É **completamente diferente** das credenciais de API hexadecimais de 32 dígitos usadas pelas APIs de negócio `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo etc.). Não as misture — usar o token da conta em uma API de negócio resultará em `401`, e vice-versa.

***

## APIs relacionadas

* [Obter a lista de solicitações de serviços da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — usar o token da conta para ver quais serviços você solicitou
* [Criar credenciais de API da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — usar o token da conta para emitir credenciais de 32 caracteres para APIs de negócios
* [Obter registros de chamadas de API da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-usage-list) — consultar cobranças e solucionar erros
* [Obter a lista de pedidos da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-list) — consultar o histórico de recargas


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.