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

# Primeiros passos com a API

> Como gerar um token e fazer sua primeira chamada na API do IPBoX

## O que é a API do IPBoX

A API do IPBoX permite que sistemas externos (um CRM, uma ferramenta de
discagem, um painel próprio) conversem diretamente com o IPBoX: efetuar
login/logout de um agente, colocar uma ligação em pausa, consultar
prospects, listas, filas, relatórios, e muito mais.

Toda a API é acessada por chamadas **POST**, com resposta em **JSON**.

## Passo 1 — Gerar um token de acesso

1. No IPBoX, acesse **IPBoX > API > Token**.
2. Clique em **Inserir** para criar um novo token.
3. Copie o token gerado — ele é a sua credencial de acesso e não deve
   ser compartilhado.

## Passo 2 — Fazer sua primeira chamada

Cada ação da API tem sua própria URL, no formato
`https://SEU_DOMINIO_IPBOX:PORTA/ipbox/api/{ação}`. O token vai no header
`Authorization` (aceita `Bearer SEU_TOKEN`, `Basic SEU_TOKEN` ou o token
puro).

<Warning>
  A maioria dos servidores IPBoX usa uma **porta específica** (não a
  porta padrão 443/HTTPS). Inclua a porta junto ao domínio, do jeito que
  você acessa o painel — por exemplo:
  `https://cliente.ipboxcloud.com.br:9052/ipbox/api/login`.
</Warning>

Exemplo — efetuar login de um agente:

```bash theme={null}
curl -X POST "https://SEU_DOMINIO_IPBOX:PORTA/ipbox/api/login" \
  -H "Authorization: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "user=1001&senha=SENHA_DO_AGENTE&time=3"
```

| Parâmetro | Obrigatório | Descrição                                                                           |
| --------- | ----------- | ----------------------------------------------------------------------------------- |
| `user`    | Sim         | Login/username do agente                                                            |
| `senha`   | Sim         | Senha do agente                                                                     |
| `time`    | Sim         | ID do time do agente — use o endpoint `getTime` para consultar os times cadastrados |
| `ramal`   | Não         | Ramal do agente (ex.: `2000`)                                                       |
| `ip`      | Não         | IP da máquina do agente — se não informado, é capturado automaticamente             |

Uma resposta de sucesso tem esse formato:

```json theme={null}
{
  "data": {
    "type": "agente",
    "id": 42
  }
}
```

## Próximos passos

* Veja a [Referência da API](/api-reference) completa, com todos os
  endpoints disponíveis (login, pausas, prospects, filas, relatórios e
  mais).
* Se você quer ser avisado **em tempo real** quando o estado de um
  agente muda (sem precisar ficar consultando a API), veja o guia de
  [Webhooks](/guides/webhooks).