Issue Adding Document with Unicode File Name - docusignapi

Question

--- Updated for clarity & Solution ---
As it pertains to the ability to add documents to an existing envelope we noticed we had an issue uploading documents that contain Unicode characters in the file name. Our call is a multi-part PUT request to the /restapi/v2/accounts/[account id]/envelopes/[envelope id]/documents endpoint which sends the document data as binary content within one of the parts of the message rather then base64 encoded the document and embedded it as part of the json payload.
Quickly we identified that the portion of our code which writes to the request stream was using Encoding.Ascii and should change to use Encoding.UTF8.
using (var writer = new StreamWriter(stream, Encoding.ASCII, 1024, true))
{
// write boundary, content type, content disposition & json content
}
However, this change produced a number of error messages depending on what we tried, for example:
{
"errorCode": "ENVELOPE_IS_INCOMPLETE",
"message": "The Envelope is not Complete. A Complete Envelope Requires Documents, Recipients, Tabs, and a Subject Line. Envelope definition missing."
}
{
"envelopeId": "XXXXXXX-1869-4555-8831-eb3ed90850c2",
"envelopeDocuments": [
{
"documentId": "1",
"order": "1",
"errorDetails": {
"errorCode": "NO_DOCUMENT_RECEIVED",
"message": "Bytes for document corresponding to documentId 1 not found in request."
}
}
]
}
Using tools like Fiddler & Postman we could now see the outbound REST calls which for all intents and purposes were virtually identical to the previous calls except they now allowed for Unicode characters.
PUT https://demo.docusign.net/restapi/v2/accounts/xxxxx/envelopes/xxxxxx-f772-48af-82ac-f0c2e95eaac1/documents HTTP/1.1
Content-Type: multipart/form-data; boundary=soucecode
Accept: application/json
X-DocuSign-Authentication: [Creds Here]
Host: demo.docusign.net
Content-Length: 11691
Expect: 100-continue
--soucecode
Content-Type: application/json
Content-Disposition: form-data
{
"documents": [
{
"order": 1,
"name": "Specíal Character.docx",
"documentId": "1"
}
]
}
--soucecode
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: file; filename="Specíal Character.docx"; documentid=1
[binary content removed for brevity]
--soucecode--

Answer 1

Docusign Rest Api also has an additional option to pass the document bytes as base64 encoded. This is alternate to the multi-part HTTP request that you have used.
From Documentation:
documentBase64 : This field can be used to include a base64 version of the document bytes within an envelope definition instead of sending the document using a multi-part HTTP request. The maximum document size is smaller if this field is used due to the overhead of the base64 encoding.
Here is a sample updateEnvelopeDocuments request
PUT /restapi/v2/accounts/{acccountId}/envelopes/{envelopeId}/documents HTTP/1.1
Host: demo.docusign.net
X-DocuSign-Authentication: <DocuSignCredentials><IntegratorKey>{key}</IntegratorKey><Username>{userName}</Username><Password>{pwd}</Password></DocuSignCredentials>
Content-Type: application/json
{
"documents": [
{
"documentId": "1",
"name" : "Doc Name",
"fileExtension": "pdf",
"documentBase64": "Add your Base64 encoded document bytes here"
}
]
}

Answer 2

After numerous red herrings DocuSign support was finally able to provide us with a working example call which we could replay from Fiddler/Postman on our side. Again they looked virtually identical. Using WinDiff which shows content not visible in normal editors we were able to see subtle differences. The following characters  were noticed around the boundaries in the non functioning call. These characters are known as BOMs (byte order markers). Turns out by default most of the Stream Writers in the .net framework output these BOM markers when using UTF8 encoding so it was not immediately clear they were there or how to turn them off. The DocuSign service is expecting they are not present in the request and will fail when they are.
To resolve : Instantiate a new instance of UTF8Encoding passing false to the constructor as below. This will prevent the BOMs from being written to the stream.
using (var writer = new StreamWriter(stream, new UTF8Encoding(false),1024, true))
{
// new UTF8Encoding(false)
// the false flags instructs the writer to NOT emit the UTF8 Preamble (BOM)
}
Incredibly simple fix for a very elusive issue.

Answer 3

Document names, and any other part of the DocuSign data handles Unicode characters just fine, including left to right.
The key is to use UTF-8 encoding. Here's the JSON and a screenshot of a quick test of using Hebrew in a document name.
JSON request:
{
"documents": [
{
"documentId": "1",
"name": "שלום Agreement",
"fileExtension": "html",
"documentBase64": "[Contents elided]"
}
],
"emailSubject": "NewCo agreement for signature",
"status": "sent",
"recipients": {
"signers": [
{
"recipientId": "1",
"name": "Larry",
"email": ... etc
Result shown in the sender's DocuSign web tool:

Answer 4

I just completed a test of using multi-part mime with a filename that uses Hebrew. After a number of issues, it worked fine.
Issues to check for:
Ensure that each separator line ends with "\r\n" (this is according to the specification)
Check that the boundary setting in the header properly matches the separator used in the request body. Note that the dashes (of the separator format) are not used in the boundary setting!
Check that each of the "definition" lines for each part has a "\r\n" line ending.
Check that the blank line after each separator consists of "\r\n"
You should give the right Content-Type in the file part of your request and give the file extension in the documents part of your json. Eg: "fileExtension": "docx"
Ensure that the file name (including any UTF-8 characters) is the same in the documents object and in the header for the mime part. (See below.)
Remember that the mime part which includes the file is sent in binary. No need to base64 encode it.
Once I got past the above, it all worked fine. See below.
Headers
{
"Authorization": "Bearer eyJ0eXAQXzvHysYca9V_47SUsBlahBlahBlah",
"Accept": "application/json",
"Content-Type": "multipart/form-data; boundary=AA1234"
}
Body Pretty-printed
--AA1234
Content-Disposition: form-data
Content-Type: application/json
{
"emailSubject": "NewCo agreement for signature",
"status": "sent",
"recipients": {
"signers": [
{
"recipientId": "1",
"name": "Joe Testor",
"email": "bvbv#gfg.ccvb",
"routingOrder": "1",
"tabs": {
"signHereTabs": [
{
"documentId": "1",
"optional": "false",
"recipientId": "1",
"name": "Please sign here",
"tabLabel": "signer1sig",
"xPosition": "100",
"yPosition": "100",
"pageNumber": "1"
}
]
}
}
]
},
"documents": [
{
"name": "שלום Agreement.docx",
"documentId": "1",
"order": "1",
"fileExtension": "docx"
}
],
"eventNotification": {
"includeDocumentFields": "false",
"envelopeEvents": [
{
"envelopeEventStatusCode": "Completed"
},
{
"envelopeEventStatusCode": "Declined"
},
{
"envelopeEventStatusCode": "Voided"
}
],
"url": "http://20f52d5f.proxy.webhookapp.com",
"requireAcknowledgment": "true",
"includeSenderAccountAsCustomField": "true",
"loggingEnabled": "true",
"includeDocuments": "false",
"signMessageWithX509Cert": "true"
}
}
--AA1234
Content-Disposition: file; filename="שלום Agreement.docx"; documentId=1
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
[Contents elided]
--AA1234--