Formato del ticket

Esta referencia sirve para mapear tus gestiones al formato que aceptan la API y la Carga masiva. El mismo ticket se manda por las dos vías.

Reglas generales

• JSON en UTF-8. Los nombres de campo distinguen mayúsculas.
• Los campos desconocidos se rechazan en todos los niveles. Lo que no entra en el contrato va en custom_fields (del ticket o del usuario) o en fields (de una llamada).
• Las fechas llevan hora y zona: 2026-10-16T13:40:00Z o 2026-10-16T13:40:00-03:00. Una fecha sin zona es inválida.
• Los ids (source_ticket_id, source_user_id, source_comment_id, source_call_id, …) son textos de 1 a 512 caracteres, estables en el tiempo.
• Las etiquetas (subject, source, status, priority, group, rating, name del usuario) admiten hasta 1.024 caracteres; cada tag hasta 255; el mail hasta 254.
• custom_fields es un objeto de clave (hasta 512 caracteres) y valor escalar: texto, número, booleano o null. No admite listas ni objetos.

Ticket (ticket/1.0)

Campo	Obligatorio	Tipo	Notas
schema_version	Sí	texto	Exactamente ticket/1.0.
source_ticket_id	Sí	id	Único dentro de la conexión. Un id ya importado no se vuelve a crear.
created_at, updated_at	Sí	fecha	updated_at no puede ser anterior a created_at.
users	Sí	lista	El catálogo completo de usuarios que el ticket referencia; al menos uno.
assignee_source_user_id	Sí (*)	id	El operador evaluado. Tiene que estar en users con rol agent o admin y con email. (*) En una carga masiva se puede omitir para heredar defaults.assignee_source_user_id del manifiesto; mandarlo en null no hereda.
subject	No	etiqueta	El asunto que se ve en la lista de tickets.
source	No	etiqueta	Origen de la gestión. Si contiene «whatsapp», el ticket queda con canal WhatsApp.
status, priority, group, rating	No	etiqueta	Etiquetas de tu sistema; se guardan como campos del ticket. rating es texto ("5", no 5).
requester_source_user_id	No	id	El cliente. Tiene que estar en users.
custom_fields	No	objeto	Tus propios datos (cartera, días de atraso, producto). Se guardan como campos del ticket y podés elegir cuáles mostrar y pasar a Auto QA en Flujos.
tags	No	lista de texto	Sin repetidos.
comments	No	lista	La conversación. Ver abajo.
calls	No	lista	La grabación. Como mucho una por ticket.
events, field_events, tag_events	No	lista	Se validan y se aceptan, pero Sniff! no los guarda.

Un ticket puede traer comments, calls, los dos o ninguno. Sólo metadatos es válido, pero no hay nada que evaluar.

Usuario

Campo	Obligatorio	Notas
source_user_id	Sí	Siempre la misma identidad. Dos definiciones distintas del mismo id en un ticket lo invalidan.
role	Sí	user (cliente), agent, admin, bot o system.
name	No	Es el nombre que se muestra en la conversación.
email	No	Obligatorio en el asignado: es cómo Sniff! lo cruza con el usuario del workspace.
active, created_at, updated_at, custom_fields	No	Se validan; no cambian nada en Sniff!.

Comentario

Campo	Obligatorio	Notas
source_comment_id	Sí	Único dentro del ticket.
created_at	Sí	Ordena la conversación.
type	Sí	message o note.
author_source_user_id	Sí	Tiene que estar en users.
body	Sí, salvo que haya adjuntos	{ "format": "plain_text" | "html", "content": "…" }. Del HTML se quitan las etiquetas, los scripts y los estilos.
source	No	Etiqueta libre.
attachments	No	Referencias a archivos de assets/, cada una con source_attachment_id, path, file_name, content_type, bytes y sha256.

Cómo se convierten en mensajes del ticket: un message de un usuario user es un turno del cliente; de un agent, admin o bot es un turno del reviewee; una note, o cualquier comentario de un system, queda como mensaje de sistema (se ve, no se evalúa). Los adjuntos se validan pero no se guardan: el mensaje muestra [adjunto: nombre-del-archivo].

Llamada

Campo	Obligatorio	Notas
source_call_id	Sí
created_at	Sí	Es el inicio de la gestión. Si hay comments, sus tiempos relativos al audio se calculan desde acá.
media	Sí	path (empieza con assets/), file_name (nombre, no ruta, hasta 255 caracteres), content_type, bytes (mayor que 0), sha256 (64 hexadecimales en minúscula).
direction	No	inbound o outbound; queda como campo tipo (entrante / saliente).
source	No	Etiqueta libre.
fields	No	Objeto libre. duration_seconds se usa como duración del ticket.

Una llamada con comments se toma como ya transcripta por tu sistema: el ticket queda listo para evaluar y no se vuelve a transcribir. Una llamada sin comments espera a la transcripción de Sniff! si la conexión tiene Transcribir audios.

Manifiesto (ticket-delivery/1.0)

Sólo en la carga masiva con formato JSON. Es el inventario de la entrega:

{
  "schema_version": "ticket-delivery/1.0",
  "delivery_id": "entrega-2026-10-16-001",
  "created_at": "2026-10-16T18:00:00-03:00",
  "mode": "create_only",
  "defaults": { "assignee_source_user_id": "op-ana" },
  "counts": { "tickets": 2, "assets": 1 },
  "tickets": [
    { "source_ticket_id": "gestion-48213", "path": "ticket_details/gestion-48213.json", "bytes": 1412, "sha256": "…" },
    { "source_ticket_id": "gestion-48214", "path": "ticket_details/gestion-48214.json", "bytes": 1388, "sha256": "…" }
  ],
  "assets": [
    { "path": "assets/llamadas/gestion-48213.mp3", "bytes": 2318944, "sha256": "…", "content_type": "audio/mpeg" }
  ]
}

Campo	Notas
schema_version	Exactamente ticket-delivery/1.0.
delivery_id	Hasta 255 caracteres, sin barras. Único dentro de la conexión; es el Id de la entrega que ves en la tabla.
created_at	Fecha con zona.
mode	Exactamente create_only.
defaults.assignee_source_user_id	Opcional. El asignado de los tickets que no traen el suyo; tiene que estar en el users de cada uno de esos tickets.
counts	tickets (de 1 a 10.000) y assets (de 0 a 50.000). Tienen que coincidir con las listas.
tickets[]	source_ticket_id, path (bajo ticket_details/, termina en .json), bytes (hasta 10 MiB), sha256.
assets[]	path (bajo assets/), bytes, sha256, content_type. Cada archivo listado una sola vez; ningún archivo del ZIP sin listar.

CSV simple

Sólo en la carga masiva. tickets.csv en la raíz del ZIP (o dentro de una carpeta) con los audios al lado. Cada fila se convierte en un ticket ticket/1.0 con una llamada; los nombres de columna no distinguen mayúsculas.

Columna	Obligatoria	Notas
id	Sí	Pasa a source_ticket_id.
fecha	Sí	dd/mm/aaaa hh:mm, dd/mm/aaaa hh:mm:ss o ISO 8601. Sin zona se toma como hora de Argentina.
asignado	Sí	Mail del operador, que tiene que ser un usuario del workspace que pueda ser evaluado.
audio	Sí	Nombre del archivo dentro del ZIP. Tipos por extensión: mp3, m4a, wav, flac, ogg, opus, mp4.
direccion	No	entrante o saliente.
asunto	No	Pasa a subject.
duracion	No	Segundos.
tags	No	Separados por ;.
cualquier otra	No	Va a los campos del ticket (como custom_fields).

Hasta 10.000 filas por entrega.

Diferencias que conviene saber

• Una grabación por ticket. Si una gestión tiene varias llamadas, mandá un ticket por cada una.
• Los adjuntos se validan pero no se guardan. Sirven para que el mensaje muestre que hubo un archivo; nadie los va a poder abrir desde Sniff!.
• Los eventos se aceptan y no se guardan. Podés mandar events, field_events y tag_events tal como los tengas; no aparecen en el ticket.
• El asignado es un usuario del workspace, cruzado por mail. Incluirlo en users no lo da de alta: eso se hace en Configuración › Usuarios.