FORMAT: 1A
HOST: http://support.api.sipsynergy.local/api

# Tickets Microservice

Welcome to the documentation.

# Group Users

## User Collection [/users]

### Get Logged In User [GET]
+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (User Full)

### Get Agents [GET /users/agents]
+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (array[User Full])

### Create [POST]
+ Request (application/json)
    + Attributes (User Create)
+ Response 201 (application/json)
    + Headers
        Location: 1

## User Resource [/users/{id}]
+ Parameters
    + id: `1` (number, required) - Given db id for user.

### Update [PATCH]
+ Request (application/json)
    + Attributes (User Update)
+ Response 202 (application/json)

### Delete [DELETE]
+ Request (application/json)
+ Response 202 (application/json)

# Group Ticket

## Ticket Collection [/tickets]
+ Attributes (Ticket Full)

### Retrieve All [GET]
+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (array[Ticket Full])

### Create Ticket [POST]
+ Request (application/json)
    + Attributes (Ticket Create)
+ Response 201 (application/json)
    + Headers
        Location: INC-123

## Ticket Resource [/tickets/{ticketId}]
Ticket resource is the place where you'd make actions against a specific incident.
+ Parameters
    + ticketId: `INC-1234` (string, required) - Ticket Human ID.

### Get Single Ticket [GET]
Get a single ticket from it's human id.

+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (array[Ticket Full])

### Update Ticket [PATCH]
+ Request (application/json)
    + Attributes (Ticket Create)
+ Response 204 (application/json)
    + Headers
        Location: INC-123

### Create Comment [POST]
+ Request (application/json)
    + Attributes (Comment Create)
+ Response 201
    + Headers
        Location: 123

### Get All Comments [GET /tickets/{ticketId}/comments]
+ Parameters
    + ticketId: `INC-1234` (string, required) - Ticket Human ID.

+ Request (application/json)
+ Response 200 (application/json)
    + Attributes
        + data (array[Comment Full])

### Get All Attributes [GET /tickets/{ticketId}/attributes]
+ Parameters
    + ticketId: `INC-1234` (string, required) - Ticket Human ID.

+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (array[Ticket Attribute Full])


### Delete Ticket [DELETE]
+ Request (application/json)
+ Response 202 (application/json)

# Group Comments

## Comment resource [/comments/{commentId}]

# Group Groups

## Group Collection [/groups]

### Retrieve All [GET]
+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (array[Group Full])

## Group Resource [/groups/{groupId}]
+ Parameters
    + groupId: `1` (number, required) - group db id.

### Get Group Resource [GET]
Get a group's resource.
+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (Group Full)

# Group States

## State Collection [/states]

### Retrieve All [GET]
+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (array[State])

## Type Collections [/states/{?type}]

### Retrieve All [GET]
+ Parameters
    + type (enum[string], optional)
        + all
        + state
        + type
        + priority
        + stage
        + outcome
+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
            + data (array[State])

# Group Events

## Event Resource [/events]

### Confirm Ticket Contacts [POST /events/confirm-contacts/{ticketId}]
This will create a system event and send an email to the tickets enabled contacts.
+ Parameters
     + ticketId: `INC-1234` (required, string) - Ticket Human ID
+ Request (application/json)
+ Response 201 (application/json)

### Confirm Ticket Contacts [GET /events/confirm-contacts/{ticketId}]
This will check the events log to see if the event has been triggered.
+ Parameters
     + ticketId: `INC-1234` (required, string) - Ticket Human ID
+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (object)
        + data (Event Full)
+ Response 404 (application/json)

# Group Reporting

### Ticket Reporting Download [GET /reporting/tickets/download{?period}]
This route will generate and download a CSV file with reporting information.
+ Parameters
    + period (string) - monthly/weekly
+ Request (application/json)
+ Response 200 (application/json)

### Ticket Reporting JSON [GET /reporting/tickets{?period}]
This route will generate and download a CSV file with reporting information.
+ Parameters
    + period (string) - monthly/weekly

+ Response 200 (application/json)
    + Attributes (object)
        + data (array[Ticket Report Json])







# Data Structures

## Timestamps (object)
+ dateCreated: `2016+12+02T17:21:22+0000` (string, required) - ISO8601
+ dateUpdated: `2016+12+02T17:21:22+0000` (string, required) - ISO8601

## Ticket Base (object)
+ organisationHumanId: `ORG-12333` (string, required) - Organisation Human ID.
+ contractHumanId: `CON-123562` (string, required) - Contract Human ID.
+ tenantHumanId: 123 (string, required) - Tenant Human ID.
+ title: `Ticket ticket` (string, optional)
+ description: this is a long a fun description (string, required) - This should be a summary of the issue(s).

## Ticket Attributes Create
+ attributes (object) + attributes required to create a ticket.
    + mainEmail: `luke.rodham@sipsynergy.co.uk` (string, optional)
    + phoneNumber: +447816432764 (string, optional)
    + preferredContactMethod: email (string, required)
    + additionalEmails: `luke.rodham@sipsynergy.co.uk` (array, optional)

## Ticket Attribute Full
+ id: 6 (number)
+ key: `Ticket 14998236` (string)
+ value: `Ticket 14998236` (string)
+ type: `Contact (string)
+ dateCreated: "2017-03-21T18:08:58+0000" (string)

## Ticket Create (object)
+ Include Ticket Base
+ reporterHumanId: `USR-12453` (string, required) - Reporter's Human ID.

## Ticket Full (object)
+ id: `INC-123432` (string)
+ Include Ticket Base
+ reporterHumanId: `USR-12345` (string, required) - Reporter's Human ID.
+ links (object)
    + self: `/tickets/INC-12343` (string, required)
    + comments: `/tickets/INC-12343/comments` (string, required)
+ Include Timestamps
+ buyer (object)
    + type: `organisations` (string)
    + id: `ORG-2134-342` (string)
    + attributes (object)
        + legalName: `Acme Company` (string)
        + name: `Acme` (string)
        + role: `partner` (string)
+ consumer (object)
    + type: `organisations` (string)
    + id: `ORG-2134-342` (string)
    + attributes (object)
        + legalName: `Acme Company` (string)
        + name: `Acme` (string)
        + role: `partner` (string)

## Comment Create
+ ticketId: INC-124321 (string, required) - The associated ticket human id.
+ description: Something useful (string, required) - The users comment.
+ userHumanId: USR-12343 (string, required) - The commenter human id.

## Comment Full
+ id: 123 (number, required) - The comments id.
+ Include Comment Create
+ Include Timestamps

## Group Full (object)
+ id: 1 (number, required)
+ name: MAC (string, required)
+ Include Timestamps

## State
+ id: 1 (number, required)
+ description: OPEN (string, required)
+ type: 1 (number, required)
+ Include Timestamps

## Event Full
+ id: 1 (number, required)
+ key: notification.ticket.create (string, required)
+ value: `Create ticket notification sent.` (string, required)
+ target: `INC-1243454` (string, required)

## Error Unprocessable Entity (object)
+ title: Unprocessable Entity
+ message: This resource could not be updated due to invalid arguments being passed.

# Ticket Report Json
+ ticketNumber: `INC-1965360` (string, required)
+ customer: `NA` (string, required)
+ buyer: `NA` (string, required)
+ ticketDescription: ``` (string, required)
+ priority: `P5 - Priority 5` (string, required)
+ category: `Default` (string, required)
+ serviceImpact: `Provisioning` (string, required)
+ outcome: `Phone` (string, required)
+ status: `New` (string, required)
+ primaryContactName: `NA` (string, required)
+ primaryContactEmail: `NA` (string, required)
+ createdAt: `2017-03-31 11:22:26` (string, required)
+ resolutionDate: `NA` (string, required)
+ assigned: `Michael Tuxford-Tite` (string, required)
+ slaAssignedTime: `00:00:00` (string, required)
+ ticketRunTime: `06:50:22` (string, required)

## User Base
+ email: `example@example.com` (string, required) - Must have an email address.
+ name: `John Doe` (string, required) - Must have a name.
+ phoneNumber: 0123456981 (number, optional) - Can have one phone number.
+ admin: false (boolean, optional) - Sets the user to an operations portal admin.
+ agent: false (boolean, optional) - Sets the user to be a sipsynergy agent.

## User Full
+ id: 1 (number, required) - Database ID.
+ humanId: `USR-123-433` (string, optional) - Users Human ID, if they have one.
+ organisationId: `ORG-1234-3542` (string, optional) - Users organisation ID, if they have one.
+ Include User Base

## User Create
+ humanId: `USR-123-433` (string, optional) - Users Human ID, if they have one.
+ organisationId: `ORG-1234-3542` (string, optional) - Users Human ID, if they have one.
+ Include User Base

## User Update
+ Include User Base