> ## 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.

# Criar solicitação de serviço da plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

Uma “solicitação (Application)” representa a relação de assinatura da conta atual com determinado serviço — é necessário solicitar primeiro, para então criar credenciais de API para essa solicitação e chamar interfaces de negócios. Ao solicitar um serviço pela primeira vez, a Application receberá o `free_amount` atualmente configurado para esse serviço; esse valor pode ser 0.

> ℹ️ 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).

## Fluxo completo de integração

Novos usuários normalmente seguem estas 5 etapas, desde o registro até a chamada da primeira interface de negócios:

1. **Obter o token da conta** → [Gerenciar token da conta da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token)
2. **Selecionar um serviço** → [Obter lista de serviços da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list)
3. **Criar uma solicitação** (este documento) → obter a cota inicial conforme a configuração do serviço
4. **Criar credenciais de API** → [Criar credenciais de API da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create)
5. **Chamar a interface de negócios** → usar o Token de 32 caracteres obtido para chamar `https://api.acedata.cloud/<path>`

## Visão geral da interface

| Item | Conteúdo |
| - | - |
| Método | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/applications/` |
| Autenticação | ✅ Token da conta necessário |
| Content-Type | `application/json` |

## Instruções de autenticação (como obter o token da conta)

Cabeçalho da solicitação:

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
```

O token da conta (Account Token) é a “chave em nível de conta” usada pelo desenvolvedor para gerenciar os recursos de sua própria conta por meio da API. Formas de obtenção:

1. **Criação com um clique no console (recomendado)**: faça login na [plataforma AceDataCloud](https://platform.acedata.cloud) → [console de Account Token](https://platform.acedata.cloud/console/platform-tokens) → clique em “Criar” para obter um token que começa com `platform-v1-`.
2. **Criação por API**: use um token de conta existente ou o JWT da sessão de login do navegador para chamar `POST /api/v1/platform-tokens/`; consulte [Gerenciar token da conta da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token) para detalhes.

> ⚠️ O token da conta é tão sensível quanto uma senha e não deve ser incluído em código de frontend ou repositórios públicos. Caso seja vazado, exclua-o imediatamente no console e crie um novo.

## Corpo da solicitação

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `service_id` | UUID | ✅ | ID do serviço a ser solicitado. Pode ser obtido em `items[].id` da [lista de serviços](https://platform.acedata.cloud/documents/platform-service-list) |

## Exemplos de solicitação

### cURL

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/applications/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{"service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452"}'
```

### Python

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

PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
SERVICE_ID = "38ecf158-36f2-42f2-8e7f-6786cdfc2452"

resp = requests.post(
    "https://platform.acedata.cloud/api/v1/applications/",
    headers={
        "accept": "application/json",
        "authorization": f"Bearer {PLATFORM_TOKEN}",
        "content-type": "application/json",
    },
    json={"service_id": SERVICE_ID},
    timeout=10,
)

if resp.status_code == 201:
    app = resp.json()
    print(f"申请成功！application_id={app['id']}")
    print(f"初始额度：{app['remaining_amount']} {app.get('service', {}).get('unit', '')}")
elif resp.status_code == 400 and resp.json().get("code") == "duplication":
    print("⚠️ 已经申请过此服务，请到 /applications/ 列表里找到现成的 application_id")
else:
    print(f"申请失败：HTTP {resp.status_code} - {resp.text}")
```

### Node.js

```javascript theme={null}
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const SERVICE_ID = '38ecf158-36f2-42f2-8e7f-6786cdfc2452'

const resp = await fetch('https://platform.acedata.cloud/api/v1/applications/', {
  method: 'POST',
  headers: {
    accept: 'application/json',
    authorization: `Bearer ${PLATFORM_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ service_id: SERVICE_ID }),
})

if (resp.status === 201) {
  const app = await resp.json()
  console.log('application_id =', app.id)
} else {
  console.error(await resp.text())
}
```

## Exemplo de resposta

### Sucesso (HTTP 201)

```json theme={null}
{
  "id": "82f57141-2323-4453-8730-60f7d833a2da",
  "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
  "remaining_amount": 1.0,
  "used_amount": 0.0,
  "paid": false,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "disabled": false,
  "allow_consume_global": false,
  "scope": "Individual",
  "type": "Usage",
  "expired_at": null,
  "tags": null,
  "metadata": null,
  "client_ip": null,
  "client_fingerprint": null,
  "created_at": "2026-04-26T07:52:27.462400Z",
  "updated_at": "2026-04-26T07:52:27.462400Z"
}
```

A estrutura dos campos retornados é consistente com [Obter detalhes da solicitação de serviço da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail).

### Já solicitado (HTTP 400)

```json theme={null}
{
  "detail": "Item already exists.",
  "code": "duplication",
  "trace_id": "1a87524f8cbba0b790b2951e2e43117e"
}
```

Esta é uma limitação rígida de design: **cada usuário pode ter apenas uma Application para cada serviço**. Caso já exista, encontre a existente por meio de [Obter lista de solicitações de serviço da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list).

### Serviço não existe (HTTP 404)

```json theme={null}
{
  "detail": "Service not found.",
  "code": "not_found",
  "trace_id": "..."
}
```

### Serviço requer revisão (HTTP 403)

```json theme={null}
{
  "detail": "This service requires manual verification.",
  "code": "need_verify",
  "trace_id": "..."
}
```

Se o serviço tiver `need_verify=true` (esse campo pode ser visto na lista de serviços), será necessário seguir o processo de ticket para solicitar inclusão na lista de permissões.

## Tratamento de erros

| HTTP | código | significado |
| - | - | - |
| 400 | `duplication` | Este serviço já foi solicitado pela conta atual |
| 400 | `invalid` | `service_id` ausente ou formato incorreto |
| 401 | `not_authenticated` | Token da conta ausente ou token foi excluído |
| 403 | `need_verify` | O serviço requer revisão, siga o processo de ticket |
| 404 | `not_found` | O serviço não existe ou foi desativado |

Formato unificado da resposta de erro:

```json theme={null}
{
  "detail": "...",
  "code": "...",
  "trace_id": "..."
}
```

## Dicas práticas

* **A criação em si não gera cobrança**: na primeira criação, a cota inicial é definida de acordo com o `free_amount` atual do serviço; esse valor pode ser 0, e criar novamente uma Application do mesmo tipo não garante a concessão repetida.
* **Verifique o campo `paid` para saber se é necessário pagar**: logo após a solicitação, `paid=false`; após chamar [Criar pedido de recarga da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) para concluir o pagamento, torna-se `true`.
* **`disabled=true` significa que foi temporariamente desativado** — por exemplo, devido ao acionamento de controle de risco, inadimplência etc. Quando desativado, a interface de negócios retornará `403`.
* **Não crie com concorrência ilimitada**: primeiro obtenha o `service_id` de destino na lista paginada de serviços e, em seguida, solicite item por item conforme as necessidades do negócio; ao encontrar `duplication`, reutilize a Application existente.

## Interfaces relacionadas

* [Obter lista de serviços da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list) — primeiro escolha o serviço
* [Obter lista de solicitações de serviços da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — visualizar todos os já solicitados
* [Obter detalhes da solicitação de serviço da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail) — visualizar uma única solicitação
* [Criar credencial de API da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — próxima etapa após a solicitação ser bem-sucedida
* [Criar pedido de recarga da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) — recarregar após a cota gratuita se esgotar


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