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

# Visão Geral da API

> Aprenda como usar a Oxenty API para integrar WhatsApp ao seu sistema

A Oxenty API é uma API REST que permite enviar e receber mensagens do WhatsApp, gerenciar sessões, contatos e grupos de forma programática.

## Base URL

Todas as requisições devem ser feitas para:

```
https://api.oxenty.api.br/api
```

## Formato de Requisições

A API aceita requisições em formato **JSON**. Sempre inclua o header:

```
Content-Type: application/json
```

## Autenticação

Todas as requisições precisam de autenticação via API Key.

<CardGroup cols={2}>
  <Card title="API Key" icon="key" href="/authentication">
    Para integrações server-to-server. Crie no dashboard e use no header `X-API-Key`.
  </Card>
</CardGroup>

### Exemplo com API Key

```bash theme={"system"}
curl -X GET "https://api.oxenty.api.br/api/sessions" \
  -H "X-API-Key: ox_live_abc123..."
```

## Formato de Respostas

Todas as respostas são em JSON. Uma resposta de sucesso típica:

```json theme={"system"}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Minha Sessão",
    "status": "connected"
  }
}
```

Uma resposta de erro:

```json theme={"system"}
{
  "statusCode": 400,
  "message": "Sessão não encontrada",
  "error": "Bad Request"
}
```

## Códigos de Status HTTP

| Código | Descrição                                     |
| ------ | --------------------------------------------- |
| `200`  | Requisição bem-sucedida                       |
| `201`  | Recurso criado com sucesso                    |
| `400`  | Requisição inválida (verifique os parâmetros) |
| `401`  | Não autenticado (token inválido ou expirado)  |
| `403`  | Sem permissão para este recurso               |
| `404`  | Recurso não encontrado                        |
| `429`  | Rate limit excedido                           |
| `500`  | Erro interno do servidor                      |

## Paginação

Endpoints que retornam listas suportam paginação:

```bash theme={"system"}
GET /api/sessions?page=1&limit=20
```

A resposta inclui metadados de paginação:

```json theme={"system"}
{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}
```

## Rate Limits

A API possui limites de requisições por minuto baseados no seu plano:

| Plano        | Requisições/min |
| ------------ | --------------- |
| Free         | 60              |
| Starter      | 300             |
| Professional | 1000            |
| Enterprise   | Ilimitado       |

Quando exceder o limite, você receberá status `429` com o header:

```
X-RateLimit-Reset: 1703952000
```

## SDKs Disponíveis

<CardGroup cols={2}>
  <Card title="Node.js/TypeScript" icon="package" href="https://www.npmjs.com/package/oxenty-sdk">
    SDK oficial: <code>
    oxenty-sdk</code>
  </Card>

  <Card title="Repositório" icon="code" href="https://github.com/jobasfernandes/oxenty-sdk">
    Código-fonte e issues
  </Card>
</CardGroup>

### Instalação do SDK

<CodeGroup>
  ```bash npm theme={"system"}
  npm install oxenty-sdk
  ```

  ```bash yarn theme={"system"}
  yarn add oxenty-sdk
  ```

  ```bash pnpm theme={"system"}
  pnpm add oxenty-sdk
  ```
</CodeGroup>

### Uso Básico

```typescript theme={"system"}
import { OxentyClient } from 'oxenty-sdk'

const client = new OxentyClient({
  baseUrl: 'https://api.oxenty.api.br',
  apiKey: 'ox_live_abc123...',
});

// Listar sessões
const sessions = await client.sessions.list();

// Enviar mensagem
await client.messages.sendText({
  sessionId: 'session-id',
  to: '5511999999999',
  text: 'Olá!',
});
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="shield" href="/authentication">
    Configure sua API Key
  </Card>

  <Card title="Criar Sessão" icon="smartphone" href="/api-reference/sessions/create">
    Conecte seu WhatsApp
  </Card>

  <Card title="Enviar Mensagens" icon="message-square" href="/api-reference/messages/overview">
    Envie sua primeira mensagem
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Receba eventos em tempo real
  </Card>
</CardGroup>