# Oratrix API - Tickets

## Status

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

Este grupo trata criacao, consulta, atualizacao e organizacao de tickets no Oratrix.

Para o **Wezapp Shots**, tickets sao relevantes quando o envio precisa abrir conversa, criar atendimento, registrar mensagens, encaminhar para fila ou permitir interacoes posteriores.

## 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: 17 endpoints.

---

## 1. Criar ticket de atendimento

```http
POST /createTicket
```

Nome na documentacao Oratrix:

```text
CreateTicket
```

Descricao:

Criar ticket de atendimento. Suporta WhatsApp e Webmail.

URL completa:

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

Body JSON:

```json
{
  "body": "Mensagem inicial",
  "number": "5511999999999",
  "externalKey": "chave-001",
  "userId": 1,
  "status": "pending",
  "queueId": null,
  "kanbanId": null,
  "chatFlowId": null,
  "reasonId": null,
  "value": null
}
```

---

## 2. Criar ticket via Webmail

```http
POST /createTicket
```

Nome na documentacao Oratrix:

```text
CreateTicketWebmail
```

Descricao:

Criar ticket via canal Webmail.

URL completa:

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

Body JSON:

```json
{
  "body": "Mensagem via email",
  "email": "contato@exemplo.com",
  "channelId": 17841443941506796,
  "externalKey": "chave-001",
  "userId": 1,
  "status": "pending",
  "name": "Nome do Contato"
}
```

---

## 3. Criar ticket com arquivo

```http
POST /createTicket
```

Nome na documentacao Oratrix:

```text
CreateTicketFile
```

Descricao:

Criar ticket enviando um arquivo via `multipart/form-data`. Suporta imagem, documento e outros formatos.

URL completa:

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

Body:

```text
Form Data
```

Campos:

| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---:|---|
| media | file | Sim | Arquivo a ser enviado |
| body | Texto | Nao | Texto da mensagem inicial |
| number | Texto | Nao | Numero WhatsApp |
| externalKey | Texto | Sim | Chave unica de controle |
| userId | ID | Nao | Usuario responsavel |
| status | Texto | Nao | Status inicial, exemplo `pending` |
| queueId | ID | Nao | Fila |
| kanbanId | ID | Nao | Kanban |
| chatFlowId | ID | Nao | Fluxo de chat |
| channelId | ID | Nao | Canal, opcional para webmail |
| email | Texto | Nao | Email, opcional para webmail |
| name | Texto | Nao | Nome, opcional para webmail |

---

## 4. Alterar fila do ticket

```http
POST /updatequeue
```

Nome na documentacao Oratrix:

```text
SetQueue
```

Descricao:

Definir ou alterar a fila de atendimento de um ticket.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 4,
  "queueId": 1
}
```

---

## 5. Definir tag principal do ticket

```http
POST /updatetag
```

Nome na documentacao Oratrix:

```text
SetTag
```

Descricao:

Definir a tag principal de um ticket.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 4,
  "tag": 1
}
```

---

## 6. Atualizar informacoes completas do ticket

```http
POST /updateticketinfo
```

Nome na documentacao Oratrix:

```text
SetTicketInfo
```

Descricao:

Atualizar informacoes completas de um ticket.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 1262,
  "userId": 1,
  "status": "pending",
  "queueId": null,
  "typebotStatus": false,
  "chatgptStatus": false,
  "dialogflowStatus": false,
  "difyStatus": false,
  "n8nStatus": false,
  "chatFlowId": null
}
```

---

## 7. Buscar ticket mais recente de contato

```http
POST /showticket
```

Nome na documentacao Oratrix:

```text
ShowTicketInformation
```

Descricao:

Buscar informacoes do ticket mais recente de um contato.

URL completa:

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

Body JSON:

```json
{
  "number": "5511999999999"
}
```

---

## 8. Buscar ticket ativo de contato em contexto chatbot

```http
POST /showticketchatbot
```

Nome na documentacao Oratrix:

```text
ShowTicketInformationChatBot
```

Descricao:

Buscar ticket ativo de um contato em contexto chatbot.

URL completa:

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

Body JSON:

```json
{
  "number": "5511999999999"
}
```

---

## 9. Buscar todos os tickets de contato

```http
POST /showallticket
```

Nome na documentacao Oratrix:

```text
ShowAllTicketInformation
```

Descricao:

Buscar todos os tickets de um contato pelo numero.

URL completa:

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

Body JSON:

```json
{
  "number": "5511999999999"
}
```

---

## 10. Listar todas as mensagens de um ticket

```http
POST /showAllMessages
```

Nome na documentacao Oratrix:

```text
ShowAllMessages
```

Descricao:

Listar todas as mensagens de um ticket.

URL completa:

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

Body JSON:

```json
{
  "ticket": "123"
}
```

---

## 11. Alterar canal do ticket

```http
POST /updateTicketChannel
```

Nome na documentacao Oratrix:

```text
UpdateTicketChannel
```

Descricao:

Alterar o canal WhatsApp de um ticket existente.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 1262,
  "whatsappId": 1,
  "channel": "whatsapp"
}
```

---

## 12. Criar nota interna

```http
POST /createNotes
```

Nome na documentacao Oratrix:

```text
CreateNotes
```

Descricao:

Criar uma nota interna em um ticket.

URL completa:

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

Body JSON:

```json
{
  "notes": "Conteudo da nota",
  "ticketId": 1262,
  "userId": 1,
  "idFront": "ID_UNICA_NOTA_001"
}
```

---

## 13. Atualizar nota interna

```http
POST /updateNote
```

Nome na documentacao Oratrix:

```text
UpdateNote
```

Descricao:

Atualizar o conteudo de uma nota existente.

URL completa:

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

Body JSON:

```json
{
  "noteId": 1,
  "notes": "Conteudo atualizado"
}
```

---

## 14. Listar notas de ticket

```http
GET /listNotes
```

Nome na documentacao Oratrix:

```text
ListNotes
```

Descricao:

Listar todas as notas de um ticket.

URL completa:

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

Query params:

| Parametro | Obrigatorio | Descricao | Exemplo |
|---|---:|---|---|
| ticketId | Sim | ID do ticket | 1262 |

---

## 15. Adicionar tag ao ticket

```http
POST /addTag
```

Nome na documentacao Oratrix:

```text
AddTag
```

Descricao:

Adicionar uma ou mais tags a um ticket.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 4,
  "tagId": 1
}
```

Observacao:

A descricao fala em uma ou mais tags, mas o exemplo mostra apenas `tagId` unico. Validar se aceita array.

---

## 16. Remover tag do ticket

```http
POST /removeTag
```

Nome na documentacao Oratrix:

```text
RemoveTag
```

Descricao:

Remover uma ou mais tags de um ticket.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 4,
  "tagId": 1
}
```

Observacao:

A descricao fala em uma ou mais tags, mas o exemplo mostra apenas `tagId` unico. Validar se aceita array.

---

## 17. Enviar estado de presenca

```http
POST /sendPresence
```

Nome na documentacao Oratrix:

```text
SendPresence
```

Descricao:

Enviar estado de presenca, como digitando ou gravando.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 1262,
  "state": "typing"
}
```

## Mapeamento sugerido com Wezapp Shots

| Wezapp Shots | Oratrix |
|---|---|
| `wezapp_dispatch_items.external_ticket_id` futuro | `ticketId` |
| `wezapp_dispatch_items.external_key` futuro | `externalKey` |
| Fila de atendimento futura | `queueId` |
| Tag externa futura | `tagId` |
| Canal externo | `whatsappId` ou `channelId` |
| Logs de atendimento | Ticket e mensagens do Oratrix |

## Observacoes para arquitetura

Tickets nao devem ser o controlador principal de saldo de shots.

O ticket e uma entidade operacional externa do Oratrix. O Wezapp deve registrar o vinculo quando necessario, mas o controle de campanha, saldo, job e item continua interno.

## Pendencias tecnicas para validar

- Confirmar formato de retorno de `/createTicket`.
- Confirmar se `/createTicket` retorna `ticketId`, `messageId` e/ou identificador externo.
- Confirmar comportamento de `externalKey` repetida.
- Confirmar se `number` e obrigatorio para WhatsApp e `email` para Webmail.
- Confirmar status validos para ticket.
- Confirmar se `showticket` retorna o mais recente mesmo encerrado ou apenas ativo.
- Confirmar diferenca entre `showticket` e `showticketchatbot`.
- Confirmar formato de retorno de `showAllMessages`.
- Confirmar se `showAllMessages` possui paginacao.
- Confirmar se `addTag` e `removeTag` aceitam array de tags.
- Confirmar estados validos em `sendPresence` alem de `typing`.

## Regras recomendadas para o Wezapp Shots

1. Criar ticket apenas quando a campanha exigir atendimento/conversa.
2. Nao criar ticket desnecessariamente para disparo simples em massa.
3. Guardar `ticketId` externo quando retornado.
4. Usar `externalKey` unica para rastreabilidade.
5. Registrar request e response em logs internos.
6. Nao recalcular saldo com base em tickets externos.
7. Proteger alteracoes de fila, tag, canal e info do ticket por permissao/auditoria.