Shoeboxed / api

Official API documentation for integrating with Shoeboxed https://www.shoeboxed.com
14 stars 5 forks source link

Can't create document with document parameter #14

Open constantine-fry opened 10 years ago

constantine-fry commented 10 years ago

I upload file with following request:

Headers:

Accept = "application/json";
Authorization = "Bearer ***";
"Content-Type" = "multipart/form-data; boundary=063E0C37-2888-45F6-8E1B-9B380EA2337A";

Body:

--063E0C37-2888-45F6-8E1B-9B380EA2337A
 Content-Disposition:form-data;name="attachment";filename="Test document.pdf"
 Content-Type:application/pdf

 //file_content
 --063E0C37-2888-45F6-8E1B-9B380EA2337A
 Content-Disposition:form-data;name="document"
 Content-Type:application/json

 {"name":"aoeu"}
 --063E0C37-2888-45F6-8E1B-9B380EA2337A--

And the result is MALFORMED_JSON_ERROR:

  {
     code = "MALFORMED_JSON_ERROR";
     details =     (
      );
     reason = "The HTTP message body couldn't be parsed as JSON.";
   }

Although If I don't put any JSON inside request it works just fine. Can you please show me any example of correct request?

constantine-fry commented 10 years ago

If i put following JSON from into body

{
  "categories": [
    ""
  ],
  "city": "",
  "company": "",
  "country": "",
  "currency": "",
  "email": "",
  "issued": "DateTime",
  "items": [
    {
      "description": "",
      "price": "",
      "quantity": "int"
    }
  ],
  "processingState": "enum",
  "mobile": "",
  "name": "",
  "notes": "",
  "paymentType": {
    "lastFourDigits": "",
    "type": "enum"
  },
  "phone": "",
  "state": "",
  "surname": "",
  "tax": 0,
  "total": 0,
  "trashed": false,
  "type": "",
  "vendor": "",
  "viewed": false,
  "website": "",
  "zip": ""
}

I have another error:

{
    code = "INTERNAL_ERROR";
    reason = "Unable to determine. The issue has been logged and we'll investigate the cause.";
    suggestions =     (
    );
}
sbxalex commented 10 years ago

@Constantine-Fry when POSTing a document, you can either supply just the image with no document parameters, or you can supply the image and all document parameters. That's why your first request failed. The second failed because of invalid enums in your supplied JSON; the processingState and paymentType.type parameters should be chosen from the given options (a list of which you'll see on the Explorer under the model for Document).

Confusingly, the Explorer does fill in the enum as string "enum" in the model schema. This is probably a UI glitch.

constantine-fry commented 10 years ago

API explorer says that document parameter is required, but it's properties are optional. On another hand co create a category one can specify only the name of a category and skip the description. I find it a bit confusing.

igstan commented 10 years ago

@Constantine-Fry I've answered your document param question in #13.

Regarding the other question, about category creation, I don't understand exactly what's the issue there. Please open a separate issue for this, though.

This issue has attracted a few non-related issues. Let's keep them separate. It'll make the discussion easier.

constantine-fry commented 10 years ago

@igstan sorry, for mixing the issues.

My investigation shows that processingState is required parameter. Request with JSON like this works just fine:

{
    type = "other";
    name = "Test document.pdf";
    processingState = "NEEDS_SYSTEM_PROCESSING";
}

But if one doesn't specify processingState, he will get MALFORMED_JSON_ERROR error. And name is not gonna be used, until you specify type parameter.

Is it intended to be so?

igstan commented 10 years ago

@Constantine-Fry yes, processingState is a required param (I'll adjust the API explorer). Also, document-specific fields aren't taken into account until a type field is present. I agree this complicates the usability of the API considerably. We're working on a better way to represent this, but for the time being, here's a short recap on how you should approach this.

1. If you want Shoeboxed to process the document, send just the processingState field with a value of NEEDS_SYSTEM_PROCESSING.

{
  "processingState": "NEEDS_SYSTEM_PROCESSING"
}

2. If you want to user to process this document, but at a later time, send just the processingState field with a value of NEEDS_USER_PROCESSING.

{
  "processingState": "NEEDS_USER_PROCESSING"
}

3. If you want to fill in some of the documents fields, you'll have to ask the user for the document type in addition to values for document-specific fields. For example, a receipt document contains a vendor field:

{
  "type": "receipt",
  "vendor": "Amazon",
  "processingState": "PROCESSED"
}

Let me know if you have any more questions regarding this. Also, was it just simple API exploration that made you discover this, or do you have a potential user workflow in mind?

constantine-fry commented 10 years ago

I have in mind a workflow.

  1. User login and select an account.
  2. User select a category.
  3. User always upload a document with selected category.

Is it ok to upload a document with following parameters?

{
  "type": "receipt",
  "name": "document name",
  "categories" : ["selected_category"],
  "processingState": "NEEDS_SYSTEM_PROCESSING"
}
igstan commented 10 years ago

@Constantine-Fry it will work with a small observation. The name field will be ignored because it's not supported on receipt documents. The API explorer is a bit limited in that regard, we haven't found a way to precisely specify what fields each document type supports, but we're working on a fix.