API HiTicket Versão 1.0


#API do HiTicket (v1.0)

  • Endereço base

    Todos os endereços referenciados neste documento tem como base a seguinte URL:

    https://api.directtalk.com.br/1.0/ticket

    A API do Ticket é servida somente sob HTTPS. Para garantir a privacidade das informações, HTTP não criptografado não é suportado.

    Autenticação/Autorização

    As requisições para a API do Ticket são protegidas utilizando Autenticação básica. Em resumo, a DirectTalk irá fornecer um usuário e uma senha exclusivamente para o uso da API, de forma que todas as requisições realizadas devem fornecer estas credenciais.

    Cabeçalhos comuns a todas as operações

    As requisições para a API do Ticket devem possuir os seguintes cabeçalhos:

    Header Valor
    Authorization Basic [basic authentication token]
    Content-Type application/json
    Accept application/json

    Cotas de consumo

    O cliente que usar essa API estará sujeito a um limite na quantidade de requisições que poderá enviar em um dado período de tempo. Essa prática é conhecida como Rate Limiting e é utilizada para garantir a qualidade do serviço.

    A cada ‘X’ minutos (variável conforme o escopo solicitado) o cliente tem direito a fazer um determinado número de requisições (também variável conforme o escopo). Passado o tempo especificado, o limite é reiniciado.

    O consumo do limite pode variar conforme o escopo e deve ser acompanhado pelos seguintes http headers:

    • X-Rate-Limit-Limit: informa o total de requisições permitidas dentro de uma janela de X minutos.
    • X-Rate-Limit-Remaining: informa quantas requisições para API ainda são permitidas dentro da janela de X minutos corrente. Se uma requisição for feita após esse valor retornar 0, a API retornará o HTTP status code 429 (Too many connections.).
    • X-Rate-Limit-Reset: devolve o número de segundos disponíveis na janela atual.

    Escopos de rate limiting

    Nome Limite de requisições Janela de tempo (em minutos)
    Padrão 60 10

    Importante: Certifique-se de checar o escopo de rate limiting no resumo de cada operação.

    Paginação

    Determinadas operações podem potencialmente retornar muitos registros. Nestes casos os resultados serão sempre paginados e os seguintes parâmetros opcionaissão suportados através de query string:

    • pageNumber: Número da página desejada. Se esse parâmetro não for passado ou for maior do que a quantidade de páginas disponíveis, será assumido que a busca é da página 1;
    • pageSize: Quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se esse parâmetro não for passado, será assumido o valor 1000;

    Para auxiliar na navegação nos resultados retornados, as operações que requerem paginação devolverão os seguintes cabeçalhos HTTP:

    X-Pagination-TotalResult: Total de resultados.
    X-Pagination-TotalPages: Total de páginas.
    Link: <https://api.directtalk.com.br/1.0/ticket/...>; rel="First", 
          <https://api.directtalk.com.br/1.0/ticket/...>; rel="Previous", 
          <https://api.directtalk.com.br/1.0/ticket/...>; rel="Next", 
          <https://api.directtalk.com.br/1.0/ticket/...>; rel="Last"
    

    É importante notar que a existência dos links está sujeita ao contexto atual. Por exemplo: se a página atual for a primeira, então o link Previous não estará disponível.

    Importante: Certifique-se de checar a paginação no resumo de cada operação.

    Retornos comuns para todas as operações em caso de erro

    Cabeçalhos
    Header Valor
    Content-Type application/json
    Códigos HTTP
    HTTP status code Descrição
    400 Erro no “formato” da requisição conforme o requisito de cada operação.
    401 O header authorization está ausente ou seu conteúdo não pode ser validado contra o serviço de autenticação.
    403 As credenciais existem mas são inválidas para uso da API.
    429 A cota de consumo foi excedida na janela atual, conforme descrito na seção sobre cotas de consumo.
    500 Erro interno não especificado.
    Corpo
        {
            "messages": [
                            "descrição do erro",
                            "descrição do erro",
                            "..."
                        ]
        }
    

    # Sub-Recursos

    Grupos

    Tipos

    Estados

    Usuários

    Tickets

    Alterações

    Comentários

    Anexos

    # Listar grupos ativos

    Resumo
    Informação Valor
    Método HTTP GET
    URL /groups
    Escopo de rate limiting Padrão
    Paginação Requerido

    RESPOSTA

    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200
    Corpo em caso de sucesso
        {
            [
                {
                    "id":"...",
                    "name":"..."
                },
                ...
            ]
        }
    

     

    # Listar tipos ativos

    Resumo
    Informação Valor
    Método HTTP GET
    URL /types
    Escopo de rate limiting Padrão
    Paginação Requerido

    RESPOSTA

    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200
    Corpo em caso de sucesso
        {
            [
                {
                    "id":"...",
                    "name":"..."
                },
                ...
            ]
        }
    

     

    # Listar estados

    Resumo
    Informação Valor
    Método HTTP GET
    URL /states
    Escopo de rate limiting Padrão
    Paginação Não requerido

    RESPOSTA

    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200
    Corpo em caso de sucesso
        {
            [
                {
                    "id":"...",
                    "name":"..."
                },
                ...
            ]
        }
    

     

    # Filtrar usuários

    Resumo
    Informação Valor
    Método HTTP GET
    URL /users
    Escopo de rate limiting Padrão
    Paginação Requerido

    REQUISIÇÃO

    Parâmetros opcionais
    • groupId: Id do grupo, quando informado, lista todos os usuários associados ao grupo.
    Formato
    • groupId informado deve ser um GUID válido.

    RESPOSTA

    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200
    Corpo em caso de sucesso
        {
            [
                {
                    "id":"...",
                    "name":"..."
                },
                ...
            ]
        }
    

     

    # Criar um novo ticket

    Resumo
    Informação Valor
    Método HTTP POST
    URL /tickets
    Escopo de rate limiting Padrão
    Paginação Não se aplica

    REQUISIÇÃO

    Corpo
    {
        "creator": "...",
        "subject": "...",
        "description": "...",
        "type": "...",
        "group": "...",
        "state": "...",
        "deadline": 1,
        "responsible":"..."
    }
    
    • creator: Identificador do usuário que está criando o ticket.
    • subject: Assunto.
    • description: Descrição.
    • type: Identificador do tipo.
    • group: Identificador do grupo.
    • state: Identificador estado.
    • deadline: (opcional) Data correspondente ao prazo, no formato epoch. Quando não informada, o prazo será determinado pelo tipo.
    • responsible: (opcional) Identificador do usuário que é responsável pelo ticket.
    Formato

    O usuário criador deve ser informado e existir.

    O assunto deve ser informado e ter até 200 caracteres.

    A descrição deve ser informada e ter até 1600 caracteres.

    O tipo deve ser informado e existir.

    O grupo deve ser informado e existir.

    O estado deve ser informado e existir.

    O estado não deve fechar o ticket.

    O prazo (quando informado) deve ser válido.

    O usuário responsável (quando informado) deve existir.

    O usuário responsável (quando informado) deve fazer parte do grupo.

    RESPOSTA

    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 201
    Location https://api.directtalk.com.br/1.0/ticket/tickets/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX

     

    # Alterar um ticket

    Resumo
    Informação Valor
    Método HTTP PUT
    URL /tickets/{id}
    Escopo de rate limiting Padrão
    Paginação Não se aplica

    REQUISIÇÃO

    Corpo
    {
        "user": "...",
        "subject": "...",
        "description": "...",
        "type": "...",
        "group": "...",
        "state": "...",
        "deadline": 1,
        "responsible":"..."
    }
    

     

    user: Identificador do usuário que está alterando o ticket.

    subject: Assunto.

    description: Descrição.

    type: Identificador do tipo.

    group: Identificador do grupo.

    state: Identificador estado.

    deadline: (opcional) Data correspondente ao prazo, no formato epoch.

    responsible: (opcional) Identificador do usuário que é responsável pelo ticket.

    Formato
    • O usuário da alteração deve ser informado e existir.
    • O assunto deve ser informado e ter até 200 caracteres.
    • A descrição deve ser informada e ter até 1600 caracteres.
    • O tipo deve ser informado e existir.
    • O grupo deve ser informado e existir.
    • O estado deve ser informado e existir.
    • O estado não deve encerrar o ticket.
    • O prazo (quando informado) deve ser válido.
    • O usuário responsável (quando informado) deve existir.
    • O usuário responsável (quando informado) deve fazer parte do grupo.

    RESPOSTA

    Cabeçalhos em caso de erro (além dos comuns a todas as operações)
    Header Valor
    HTTP status code 404 (ticket não existe)
    HTTP status code 409 (ticket já fechado)
    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200

     

    # Fechar um ticket

    Resumo
    Informação Valor
    Método HTTP PATCH
    URL /tickets/{id}?state=close
    Escopo de rate limiting Padrão
    Paginação Não se aplica

    REQUISIÇÃO

    Corpo
    {
        "user": "..."
    }
    
    • user: Identificação do usuário que está fechando o ticket.
    Formato
    • usuário deve ser informado e existir.

    RESPOSTA

    Cabeçalhos em caso de erro (além dos comuns a todas as operações)
    Header Valor
    HTTP status code 404 (ticket não existe)
    HTTP status code 409 (ticket já fechado)
    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200

     

    # Reabrir um ticket

    Resumo
    Informação Valor
    Método HTTP PATCH
    URL /tickets/{id}?state=reopen
    Escopo de rate limiting Padrão
    Paginação Não se aplica

    REQUISIÇÃO

    Corpo
    {
        "user": "...",
        "state": "..."
    }
    
    • user: Identificação do usuário que está reabrindo o ticket.
    • state: Identificação do estado para qual o ticket deve ser reaberto.
    Formato
    • usuário deve ser informado e existir.
    • estado deve ser informado e existir.
    • estado não deve fechar o ticket.

    RESPOSTA

    Cabeçalhos em caso de erro (além dos comuns a todas as operações)
    Header Valor
    HTTP status code 404 (ticket não existe)
    HTTP status code 409 (ticket já aberto)
    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200

     

    # Filtrar tickets

    Resumo
    Informação Valor
    Método HTTP GET
    URL /tickets
    Escopo de rate limiting Padrão
    Paginação Requerido

    REQUISIÇÃO

    Parâmetros opcionais
    • userId: Identificador do usuário. Quando informado, considera o escopo do usuário para localizar um ticket.
    • groupId: Identificador do grupo. Se houver mais de um, deve ser separado por vírgula.
    • typeId: Identificador do tipo. Se houver mais de um, deve ser separado por vírgula.
    • stateId: Identificador do estado. Se houver mais de um, deve ser separado por vírgula.
    • responsibleId: Identificador do usuário responsável. Se houver mais de um, deve ser separado por vírgula.
    • creatorId: Identificador do usuário criador. Se houver mais de um, deve ser separado por vírgula.
    • startDate: Data/hora inicial para busca, no formato epoch.
    • endDate: Data/hora final para busca, no formato epoch.
    • dateInfo: Parâmetro que informa sobre qual data o intervalo definido pelos parâmetros startDate e endDate dizem respeito. Esse parâmetro suporta duas opções:
      • createDate (padrão)
      • endDate
    • sort: Informação pela qual se deseja ordenar o resultado:
      • number (padrão quando não informado)
      • subject
      • group
      • type
      • deadline
    • desc: Quando informado, ordena de forma decrescente.
    Formato
    • userId informado deve ser um GUID válido.
    • O(s) groupId informado(s) deve(m) ser GUID(s) válido(s).
    • O(s) typeId informado(s) deve(m) ser GUID(s) válido(s).
    • O(s) stateId informado(s) deve(m) ser GUID(s) válido(s).
    • O(s) responsibleId informado(s) deve(m) ser GUID(s) válido(s).
    • O(s) creatorId informado(s) deve(m) ser GUID(s) válido(s).
    • O valor informado para deadline deve estar entre os valores suportados.
    • O valor informado para sort deve estar entre os valores suportados.
    • O período informado por startDate e endDate deve ser válido.
    • O período informado deve ter no máximo 31 dias.
    • dateInfo só deve ser informado quando houver um período.
    • O valor informado para dateInfo deve estar entre os valores suportados.

    RESPOSTA

    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200
    Corpo em caso de sucesso
        {
            [
                {
                    "id":"...",
                    "number": "...",
                    "subject":"...",
                    "description": "...",
                    "type": {
                                "id":"...",
                                "name":"..."
                            },
                    "group": {
                                "id":"...",
                                "name":"..."
                            },
                    "state": {
                                "id":"...",
                                "name":"..."
                            },
                    "deadline": 1,
                    "responsible":  {
                                        "id":"...",
                                        "name":"..."
                                    },
                    "creationDate": "...",
                    "creationUser": {
                                        "id":"...",
                                        "name":"..."
                                    },
                    "endDate": 1
                },
                ...
            ]
        }
    
    • id: GUID que representa o identificador do ticket.
    • number: Número do ticket (gerado automaticamente para facilitar localização).
    • subject: Assunto.
    • description: Descrição.
    • type: Tipo.
    • group: Grupo.
    • state: Estado.
    • deadline: Prazo, no formato epoch.
    • responsible: (pode ser nulo) Responsável.
    • creationDate: Data de criação, no formato epoch.
    • creationUser: Usuário que criou o ticket.
    • endDate: (pode ser nulo) Data de encerramento, no formato epoch.

     

    # Buscar tickets

    Resumo
    Informação Valor
    Método HTTP GET
    URL /tickets/search
    Escopo de rate limiting Padrão
    Paginação Requerido

    REQUISIÇÃO

    Parâmetros
    • text: Valor a ser buscado. A pesquisa é efetuada no campo assunto e na descrição.
    Parâmetros opcionais
    • userId: Identificador do usuário. Quando informado, considera o escopo do usuário para localizar um ticket.
    Formato
    • userId informado deve ser um GUID válido.
    • text a ser buscado deve ser preenchido e ter mais de 3 caracteres.

     

    RESPOSTA

    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200
    Corpo em caso de sucesso
        {
            [
                {
                    "id":"...",
                    "number": "...",
                    "subject":"...",
                    "description": "...",
                    "type": {
                                "id":"...",
                                "name":"..."
                            },
                    "group": {
                                "id":"...",
                                "name":"..."
                            },
                    "state": {
                                "id":"...",
                                "name":"..."
                            },
                    "deadline": 1,
                    "responsible":  {
                                        "id":"...",
                                        "name":"..."
                                    },
                    "creationDate": "...",
                    "creationUser": {
                                        "id":"...",
                                        "name":"..."
                                    },
                    "endDate": 1
                },
                ...
            ]
        }
    
    • id: GUID que representa o identificador do ticket.
    • number: Número do ticket (gerado automaticamente para facilitar localização).
    • subject: Assunto.
    • description: Descrição.
    • type: Tipo.
    • group: Grupo.
    • state: Estado.
    • deadline: Prazo, no formato epoch.
    • responsible: (pode ser nulo) Responsável.
    • creationDate: Data de criação, no formato epoch.
    • creationUser: Usuário que criou o ticket.
    • endDate: (pode ser nulo) Data de encerramento, no formato epoch.

     

    # Consultar um ticket

    Resumo
    Informação Valor
    Método HTTP GET
    URL /tickets/{id}
    Escopo de rate limiting Padrão
    Paginação Não se aplica

    REQUISIÇÃO

    Parâmetros opcionais
    • userId: Identificador do usuário. Quando informado, considera o escopo do usuário para localizar um ticket.
    Formato

    userId informado deve ser um GUID válido.

    RESPOSTA

    Cabeçalhos em caso de erro (além dos comuns a todas as operações)
    Header Valor
    HTTP status code 404 (ticket não existe)
    Cabeçalhos em caso de sucesso
    Header Valor
    HTTP status code 200
    Corpo em caso de sucesso
        {
            "id":"...",
            "number": "...",
            "subject":"...",
            "description": "...",
            "type": {
                        "id":"...",
                        "name":"..."
                    },
            "group": {
                        "id":"...",
                        "name":"..."
                    },
            "state": {
                        "id":"...",
                        "name":"..."
                    },
            "deadline": 1,
            "responsible":  {
                                "id":"...",
                                "name":"..."
                            },
            "creationDate": "...",
            "creationUser": {
                            "id":"...",
                            "name":"..."
                          },
            "endDate": 1
        }
    
    • id: GUID que representa o identificador do ticket.
    • number: Número do ticket (gerado automaticamente para facilitar localização).
    • subject: Assunto.
    • description: Descrição.
    • type: Tipo.
    • group: Grupo.
    • state: Estado.
    • deadline: Prazo, no formato epoch.
    • responsible: (pode ser nulo) Responsável.
    • creationDate: Data de criação, no formato epoch.
    • creationUser: Usuário que criou o ticket.
    • endDate: (pode ser nulo) Data de encerramento, no formato epoch.

     

    # Listar alterações do ticket

    Resumo
    Informação Valor
    Método HTTP GET
    URL /tickets/{id}/changes
    Escopo de rate limiting Padrão
    Paginação Requerido

REQUISIÇÃO

Parâmetros opcionais
  • userId: Identificador do usuário. Quando informado, considera o escopo do usuário para localizar um ticket.
Formato
  • userId informado deve ser um GUID válido.

RESPOSTA

Cabeçalhos em caso de erro (além dos comuns a todas as operações)
Header Valor
HTTP status code 404 (ticket não existe)
Cabeçalhos em caso de sucesso
Header Valor
HTTP status code 200
Corpo em caso de sucesso
    {
        [
            {
                "id": "...",
                "date": 1,
                "user": {
                            "id":"...",
                            "name":"..."
                        },
                "details":  [
                                {
                                    "information":"...",
                                    "value":"..."
                                },
                                ...
                            ]
                },
                ...
        ]
    }
  • id: GUID que representa o identificador do conjunto de alterações.
  • date: Data do conjunto de alterações, no formato epoch.
  • user: Usuário que efetuou as alterações.
  • details: Lista com ao menos uma alteração:
    • information: Informação alterada.
    • oldValue: Valor antes da alteração.

 

# Adicionar um comentário em um ticket

Resumo
Informação Valor
Método HTTP POST
URL /tickets/{id}/comments
Escopo de rate limiting Padrão
Paginação Não se aplica

REQUISIÇÃO

Corpo
{
    "creator": "...",
    "content": "..."
}
  • creator: Identificador do usuário que fez o comentário.
  • content: Comentário.
Formato
  • O usuário criador deve ser informado e existir.
  • O comentário deve ser informado e ter até 2000 caracteres.

RESPOSTA

Cabeçalhos em caso de erro (além dos comuns a todas as operações)
Header Valor
HTTP status code 404 (ticket não existe)
HTTP status code 409 (ticket já fechado)
Cabeçalhos em caso de sucesso
Header Valor
HTTP status code 201

 

# Listar comentários de um ticket

Resumo
Informação Valor
Método HTTP GET
URL /tickets/{id}/comments
Escopo de rate limiting Padrão
Paginação Requerido

REQUISIÇÃO

Parâmetros opcionais
  • userId: Identificador do usuário. Quando informado, considera o escopo do usuário para localizar um ticket.
Formato
  • userId informado deve ser um GUID válido.

RESPOSTA

Cabeçalhos em caso de erro (além dos comuns a todas as operações)
Header Valor
HTTP status code 404 (ticket não existe)
Cabeçalhos em caso de sucesso
Header Valor
HTTP status code 200
Corpo em caso de sucesso
    {
        [
            {
                "id":"...",
                "date": 1,
                "user": {
                            "id":"...",
                            "name":"..."
                        },
                "content":"..."
            },
            ...
        ]
    }
  • id: GUID que representa o identificador do comentário.
  • date: Data do comentário, no formato epoch.
  • user: Usuário que efetuou o comentário.
  • content: Comentário propriamente dito.

 

# Adicionar um anexo em um ticket

Resumo
Informação Valor
Método HTTP POST
URL /tickets/{id}/attachments?userid={userid}
Escopo de rate limiting Padrão
Paginação Não se aplica

REQUISIÇÃO

Header Valor Descrição
Content-Type multipart/form-data; boundary=xxxxxxxxxx o post deve usar enctype=”multipart/form-data”no form

O arquivo deve estabelecer seu nome e tipo no “part” (vide RFC-1867). Preferencialmente deve ser codificado em base64 para a transferência – nesse caso, a informação também é adicionada ao “part” (vide RFC1521). Ex.:

#!
--Boundary_XXXXXXXXX
Content-Transfer-Encoding: BASE64
Content-Type: text/plain
Content-Disposition: form-data; filename="nome do arquivo.txt"; name="file"

SXNzbyDDqSB1bSB0ZXN0ZS4=
--Boundary_XXXXXXXXX--
Parâmetros
  • userId: Identificador do usuário que está adicionando o anexo.
Formato
  • userId informado deve ser um GUID válido.

RESPOSTA

Cabeçalhos em caso de erro (além dos comuns a todas as operações)
Header Valor
HTTP status code 404 (ticket não existe)
HTTP status code 409 (ticket já fechado)
Cabeçalhos em caso de sucesso
Header Valor
HTTP status code 201

 

# Listar anexos de um ticket

Resumo
Informação Valor
Método HTTP GET
URL /tickets/{id}/attachments
Escopo de rate limiting Padrão
Paginação Requerido

REQUISIÇÃO

Parâmetros opcionais
  • userId: Identificador do usuário. Quando informado, considera o escopo do usuário para localizar um ticket.
Formato
  • userId informado deve ser um GUID válido.

RESPOSTA

Cabeçalhos em caso de erro (além dos comuns a todas as operações)
Header Valor
HTTP status code 404 (ticket não existe)
Cabeçalhos em caso de sucesso
Header Valor
HTTP status code 200
Corpo em caso de sucesso
    {
        [
            {
              "id": "...",
              "name": "...",
              "url": "...",
              "mimeType": "...",
              "length": 1,
              "humanReadableLength": "..."
            },
            ...
        ]
    }
  • id: GUID que representa o identificador do anexo.
  • name: Nome do arquivo.
  • url: URL para baixar o anexo.
  • mimeType: Mime type correspondente ao tipo do arquivo.
  • length: Tamanho do arquivo em bytes.
  • humanReadableLength: Tamanho do arquivo tratado para facilitar a leitura.

 

# Baixar um anexo de um ticket

Resumo
Informação Valor
Método HTTP GET
URL /tickets/{id}/attachments/{attachmentId}/content
Escopo de rate limiting Padrão
Paginação Não se aplica

REQUISIÇÃO

Parâmetros opcionais
  • userId: Identificador do usuário. Quando informado, considera o escopo do usuário para localizar um ticket.
Formato
  • userId informado deve ser um GUID válido.

RESPOSTA

Cabeçalhos em caso de erro (além dos comuns a todas as operações)
Header Valor
HTTP status code 404 (ticket não existe)
Cabeçalhos em caso de sucesso
Header Valor
HTTP status code 200
Content-Type {mime-type} do arquivo
Content-Length {length} do arquivo
Last-Modified {last-modified} do arquivo