openapi: 3.2.0
info:
title: Tradeshift External Dx Category Documents Document API
version: 1.0.0
servers:
- url: https://api.tradeshift.com/tradeshift
tags:
- name: dx-category--documents-document
paths:
/rest/external/documents:
get:
responses:
'200':
description: 'The list of documents found with the same response mime-type as the one
specified in the Accept header. The returned result is ordered ascending or descending
(defaults to descending) based on the selected "ordering" parameter (defaults to LastEdit).
'
content:
application/json:
example:
itemsPerPage: 25
itemCount: 14
indexing: false
numPages: 1
pageId: 0
Document:
- DocumentId: 7f8959f0-3372-4a5e-b764-7fb42f1ff494
ID: '5'
URI: https://api.tradeshift.com/rest/external/documents/7f8959f0-3372-4a5e-b764-7fb42f1ff494
DocumentType:
mimeType: text/xml
documentProfileId: nes.p5.order.ubl.2.1.dk
type: order
State: LOCKED
LastEdit: '2017-03-01T15:07:14.421+01:00'
Actor:
Created: '2017-02-27T11:29:19.564+01:00'
FirstName: ''
LastName: ''
Email: steve.armstrong@eltec.test.ts.sv
ReceiverCompanyName: simon.owen@simons-catering.test.ts.sv
Tags:
Tag: []
ItemInfos:
- type: document.description
value: '1'
- type: document.total
value: '1.25'
- type: document.currency
value: DKK
- type: document.issuedate
value: '2017-03-01'
LatestDispatch:
DispatchId: 641a034b-e3fc-4218-9a0b-148ed269db51
ObjectId: 7f8959f0-3372-4a5e-b764-7fb42f1ff494
Created: '2017-03-01T15:16:15.657+01:00'
SenderUserId: 0cb783f9-22c6-455f-84f1-83f8b3b5bdf5
DispatchState: COMPLETED
LastStateChange: '2017-03-01T15:16:15.657+01:00'
ReceiverConnectionId: 7593c621-d8e8-4b6f-b296-01310f71ff4e
DispatchChannel: TRADESHIFT
SentReceivedTimestamp: '2017-03-01T15:15:40.478+01:00'
ProcessState: PENDING
ConversationStates:
- Axis: PROCESS
State: PENDING
Timestamp: '2017-03-01T15:15:23.059+01:00'
- Axis: OTHERPART
State: OTHER_PENDING
Timestamp: '2017-03-01T15:16:18.023+01:00'
- Axis: DELIVERY
State: SENT
Timestamp: '2017-03-01T15:16:17.968+01:00'
UnifiedState: DELIVERED
Deleted: false
Properties:
- scheme: emailBody
value: ''
- scheme: emailSubject
value: ''
ConversationId: 5afdf6e8-862b-40bc-8bf2-86d6364df85c
SettlementIds:
- 641a034b-e3fc-4218-9a0b-148ed269db58
- 641a034b-e3fc-4218-9a0b-148ed269db59
schema:
type: object
properties:
itemsPerPage:
type: integer
itemCount:
type: integer
indexing:
type: boolean
numPages:
type: integer
pageId:
type: integer
Document:
type: array
items:
type: object
properties:
DocumentId:
pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
description: String representation of an Universally unique identifier (UUID), version 5. See RFC 4122
type: string
ID:
type: string
URI:
type: string
DocumentType:
type: object
properties:
mimeType:
type: string
documentProfileId:
type: string
type:
type: string
required:
- mimeType
- documentProfileId
- type
State:
enum:
- DELETION_AWAITING_APPROVAL
- DELETION_REQUESTED
- DELETION_IN_PROGRESS
- DELETION_COMPLETE
- DELETION_FAILED
type: string
LastEdit:
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.\d{3})?(Z|(\+|\-)[0-9]{2}:[0-9]{2})
description: ISO8601 formatted DateTime in UTC timezone, fx 2014-12-09T16:11:53Z with optionally .001 for milliseconds.
type: string
Actor:
type: object
properties:
Created:
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.\d{3})?(Z|(\+|\-)[0-9]{2}:[0-9]{2})
description: ISO8601 formatted DateTime in UTC timezone, fx 2014-12-09T16:11:53Z with optionally .001 for milliseconds.
type: string
Firstname:
type: string
Lastname:
type: string
Email:
type: string
required:
- Created
- Firstname
- Lastname
- Email
ReceiverCompanyName:
type: string
Tags:
type: object
properties:
Tag:
type: array
items:
type: string
required:
- Tag
ItemInfos:
type: array
items:
type: object
properties:
ItemInfo:
type: object
properties:
type:
type: string
value:
type: string
required:
- type
- value
required:
- ItemInfo
LatestDispatch:
type: object
properties:
DispatchId:
pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
description: String representation of an Universally unique identifier (UUID), version 5. See RFC 4122
type: string
ObjectId:
pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
description: String representation of an Universally unique identifier (UUID), version 5. See RFC 4122
type: string
Created:
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.\d{3})?(Z|(\+|\-)[0-9]{2}:[0-9]{2})
description: ISO8601 formatted DateTime in UTC timezone, fx 2014-12-09T16:11:53Z with optionally .001 for milliseconds.
type: string
SenderUserId:
pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
description: String representation of an Universally unique identifier (UUID), version 5. See RFC 4122
type: string
DispatchState:
enum:
- ACCEPTED
- PROCESSING
- COMPLETED
- FAILED_TRANSIENT
- FAILED
type: string
LastStateChange:
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.\d{3})?(Z|(\+|\-)[0-9]{2}:[0-9]{2})
description: ISO8601 formatted DateTime in UTC timezone, fx 2014-12-09T16:11:53Z with optionally .001 for milliseconds.
type: string
ReceiverConnectionId:
pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
description: String representation of an Universally unique identifier (UUID), version 5. See RFC 4122
type: string
DispatchChannel:
type: string
required:
- DispatchId
- ObjectId
- Created
- SenderUserId
- DispatchState
- LastStateChange
- ReceiverConnectionId
- DispatchChannel
SentReceivedTimestamp:
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.\d{3})?(Z|(\+|\-)[0-9]{2}:[0-9]{2})
description: ISO8601 formatted DateTime in UTC timezone, fx 2014-12-09T16:11:53Z with optionally .001 for milliseconds.
type: string
ProcessState:
type: string
ConversationStates:
type: array
items:
type: object
properties:
Axis:
enum:
- PROCESS
- DELIVERY
- PAYMENT
- OTHERPART
- REPLACEMENT
- FINANCING
- GLOBAL
type: string
State:
enum:
- PROCESS_ANY
- PAID
- REJECTED
- OVERDUE
- ACCEPTED
- PENDING
- INVOICED
- DISPUTED
- AWAITING_ASSISTANCE
- ASSISTANCE_PROVIDED
- CANCELED
- ASSISTANCE_CANCELED
- PUNCHOUT_SENT
- PUNCHOUT_EDIT
- DELIVERY_ANY
- FAILED
- SENT
- RECEIVED
- PROCESSING
- PENDING_CONNECTION
- PAYMENT_ANY
- PAYMENT_CREATED
- PAYMENT_PROCESSING
- PAYMENT_PENDING
- PAYMENT_COMPLETED
- PAYMENT_INCOMPLETE
- PAYMENT_REVERSAL_INCOMPLETE
- PAYMENT_EXPIRED
- PAYMENT_ERROR
- OTHER_ANY
- OTHER_REJECTED
- OTHER_CANCELED
- OTHER_PENDING
- OTHER_PAID
- OTHER_ACCEPTED
- OTHER_PAYMENT_COMPLETED
- OTHER_INVOICED
- OTHER_DISPUTED
- OTHER_OVERDUE
- REPLACEMENT_ANY
- ORIGINAL
- REPLACED
- CORRECTED
- FINANCING_ANY
- FINANCING_OFFERED
- FINANCING_OFFER_ACCEPTED_BY_SUPPLIER
- FINANCING_FUNDED
type: string
Timestamp:
type: string
required:
- Axis
- State
- Timestamp
UnifiedState:
enum:
- UNDETERMINED
- IN_TRANSIT
- PENDING_NOT_A_CONTACT
- FAILED_DELIVERY
- SENT
- DELIVERED
- ACCEPTED
- OVERDUE
- PAID_UNCONFIRMED
- PAID_CONFIRMED
- REJECTED_BY_SENDER
- REJECTED_BY_RECEIVER
- DISPUTED_BY_RECEIVER
- REPLACED
- CORRECTED
- AWAITING_ASSISTANCE
- ASSISTANCE_PROVIDED
- CANCELED
- ASSISTANCE_CANCELED
- PUNCHOUT_SENT
- PUNCHOUT_EDIT
type: string
Deleted:
type: boolean
Properties:
type: array
items:
type: object
properties:
scheme:
type: string
value:
type: string
required:
- scheme
- value
ConversationId:
type: string
SettlementIds:
type: array
items:
type: string
OrderTypeCode:
type: string
required:
- DocumentId
- ID
- URI
- DocumentType
- State
- LastEdit
- Actor
- ReceiverCompanyName
- Tags
- ItemInfos
- LatestDispatch
- SentReceivedTimestamp
- ProcessState
- ConversationStates
- UnifiedState
- Deleted
- Properties
- ConversationId
- SettlementIds
- OrderTypeCode
required:
- itemsPerPage
- itemCount
- indexing
- numPages
- pageId
- Document
'400':
description: Bad request error
'406':
description: The request uses Accept headers that the server is unable to fulfill
description: Gets a list of documents for the current user in XML or JSON format depending on the request Accept header. If multiple criteria are specified, they act as logical AND, unless specified otherwise. Drafts are not returned by default, unless stag=draft is specified. The return list of documents can be sorted by DueDate, LastEdit, Number, Amount, Date, Type.
operationId: get-rest-external-documents
parameters:
- name: Accept
in: header
required: true
description: Media types which are acceptable for the response. The possible values are text/xml and application/json.
schema:
enum:
- application/xml
- application/json
type: string
- name: tag
in: query
description: The tag the document must have. Can be used multiple times, which is interpreted as OR unless you set useAndOperatorForTags to true, then it will be AND.
schema:
type: string
- name: useAndOperatorForTags
in: query
description: It sets the tags based search to meet all criteria within the set of provided filters.
schema:
default: false
type: boolean
- name: withouttag
in: query
description: The tag the document must not have. Can be used multiple times, which is interpreted as AND.
schema:
type: string
- name: propertykey
in: query
description: Must be specified together with propertyvalue. Each pair of propertykey and propertyvalue will be interpreted as AND by default unless you set useOrOperatorForProperties to true, then it will be OR.
schema:
type: array
items:
type: string
- name: propertyvalue
in: query
description: See propertykey.
schema:
type: array
items:
type: string
- name: useOrOperatorForProperties
in: query
description: It sets the property based search to meet at least one criteria within the set of provided filters.
schema:
type: boolean
- name: ascending
in: query
description: Whether the documents are ordered in ascending or descending order (for last edited date), defaults to descending.
schema:
default: false
type: boolean
- name: type
in: query
description: The type of documents to include. Examples of document types 'invoice', 'creditnote'. Can be used multiple times, which is interpreted as OR.
schema:
type: string
- name: page
in: query
description: Result page to return. Each page has 'limit' number of results.
schema:
default: 0
type: integer
- name: limit
in: query
description: Maximum number of results to return. This is also the number of results on each skipped page. Capped to 100. If _onlyIndex is set to true, includesourcedocuments and populatePersonInfo to false value is capped to 10000.
schema:
default: 25
type: integer
- name: id
in: query
description: The documents to get DocumentInformation for (a Tradeshift UUID value)
schema:
type: string
- name: businessId
in: query
description: Limits documents to those with the given business id (invoice/credit note/purchase order number, e.g. 'ABC-123'). Note that business ids are not guaranteed to be unique for received documents, and may potentially be duplicated for different documents, even sent by the same supplier.
schema:
type: string
- name: sentBy
in: query
description: Sender company tenant id (a Tradeshift UUID value).
schema:
type: string
- name: sentTo
in: query
description: Receiver company tenant ids (a Tradeshift UUID value).
schema:
type: string
- name: stag
in: query
description: The system tag the document must have. Can be used multiple times, which is interpreted as OR. Known system include "inbox", "outbox", "draft", "sales", "purchases", "deleted".
schema:
type: string
- name: minissuedate
in: query
description: Earliest issue date of documents to match (according to UBL content).
schema:
type: string
- name: maxissuedate
in: query
description: Latest issue date of documents to match (according to UBL content).
schema:
type: string
- name: since
in: query
description: Limits documents to those which have changed since the given timestamp, formatted as a XSD-timestamp.
schema:
type: string
- name: createdBefore
in: query
description: Limits documents to those which were created before the given timestamp, formatted as a XSD-timestamp.
schema:
type: string
- name: createdAfter
in: query
description: Limits documents to those which were created after the given timestamp, formatted as a XSD-timestamp.
schema:
type: string
- name: processState
in: query
description: The _user_ state the document must have (see /metadata). Can be used multiple times, which is interpreted as OR. Note that this parameter is misnamed as it searches among all user states, not just process state.
schema:
type: string
- name: withoutProcessState
in: query
description: The process state the document must not have (see /metadata). Can be used multiple times, which is interpreted as AND. Note that this parameter is misnamed as it searches among all user states, not just process state.
schema:
type: string
- name: branchId
in: query
description: Document business ids. Can be used multiple times, which is interpreted as OR.
schema:
type: string
- name: totals
in: query
description: Whether to calculate the documents total amount or not.
schema:
default: false
type: boolean
- name: state
in: query
description: 'Representing the state (e.g. SENT, DELIVERED, ACCEPTED) of the searched documents.
Can be used multiple times, which is interpreted as OR.
Accepted values are: UNDETERMINED, IN_TRANSIT, PENDING_NOT_A_CONTACT, FAILED_DELIVERY, SENT, DELIVERED, ACCEPTED, OVERDUE, PAID_UNCONFIRMED, PAID_CONFIRMED, REJECTED_BY_SENDER, REJECTED_BY_RECEIVER, DISPUTED_BY_RECEIVER, CLOSED, REPLACED, CORRECTED, IN_ENRICHMENT, IN_CLEARANCE, COLLECTED, AWAITING_ASSISTANCE, ASSISTANCE_PROVIDED, CANCELED, ASSISTANCE_CANCELED, PUNCHOUT_SENT, PUNCHOUT_EDIT.
'
schema:
type: string
- name: ordering
in: query
description: Field that indicates the criteria on which result will be ordered upon returning (e.g. DueDate, Amount, Date).
schema:
default: LastEdit
type: string
- name: sales
in: query
description: This parameter decides whether the transaction type of selected documents should be sale or not.
schema:
type: boolean
- name: query
in: query
description: 'This parameter defines the specific text to be searched within the documents. It can include a single or
multiple words or phrases and documents that match the search condition will be returned.
'
schema:
type: string
- name: copyIndicator
in: query
description: Whether to search only copies of documents, originals or both.
schema:
type: boolean
- name: onlycopies
in: query
description: Whether to search only copies of documents.
schema:
default: false
type: boolean
- name: onlydrafts
in: query
description: Whether to search only drafts.
schema:
default: false
type: boolean
- name: onlydeleted
in: query
description: Whether to search only deleted documents.
schema:
default: false
type: boolean
- name: includesourcedocuments
in: query
description: Whether to include the raw UBL document in the result. The UBL documents are stripped of attachments before they are returned.
schema:
default: false
type: boolean
- name: waitForIndex
in: query
description: Whether to wait for pending documents to be indexed.
schema:
default: true
type: boolean
- name: _onlyIndex
in: query
description: This flag allows document listing using exclusively the data from the index.
schema:
default: false
type: boolean
- name: conversationId
in: query
description: The document conversation id used for getting its related documents.
schema:
type: string
- name: totalFrom
in: query
description: It represents the minimum value of the total range that can be used to filter documents.
schema:
type: number
- name: totalTo
in: query
description: It represents the maximum value of the total range that can be used to filter documents.
schema:
type: number
- name: currency
in: query
description: It represents the currency that can be used to filter documents only of that currency.
schema:
type: string
- name: requesterId
in: query
description: 'This field can be used to filter documents by the given list of requester Ids, only applicable for Purchase Request Documents. The requester is either the creating person or the document or if specified the "on behalf of" person
'
schema:
type: string
- name: invoiceTypeCode
in: query
description: 'This field represents the type of invoice for an invoice document. If the field is missing then we will have a normal/commercial invoice filter. For value 325 proforma invoice type will be searched and for value 386 we will have prepayment invoice.
'
schema:
type: array
items:
type: number
- name: accountingSystemId
in: query
description: 'This field represents a custom value assigned by a client to a connection with a supplier.
'
schema:
type: string
- name: accountingCost
in: query
description: This field represents a custom value assigned by a client refering to a Cost Center.
schema:
type: string
- name: profileId
in: query
description: It represents the profile id of a given document.
schema:
type: string
- name: populatePersonInfo
in: query
description: Populate person info (actor and requester)
schema:
default: true
type: boolean
- name: orderTypeCode
in: query
description: This field represents the type of order for an order document.
schema:
type: array
items:
type: number
- name: orderChangeTypeCode
in: query
description: This field represents the type of order for an order change document.
schema:
type: array
items:
type: number
x-annotation-dx-category: documents-document
summary: find documents
tags:
- dx-category--documents-document
/rest/external/documents/companies/{owningCompanyId}/{documentId}:
parameters:
- name: owningCompanyId
in: path
required: true
schema:
type: string
description: UUID identifier of company account owning the document.
- name: documentId
in: path
required: true
schema:
type: string
description: Document UUID identifier
get:
responses:
'307':
description: 'Successful response
'
headers:
Location:
schema:
type: string
'404':
description: 'Document not found or the security check do not pass
'
description: 'Retrieves a document in the context of an owning company. If the supplied authentication context has access to
see document identified by {documentId}, meaning the sender of the document, then returns a redirect to GET the document with {documentId}.
If the supplied authentication context does not have access to the document, then checks to see if it has
access to a document that references the supplied {documentId}, and returns a redirect to GET that referencing document instead.
This endpoint is used for example when the receiver of a document does not know the id of the document from
his side, but instead knows the company who sent it and the document id from that company context. The response
will be a redirect to GET a content of the document accessible by the receiver.
This only works if a sender tries to access one of its documents, or a receiver tries to find a content based
on a sender side reference id. It does not work for if a sender tries to access a document content based on the
reference to a receiver side, because this information is stored only on the receiver side copy of the document.
'
operationId: get-rest-external-documents-companies-owningcompanyid-documentid
parameters:
- name: Accept
in: header
required: true
description: 'The MIME media type of the response content. Example: text/xml, application/json, application/*
'
schema:
default: text/xml
type: string
x-annotation-dx-category: documents-document
summary: Get company document
tags:
- dx-category--documents-document
/rest/external/documents/csv:
get:
responses:
'200':
description: The list of documents as text/csv.
'400':
description: Bad request error
'406':
description: The request uses Accept headers that the server is unable to fulfill
description: Gets a list of documents in CSV format for the current user. If multiple criteria are specified, they act as logical AND, unless specified otherwise. Drafts are not returned by default, unless stag=draft is specified. Could be sorted by DueDate, LastEdit, Number, Amount, Date, Type. The returned mime-type is always text/csv regardless if Accept header is application/csv or text/csv.
operationId: get-rest-external-documents-csv
parameters:
- name: Accept
in: header
required: true
description: Media types which are acceptable for the response. The possible values are application/csv and text/csv.
schema:
enum:
- text/csv
- application/csv
type: string
- name: tag
in: query
description: The tag the document must have. Can be used multiple ti
# --- truncated at 32 KB (147 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tradeshift/refs/heads/main/openapi/tradeshift-dx-category-documents-document-api-openapi.yml