Documents Ticket

Documents can be applied to a specific ticket.

GET/api/v3.0/tickets/{ticket_id}/all-documents

The url returned in the document lists of this page points to the Bob! Desk web application: it only works with a browser session and answers 401 to the API token. To download a file with your token, call this endpoint with the document's s3_key: it returns a temporary signed link, which you then download directly, without any header.

The s3_key is the last path segment of that url, i.e. everything after /api/ged/secure/, extension included (e.g. 3f2a1c7e-5d0e-4b1a-9c2d-8e7f6a5b4c3d_v1.pdf).

The s3_key is also returned as such on quotes[], invoices[] and purchases[] of the tickets resource, in the list as well as in the detail (the detail also carries a ready-to-use download_url).

The signed link is valid for several days (at least 48 hours). Do not store it: request a new one when you need the file again. Only a document shared with your account can be resolved: any other key, or a deleted document, returns 404.

Route Parameters

Name
s3_key
Type
string
Description
The s3_key of the document: the last path segment of its url.

Properties of the response

Name
url
Type
String
Description
The temporary signed download link.

Request

GET

/api/v3.0/documents/{s3_key}

# 1. url of a document in all-documents:
#    https://…/api/ged/secure/3f2a1c7e-5d0e-4b1a-9c2d-8e7f6a5b4c3d_v1.pdf
# 2. ask a download link for its s3_key
curl https://api.bob-desk.com/api/v3.0/documents/3f2a1c7e-5d0e-4b1a-9c2d-8e7f6a5b4c3d_v1.pdf \
  -H "Authorization: Bearer {token}"
# 3. download the file from the signed link, without any header
curl -o document.pdf "{url}"

Response

{
  "url": "https://…"
}

POST/api/v3.0/tickets/{ticket_id}/upload-document

Upload a document

This endpoint allows you to upload a document for a specific ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Properties of the request

Name
file
Type
File
Description
The document file

Request

POST

/api/v3.0/tickets/:ticket_id/upload-document

curl -X POST https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/upload-document \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/file"

Response

{
  "message": "ok"
}

GET/api/v3.0/tickets/{ticket_id}/quotes

Quotes list

This endpoint returns all quotes for a specific ticket. Only the documents shared with your account and not deleted are returned.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Properties of the response

Name
quotes
Type
Array
Description
An array of quotes
Name
quotes.document_id
Type
ObjectID
Description
The document id.
Name
quotes.s3_key
Type
String
Description
Key of the file, to pass to Download link of a document.
Name
quotes.url
Type
String
Description
Link of the file in the Bob! Desk web application (https://…/api/ged/secure/{s3_key}). It needs a browser session and answers 401 to the API token: to download the file with your token, see Download link of a document.
Name
quotes.name
Type
String
Description
The document name
Name
quotes.tags
Type
Array
Description
An array of tags
Name
quotes.tags._id
Type
ObjectID
Description
The tag id
Name
quotes.tags.label
Type
String
Description
The tag label
Name
quotes.reference
Type
String
Description
The quote reference
Name
quotes.price
Type
String
Description
The price defined for this quote

Request

GET

/api/v3.0/tickets/:ticket_id/quotes

curl -G https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/quotes \
  -H "Authorization: Bearer {token}" \

Response

{
  "quotes": [
    {
      "document_id": "63725f259ab7e72a4fb4ae90",
      "s3_key": "3f2a1c7e-5d0e-4b1a-9c2d-8e7f6a5b4c3d_v1.pdf",
      "url": "url_to_document",
      "name": "document.pdf",
      "tags": [
        {
          "_id": "5f9b5b5b9ab7e72a4fb4ae69",
          "label": "quote_label"
        }
      ],
      "reference": "JK123123",
      "price": "7000"
      }
  ]
}

POST/api/v3.0/tickets/{ticket_id}/upload-quote

Upload a quote

This endpoint allows you to upload a quote for a specific ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Properties of the request (Required)

Name
file
Type
File
Description
The quote file
Name
upload_to_client
Type
string
Description
true (default): your account is the contractor of the ticket and sends the quote to its client.
false: your account is the client of the ticket and records a quote received from the contractor assigned on it.
(Allowed values: true or false)
Name
reference
Type
string
Description
The quote reference
Name
price
Type
string
Description
The quote price
Name
reopen_ticket_if_closed
Type
string
Description
If set to true, the ticket will be reopened if it is closed

Errors

400: file, reference or price is missing. The request must be sent as multipart/form-data.
403 (accounting is locked): the ticket is not visible to your account, or an invoice is being validated on it, which locks its accounting. The quote is refused.

Request

POST

/api/v3.0/tickets/:ticket_id/upload-quote

curl -X POST https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/upload-quote \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/file"
  -F "upload_to_client=false"
  -F "reference=quote_reference"
  -F "price=quote_price"
  -F "reopen_ticket_if_closed=false"

Response

{
  "message": "quote uploaded"
}

GET/api/v3.0/tickets/{ticket_id}/invoices

Invoices list

This endpoint returns all invoices for a specific ticket. Only the documents shared with your account and not deleted are returned.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Properties of the response

Name
invoices
Type
Array
Description
An array of invoices
Name
invoices.document_id
Type
ObjectID
Description
The document id.
Name
invoices.s3_key
Type
String
Description
Key of the file, to pass to Download link of a document.
Name
invoices.url
Type
String
Description
Link of the file in the Bob! Desk web application (https://…/api/ged/secure/{s3_key}). It needs a browser session and answers 401 to the API token: to download the file with your token, see Download link of a document.
Name
invoices.name
Type
String
Description
The document name
Name
invoices.tags
Type
Array
Description
An array of tags
Name
invoices.tags._id
Type
ObjectID
Description
The tag id
Name
invoices.tags.label
Type
String
Description
The tag label
Name
invoices.reference
Type
String
Description
The invoice reference
Name
invoices.price
Type
String
Description
The price defined for this invoice

Request

GET

/api/v3.0/tickets/:ticket_id/invoices

curl -G https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/invoices \
  -H "Authorization: Bearer {token}" \

Response

{
  "invoices": [
    {
      "document_id": "63725f259ab7e72a4fb4ae91",
      "s3_key": "8b1e2d3c-4f5a-4b6c-9d7e-0f1a2b3c4d5e_v1.pdf",
      "url": "url_to_document",
      "name": "document.pdf",
      "tags": [
        {
          "_id": "5f9b5b5b9ab7e72a4fb4ae69",
          "label": "invoice_label"
        }
      ],
      "reference": "L0121341",
      "price": "400"
    }
  ]
}

POST/api/v3.0/tickets/{ticket_id}/upload-invoice

Upload an invoice

This endpoint allows you to upload an invoice for a specific ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Properties of the request (Required)

Name
file
Type
File
Description
The invoice file
Name
upload_to_client
Type
string
Description
true (default): your account is the contractor of the ticket and sends the invoice to its client.
false: your account is the client of the ticket and records an invoice received from the contractor assigned on it.
(Allowed values: true or false)
Name
reference
Type
string
Description
The invoice reference
Name
price
Type
string
Description
The invoice price

Errors

400: file, reference or price is missing. The request must be sent as multipart/form-data.
403 (accounting is locked): the ticket is not visible to your account, or an invoice is being validated on it, which locks its accounting. The invoice is refused.

Request

POST

/api/v3.0/tickets/:ticket_id/upload-invoice

curl -X POST https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/upload-invoice \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/file"
  -F "upload_to_client=false"
  -F "reference=invoice_reference"
  -F "price=invoice_price"

Response

{
  "message": "invoice uploaded"
}

GET/api/v3.0/tickets/{ticket_id}/reports

Reports list

This endpoint returns all reports for a specific ticket. Only the documents shared with your account and not deleted are returned.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Properties of the response

Name
reports
Type
Array
Description
An array of reports
Name
reports.document_id
Type
ObjectID
Description
The document id.
Name
reports.s3_key
Type
String
Description
Key of the file, to pass to Download link of a document.
Name
reports.url
Type
String
Description
Link of the file in the Bob! Desk web application (https://…/api/ged/secure/{s3_key}). It needs a browser session and answers 401 to the API token: to download the file with your token, see Download link of a document.
Name
reports.name
Type
String
Description
The document name
Name
reports.tags
Type
Array
Description
An array of tags
Name
reports.tags._id
Type
ObjectID
Description
The tag id
Name
reports.tags.label
Type
String
Description
The tag label

Request

GET

/api/v3.0/tickets/:ticket_id/reports

curl -G https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/reports \
  -H "Authorization: Bearer {token}" \

Response

{
  "reports": [
    {
      "document_id": "5f9b5b5b9ab7e72a4fb4ae69",
      "s3_key": "c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f_v1.pdf",
      "url": "url_to_document",
      "name": "document.pdf",
      "tags": [
        {
          "_id": "5f9b5b5b9ab7e72a4fb4ae69",
          "label": "Rapport d'intervention"
        }
      ]
    }
  ]
}

POST/api/v3.0/tickets/{ticket_id}/upload-report

Upload a report

This endpoint allows you to upload a report for a specific ticket.

Route Parameters

Name
ticket_id
Type
ObjectID
Description
The ticket id

Properties of the request (Required)

Name
file
Type
File
Description
The report file

Coming soon

This endpoint can allow you to upload a report and specify if this report is a reserve report and create a new ticket with the reserve report.

Request

POST

/api/v3.0/tickets/:ticket_id/upload-report

curl -X POST https://api.bob-desk.com/api/v3.0/tickets/:ticket_id/upload-report \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/file"

Response

{
  "message": "report uploaded"
}