API DTTICKET Versão 1.0


#API do DT Ticket (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 opcionais sã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":"..."
            },
            ...
        ]
    }

Voltar para todos os Sub-Recursos

# 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":"..."
            },
            ...
        ]
    }

Voltar para todos os sub-recursos

# 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":"..."
            },
            ...
        ]
    }

Voltar para todos os sub-recursos

# 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
  • O 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":"..."
            },
            ...
        ]
    }

Voltar para todos os sub-recursos

# 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

Voltar para todos os sub-recursos

# 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

Voltar para todos os sub-recursos

# 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
  • O 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

Voltar para todos os sub-recursos

# 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
  • O usuário deve ser informado e existir.
  • O estado deve ser informado e existir.
  • O 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

Voltar para todos os sub-recursos

# 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
  • O 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.

Voltar para todos os sub-recursos

# 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
  • O userId informado deve ser um GUID válido.
  • O 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.

Voltar para todos os sub-recursos

# 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
  • O 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.

Voltar para todos os sub-recursos

# 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
  • O 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.

Voltar para todos os sub-recursos

# 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

Voltar para todos os sub-recursos

# 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
  • O 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.

Voltar para todos os sub-recursos

# 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
  • O 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

Voltar para todos os sub-recursos

# 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
  • O 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.

Voltar para todos os sub-recursos

# 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
  • O 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

Voltar para todos os sub-recursos