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

# Contatos

> Endpoints para criar, atualizar contatos e gerenciar etiquetas (tags).

# Contatos

API dedicada para gerenciar contatos da sua instância. Todos os endpoints **criam o contato automaticamente** se o telefone informado ainda não existir na base.

<Note>
  Todos os endpoints requerem o header `X-Client-Token`. Veja [Autenticação](/api/autenticacao).
</Note>

## Base URL

```
https://wapi.stegia.com.br/functions/v1/contacts-api
```

***

## Criar Contato

```
POST /contacts-api/create
```

Cria um novo contato com dados completos. Se já existir (por `phone + instanceId`), os campos enviados são **atualizados** (idempotente).

### Parâmetros

| Campo          | Tipo           | Obrigatório | Descrição                                                |
| -------------- | -------------- | ----------- | -------------------------------------------------------- |
| `instanceId`   | string         | ✅           | ID da instância                                          |
| `phone`        | string         | ✅           | Número (formato: `5511999999999`)                        |
| `name`         | string         | ❌           | Nome do contato                                          |
| `email`        | string         | ❌           | E-mail                                                   |
| `company`      | string         | ❌           | Empresa                                                  |
| `jobTitle`     | string         | ❌           | Cargo                                                    |
| `notes`        | string         | ❌           | Anotações livres                                         |
| `tags`         | array\<string> | ❌           | Nomes de etiquetas (cria automaticamente se não existir) |
| `utmSource`    | string         | ❌           | Origem UTM                                               |
| `utmMedium`    | string         | ❌           | Meio UTM                                                 |
| `utmCampaign`  | string         | ❌           | Campanha UTM                                             |
| `customLabels` | object         | ❌           | Campos customizados (chave/valor)                        |

### Exemplo

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/contacts-api/create" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "name": "João Silva",
    "email": "joao@email.com",
    "company": "ACME Corp",
    "jobTitle": "Diretor",
    "notes": "Lead vindo do evento X",
    "tags": ["vip", "lead-quente"],
    "utmSource": "google",
    "customLabels": { "segmento": "premium", "tier": "ouro" }
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "action": "created",
  "contactId": "uuid-do-contato",
  "tagsApplied": ["vip", "lead-quente"]
}
```

***

## Atualizar Contato

```
POST /contacts-api/update
```

Atualiza campos de um contato existente. Se não existir, é criado. **Tags são adicionadas, não substituem** as existentes.

### Parâmetros

Mesmos campos do `/create`, mais:

| Campo        | Tipo    | Obrigatório | Descrição            |
| ------------ | ------- | ----------- | -------------------- |
| `isFavorite` | boolean | ❌           | Marcar como favorito |
| `isArchived` | boolean | ❌           | Arquivar             |
| `isBlocked`  | boolean | ❌           | Bloquear             |

### Exemplo

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/contacts-api/update" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "company": "Nova Empresa LTDA",
    "notes": "Atualizado via integração CRM",
    "tags": ["cliente-ativo"]
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "action": "updated",
  "contactId": "uuid-do-contato",
  "fieldsUpdated": ["company", "notes"],
  "tagsApplied": ["cliente-ativo"]
}
```

***

## Gerenciar Etiquetas

```
POST /contacts-api/tags
```

Adiciona e/ou remove etiquetas de um contato em uma única chamada.

### Parâmetros

| Campo        | Tipo           | Obrigatório | Descrição                                      |
| ------------ | -------------- | ----------- | ---------------------------------------------- |
| `instanceId` | string         | ✅           | ID da instância                                |
| `phone`      | string         | ✅           | Número do contato                              |
| `addTags`    | array\<string> | ❌           | Etiquetas para adicionar (cria se não existir) |
| `removeTags` | array\<string> | ❌           | Etiquetas para remover                         |

### Exemplo

```bash theme={null}
curl -X POST "https://wapi.stegia.com.br/functions/v1/contacts-api/tags" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "addTags": ["vip", "convertido"],
    "removeTags": ["lead-frio"]
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "contactId": "uuid-do-contato",
  "tagsApplied": ["vip", "convertido"],
  "tagsRemoved": ["lead-frio"]
}
```

***

## Comportamentos Automáticos

<AccordionGroup>
  <Accordion title="Auto-criação de Contato">
    Se o `phone` informado não existir na sua instância, o sistema **cria automaticamente** um novo contato com `origin: "api"` antes de aplicar quaisquer outras operações (atualização, tags, etc).
  </Accordion>

  <Accordion title="Etiquetas por Nome">
    O parâmetro `tags` aceita **nomes** (strings), não UUIDs. Se a etiqueta não existir na instância, ela é criada automaticamente com uma cor aleatória e fica disponível para uso futuro no painel.
  </Accordion>

  <Accordion title="Idempotência">
    O endpoint `/create` é seguro para chamar múltiplas vezes — se o contato já existir, ele apenas atualiza os campos enviados sem duplicar registros.
  </Accordion>

  <Accordion title="Variantes de Telefone">
    O sistema reconhece automaticamente variações do número brasileiro (com/sem nono dígito), garantindo que `5511999999999` e `551199999999` sejam tratados como o mesmo contato.
  </Accordion>
</AccordionGroup>