Saltar para o conteúdo

Tickets

Caixa de entrada partilhada, formulários e automações para pedidos de clientes.

Abrir Tickets
Verificado com o painel em 18 de novembro de 2026

A API de tickets permite que software exterior à Xuda trabalhe um balcão: abrir um ticket, listar e ler tickets, responder, atribuir, mover um ticket entre fases e fechá-lo, e ler os tópicos e a equipa. Os formulários, os fluxos de trabalho, os agentes de IA, as notas internas e as definições ficam no dashboard.

Cada chamada é um POST para https://xuda.ai/cpi/<method> com um corpo JSON que leva a chave de API da sua conta como api_key. Uma chamada funciona no balcão da conta que é dona da chave, ao abrigo do plano desse balcão, e não pode indicar outro balcão. Crie a chave no dashboard, em Programadores, e mantenha-a fora de páginas e de código público.

A resposta é { "code": ..., "data": ... }. Um code positivo é sucesso. Uma recusa é um código negativo com uma frase em data.

curl -s https://xuda.ai/cpi/ticket_api_submit \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","name":"Jordan Lee","email":"[email protected]","subject":"Export fails","details":"The export button returns a 500."}'
const res = await fetch('https://xuda.ai/cpi/ticket_api_submit', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    name: 'Jordan Lee',
    email: '[email protected]',
    subject: 'Export fails',
    details: 'The export button returns a 500.',
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/ticket_api_submit',
    json={
        'api_key': 'YOUR_API_KEY',
        'name': 'Jordan Lee',
        'email': '[email protected]',
        'subject': 'Export fails',
        'details': 'The export button returns a 500.',
    },
)

name e details são obrigatórios. Um contacto é criado ou reutilizado a partir de email, o ticket é registado com a origem api, e a resposta é uma vista reduzida: número, id, estado, fase, assunto, tópico, requerente, o id do responsável e as datas e horas. Os ids internos e o estado da automatização nunca são devolvidos.

email é opcional quando uma integração ou um agente regista o ticket para si própria: envie apenas um name, e nenhum contacto é criado e nada é enviado por e-mail ao requerente.

Os campos opcionais dão ao ticket um subject, phone, company, um topic_id e subtopic_id dos tópicos do balcão, o seu próprio reference_id, uma priority de 1 (a mais alta) a 4, um type (issue, bug, feature ou task) e attachments.

Para atribuir o novo ticket a alguém, indique-o com assignee_uid ou assignee_email, um dos dois. Tem de pertencer à equipa do espaço de trabalho do balcão, que é o seu proprietário e os membros aceites do espaço de trabalho. Um responsável recusado não regista nenhum ticket.

Encontrar e ler tickets

ticket_api_list lista tickets com os filtros que o dashboard tem: status (open ou closed), source, topic_id, type, assignee_uid, reference_id, uma search de texto livre sobre o assunto, os detalhes e o número do ticket, e um intervalo created_from e created_to. Ordene com sort (date_created_ts, last_activity_ts, status_ts ou priority) e dir, e pagine com limit (até 500) e o bookmark da resposta anterior.

ticket_api_get lê um ticket por ticket_id, com as suas interações públicas. As notas internas e os rascunhos de IA nunca são devolvidos.

ticket_api_topics devolve os tópicos e subtópicos do balcão, para que o seu próprio formulário possa mostrar o mesmo seletor que o formulário alojado. ticket_api_team devolve as pessoas a quem um ticket pode ser atribuído, cada uma com um uid, um nome e um e-mail.

curl -s https://xuda.ai/cpi/ticket_api_reply \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","body":"Thanks, we are looking into it."}'
curl -s https://xuda.ai/cpi/ticket_api_set_stage \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","status_stage":"in_progress"}'
curl -s https://xuda.ai/cpi/ticket_api_close \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","reason":"Fixed in the latest release."}'
  • ticket_api_reply publica sempre uma resposta pública, nunca uma nota interna. É o balcão a responder, a não ser que passe as_requester: true, que a publica como mensagem do próprio requerente. Nesse caso o responsável, ou o dono do balcão, é notificado, e não conta como a primeira resposta do balcão.
  • ticket_api_set_stage move um ticket aberto para new, in_progress, waiting_customer ou resolved. Um ticket fechado é recusado a não ser que passe reopen: true, que o abre de novo nessa fase. Indicar a fase que o ticket já tem não altera nada.
  • ticket_api_assign atribui um ticket a uma pessoa da equipa por assignee_uid ou assignee_email. Indicar o responsável atual não altera nada. Se mais do que um membro da equipa tiver esse e-mail, a chamada é recusada com -409 e passa o uid em vez disso.
  • ticket_api_close fecha o ticket. O reason opcional é mostrado ao cliente. Uma resposta do cliente dentro do prazo de reabertura faz o ticket voltar.

Ler a lista do próprio balcão

get_support_tickets lê os tickets de volta para a conta com sessão iniciada que é dona do balcão, e pode ser limitado a um ticket com _id. Tem uma forma diferente da vista ticket_api_*, que é feita para um chamador exterior à Xuda.

Planos e limites

O plano decide o que uma chave pode fazer. Ler (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) precisa de acesso de leitura, e escrever (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) precisa de acesso total. Um plano sem ele responde -402. Cada plano tem também um número de chamadas por minuto, e acima dele uma chamada é respondida com -429 até ao minuto seguinte. O histórico segue a janela de retenção do plano, por isso um ticket mais antigo do que ela não pode ser lido. A página de planos tem os números.

Um novo ticket conta para a quota do mês, tal como por qualquer outra forma de entrada.

Métodos

Que tal está este guia?

Última atualização em 16 de novembro de 2026