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.

Todos os endpoints requerem o header X-Client-Token. Veja Autenticação.

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

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

{
  "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

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

{
  "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

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

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

Comportamentos Automáticos

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).

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.

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.

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.

​Contatos

​Base URL

​Criar Contato

​Parâmetros

​Exemplo

​Resposta

​Atualizar Contato

​Parâmetros

​Exemplo

​Resposta

​Gerenciar Etiquetas

​Parâmetros

​Exemplo

​Resposta

​Comportamentos Automáticos

Contatos

Base URL

Criar Contato

Parâmetros

Exemplo

Resposta

Atualizar Contato

Parâmetros

Exemplo

Resposta

Gerenciar Etiquetas

Parâmetros

Exemplo

Resposta

Comportamentos Automáticos