1. REST API for Oracle Intelligent Track and Trace
  2. Tasks
  3. Document Submission

Submit document

post

/bca/api/documentReceiver/v1/networks/{networkId}/flows/{flowId}/steps/{stepId}/variants/{variantId}

The operation submits the document provided in the request body for a given network ID, flow ID, step ID and document type variant ID.

Permisions

Any user with any application role can submit documents. However, the user must belong to the trading partner that is configured as a submitter for the step.

Request

Path Parameters
Supported Media Types
Request Body - multipart/related ()
Root Schema : schema
Type: object
Additional Properties Allowed: true
Show Source
Nested Schema : root
Type: object
Request Body - multipart/mixed ()
Root Schema : schema
Type: object
Additional Properties Allowed: true
Request Body - text/csv ()
Root Schema : schema
Type: string
Request Body - application/json ()
Root Schema : schema
Type: object
Back to Top

Response

202 Response

Document related to specified document type variant was accepted for processing. The json response is available for CSV documents only.
Body ()
Root Schema : CSV Document Post Response
Type: object
Title: CSV Document Post Response
Additional Properties Allowed
Show Source
  • CSV Record
    Title: CSV Record
    CSV record information identified by record identifier.
Nested Schema : CSV Record
Type: object
Title: CSV Record
CSV record information identified by record identifier.
Show Source
  • problems
  • Allowed Values: [ "ACCEPTED", "REJECTED" ]
    Record status (ACCEPTED - record was accepted for processing, REJECTED - record was rejected/excluded from processing). Note that the behavior isn't transactional. If one of the records is REJECTED the ramaining records won't be affected.
Nested Schema : problems
Type: array
Show Source
Nested Schema : CSV Record Problem
Type: object
Title: CSV Record Problem
Show Source
  • Problem description
  • Allowed Values: [ "PARSING", "VALIDATION" ]
    Problem type (PARSING - problem occured when the CSV document was parsed, VALIDATION - problem occured when the translated JSON document was validated against JSON schema).

400 Response

Input document is invalid. The json response is available for CSV documents only. Also, if the CSV file cannot be reliably split into multiple records during the parsing phase, the error code 400 will be returned with only simple string error description.
Body ()
Root Schema : CSV Document Post Response
Type: object
Title: CSV Document Post Response
Additional Properties Allowed
Show Source
  • CSV Record
    Title: CSV Record
    CSV record information identified by record identifier.
Nested Schema : CSV Record
Type: object
Title: CSV Record
CSV record information identified by record identifier.
Show Source
  • problems
  • Allowed Values: [ "ACCEPTED", "REJECTED" ]
    Record status (ACCEPTED - record was accepted for processing, REJECTED - record was rejected/excluded from processing). Note that the behavior isn't transactional. If one of the records is REJECTED the ramaining records won't be affected.
Nested Schema : problems
Type: array
Show Source
Nested Schema : CSV Record Problem
Type: object
Title: CSV Record Problem
Show Source
  • Problem description
  • Allowed Values: [ "PARSING", "VALIDATION" ]
    Problem type (PARSING - problem occured when the CSV document was parsed, VALIDATION - problem occured when the translated JSON document was validated against JSON schema).

403 Response

User is not authorized to send the document or a virus/malware has been found in the attachments.

404 Response

Business network, flow or step is not available to the current tenant, or the variant with variantId is not available for the document type accepted by this business flow step.

409 Response

Business flow is not active.

413 Response

Submitted request exceeds the maximum allowed size or attachment limits.

415 Response

CSV upload is not supported for this document type variant. Applicable only if Content-Type is text/csv.
Back to Top

Examples

Example of application/json Request Payload

The request body contains a document that should be submitted. The document needs to be a valid document of the document type associated with the business flow step and variant.

Request Example (curl command):

curl -X POST -i -H 'Content-type: application/json' -H 'Authorization: Bearer eyJ7NXQ...fMf46Q0yKopDxQ' -d '${REQUEST_BODY}' 'https://accountname.iad.bca.ocs.oraclecloud.com/bca/api/documentReceiver/v1/networks/local/flows/12/steps/3/variants/variant_a'
For generating an access token see Authentication.

Request Body:


    {
      "id": "IOT_EVENT_ID",
      "type": "INFO",
      "name": "EVENT_CODE",
      "description": "Event code description",
      "vehicle": {
        "sensorData": [
          {
            "key": "speed",
            "value": 50,
            "type": "number"
          }
        ]
      }
    }

Example of text/csv Request Payload

The request body contains a CSV document that should be submitted. The custom CSV format supports submitting one or more documents in one HTTP request, whereas JSON format supports only one document at a time. During the processing, a CSV document is transformed into one or more JSON files that are associated with the same business flow step and variant. The first column in CSV document is called record identifier, and identifies a single json document. It's the same as if one or more json documents are sent in a single batch. Attachments cannot be sent as a part of the CSV document.

Request Example (curl command):

curl -X POST -i -H 'Content-type: text/csv' -H 'Authorization: Bearer eyJ7NXQ...fMf46Q0yKopDxQ' -d '${REQUEST_BODY}' 'https://accountname.iad.bca.ocs.oraclecloud.com/bca/api/documentReceiver/v1/networks/local/flows/12/steps/3/variants/variant_a'
For generating an access token see Authentication.

Request Body:

record identifier, result/orderNumber, result/orderDate, result/currencyCode, result/orderLine/itemNumber, result/orderLine/quantity, result/orderLine/itemDescription
,                  string,             integer,          string,              list[object(number)],        list[object(number)],      list[object(string)]
1,                 X118654,            1614955016,       USD,                 1,                           2,                         LAPTOP
1,                 ,                   ,                 ,                    2,                           12,                        KEYBOARD
1,                 ,                   ,                 ,                    3,                           2,                         MOUSE
2,                 X118566,            1614955385,       GBP,                 1,                           5,                         LAPTOP
2,                 ,                   ,                 ,                    2,                           3,                         MOUSE
For the detailed CSV format description, see: CSV Data Format

Response codes

HTTP 202 Accepted - in case at least one record was accepted for processing

HTTP 400 if all records have validation errors.

HTTP 415 if CSV upload is not supported for this document type variant

Response example (202):

    {
      "1": {
        "status": "ACCEPTED"
      },
      "2": {
        "status": "REJECTED",
        "problems": [
          {
            "type": "PARSING",
            "description": "The 'result/orderDate' property value (X12) should be integer"
          }
        ]
    }

Response example (400):

    {
      "1": {
        "status": "REJECTED",
        "problems": [
        {
          "type": "PARSING",
          "description": "The 'result/orderDate' property is missing"
        }
        ]
      },
      "2": {
        "status": "REJECTED",
        "problems": [
        {
          "type": "VALIDATION",
          "description": "The 'result/currencyCode' property value (USS) is invalid"
        },
        {
          "type": "VALIDATION",
          "description": "The 'result/orderDate' property value (155) should be in utc-millisec format"
        }
        ]
      }
    }

Example of multipart Request Payload

A document containing one or more attachments must be sent with a multipart/related or multipart/mixed request, the document as the root (for related) or first (for mixed) body part and the attachments as additional request body parts. The document needs to be a valid document of the document type associated with the business flow step and variant. For more details, refer to https://tools.ietf.org/html/rfc1341 and https://tools.ietf.org/html/rfc2387.

The following headers are used to describe individual body parts in multipart request:

  • Content-Id: Optional header. Identifier of the body part. The Content-ID value must be unique within the HTTP request. If id is not provided, it is generated from other fields in the following order: Content-Disposition, Content-Description, Content-Type
  • Content-Type: Media type of the body part. It's returned when user downloads the attachment. This header is mandatory for all body parts. The root body part Content-Type must be application/json.
  • Content-Disposition: Optional header. Indicates whether a MIME body part is to be shown inline or is an attachment. The only allowed value is attachment. If user sends inline, server responds with HTTP 400. Attribute filename is used when user downloads the attachment. If missing, downloaded file name will be named as the id (see Content-Id above). Refer to https://tools.ietf.org/html/rfc2183 for details.
  • Content-Description: Optional header. It's used by the application to present the attachment in human-readable way.
  • Content-Transfer-Encoding: This header is optional. Can be used to specify how attachment data are encoded in a message body part, e.g. images can be encoded into ACSII format using base64 encoding.
    The supported values are: "7bit"(default), "8bit", "binary", "quoted-printable", "base64". For more details, refer to https://tools.ietf.org/html/rfc4021#page-46 or https://www.w3.org/Protocols/rfc1341/5_Content-Transfer-Encoding.html.
  • X-CSV-Record-ID: This header is required for an attachment body part that is specified for documents in CSV format. The header is used to associate an attachment with a particular document.
    Since the CSV format allows you to submit multiple documents in a single HTTP request, the header value must correspond to a record identifier value that identifies the document.
    This header is not required when the root part contains a single document with a single record identifier value. In such a case, all attachments are associated with this document.

Request Example - application/json with attachments (curl command):

curl -X POST -i -H 'Content-Type: multipart/related; type="application/json"; boundary=part-delimiter' -H 'Authorization: Bearer eyJ7NXQ...fMf46Q0yKopDxQ' --data-binary '${REQUEST_BODY}' 'https://accountname.iad.bca.ocs.oraclecloud.com/bca/api/documentReceiver/v1/networks/local/flows/12/steps/3/variants/variant_a'
For generating an access token see Authentication.

Request Body:


    --part-delimiter
    Content-Type: application/json

    {
      "id": "IOT_EVENT_ID",
      "type": "INFO",
      "name": "EVENT_CODE",
      "description": "Event code description",
      "vehicle": {
        "sensorData": [
          {
            "key": "speed",
            "value": 50,
            "type": "number"
          }
        ]
      }
    }

    --part-delimiter
    Content-Type: image/jpeg
    Content-ID: sensor-picture
    Content-Disposition: attachment; filename=sensor-picture.jpeg;
    Content-Description: The picture of the sensor
    Content-Transfer-Encoding: base64

    /9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBxA.../9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBxA

    --part-delimiter
    Content-Type: application/pdf
    Content-ID: sensor-manual
    Content-Disposition: attachment; filename=sensor-manual.pdf;
    Content-Description: Detail manual of sensor installation in PDF format
    Content-Transfer-Encoding: base64

    JVBERi0xLjYNCiWAgYKDDQoxIDAgb2JqDQo8PCA...g0Kc3RhcnR4cmVmDQoxMjE5MQ0KJSVFT0YNCg==

    --part-delimiter
    Content-Type: text/plain
    Content-ID: simple-text

    SIMPLE TEXT

    --part-delimiter--

Request Example - text/csv with attachments (curl command):

curl -X POST -i -H 'Content-Type: multipart/related; type="text/csv"; boundary=part-delimiter' -H 'Authorization: Bearer eyJ7NXQ...fMf46Q0yKopDxQ' --data-binary '${REQUEST_BODY}' 'https://accountname.iad.bca.ocs.oraclecloud.com/bca/api/documentReceiver/v1/networks/local/flows/12/steps/3/variants/variant_a'
For generating an access token see Authentication.

Request Body:


    --part-delimiter
    Content-Type: text/csv

    record identifier, result/orderNumber, result/orderDate, result/currencyCode, result/orderLine/itemNumber, result/orderLine/quantity, result/orderLine/itemDescription
    ,                  string,             integer,          string,              list[object(number)],        list[object(number)],      list[object(string)]
    1,                 X118654,            1614955016,       USD,                 1,                           2,                         LAPTOP
    1,                 ,                   ,                 ,                    2,                           12,                        KEYBOARD
    1,                 ,                   ,                 ,                    3,                           2,                         MOUSE
    2,                 X118566,            1614955385,       GBP,                 1,                           5,                         LAPTOP
    2,                 ,                   ,                 ,                    2,                           3,                         MOUSE

    --part-delimiter
    Content-Type: image/jpeg
    Content-ID: sensor-picture
    Content-Disposition: attachment; filename=sensor-picture.jpeg;
    Content-Description: The picture of the sensor
    Content-Transfer-Encoding: base64
    X-CSV-Record-ID: 1

    /9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBxA.../9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBxA

    --part-delimiter
    Content-Type: application/pdf
    Content-ID: sensor-manual
    Content-Disposition: attachment; filename=sensor-manual.pdf;
    Content-Description: Detail manual of sensor installation in PDF format
    Content-Transfer-Encoding: base64
    X-CSV-Record-ID: 1

    JVBERi0xLjYNCiWAgYKDDQoxIDAgb2JqDQo8PCA...g0Kc3RhcnR4cmVmDQoxMjE5MQ0KJSVFT0YNCg==

    --part-delimiter
    Content-Type: text/plain
    Content-ID: simple-text
    X-CSV-Record-ID: 2

    SIMPLE TEXT

    --part-delimiter--
Back to Top