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

# Introdução à API

> Autenticação, URL base e estrutura das requisições da Bliper API

## Base URL

Todas as requisições devem ser feitas para:

```
https://api.bliper.io
```

## Autenticação

A Bliper API utiliza dois mecanismos de autenticação combinados:

1. **Client-Token** — header HTTP obrigatório em todas as requisições
2. **Instance Token** — embutido na URL de cada endpoint de instância

### Client-Token

Seu token de conta, obtido no [Dashboard Bliper](https://app.bliper.ai):

```bash theme={null}
Client-Token: SEU_CLIENT_TOKEN
```

<Warning>
  Nunca exponha seu `Client-Token` em código front-end, aplicativos móveis ou repositórios públicos.
</Warning>

## Estrutura da URL

Todos os endpoints de instância seguem o padrão:

```
https://api.bliper.io/instances/{instanceId}/token/{instanceToken}/{ação}
```

### Exemplo

```bash theme={null}
curl -X GET 'https://api.bliper.io/instances/abc123/token/tok_xxxx/status' \
  -H 'Client-Token: SEU_CLIENT_TOKEN'
```

Você encontra o `instanceId` e o `instanceToken` no [Dashboard Bliper](https://app.bliper.ai) após criar uma instância — ou no retorno do endpoint de [criação de instância](/api-reference/instance/create).

<Note>
  O endpoint de criação de instância (`POST /instances`) é a única exceção — ele não usa `instanceId` e `instanceToken` na URL.
</Note>

## Codigos de Status HTTP

| Código | Significado                                          |
| ------ | ---------------------------------------------------- |
| `200`  | Sucesso — requisição processada                      |
| `202`  | Aceito — mensagem enfileirada para envio             |
| `400`  | Requisição inválida — parâmetros incorretos          |
| `401`  | Não autorizado — `Client-Token` inválido ou ausente  |
| `404`  | Não encontrado — instância ou recurso inexistente    |
| `409`  | Conflito — instância já existe ou não está conectada |
| `429`  | Muitas requisições — limite de taxa atingido         |
| `500`  | Erro interno do servidor                             |

## Resposta de Envio de Mensagem

Todos os endpoints de envio (`send-*`, `forward-message`) retornam **HTTP 202** com o seguinte formato:

```json theme={null}
{
  "messageId": "3EB0C767D02DCC481523",
  "id": "3EB0C767D02DCC481523"
}
```

| Campo       | Tipo   | Descrição                   |
| ----------- | ------ | --------------------------- |
| `messageId` | string | ID da mensagem no WhatsApp  |
| `id`        | string | Mesmo valor que `messageId` |

## Formato de Números de Telefone

Todos os números devem ser enviados no formato internacional, sem `+`, espaços ou formatação:

| Correto         | Errado                |
| --------------- | --------------------- |
| `5511999999999` | `+55 (11) 99999-9999` |
| `5511999999999` | `11999999999`         |

O código do país é obrigatório. Para o Brasil, use `55`.

## Identificadores de Grupo

Grupos do WhatsApp usam o formato `JID` com sufixo `@g.us`:

```
120363123456789@g.us
```

Este identificador é retornado pelos endpoints de grupo e deve ser usado como parâmetro `phone` ao enviar mensagens para grupos.

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar Instância" icon="server" href="/api-reference/instance/create">
    Crie sua primeira instância e conecte ao WhatsApp.
  </Card>

  <Card title="Enviar Mensagem" icon="message" href="/api-reference/messages/send-text">
    Envie sua primeira mensagem de texto.
  </Card>
</CardGroup>