YAS Conversas API v1

Para a IA (ou outro sistema) atender, consultar e atualizar clientes no CRM da YAS.

Acesso

Crie uma chave em ⚙ Administração → Integrações (API). Envie em todo pedido:

Authorization: Bearer yas_xxxxxxxxxxxxxxxx
Content-Type: application/json

Endereço base: https://conversas.yasmoveis.com.br/api/v1. Tudo o que a API faz aparece na linha do tempo como Robô (IA). O cliente é identificado pelo telefone (:tel), comparado pelos 8 últimos dígitos.

Rotas

Método	Rota	O que faz
GET	`/conversas`	Lista conversas (`?status=aberta\|pendente\|resolvida\|todas&busca=`)
GET	`/conversas/:tel`	Conversa, últimas mensagens, campos, etiquetas e agenda
POST	`/conversas/:tel/mensagens`	Envia mensagem ao cliente: `{"texto": "..."}` (só dentro da janela de 24h)
POST	`/conversas/:tel/notas`	Nota interna (o cliente não vê): `{"texto": "..."}`
POST	`/conversas/:tel/ia`	Liga/desliga a IA na conversa: `{"ativa": true}`
POST	`/conversas/:tel/transferir`	Passa para humano/setor: `{"setor": "Venda", "responsavel_email": "...", "nota": "..."}`
POST	`/conversas/:tel/info`	Campos e etiquetas: `{"campos": {"ambientes": "Cozinha", "metragem": "12"}, "etiquetas": ["Quente"]}` (etiquetas substituem a lista)
GET	`/midia/:id`	Baixa o arquivo de uma mensagem (áudio, foto, vídeo, PDF) pelo id da mensagem
GET	`/campos`	Lista os campos (chave, nome, tipo, opções)
POST	`/conversas/:tel/tarefas`	Agenda: `{"tipo": "visita\|medicao\|ligacao\|follow-up\|outro", "quando": "2026-11-10T14:00:00-03:00", "loja": "Mooca", "responsavel_email": "...", "observacao": "..."}`
GET	`/tarefas`	Agenda geral (`?de=AAAA-MM-DD&ate=AAAA-MM-DD&status=pendente`)
PATCH	`/tarefas/:id`	`{"status": "feita\|cancelada\|pendente"}` ou `{"quando": "..."}`
GET	`/crm/config`	Lojas, vendedores, origens, etapas, motivos e SDRs do sistema SDR
GET	`/conversas/:tel/lead`	Lead(s) do cliente no SDR
POST	`/conversas/:tel/lead`	Cria/atualiza o lead no SDR: `{"id": 123, "etapa_id": 4, "loja_id": 2, "valor_orcamento": "25000"}`. Loja sem vendedor = rodízio da loja.

Webhooks (o CRM avisa a IA)

Cadastre a URL em Integrações (API). A cada evento o CRM faz um POST com JSON e o cabeçalho X-YAS-Assinatura: sha256=<HMAC do corpo com o segredo>. Tenta de novo até 3 vezes se falhar.

Eventos: mensagem.recebida, mensagem.enviada, nota.criada, conversa.atribuida, conversa.transferida, ia.alterada, lead.atualizado, tarefa.criada, tarefa.atualizada, contato.atualizado.

{
  "evento": "mensagem.recebida",
  "quando": "2026-11-06T18:00:00.000Z",
  "contato": { "telefone": "5511999998888", "nome": null, "nome_whatsapp": "Maria", "origem": "Google Ads",
               "campos": {}, "ia_ativa": true, "setor_id": 5, "responsavel_id": 3 },
  "conversa_id": 42,
  "mensagem": { "id": 901, "direcao": "entrada", "tipo": "texto", "texto": "Quero orçamento de cozinha" }
}

Regra de passagem: quando um humano responde o cliente, a IA é desligada sozinha naquela conversa (evento ia.alterada). A IA só deve responder quando contato.ia_ativa for true.

Exemplo

curl -X POST https://conversas.yasmoveis.com.br/api/v1/conversas/11999998888/tarefas \
  -H "Authorization: Bearer yas_..." -H "Content-Type: application/json" \
  -d '{"tipo":"visita","quando":"2026-11-10T14:00:00-03:00","loja":"Mooca","observacao":"Leva a planta"}'