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

# Visão geral da API

> API REST do LF Connect — endpoints, convenções e exemplos.

A API do LF Connect é **REST**, retorna **JSON**, autentica via header `api_access_token`
e segue padrões previsíveis em toda a base.

## Base URL

```
https://chat.lfautomatiza.com/api/v1
```

A maioria dos endpoints é **escopada por conta** (workspace) e segue o padrão:

```
/api/v1/accounts/{account_id}/{recurso}
```

## Convenções

| Aspecto         | Como funciona                                             |
| --------------- | --------------------------------------------------------- |
| Formato         | JSON em request e response                                |
| Autenticação    | Header `api_access_token`                                 |
| Identificadores | Inteiros (`account_id`, `inbox_id`, `conversation_id`...) |
| Datas           | ISO 8601 (`"2026-05-18T14:23:11.000Z"`) ou timestamp Unix |
| Paginação       | Query param `page` (1-indexed), 25 itens por página       |
| Filtros         | Query params (`?status=open&assignee_type=me`)            |
| Erros           | HTTP status code + body `{ "error": "mensagem" }`         |

## Códigos de resposta

| Código                      | Significado                    |
| --------------------------- | ------------------------------ |
| `200 OK`                    | Requisição bem-sucedida        |
| `201 Created`               | Recurso criado                 |
| `204 No Content`            | Sucesso sem corpo (DELETE)     |
| `400 Bad Request`           | Payload ou parâmetro inválido  |
| `401 Unauthorized`          | Token ausente ou inválido      |
| `403 Forbidden`             | Sem permissão pra ação         |
| `404 Not Found`             | Recurso não existe             |
| `422 Unprocessable Entity`  | Validação de negócio falhou    |
| `429 Too Many Requests`     | Rate limit estourado           |
| `500 Internal Server Error` | Erro do servidor (abre ticket) |

## Recursos disponíveis

<CardGroup cols={2}>
  <Card title="Conversas" icon="messages" href="/api-reference/conversations">
    CRUD, atribuição, labels, status, filtros avançados
  </Card>

  <Card title="Mensagens" icon="comment" href="/api-reference/messages">
    Enviar texto, mídia, templates aprovados, notas privadas
  </Card>

  <Card title="Contatos" icon="address-book" href="/api-reference/contacts">
    Criar, listar, importar CSV, segmentar, mesclar
  </Card>

  <Card title="Inboxes" icon="inbox" href="/api-reference/inboxes">
    Canais, horário comercial, agentes vinculados
  </Card>

  <Card title="Equipes e agentes" icon="users" href="/api-reference/teams-agents">
    Convidar agentes, gerenciar equipes e membros
  </Card>

  <Card title="Labels" icon="tags" href="/api-reference/labels">
    CRUD de etiquetas usadas em conversas e contatos
  </Card>

  <Card title="Atributos personalizados" icon="list" href="/api-reference/custom-attributes">
    Campos customizados pra conversas e contatos
  </Card>

  <Card title="Campanhas" icon="bullhorn" href="/api-reference/campaigns">
    One-off e ongoing, audiência por labels, agendamento
  </Card>

  <Card title="Regras de automação" icon="bolt" href="/api-reference/automation-rules">
    Evento → Condição → Ação, sem código
  </Card>

  <Card title="Macros" icon="wand-magic-sparkles" href="/api-reference/macros">
    Sequências executadas manualmente pelo agente
  </Card>

  <Card title="Respostas rápidas" icon="bolt-lightning" href="/api-reference/canned-responses">
    Textos pré-definidos com atalho `/`
  </Card>

  <Card title="Relatórios" icon="chart-line" href="/api-reference/reports">
    Métricas de conversas, agentes, equipes, CSAT
  </Card>

  <Card title="Webhooks (API)" icon="webhook" href="/api-reference/webhooks-management">
    Cadastrar e gerenciar webhooks programaticamente
  </Card>

  <Card title="Kanban" icon="kanban" href="/api-reference/kanban/funnels">
    Funis, cards, automações, importação
  </Card>
</CardGroup>

## Primeira chamada

Liste suas conversas pra confirmar que tudo está conectado:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://chat.lfautomatiza.com/api/v1/accounts/1/conversations \
    -H "api_access_token: SEU_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    'https://chat.lfautomatiza.com/api/v1/accounts/1/conversations',
    { headers: { 'api_access_token': process.env.LF_TOKEN } }
  );
  console.log(await res.json());
  ```

  ```python Python theme={null}
  import requests
  r = requests.get(
      'https://chat.lfautomatiza.com/api/v1/accounts/1/conversations',
      headers={'api_access_token': TOKEN}
  )
  print(r.json())
  ```
</CodeGroup>

Resposta esperada:

```json theme={null}
{
  "data": {
    "meta": {
      "all_count": 47,
      "mine_count": 12
    },
    "payload": [
      {
        "id": 123,
        "status": "open",
        "contact": {
          "name": "Carlos Antônio",
          "phone_number": "+5521999544338"
        },
        "messages_count": 4
      }
    ]
  }
}
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="/essentials/authentication">
    Como pegar token e enviar nas requisições
  </Card>

  <Card title="Rate limits" icon="gauge" href="/essentials/rate-limits">
    Tetos, headers e como evitar 429
  </Card>

  <Card title="Webhooks" icon="webhook" href="/essentials/webhooks">
    Reagir a eventos em tempo real
  </Card>

  <Card title="API Kanban" icon="kanban" href="/api-reference/kanban/funnels">
    Pipeline comercial via API
  </Card>
</CardGroup>