API do HiTicket v1.1


Endereço base

Todos os endereços referenciados neste documento tem como base a seguinte URL : https://api.directtalk.com.br/1.1/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

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 100 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/&#8230;\>; rel=”First”,

<https://api.directtalk.com.br/1.0/ticket/&#8230;\>; rel=”Previous”,

<https://api.directtalk.com.br/1.0/ticket/&#8230;\>; rel=”Next”,

<https://api.directtalk.com.br/1.0/ticket/&#8230;\>; 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

GET /groups (listar grupos ativos)

Tipos

GET /types (listar tipos ativos)

Estados

GET /states (listar estados)

Usuários

GET /users (filtrar usuários)

Tickets

POST /tickets (criar um novo ticket) PUT /tickets/{id} (alterar um ticket)

PATCH /tickets/{id}?state=close (fechar um ticket) PATCH /tickets/{id}?state=reopen (reabrir um ticket) GET /tickets (filtrar tickets)

GET /tickets/search (buscar tickets) GET /tickets/{id} (consultar um ticket)

Alterações

GET /tickets/{id}/changes (listar alterações do ticket)

Comentários

POST /tickets/{id}/comments (adicionar um comentário em um ticket) GET /tickets/{id}/comments (listar comentários de um ticket)

GET /tickets/{id}/comments/public (listar comentários públicos de um ticket) GET /tickets/{id}/comments/private (listar comentários privados de um ticket)

Anexos

POST /tickets/{id}/attachments (adicionar um anexo em um ticket) GET /tickets/{id}/attachments (listar anexos de um ticket)


GET /tickets/{id}/attachments/public (listar anexos públicos de um ticket) GET /tickets/{id}/attachments/private (listar anexos privados de um ticket)

GET /tickets/{id}/attachments/{attachmentId}/content (baixar um anexo de um ticket)

Monitoramento

GET /ticket/monitoring/groups (monitoria de tickets por grupos) GET /ticket/monitoring/state (monitoria de tickets por estados) GET /ticket/monitoring/tipo (monitoria de tickets por tipos)

GET /ticket/monitoring/volumetry (monitoria de tickets por volumetria)

Webhook

POST /webhooks (Criar uma nova assinatura) GET /webhooks (Listar as assinaturas)

GET /webhooks/?type=create (Listar as assinaturas de um tipo específico) GET /webhooks/?type=update (Listar as assinaturas de um tipo específico) GET /webhooks/{id} (listar os detalhes de uma assinatura)

PUT /webhooks/{id} (Atualizar uma assinatura existente) DELETE /webhooks/{id} (Excluir uma assinatura existente)

GET /webhooks/{id}/logs (Retornar os eventos de uma determinada assinatura) GET /webhooks/payloads/{id} (Retornar um payload específico)

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

 

Informação Valor
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

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

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": "...",
   "externaldata": [
      {
         "datatype": 0,
         "key": "...",
         "value": "..."
      }
   ]
}
  • 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.
  • externaldata: (opcional) Informações adicionais que serão incluídas no ticket.
  • datatype: Identificador do tipo de informação. Trataremos os tipos 0 – Email e 1 – ConsumerName
  • key: Chave da informação que será incluída
  • value: Valor da informação que será incluída.

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

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

Reabrir um ticket

Resumo

 

Informação Valor
Método HTTP PATCH

Informação Valor
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

Filtrar tickets

Resumo

 

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

 

REQUISIÇÃO

  • 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.
  • externaldata: quando informado buscapor tickets que tenham as chaves externas conforme informado. Deverá ser informado qual chave e seu valor separados por | (pipe). Se houver mais de um, deve ser separado por ponto e vírgula. Chaves que podem ser consultadas: email e receipt. Exemplo: email|teste@directtalk.com.br;receipt|0D9I8R7E6C

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

{
		[
			{
				"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

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

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 .

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.

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": "...",
	"public": true
}

creator: Identificador do usuário que fez o comentário.

content: Comentário.

public: Identifica se o comentário é publico (true) ou privado (false)

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

  • 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":"..."
				"public": true
			},
			...
		]
	}

  • 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.
  • public: Identifica se o comentário é publico (true) ou privado (false)

Listar comentários públicos de um ticket

Resumo

 

Informação Valor
Método HTTP GET
URL /tickets/{id}/comments/public
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":"..."
				"public": true
			},
			...
		]
	}


  • 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.
  • public: Identifica se o comentário é publico (true) ou privado (false)

Listar comentários privados de um ticket

Resumo

 

Informação Valor
Método HTTP GET
URL /tickets/{id}/comments/private
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":"..."
				"public": true
			},
			...
		]
	}


  • 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.
  • public: Identifica se o comentário é publico (true) ou privado (false)

Resumo

 

Informação Valor
Método HTTP POST
URL /tickets/{id}/attachments?userid={userid}&publicAttach={public}
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.
  • publicAttach: Identifica se o anexo é publico (true) ou privado (false)

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

Listar anexos de um ticket

Resumo

 

Informação Valor
Método HTTP GET
URL /tickets/{id}/attachments

 

Informação Valor
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": "...",
			  "public": ...
		    },
			...
    	]
	}


  • 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.
  • public: Identifica se o anexo é publico (true) ou privado (false)

Listar anexos públicos de um ticket

Resumo

 

Informação Valor
Método HTTP GET
URL /tickets/{id}/attachments/public
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": "...",
			  "public": ...
		    },
			...
    	]
	}


  • 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.
  • public: Identifica se o anexo é publico (true) ou privado (false)

Listar anexos privados de um ticket


Resumo

Informação Valor
Método HTTP GET
URL /tickets/{id}/attachments/private
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": "...",
			  "public": ...
		    },
			...
    	]
	}


  • 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.
  • public: Identifica se o anexo é publico (true) ou privado (false)

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)
Header

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

 

Monitoria de tickets por grupos

Resumo

 

Informação Valor
Método HTTP GET
URL **/ticket/monitoring/groups
Escopo de rate limiting Padrão

 

REQUISIÇÃO

 

Parâmetros opcionais

  • 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.
  • startDate: Data/hora inicial para busca, no formato epoch .
  • endDate: Data/hora final para busca, no formato epoch .

Formato

  • 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 período informado por startDate e endDate deve ser válido.
  • O período informado deve ter no máximo 31 dias.

RESPOSTA

 Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo em caso de sucesso

[
	    {
	        "groupId": "...",
	        "groupName": "...",
	        "value": 1
	    },
    	   ...
]


  • groupId: GUID que representa o identificador do grupo.
  • groupName: Nome do Grupo.
  • value: Quantidade de tickets.

Monitoria de tickets por estados

Resumo

 

Informação Valor
Método HTTP GET
URL **/ticket/monitoring/states
Escopo de rate limiting Padrão

 

REQUISIÇÃO

 

Parâmetros opcionais

  • 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.
  • startDate: Data/hora inicial para busca, no formato epoch .
  • endDate: Data/hora final para busca, no formato epoch .

Formato

  • 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 período informado por startDate e endDate deve ser válido.
  • O período informado deve ter no máximo 31 dias.

RESPOSTA

 Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo em caso de sucesso

[
	    {
	        "typeId": "...",
	        "typeName": "...",
	        "value": 1
	    },
    	   ...
]


  • groupId: GUID que representa o identificador do grupo.
  • groupName: Nome do Grupo.
  • value: Quantidade de tickets.

Monitoria de tickets por estados

Resumo

 

Informação Valor
Método HTTP GET
URL **/ticket/monitoring/states
Escopo de rate limiting Padrão

 

REQUISIÇÃO

 

Parâmetros opcionais

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. startDate: Data/hora inicial para busca, no formato epoch .

endDate: Data/hora final para busca, no formato epoch .

Formato

  • 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 período informado por startDate e endDate deve ser válido.
  • O período informado deve ter no máximo 31 dias.

RESPOSTA

 

Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo em caso de sucesso

	[
	    {
	        "stateId": "...",
	        "stateName": "...",
	        "value": 1
	    },
    	   ...
]

  • stateId: GUID que representa o identificador do estado.
  • stateName: Nome do Estado.
  • value: Quantidade de tickets.

Monitoria de tickets por tipos

Resumo

 

Informação Valor
Método HTTP GET
URL **/ticket/monitoring/types
Escopo de rate limiting Padrão

 

REQUISIÇÃO

 

Parâmetros opcionais

  • 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.
  • startDate: Data/hora inicial para busca, no formato epoch .
  • endDate: Data/hora final para busca, no formato epoch .

Formato

  • 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 período informado por startDate e endDate deve ser válido.
  • O período informado deve ter no máximo 31 dias.

RESPOSTA

 

Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo em caso de sucesso

	[
	    {
	        "typeId": "...",
	        "typeName": "...",
	        "value": 1
	    },
    	   ...
]

  • typeId: GUID que representa o identificador do tipo.
  • typeName: Nome do Tipo.
  • value: Quantidade de tickets.

Monitoria de tickets por  volumetria

Resumo

 

Informação Valor
Método HTTP GET
URL **/ticket/monitoring/volumetry
Escopo de rate limiting Padrão

 

REQUISIÇÃO

 

Parâmetros obrigatórios

startDate: Data/hora inicial para busca, no formato epoch .

endDate: Data/hora final para busca, no formato epoch .

Parâmetros opcionais

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

Formato

  • 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 período informado por startDate e endDate deve ser válido.
  • O período informado deve ter no máximo 31 dias.

RESPOSTA

 Cabeçalhos em caso de sucesso

  

Header Valor
HTTP status code 200

 

Corpo em caso de sucesso

[
	    {
            "date": 1,
            "opened": 2,
            "closed": 3
        },
    	   ...
]

  • date: Data da informação, no formato epoch .
  • opened: Quantidade de tickets abertos na data.
  • closed: Quantidade de tickets fechados na data.

Webhook – Criar assinatura

Informação Valor
Método HTTP POST
URL **/webhooks
Escopo de rate limiting Padrão

REQUISIÇÃO

 Corpo

{
	"typeName": "...",
	"subscriptionUrl": "..."
}


  • typeName: Tipo da assinatura
  • subscriptionUrl: Url da API onde serão enviadas as notificações.

Formato

  • A subscriptionUrl tem que ser válida.
  • o typeName tem que ser create ou update

 

RESPOSTA

 Cabeçalhos em caso de sucesso

{
		"id":"...",
		"typeName":"...",
		"url":"..."
	}


  • id: GUID que representa o identificador da assinatura.
  • typeName: nome do tipo do log, pode ser create ou update.
  • url url de assinatura cadastrada (onde vai ser feita a requisição).

Webhook – Listar as assinaturas

Informação Valor
Método HTTP GET
URL **/webhooks?type={type}
Escopo de rate limiting Padrão

RESPOSTA

 

Cabeçalhos em caso de erro

 

Header Valor
HTTP status code 404 (assinatura não encontrada)

Corpo em caso de erro

{
		"Message": "subscription not found"
	}

Cabeçalhos em caso de sucesso

 
Header Valor
HTTP status code 200

Corpo em caso de sucesso

[
		{
			"id":"...",
			"typeName":"...",
			"url":"..."
		},
		...
	]

Webhook – Listar as assinaturas de um tipo específico

Informação Valor
Método HTTP GET
URL **/webhooks
Escopo de rate limiting Padrão

RESPOSTA

 

Parâmetros obrigatórios

type: O tipo precisa ser create ou update.

Cabeçalhos em caso de erro

 

Header Valor
HTTP status code 404 (assinatura não encontrada)

Corpo em caso de erro

{
		"Message": "subscription not found"
	}

Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo em caso de sucesso

[
		{
			"id":"...",
			"typeName":"...",
			"url":"..."
		},
		...
	]

Webhook – Listar os detalhes de uma assinatura

Informação Valor
Método HTTP GET
URL **/webhooks/{id}
Escopo de rate limiting Padrão

RESPOSTA

 

Cabeçalhos em caso de erro

 

Header Valor
HTTP status code 404 (assinatura não encontrada)

Corpo em caso de erro

{
		"Message": "subscription not found"
	}

Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo em caso de sucesso

{
		"id":"...",
		"typeName":"...",
		"url":"..."
	}

Webhook – Atualizar uma assinatura existente

Informação Valor
Método HTTP PUT
URL **/webhooks/{id}
Escopo de rate limiting Padrão

REQUISIÇÃO

 

Cabeçalhos em caso de erro

 

Header Valor
HTTP status code 404 (assinatura não encontrada)

Corpo em caso de erro

{
		"Message": "subscription not found"
	}

Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo

	"subscriptionUrl": "..."
}

Formato

A subscriptionUrl tem que ser válida.

RESPOSTA

 

Cabeçalhos em caso de erro

 

Header Valor
HTTP status code 404 (assinatura não encontrada)

Corpo em caso de erro

{
		"Message": "subscription not found"
	}

Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo em caso de sucesso

{
		"id":"...",
		"typeName":"...",
		"url":"..."
	}

Webhook – Excluir uma assinatura existente

Informação Valor
Método HTTP DELETE
URL **/webhooks/{id}
Escopo de rate limiting Padrão

RESPOSTA

 

Cabeçalhos em caso de erro

 

Header Valor
HTTP status code 404 (assinatura não encontrada)

Corpo em caso de erro

	{
		"Message": "subscription not found"
	}

Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 204

 

Webhook – Retornar os eventos de log de uma determinada assinatura

Informação Valor
Método HTTP GET
URL **/webhooks/{id}/logs
Informação Valor
Escopo de rate limiting Padrão

RESPOSTA

 

Cabeçalhos em caso de erro

 

Header Valor
HTTP status code 404 (assinatura não encontrada)

Corpo em caso de erro

	
	{
		"Message": "subscription not found"
	}

Cabeçalhos em caso de sucesso

 

Header Valor
HTTP status code 200

Corpo em caso de sucesso

[
		{
			"id":"...",
			"typeName":"...",
			"responseId":"...",
			"logDate":"...",
			"typeLog":"...",
			"subscriptionUrl":"...",
			"logDetail":"..."
		},
		...
	]
  • id: GUID que representa o identificador do log.
  • typeName: nome do tipo do log, pode ser create ou update. responseId: resposta que foi retornada na requisição. logDate Data de criação do log, no formato epoch .
  • typeLog tipo do log, pode ser success ou error. subscriptionUrl url de assinatura cadastrada. logDetail detalhes do log.

Webhook – Retornar um payload específico

Informação Valor
Método HTTP GET
URL **/webhooks/payloads/{id}
Escopo de rate limiting Padrão

Cabeçalhos em caso de erro

 

Header Valor
HTTP status code 404 (assinatura não encontrada)

Corpo em caso de erro

{
		"Message": "subscription not found"
	}

RESPOSTA – Assinatura do tipo create

 

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		
    }

RESPOSTA – Assinatura do tipo update

 

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": "...",
        "endDate": 1,
		"updateDate": 1,
		"userUpdate": {
				"id":"...",
				"name":"..."
			},
		"updateDetails":  [
					{
						"information":"...",
						"value":"..."
					},
					...
				]		
    }
  • 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 .
  • endDate: (pode ser nulo) Data de encerramento, no formato epoch .
  • updateDate: (pode ser nulo) Data de atualização, no formato epoch .
  • userUpdate: (pode ser nulo) Detalhes da atualização do usuário.
  • updateDetails: (pode ser nulo) Detalhes da atualização do ticket.