API do atendimento, eventos e exportação em massa
Tudo o que uma integração precisa do módulo de atendimento: os endpoints de chamados, thread, SLA, filas, catálogo, direitos e pesquisas; assinaturas de evento assinadas, com retentativa e re-entrega; um feed que você retoma por cursor; exportação em massa de chamados e mensagens; e importação idempotente do histórico de outra ferramenta. Cada endpoint tem a ferramenta equivalente no servidor MCP.
O atendimento sempre esteve ao alcance da API genérica de registros: o chamado é um registro, então listar e criar já funcionava. O que não funcionava é tudo o que mora ao lado do chamado e não é registro. A thread de mensagens, o relógio do SLA, as filas, o catálogo de serviços, o saldo de contrato e as pesquisas não tinham endpoint nenhum, então uma integração conseguia abrir o caso e não conseguia responder a ele.
Este artigo cobre os endpoints de atendimento, as mesmas ferramentas no servidor MCP, as assinaturas de evento com retentativa e re-entrega, o feed de eventos retomável, e como trazer o histórico de chamados de outra ferramenta.
Por onde começar - Crie uma chave de API em Configurações, em API e desenvolvedores. A chave resolve a sua conta e escopa tudo a ela. - Toda chamada autentica como o resto da API: Authorization: Bearer seguido da sua chave. - Tudo deste artigo vive sob /api/v1/service e é escopado ao objeto ticket. Uma chave restrita a outros objetos não chega aqui. - Cada endpoint tem a ferramenta equivalente no servidor MCP, então um agente de IA conectado ao SellioCRM faz exatamente as mesmas coisas.
Chamados - GET /api/v1/service/tickets lista os chamados em linhas achatadas, com filtro por status, prioridade, fila, responsável ou texto livre. Use updated_since com uma data para puxar só o que mudou desde a última sincronização, e limit e offset para paginar. - GET /api/v1/service/tickets/{id} devolve um chamado com o relógio do SLA: o prazo, se está pausado, o alvo de primeira resposta e o de próxima resposta. Esse relógio é o motivo de este endpoint existir; o endpoint genérico devolve os campos, não os prazos. - POST /api/v1/service/tickets abre o chamado pelo mesmo caminho da tela, então o protocolo, os prazos de SLA, as regras de roteamento e os webhooks de saída acontecem junto. - PATCH /api/v1/service/tickets/{id} muda status, prioridade, categoria, fila e o responsável. Atribuir é o mesmo verbo que mudar status, e por isso não tem endpoint próprio. - GET e POST /api/v1/service/tickets/{id}/messages leem e escrevem na thread. kind public responde ao cliente e manda o e-mail; kind internal deixa uma nota que só a equipe vê. - POST /api/v1/service/tickets/merge mescla dois chamados: o secundário é absorvido pelo principal e as mensagens dele vão junto.
O que mora ao lado do chamado - GET /api/v1/service/queues lista as filas com capacidade por atendente, horário e prioridade padrão. Leia antes de rotear: o nome da fila é o que a criação espera. - GET e POST /api/v1/service/catalog leem a vitrine do catálogo de serviços e pedem um item. O pedido abre um chamado de verdade com a fila e a prioridade do item; mande a sua idempotencyKey para o reenvio devolver o pedido que já existe em vez de abrir um segundo. - GET /api/v1/service/entitlements devolve os direitos de atendimento por conta ou contrato, com o saldo. - GET /api/v1/service/surveys devolve os convites de pesquisa de satisfação com estado e data de resposta. Pesquisa anônima nunca devolve quem respondeu.
Eventos, em tempo real e por cursor Uma integração precisa das duas metades do tempo real: ser avisada no instante em que algo acontece, e recuperar o que perdeu enquanto esteve fora do ar. A primeira vem da assinatura; a segunda, do feed.
- POST /api/v1/service/subscriptions cadastra uma URL e os eventos que interessam. events aceita o tipo exato ou um curinga de família, como ticket.* Evento desconhecido é recusado com o nome dele, porque uma assinatura que nunca dispara é pior do que um erro. O segredo volta uma vez; copie.
- Cada entrega chega como um POST com três cabeçalhos: x-sellio-event com o nome do evento, x-sellio-delivery com o id daquela tentativa, e x-sellio-signature na forma sha256 seguido do código calculado sobre o corpo exato com o seu segredo. Recalcule do seu lado e compare; se não bater, descarte.
- Entrega que falha é retentada com espera crescente, cerca de um minuto, cinco, trinta, duas horas e seis horas. Depois disso ela é marcada como encerrada e fica no log.
- GET /api/v1/service/deliveries é a resposta consultável para este evento chegou. Cada linha traz as tentativas, o último código, o erro e a próxima tentativa agendada.
- POST /api/v1/service/deliveries/{id}/replay reenvia uma entrega. Ela manda o corpo guardado, bit a bit o mesmo que saiu da primeira vez. Remontar o payload agora entregaria o estado de hoje com o carimbo de ontem.
- GET /api/v1/service/events é o feed. Passe o cursor da resposta anterior e receba só o que aconteceu depois daquele ponto. O nextCursor volta mesmo na página vazia, e é ele que você guarda. Trate o cursor como opaco: fazer conta com ele é como a integração quebra em silêncio mais adiante.
- GET /api/v1/service/event-types lista todo evento que o produto sabe mandar, em quais dos três cadastros de webhook ele pode ser assinado, e se chegar a uma assinatura de atendimento depende do barramento de eventos estar ligado na sua conta. Leia antes de criar uma assinatura.
Exportar chamados e mensagens GET /api/v1/service/export recebe entity tickets ou messages e format json ou csv. A exportação de mensagens é o motivo de este endpoint existir: a thread não é registro, então nenhuma outra superfície a entregava em massa. Filtre por since, status, queue, ticketId ou kind, e pagine com limit, até 500, e offset. A resposta json traz hasMore para você saber que ainda falta página.
Trazer o histórico de outra ferramenta POST /api/v1/service/import recebe até 500 linhas por chamada. Cada linha precisa de externalKey, que é o número do chamado na ferramenta que você está deixando, e de um assunto. Pode trazer também corpo, e-mail, nome e telefone do solicitante, prioridade, categoria, fila, canal, status e createdAt.
- A importação é idempotente por externalKey. Importar o mesmo arquivo duas vezes marca as linhas como já existentes em vez de duplicar, então dá para reprocessar um lote que falhou sem medo.
- O chamado nasce com a data e o status da origem. Sem isso, quinze mil casos encerrados entrariam como novos com a data de hoje, alagando a fila de quem está atendendo agora e mentindo em todo relatório por período.
- Mande dryRun true para ver o que aconteceria sem gravar nada.
- Linha que não passa na validação vira uma entrada em problems com a posição dela no lote, e o resto do lote entra. Três datas estragadas não obrigam a recomeçar do zero.