Help Desk e SLA
Chamados do help desk, os comentários de cada chamado e as políticas de SLA (só leitura).
Chamados
Recurso do plano: Help Desk / Chamados.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/tickets | Lista com paginação |
GET | /external/v1/tickets/:id | Busca um registro pelo ID |
POST | /external/v1/tickets | Cria um registro |
PUT | /external/v1/tickets/:id | Atualiza um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/tickets" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/tickets/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
requestedByType | enum | Sim | Tipo do solicitante do ticket. Valores: CUSTOMER, INTERNAL. |
customerId | string | Não | ID de pessoa. Representa o cliente solicitante. |
companyUserId | string | Não | ID de usuário da empresa. Representa o usuário interno solicitante. |
contactName | string | Não | Nome de contato do solicitante. |
contactEmail | string | Não | E-mail de contato do solicitante. |
contactPhone | string | Não | Telefone de contato do solicitante. |
title | string | Sim | Título do ticket. |
description | string | Sim | Descrição detalhada do ticket. |
category | enum | Sim | Categoria do ticket. Valores: INCIDENT, REQUEST, QUESTION, PROBLEM, CHANGE. |
subcategory | string | Não | Subcategoria do ticket. |
priority | enum | Sim | Prioridade do ticket. Valores: CRITICAL, HIGH, MEDIUM, LOW. |
assignedToUserId | string | Não | ID de usuário da empresa. Representa o atendente responsável. |
teamId | string | Não | ID de unidade de negócio. Representa a equipe responsável. |
businessUnitId | string | Não | ID de unidade de negócio. Representa a unidade de negócio. |
dueDate | string (data ISO 8601) | Não | Data limite para resolução do ticket. |
estimatedEffortMinutes | number | Não | Esforço estimado em minutos. |
watcherUserIds | string[] | Não | Lista de IDs de usuários da empresa que observam o ticket. |
executorUserIds | string[] | Não | Lista de IDs de usuários da empresa que atuam como executores (2º atendente) do ticket. |
watcherContacts | object | Não | Observadores externos do ticket (contatos por e-mail). Cada item: { name?, email }. |
contractId | string | Não | ID de contrato. |
projectId | string | Não | ID de projeto. |
dealId | string | Não | ID de negócio. |
parentTicketId | string | Não | ID do ticket pai. |
source | enum | Não | Origem do ticket. Valores: MANUAL, EMAIL, API, PORTAL, CHAT, SYSTEM. |
inboundEmailMessageId | string | Não | ID de e-mail recebido. |
tags | string[] | Não | Etiquetas livres do chamado (lista de textos). O back apara espaços, descarta vazias e repetidas (sem diferenciar maiúsculas). Guarda até ${TICKET_TAG_MAX_COUNT} etiquetas; a que passar de ${TICKET_TAG_MAX_LENGTH} caracteres é cortada. Na edição: a lista substitui o conjunto, [] limpa e ausente mantém. |
metadata | object | Não | Objeto JSON livre. |
curl -X POST "https://erp-api.ideros.api.br/external/v1/tickets" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"requestedByType": "CUSTOMER",
"title": "Erro ao acessar relatório",
"description": "Ao abrir o relatório financeiro aparece uma mensagem de erro.",
"category": "INCIDENT",
"priority": "HIGH"
}'
Atualizar
Envie no corpo só os campos que mudam, com os mesmos nomes da tabela de criação. Responde 200 com o registro atualizado. Registro de outra empresa responde 403; registro inexistente, 404.
Comentários do chamado
Recurso do plano: Help Desk / Chamados.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/ticket-comments | Lista com paginação |
GET | /external/v1/ticket-comments/:id | Busca um registro pelo ID |
POST | /external/v1/ticket-comments | Cria um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
Exemplo com filtro (o valor de relations vai codificado para URL; aqui ele aparece legível: {"where":{"ticketId":"ID_DO_CHAMADO"}}):
curl -G "https://erp-api.ideros.api.br/external/v1/ticket-comments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"ticketId":"ID_DO_CHAMADO"}}'
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/ticket-comments/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ticketId | string | Sim | ID de chamado. |
authorUserId | string | Não | ID de usuário da empresa. Representa o autor do comentário. |
authorCustomerId | string | Não | ID de pessoa. Representa o cliente autor do comentário. |
content | string | Sim | Conteúdo do comentário (aceita HTML do editor rich text). |
isInternal | boolean | Não | Indica se o comentário é interno (visível apenas para atendentes). |
visibleToCustomer | boolean | Não | Interação pública visível para o cliente (portal e notificações). Padrão true; false esconde do cliente. Em nota interna é sempre false. |
notifyTeam | boolean | Não | Se true, notifica o time interno (responsável + executores + observadores internos) in-app sobre esta interação. Se omitido/false, apenas registra. |
mentionedUserIds | string[] | Não | IDs de usuários da empresa mencionados (@) na interação. Cada mencionado recebe notificação in-app dedicada. |
metadata | object | Não | Campo genérico para guardar objetos estruturados como JSON (ex.: 'fileReferences' com os anexos da interação no formato 'id/nome/size'). |
Políticas de SLA
Recurso do plano: Acordo de Nível de Serviço.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/sla-policies | Lista com paginação |
GET | /external/v1/sla-policies/:id | Busca um registro pelo ID |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/sla-policies" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/sla-policies/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Campos do registro
Além de id, isActive, createdAt e updatedAt, o registro traz:
| Campo | Tipo | Descrição |
|---|---|---|
name | string | Nome da política de SLA. |
description | string | Descrição da política. |
isDefault | boolean | Define como política padrão da empresa. |
workShiftId | string | ID do turno de atendimento vinculado (WorkShift). |
metadata | object | Metadados adicionais. |
A nossa equipe ajuda você a configurar e usar esse recurso.