# Create a Document and Signature Definitions Resource

# Alias

`DocumentCreation`

# Description

Creates a document and signature definitions resource. This resource can be created for two purposes: generating multiple signatures on a document or signing several external data objects from their hashes or several XMLDSig/XAdES Manifest objects.

In the first case, currently, only resources of this type containing a document and a definition of the PAdES-Basic, PAdES-BES, and PAdES-EPES, XMLDSig, XAdES-BES or XAdES-EPES signatures can be created.

Important

Subsequently, more signature definitions can be added via the Create a signature definition operation. If a document and signature definitions resource contains several signature definitions, the signatures for these definitions must be performed sequentially, i.e., without interweaving the operations for obtaining the hash of the document with operations for inserting the digital signature corresponding to different signature definitions.

In the second case, currently, only resources of this type containing an empty document and a definition of the externally detached XMLDSig/XAdES signature can be created.

The operation is useful for:

- Signing a batch of documents: for uploading the documents (and optionally the signature definitions) for subsequently creating the corresponding signature process.

- Signing a document and delegating the orchestrating of the signature process to the TRIDENT: for uploading the document (and optionally the signature definitions) for subsequently creating the corresponding signature process.

- Signing a document and orchestrating the signature process.

# Request

`POST /trustedx-resources/esignsp/v2/documents`

## Authorization

The request must contain a bearer access token generated by an authorization server of the platform. This token must have a scope that includes the `urn:safelayer:eidas:sign:process:document` value and must be used as explained in RFC 6750. Basically, the access token must be included in an `Authorization` header as follows:

`Authorization: Bearer <token>`

The client application must obtain the required access token via client credentials grant OAuth 2.0 interaction with the platform.

## Content-Type Header

There are three possibilities, depending on whether the resource is created for (i) signing a document provided with the signature definitions, (ii) signing a document provided without the signature definitions or (iii) signing multiple external data objects from their hashes.

### If the resource is created for signing a document provided along with the signature definitions:

`Content-Type: multipart/form-data; boundary=<part_boundary_mark>`

Where `<part_boundary_mark>` is the string that delimits the parts of the multipart entity inserted in the body.

### If the resource is created for signing a document provided without the signature definitions:

In this case, the `Content-Type` corresponds to the type of document to be signed (e.g., `application/pdf, text/xml`, etc.)

### The resource is created for signing multiple external data objects from their hashes or several XMLDSig/XAdES Manifest objects:

`Content-Type: application/json`

## Body

There are three possibilities, depending on whether the resource is created for signing a document provided with the signature definitions, signing a document provided without the signature definitions, or signing several external data objects from their hashes or several XMLDSig/XAdES Manifest objects.

- The resource is created for signing a document provided along with the signature definitions

- The resource is created for signing a document provided without signature definitions

- The resource is created for signing several external data objects from their hashes or several XMLDSig/XAdES Manifest objects

### The resource is created for signing a document provided along with the signature definitions

Contains a `multipart/form-data` entity with two parts: one of them, `"signers"`, is optional and contains a JSON array with the data required for creating the signature definitions of the resource. If no signature data is provided (i.e., the `"signers"` part contains an empty array), this data must be provided subsequently to the resource via the create a signature definition operation. The other part, `"document"`, contains the document to be assigned to the resource (subsequently, the document to be signed). The `Content-Type` header of this part specifies the type of this document (a PDF if the value in the header is `application/PDF`, an XML document if the value is `text/xml;charset="UTF-8"`, etc.). The `Content-Transfer-Encoding` header of the `"document"` part is only necessary when the document to be signed is encoded in binary (a PDF document, a PNG image, etc).

`------x1Xxx2XXxxx3XXX3xxxXX2xxX1x`
`Content-Disposition: form-data; name="signers"`
`Content-Type: application/json`
`[`
`{`
`"signature_policy_id" : {string},`
`"parameters" : {Parameters}`
`}`
`]`
`------x1Xxx2XXxxx3XXX3xxxXX2xxX1x`
`Content-Disposition: form-data; name="document";`
`Content-Type: application/pdf`
`Content-Transfer-Encoding: binary`
`<doc>`
`------x1Xxx2XXxxx3XXX3xxxXX2xxX1x--`

### The resource is created for signing a document provided without signature definitions

In this case, the body contains the document to be signed.

### The resource is created for signing multiple external data objects from their hashes or several XMLDSig/XAdES Manifest objects

In this case, the body contains a JSON object with the data required for creating the signature process:

`[`
`{`
`"signature_policy_id" : {string},`
`"parameters" : {Parameters}`
`}`
`]`

### Properties of the JSON object containing the data for creating the signature definitions

The JSON object containing the data used for creating the signature definitions has the following properties:

Property | Usage | Description
`signature_policy_id` | Required | Value assigned to the signature_policy_id property of one of the signature definitions of the resource created. If the resource is created for signing a document provided, the property can have the following values: `"urn:safelayer:eidas:policies:sign:document:pdf"`: definition of an ETSI PAdES signature (ETSI TS 102 778). `"urn:safelayer:eidas:policies:sign:document:xml"`: definition of a W3C XMLDSig/XAdES signature (ETSI TS 101 903). If the resource is created for signing multiple external data objects from their hashes, the property can only have the value `"urn:safelayer:eidas:policies:sign:document:xml"`.
`parameters` | Optional | Value assigned to the `parameters` property of one of the signature definitions of the resource created. This property is optional and can be omitted in some array elements.

# Response

## Status-Line

If the document and signature definitions resource is created successfully, the HTTP response will contain the following `Status-Line` (see HTTP Response Status for all the possible cases).

`HTTP/1.1 201 Created`

## Location Header

URL of the document and signature definitions resource created. This URL has the following structure:

`Location: https://<host>:<port>/trustedx-resources/esignsp/v2/documents/{doc_and_sigdefs_id}`

Where `{doc_and_sigdefs_id}` is the identifier of the document and signature definitions resource created.

## Content-Type Header

`Content-Type: application/json`

## Body

Contains a JSON object with the following structure:

`{`
`"id" : {string},`
`"self" : {string},`
`"signers" : [`
`{`
`"id" : {string},`
`"self" : {string}`
`}`
`]`
`}`

Property | Description
`id` | Identifier of the document and signature definitions resource.
`self` | URL of the document and signature definitions resource created.
`signers[]` | Information on the signature definitions contained in the resource created.
`signers[].id` | Identifier of one of the signature definitions contained in the resource created.
`signers[].self` | URL of one of the signature definitions contained in the resource created.

## Example

`HTTP/1.1 201 Created`
`Location: http://www.example.com/trustedx-resources/esignsp/v2/documents/idd_111`
`Content-Type: application/json`
`{`
`id" : "idd_111",`
`self" : "http://www.example.com/trustedx-resources/esignsp/v2/documents/idd_111",`
`"signers" : [`
`{`
`"id" : "ids_222",`
`"self" : "http://www.example.com/trustedx-resources/esignsp/v2/documents/idd_111/signers/ids_222"`
`}`
`]`
`}`