# API do desenvolvedor

URL canônica: https://texttree.ai/pt-br/docs/developer-api/
URL em Markdown: https://texttree.ai/pt-br/docs/developer-api.md
Tipo de página: docs
Translation status: draft
Legal status: english_controls

## Resumo

Envio de mensagens e contratos estaduais para a API alfa TextTree atual.

## Conteúdo fonte

# API para desenvolvedores

A API JSON atual é intencionalmente restrita. Está focado em um caminho crítico de produção:
Coloque SMS de saída na fila e verifique seu status.

## URL base

O desenvolvimento local com Phoenix é executado em `http://localhost:4001`.

Todos os endpoints de desenvolvedor documentados residem em `/api/v1`.

## Autenticação

As chamadas autenticadas para a API requerem um token de acesso ao portador `txt_...` emitido pelo TextTree.
O mesmo modelo de identidade local é usado para o aplicativo do navegador, a API do desenvolvedor e
Rotas MCP. As chaves de API herdadas `txk_...` são mantidas como registros internos e não são
são aceitos por `/api/v1/messages`.

```http
Authorization: Bearer <textree_access_token>
Accept: application/json
```

`POST /api/v1/messages` requer `messages:write`. Pontos finais de inventário numérico
requerem `numbers:read` ou `numbers:write`. Identidades de e-mail, Google,
carteira e agente são normalizados para a mesma identidade TextTree local antes
autorização.

## Inicialização de conta sem cabeça

Os clientes de IA e API podem criar uma conta sem e-mail, Google OAuth ou
autenticação de carteira usando nome de usuário e senha de inicialização.

`POST /api/v1/accounts`

Esta rota é pública, somente JSON, e está limitada à criação bem-sucedida da conta
por endereço IP a cada cinco minutos. TextTree armazena um hash do endereço IP para
o registro de limitação; o IP bruto não é armazenado.

### Corpo da solicitação

```json
{
  "username": "agent-demo",
  "password": "correct horse battery staple"
}
```

### Resposta bem sucedida

```json
{
  "account": {
    "id": "9d7d9df7-58a0-4716-b82e-7ad5e73f7b36",
    "username": "agent-demo"
  },
  "backup_codes": ["AAAA-BBBB-CCCC-DDDD"],
  "token": {
    "type": "Bearer",
    "access_token": "txt_...",
    "scopes": ["mcp:read", "mcp:execute", "messages:write"],
    "expires_at": "2026-06-03T15:30:00Z"
  }
}
```

Salve o portador do token `txt_...` e os códigos de backup imediatamente. O e-mail
sintético interno, o hash do token, a senha e o hash de IP de limitação nunca são retornados.

### Erros

- `422` com `{"error":"validation_failed","details":...}` para nomes de usuário inválidos ou duplicados
  ou senhas inválidas
- `429` com `{"error":"account_creation_rate_limited","retry_after_seconds":...}` quando o
  O IP do solicitante já criou uma conta nos últimos cinco minutos

## Saúde

`GET /api/v1/health`

Esta rota é pública e útil para verificações de implantação e testes rápidos locais.

## Enfileirar uma mensagem enviada

`POST /api/v1/messages`

### Corpo da solicitação

```json
{
  "phone_number": "+15551234567",
  "body": "Your verification code is 482019",
  "estimated_cost_cents": 2,
  "idempotency_key": "msg_2026_04_26_0001",
  "metadata": {
    "campaign": "alpha-invite",
    "source": "api"
  }
}
```

### Campos

- `phone_number`: número de telefone do destinatário no formato E.164, obrigatório
- `body`: string obrigatória, de 1 a 1600 caracteres
- `estimated_cost_cents`: número inteiro positivo opcional, padrão para o custo de SMS configurado
- `idempotency_key`: string opcional, de 8 a 128 caracteres, com escopo definido por usuário
- `metadata`: objeto JSON opcional

`phone_number` é o campo destinatário de V1. Não envie `to`, a menos que uma versão futura da API o documente explicitamente.
As remessas API usam seleção automática de remetente. Os envios do aplicativo do navegador podem
escolha um número de marca conectado; Esse remetente selecionado passa a fazer parte do
solicitação de mensagem idempotente.

### curl

```bash
curl https://api.texttree.ai/api/v1/messages \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "body": "Your verification code is 482019",
    "idempotency_key": "msg_2026_04_26_0001"
  }'
```

### Respostas bem sucedidas

Mensagens recém-enfileiradas retornam `202 Accepted`:

```json
{
  "message": {
    "id": "8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb",
    "status": "queued",
    "phone_number": "+15551234567",
    "body": "Your verification code is 482019",
    "provider": "messaging_provider",
    "consent_status": "missing",
    "external_id": null,
    "estimated_cost_cents": 2,
    "idempotency_key": "msg_2026_04_26_0001",
    "metadata": {
      "campaign": "alpha-invite",
      "source": "api"
    },
    "inserted_at": "2026-04-26T20:44:12Z",
    "updated_at": "2026-04-26T20:44:12Z",
    "links": {
      "self": "/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb"
    }
  },
  "replayed": false
}
```

Se o mesmo usuário reproduzir o mesmo `idempotency_key` com a mesma carga de mensagem
e a mesma seleção de remetente, TextTree retorna `200 OK` com a mensagem existente
e `"replayed": true`.

### Respostas de erro- `422` com `{"error":"validation_failed","details":...}` quando o corpo está mal formado
- `403` com `{"error":"workspace_suppressed"}` quando o destinatário é bloqueado por uma exclusão do espaço de trabalho
- `402` com `{"error":"spend_limit_exceeded"}` quando o limite de gastos atual for excedido
- `409` com `{"error":"idempotency_conflict"}` quando uma chave idempotente é reutilizada com um
  destinatário, corpo, custo ou remetente diferente
- `422` ou detalhes de falha vinculada ao provedor quando um remetente de aplicativo selecionado não é mais
  está disponível para o espaço de trabalho

## Verifique o status de uma mensagem

`GET /api/v1/messages/:id`

Isso retorna o mesmo wrapper `message` usado nas respostas de construção.

O ciclo de vida atual de um estado de mensagem é:

-`queued`
-`dispatching`
-`sent`
-`delivered`
-`failed`
-`blocked`

`external_id` é concluído quando a execução orientada ao fornecedor tiver um identificador de fornecedor estável.

### Exemplo de status

```bash
curl https://api.texttree.ai/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"
```

```json
{
  "message": {
    "id": "8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb",
    "status": "delivered",
    "phone_number": "+15551234567",
    "estimated_cost_cents": 2,
    "links": {
      "self": "/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb"
    }
  }
}
```

## Antes de enviar

A criação da conta é iniciada automaticamente usando `POST /api/v1/accounts` e
`POST /mcp/accounts`, mas o envio de saída ainda requer a configuração do espaço de trabalho.
Antes que `POST /api/v1/messages` possa ter sucesso em um novo espaço de trabalho, o chamador ou
o operador deve:

- autenticar via TextTree e incluir um token com `messages:write`
- confirme se o destinatário não está sob exclusão ativa do espaço de trabalho
- definir um limite de gastos ativo em `/app`
- definir um remetente de teste, número de remetente ativo ou modo de envio automático

## API de números

`GET /api/v1/numbers` requer `numbers:read`.

`POST /api/v1/numbers` requer `numbers:write` e compra um número através do
Limite do provedor de mensagens TextTree. Inclui um `area_code` quando o
operadora deseja um número local. As compras ao vivo permanecem bloqueadas, a menos que a implantação
Ative explicitamente a barreira de proteção de compra de número ativo.

```bash
curl https://api.texttree.ai/api/v1/numbers \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "area_code": "415",
    "friendly_name": "Support line"
  }'
```

Compras bem-sucedidas retornam `201 Created`:

```json
{
  "number": {
    "id": "b86fbe4d-2b92-4664-8e91-d2ed1d37f827",
    "number": "+14155550123",
    "friendly_name": "Support line",
    "capabilities": ["sms"],
    "status": "connected",
    "inbound_webhook_url": "https://app.texttree.ai/webhooks/provider/incoming",
    "compliance_status": "pending"
  },
  "webhook_configured": false,
  "warning": "provider_inbound_webhook_configuration_api_not_documented"
}
```

## Limites atuais da fase alfa

A API do desenvolvedor **não** expõe atualmente:

- Endpoints CRUD herdados de metadados de consentimento/contato
- Endpoints CRUD de exclusões de espaço de trabalho
- limites de gastos nos endpoints CRUD
- criação direta de sessões de financiamento; use faturas de financiamento de integração para recargas de lançamento