# Oratrix API - Mensagens Avancadas

## Status

Documentacao parcial baseada na parte enviada para o projeto Wezapp Shots.

Este grupo contem endpoints de mensagens especiais dependentes de `ticketId`, como localizacao, vCard e busca em mensagens de um ticket.

Para o Wezapp Shots, sao recursos auxiliares. O envio principal de campanha deve continuar baseado em endpoints de mensagem por numero ou fluxo interno de disparo.

## Base URL

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}
```

## Autenticacao

```http
Authorization: Bearer {token}
```

## Endpoints do grupo

Total documentado nesta parte: 3 endpoints.

---

## 1. Enviar localizacao

```http
POST /sendLocation
```

Nome na documentacao Oratrix:

```text
SendLocation
```

Descricao:

Enviar localizacao geografica para um contato.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/sendLocation
```

Body JSON:

```json
{
  "ticketId": 1262,
  "latitude": -23.5505,
  "longitude": -46.6333,
  "name": "Sao Paulo",
  "address": "Av. Paulista, 1000"
}
```

---

## 2. Enviar vCard

```http
POST /sendVcard
```

Nome na documentacao Oratrix:

```text
SendVcard
```

Descricao:

Enviar contato em formato vCard para um ticket.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/sendVcard
```

Body JSON:

```json
{
  "ticketId": 1262,
  "contact": {
    "name": "Nome Contato",
    "number": "5511999999999",
    "email": "contato@email.com"
  }
}
```

---

## 3. Buscar mensagens em um ticket

```http
GET /searchMessages
```

Nome na documentacao Oratrix:

```text
SearchMessages
```

Descricao:

Buscar mensagens por texto dentro de um ticket.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/searchMessages
```

Query params:

| Parametro | Obrigatorio | Descricao | Exemplo |
|---|---:|---|---|
| ticketId | Sim | ID do ticket | 1262 |
| searchParam | Sim | Texto para busca | ola |

## Mapeamento sugerido com Wezapp Shots

| Wezapp Shots | Oratrix |
|---|---|
| Ticket externo futuro | `ticketId` |
| Mensagem de localizacao futura | `/sendLocation` |
| Mensagem de contato futura | `/sendVcard` |
| Auditoria/diagnostico de conversa | `/searchMessages` |

## Observacoes para arquitetura

Estes endpoints dependem de `ticketId`, logo parecem exigir conversa/ticket existente no Oratrix.

Para campanhas em massa, devem ser tratados como recursos complementares, nao como fluxo principal de disparo.

## Pendencias tecnicas para validar

- Confirmar se `ticketId` e obrigatorio em `/sendLocation` e `/sendVcard`.
- Confirmar se localizacao pode ser enviada por numero sem ticket.
- Confirmar se vCard pode ser enviado por numero sem ticket.
- Confirmar formato de retorno de `/searchMessages`.
- Confirmar se `/searchMessages` possui paginacao.
- Confirmar se busca diferencia maiusculas/minusculas e acentos.

## Regras recomendadas para o Wezapp Shots

1. Usar apenas quando houver ticket externo valido.
2. Nao usar como base do disparo principal.
3. Registrar payload e resposta em logs internos quando acionado pelo Wezapp.
4. Tratar busca de mensagens como recurso de diagnostico/conciliacao, nao como fonte primaria de status de shot.