# Contatos

> Criar, buscar, editar e apagar contatos.

Contatos são as pessoas que falam com a sua organização. O telefone é único por organização (com ou sem o nono dígito): repetir dá `409 telefone_repetido`.

- Busque por `busca` (parte do nome ou do telefone, ou o e-mail exato), `telefone` ou `email`.
- `campos` guarda campos personalizados (objeto livre, até 16 mil caracteres): convênio, plano, código no seu sistema...
- No `PATCH`, mande só o que muda; `null` apaga o valor.
- Apagar um contato apaga junto as conversas dele. Não tem volta.

**Códigos de erro comuns aqui**: `contato_inexistente`, `telefone_invalido`, `telefone_repetido`, `cursor_invalido` (todos em [Erros](https://docs.forsi.com.br/erros)).

## GET /contatos — Listar e buscar contatos

- URL: `GET https://chat.forsi.com.br/api/v1/contatos`
- Acesso: escopo `contatos:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com lista de `Contato` (paginada por cursor)
- Página: https://docs.forsi.com.br/api/contatos/listar-contatos (Markdown: https://docs.forsi.com.br/api/contatos/listar-contatos.md)

Busca por telefone acha com e sem o 9º dígito.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `busca` | string | não | Parte do nome ou do telefone, ou o e-mail exato. até 100 caracteres |
| `telefone` | string | não | Com DDI e DDD. Acha o contato com ou sem o 9º dígito. mín. 8 caracteres até 30 caracteres ex.: +55 31 98888-7777 |
| `email` | string | não | até 254 caracteres |
| `limite` | integer | não | Itens por página (1 a 100, padrão 50). |
| `cursor` | string | não | Valor de `proximo` da página anterior. até 80 caracteres |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/contatos?telefone=31988887777" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": [
    {
      "id": "08054a7f-a752-481e-9915-cf4cf944df39",
      "nome": "Maria Souza",
      "nome_whatsapp": "Maria",
      "telefone": "+5531988887777",
      "email": "maria@exemplo.com.br",
      "instagram": "maria.souza",
      "campos": {"convenio":"Unimed"},
      "bloqueado": false,
      "criado_em": "2026-10-04T13:05:12.481Z",
      "atualizado_em": "2026-10-04T13:05:12.481Z",
      "primeiro_anuncio": {
        "anuncio_id": "texto",
        "titulo": "Consulta de retorno",
        "canal": "whatsapp",
        "clicado_em": "2026-10-04T13:05:12.481Z"
      }
    }
  ],
  "proximo": "1791205512481_3791c08d-72dd-4002-89ff-1e14a11c07e5"
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## POST /contatos — Criar contato

- URL: `POST https://chat.forsi.com.br/api/v1/contatos`
- Acesso: escopo `contatos:escrever` · módulo do plano: API · aceita `Idempotency-Key`
- Sucesso: `201`, `{"dados": ...}` com `Contato`
- Página: https://docs.forsi.com.br/api/contatos/criar-contato (Markdown: https://docs.forsi.com.br/api/contatos/criar-contato.md)

Telefone repetido (com ou sem o 9) dá 409.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `nome` | string ou null | não |  |
| `telefone` | string ou null | não |  |
| `email` | string ou null | não |  |
| `instagram` | string ou null | não |  |
| `campos` | objeto livre | não | Campos personalizados (objeto livre, até 16 mil caracteres). |

**Exemplo (curl)**

```bash
curl -X POST "https://chat.forsi.com.br/api/v1/contatos" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{
    "nome": "Maria Souza",
    "telefone": "+55 31 98888-7777",
    "email": "maria@exemplo.com.br",
    "campos": {"convenio":"Unimed"}
  }'
```

**Resposta `201` (exemplo)**

```json
{
  "dados": {
    "id": "08054a7f-a752-481e-9915-cf4cf944df39",
    "nome": "Maria Souza",
    "nome_whatsapp": "Maria",
    "telefone": "+5531988887777",
    "email": "maria@exemplo.com.br",
    "instagram": "maria.souza",
    "campos": {"convenio":"Unimed"},
    "bloqueado": false,
    "criado_em": "2026-10-04T13:05:12.481Z",
    "atualizado_em": "2026-10-04T13:05:12.481Z",
    "primeiro_anuncio": {
      "anuncio_id": "texto",
      "titulo": "Consulta de retorno",
      "canal": "whatsapp",
      "clicado_em": "2026-10-04T13:05:12.481Z"
    }
  }
}
```

**Erros**: `401`, `403`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## GET /contatos/{id} — Ver um contato

- URL: `GET https://chat.forsi.com.br/api/v1/contatos/{id}`
- Acesso: escopo `contatos:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Contato`
- Página: https://docs.forsi.com.br/api/contatos/ver-contato (Markdown: https://docs.forsi.com.br/api/contatos/ver-contato.md)

Contato mesclado responde com o que ficou.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/contatos/08054a7f-a752-481e-9915-cf4cf944df39" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200`**: mesmo formato do exemplo de `Contato` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## PATCH /contatos/{id} — Atualizar contato

- URL: `PATCH https://chat.forsi.com.br/api/v1/contatos/{id}`
- Acesso: escopo `contatos:escrever` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Contato`
- Página: https://docs.forsi.com.br/api/contatos/atualizar-contato (Markdown: https://docs.forsi.com.br/api/contatos/atualizar-contato.md)

Só os campos enviados mudam; null apaga o campo.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `nome` | string ou null | não |  |
| `telefone` | string ou null | não |  |
| `email` | string ou null | não |  |
| `instagram` | string ou null | não |  |
| `campos` | objeto livre | não | Campos personalizados (objeto livre, até 16 mil caracteres). |

**Exemplo (curl)**

```bash
curl -X PATCH "https://chat.forsi.com.br/api/v1/contatos/08054a7f-a752-481e-9915-cf4cf944df39" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria.souza@exemplo.com.br",
    "campos": {"convenio":"Particular"}
  }'
```

**Resposta `200`**: mesmo formato do exemplo de `Contato` acima (campos em "Objetos das respostas").

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## DELETE /contatos/{id} — Apagar contato

- URL: `DELETE https://chat.forsi.com.br/api/v1/contatos/{id}`
- Acesso: escopo `contatos:escrever` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com `Apagado`
- Página: https://docs.forsi.com.br/api/contatos/apagar-contato (Markdown: https://docs.forsi.com.br/api/contatos/apagar-contato.md)

Apaga o contato e as conversas dele. Não tem volta.

**Parâmetros no caminho**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | sim | No caminho da URL. |

**Exemplo (curl)**

```bash
curl -X DELETE "https://chat.forsi.com.br/api/v1/contatos/08054a7f-a752-481e-9915-cf4cf944df39" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{"dados":{"apagado":false,"conversas_apagadas":1}}
```

**Erros**: `401`, `403`, `404`, `409`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## Objetos das respostas

Campos de cada objeto devolvido em `dados`. Campos novos podem aparecer: ignore os que não conhecer.

### Contato

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `nome` | string ou null | não |  |
| `nome_whatsapp` | string ou null | não |  |
| `telefone` | string ou null | não |  |
| `email` | string ou null | não |  |
| `instagram` | string ou null | não |  |
| `campos` | objeto livre | não |  |
| `bloqueado` | boolean | não |  |
| `criado_em` | data e hora ISO 8601 | não |  |
| `atualizado_em` | data e hora ISO 8601 | não |  |
| `primeiro_anuncio` | object ou null | não | Primeiro anúncio que levou a pessoa ao WhatsApp, Instagram ou Messenger. |
| `primeiro_anuncio.anuncio_id` | string ou null | não |  |
| `primeiro_anuncio.titulo` | string ou null | não |  |
| `primeiro_anuncio.canal` | string | não |  |
| `primeiro_anuncio.clicado_em` | data e hora ISO 8601 | não |  |

### Apagado

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `apagado` | boolean | não |  |
| `conversas_apagadas` | integer | não |  |

---

Página: https://docs.forsi.com.br/api/contatos · Índice: https://docs.forsi.com.br/llms.txt · Tudo num arquivo: https://docs.forsi.com.br/llms-full.txt