API de atención, eventos y exportación masiva
Todo lo que una integración necesita del módulo de atención: los endpoints de casos, hilo, SLA, colas, catálogo, derechos y encuestas; suscripciones de eventos firmadas, con reintento y reenvío; un feed que se reanuda por cursor; exportación masiva de casos y mensajes; e importación idempotente del historial de otra herramienta. Cada endpoint tiene su herramienta equivalente en el servidor MCP.
El servicio de atencion siempre estuvo al alcance de la API generica de registros: un caso es un registro, asi que listar y crear ya funcionaba. Lo que no funcionaba es todo lo que vive al lado del caso y no es un registro. El hilo de mensajes, el reloj del SLA, las colas, el catalogo de servicios, el saldo del contrato y las encuestas no tenian endpoint alguno, de modo que una integracion podia abrir el caso y no podia responderlo.
Este articulo cubre los endpoints de atencion, las mismas herramientas en el servidor MCP, las suscripciones de eventos con reintento y reenvio, el feed de eventos reanudable, y como traer el historial de casos desde otra herramienta.
Por donde empezar - Cree una clave de API en Configuracion, en API y desarrolladores. La clave resuelve su cuenta y limita todo a ella. - Cada llamada se autentica igual que el resto de la API: Authorization: Bearer seguido de su clave. - Todo lo de este articulo vive bajo /api/v1/service y esta limitado al objeto ticket. Una clave restringida a otros objetos no llega aqui. - Cada endpoint tiene su herramienta equivalente en el servidor MCP, asi que un agente de IA conectado a SellioCRM hace exactamente lo mismo.
Casos - GET /api/v1/service/tickets lista los casos en filas planas, con filtro por estado, prioridad, cola, responsable o texto libre. Use updated_since con una fecha para traer solo lo que cambio desde la ultima sincronizacion, y limit y offset para paginar. - GET /api/v1/service/tickets/{id} devuelve un caso con el reloj del SLA: el vencimiento, si esta en pausa, el objetivo de primera respuesta y el de proxima respuesta. Ese reloj es la razon de existir de este endpoint; el generico devuelve los campos, no los plazos. - POST /api/v1/service/tickets abre el caso por el mismo camino que la pantalla, asi que el numero de protocolo, los plazos de SLA, las reglas de enrutamiento y los webhooks de salida ocurren igual. - PATCH /api/v1/service/tickets/{id} cambia estado, prioridad, categoria, cola y responsable. Asignar es el mismo verbo que cambiar el estado, por eso no tiene endpoint propio. - GET y POST /api/v1/service/tickets/{id}/messages leen y escriben en el hilo. kind public responde al cliente y envia el correo; kind internal deja una nota que solo ve el equipo. - POST /api/v1/service/tickets/merge fusiona dos casos: el secundario es absorbido por el principal y sus mensajes se mueven con el.
Lo que vive al lado del caso - GET /api/v1/service/queues lista las colas con capacidad por agente, horario y prioridad predeterminada. Leala antes de enrutar: el nombre de la cola es lo que espera la creacion. - GET y POST /api/v1/service/catalog leen la vitrina del catalogo de servicios y solicitan un item. La solicitud abre un caso real con la cola y la prioridad del item; envie su propia idempotencyKey para que un reintento devuelva la solicitud existente en vez de abrir una segunda. - GET /api/v1/service/entitlements devuelve los derechos de atencion por cuenta o contrato, con el saldo. - GET /api/v1/service/surveys devuelve las invitaciones de encuesta de satisfaccion con su estado y fecha de respuesta. Una encuesta anonima nunca devuelve quien respondio.
Eventos, en tiempo real y por cursor Una integracion necesita las dos mitades del tiempo real: que le avisen en el instante en que algo pasa, y recuperar lo que se perdio mientras estuvo caida. La primera viene de la suscripcion; la segunda, del feed.
- POST /api/v1/service/subscriptions registra una URL y los eventos que le interesan. events acepta el tipo exacto o un comodin de familia, como ticket.* Un evento desconocido se rechaza con su nombre, porque una suscripcion que nunca dispara es peor que un error. El secreto vuelve una sola vez; copielo.
- Cada entrega llega como un POST con tres cabeceras: x-sellio-event con el nombre del evento, x-sellio-delivery con el id de ese intento, y x-sellio-signature en la forma sha256 seguido del codigo calculado sobre el cuerpo exacto con su secreto. Recalculelo de su lado y compare; si no coincide, desechelo.
- Una entrega que falla se reintenta con esperas crecientes, alrededor de un minuto, cinco, treinta, dos horas y seis horas. Despues queda marcada como cerrada y permanece en el registro.
- GET /api/v1/service/deliveries es la respuesta consultable a llego este evento. Cada linea trae los intentos, el ultimo codigo, el error y el proximo reintento programado.
- POST /api/v1/service/deliveries/{id}/replay reenvia una entrega. Manda el cuerpo guardado, byte por byte el mismo que salio la primera vez. Rehacer el payload ahora entregaria el estado de hoy con la fecha de ayer.
- GET /api/v1/service/events es el feed. Pase el cursor de la respuesta anterior y reciba solo lo que ocurrio despues de ese punto. nextCursor vuelve incluso en una pagina vacia, y es lo que usted guarda. Trate el cursor como opaco: hacer aritmetica con el es la forma en que una integracion se rompe en silencio mas adelante.
- GET /api/v1/service/event-types lista todo evento que el producto sabe enviar, en cual de los tres registros de webhook se puede suscribir, y si llegar a una suscripcion de atencion depende de que el bus de eventos este encendido en su cuenta. Leala antes de crear una suscripcion.
Exportar casos y mensajes GET /api/v1/service/export recibe entity tickets o messages y format json o csv. La exportacion de mensajes es la razon de existir de este endpoint: el hilo no es un registro, asi que ninguna otra superficie lo entregaba en masa. Filtre por since, status, queue, ticketId o kind, y pagine con limit, hasta 500, y offset. La respuesta json trae hasMore para que sepa que todavia falta pagina.
Traer el historial desde otra herramienta POST /api/v1/service/import recibe hasta 500 filas por llamada. Cada fila necesita externalKey, que es el numero del caso en la herramienta que esta dejando, y un asunto. Puede traer tambien cuerpo, correo, nombre y telefono del solicitante, prioridad, categoria, cola, canal, estado y createdAt.
- La importacion es idempotente por externalKey. Importar el mismo archivo dos veces marca las filas como ya existentes en lugar de duplicarlas, asi que puede reprocesar un lote fallido sin miedo.
- El caso nace con la fecha y el estado del origen. Sin eso, quince mil casos cerrados entrarian como nuevos con la fecha de hoy, inundando la cola de quien esta atendiendo ahora y mintiendo en todo informe por periodo.
- Envie dryRun true para ver que pasaria sin escribir nada.
- Una fila que no pasa la validacion se convierte en una entrada de problems con su posicion en el lote, y el resto del lote entra. Tres fechas rotas no obligan a empezar de nuevo.