RAFE – FILES API

FilesAPI is a REST-based HTTP API, which enables registered users to download or upload EDI files from/to EDICENTER.

Base URL: https://rafe.edicenter.de/files

OPERATION METHOD PATH REQUEST BODY RESPONSE BODY
ListProfiles GET /files/profiles - application/json
ListFiles GET /files/{profile?} - application/json
DownloadFile GET /files/{profile}/{file} - application/octet
DeleteFile DELETE /files/{profile}/{file} - application/json
UploadFile POST /files/{profile}
/files/unidoc		 application/octet application/json
TestAuthenticate GET /files/test-auth - plain/text

Path parameters are enclosed in curly braces {...}.

AUTHENTICATION

RAFE requires each client request be authenticated. As authentication scheme RAFE uses the HTTP Basic Authentication. The client must send an Authorization header with its credentials for each request. Example request with the Authorization header:

GET /files/test-auth
Host: rafe.edicenter.de
Authorization: Basic {Base64 encoded string username:password}

If the client doesn't send Autorization header, the RAFE server responds with 401 Unauthorized.

If the client sends Authorization header with wrong credentials, the RAFE server responds with 401 Unauthorized.

You can obtain username and password from EDICENTER.

The client must send an Authorization header with its credentials for each request.

PROFILES

The FILES API has the concept of a profile.

The EDICENTER profile defines which EDI messages a user can exchange with his EDI partner.

A user can have one or more profiles. Every file that is transfered between the client and the server must be associated with exactly one profile.

Besides, each profile defines the direction of file transfer:

ListProfiles

Retrieves a list of all user profiles.

GET /files/profiles

PARAMETERS

none

RESPONSE

STATUS CODE BODY DESCRIPTION
200 OK application/json JSON array where each object has two properties: profile and profileType.

Example response:

[
    {
        "profile": "USER01_PART01_S_ORDERS",
        "profileType": "Send"
    },
    {
        "profile": "USER01_PART01_E_INVOIC",
        "profileType": "Receive"
    },
    {
        "profile": "USER01_PART01_E_ORDRSP",
        "profileType": "Receive"
    }
]

ListFiles

Retrieves a list of EDI file available for download.

GET /files/{profile?}

PARAMETERS

TYPE NAME DESCRIPTION
Path {profile?} Receive profile name. Optional parameter.

RESPONSE

STATUS CODE BODY DESCRIPTION
200 OK application/json JSON array
400 Bad Request application/json The error message indicates which error is present.

Request with {profile} path parameters returns only {profile}'s files.

Request without profile returns returns all Receive profiles files available for download.

The files can be downloaded individually with DownloadFile.

JSON structure:

[
    {
        "file" : {
            "name": string,
            "profile": string,
            "sha256": string
            "size": integer,
        "links": [
            {
                "href": string,
                "type": string
            },
            ...
        ]
    },
    {
        ...
    },
    ...
]

Example:

[
  {
    "file": {
      "name": "2022-11-24-12-09-43.txt",
      "profile": "USER01_PART01_E_INVOIC",
      "sha256": "A903E887BE98CEF8C021288791577EAD6DC7A22B031DB6BF8CE327FFB0F8C5DB",
      "size": 16688
    },
    "links": [
      {
        "href": "/files/USER01_PART01_E_INVOIC/2022-11-24-12-09-43.txt",
        "type": "GET"
      },
      {
        "href": "/files/USER01_PART01_E_INVOIC/2022-11-24-12-09-43.txt",
        "type": "DELETE"
      }
    ]
  },
  {
    "file": {
      "name": "2022-11-24-12-11-43.txt",
      "profile": "USER01_PART01_E_INVOIC",
      "sha256": "20C0AA051C66FE0BD517F28B40E8C8F22F506A77B44F06E883EE253C46ED2344",
      "size": 17817
    },
    "links": [
      {
        "href": "/files/USER01_PART01_E_INVOIC/2022-11-24-12-11-43.txt",
        "type": "GET"
      },
      {
        "href": "/files/USER01_PART01_E_INVOIC/2022-11-24-12-11-43.txt",
        "type": "DELETE"
      }
    ]
  },
  {
    "file": {
      "name": "2022-11-24-12-13-43.txt",
      "profile": "USER01_PART01_E_INVOIC",
      "sha256": "06E3A4D29A21E72CF09CD2FA3D3B701A8881FEE719810E43EDF3BD9BAE02BA49",
      "size": 14641
    },
    "links": [
      {
        "href": "/files/USER01_PART01_E_INVOIC/2022-11-24-12-13-43.txt",
        "type": "GET"
      },
      {
        "href": "/files/USER01_PART01_E_INVOIC/2022-11-24-12-13-43.txt",
        "type": "DELETE"
      }
    ]
  },
  {
    "file": {
      "name": "2022-11-24-12-09-43.txt",
      "profile": "USER01_PART01_E_ORDRSP",
      "sha256": "073F62CFC7B2F79AB0D669C8D9AFC083002B14CE1386BCF8B021FA4E2ED5E3D3",
      "size": 7044
    },
    "links": [
      {
        "href": "/files/USER01_PART01_E_ORDRSP/2022-11-24-12-09-43.txt",
        "type": "GET"
      },
      {
        "href": "/files/USER01_PART01_E_ORDRSP/2022-11-24-12-09-43.txt",
        "type": "DELETE"
      }
    ]
  },
  {
    "file": {
      "name": "2022-11-24-12-11-43.txt",
      "profile": "USER01_PART01_E_ORDRSP",
      "sha256": "EFDC123012FDD60B26491901CFC7427B8C75563187DFDC831A8E776C8D437481",
      "size": 17922
    },
    "links": [
      {
        "href": "/files/USER01_PART01_E_ORDRSP/2022-11-24-12-11-43.txt",
        "type": "GET"
      },
      {
        "href": "/files/USER01_PART01_E_ORDRSP/2022-11-24-12-11-43.txt",
        "type": "DELETE"
      }
    ]
  },
  {
    "file": {
      "name": "2022-11-24-12-13-43.txt",
      "profile": "USER01_PART01_E_ORDRSP",
      "sha256": "84BF52F0CE9EC4757E24D93B48141F0ABEACCDCBA556979F131B0356B83D8455",
      "size": 28598
    },
    "links": [
      {
        "href": "/files/USER01_PART01_E_ORDRSP/2022-11-24-12-13-43.txt",
        "type": "GET"
      },
      {
        "href": "/files/USER01_PART01_E_ORDRSP/2022-11-24-12-13-43.txt",
        "type": "DELETE"
      }
    ]
  }
]

Example: retrieves the JSON list of all Receive profiles with their files. Note: Path parameter {profile?} omitted.

curl -u USER01:pa$$w0rd https://rafe.edicenter.de/files

DownloadFile

With DownloadFile the client can download EDI files from EDICENTER.

GET /files/{profile}/{file}

PARAMETERS

TYPE NAME DESCRIPTION
Path {profile} Receive profile name
Path {file} File name

Example: Download and save a file locally:

curl -u USER01:pa$$w0rd --ouput invoice.txt https://rafe.edicenter.de/files/USER01_PART01_E_INVOIC/invoic101.txt

RESPONSE

STATUS CODE BODY DESCRIPTION
200 OK application/octet-stream RAFE server sends file bytes as payload. Body size equals payload size.
400 Bad Request application/json The error message indicates which error is present.

Error message JSON:

{
  "errors": [    
    "error message here ...",
    ...
  ]
}

DeleteFile

With DeleteFile the client can delete EDI files at EDICENTER. One file can be deleted per request. Deleted file cannot be downloaded anymore.

DELETE /files/{profile}/{file}

PARAMETERS

TYPE NAME DESCRIPTION
Path {profile} Receive profile name
Path {file} File name

Example: Delete a file at EDICENTER:

curl -v -u USER01:pa$$w0rd -X DELETE  https://rafe.edicenter.de/files/USER01_PART01_E_INVOIC/invoic101.txt

RESPONSE

STATUS CODE BODY DESCRIPTION
200 OK application/json File successfully deleted.
400 Bad Request application/json The error message indicates which error is present.

Example 200 OK response:

{
  "endpoint": "DeleteFile",
  "status": "file deleted",
  "file": {
    "name": "2022-11-24-16-08-51.txt",
    "profile": "USER01_PART01_E_INVOIC",
    "sha256": "2CB6186F0E25B36242C1FB63A5457A1BB3E1A549FE4F6FCC33E6BB41F3BCE455",
    "size": 116651
  }
}

UploadFile

With UploadFile the client can upload EDI files to EDICENTER. Only one file per request can be uploaded. Body must contain file bytes as payload. Body size equals payload size.

To upload non-UNIDOC file:

POST /files/{profile}

To upload UNIDOC file:

POST /files/unidoc

PARAMETERS

TYPE NAME DESCRIPTION
Path {profile} Send profile
Body n/a Uploaded file bytes; Content-Type: application/octet-stream

If the client sends a UNIDOC file it must specify the string unidoc in the path. When receiving the file, the RAFE server extracts the sender, recipient and message type from UNIDOC. With this information, the RAFE server is able to assign the uploaded UNIDOC to the customer's data in EDICENTER.

UNIDOC file must be UTF-8 encoded. UTF-8 BOM is not allowed.

The RAFE server is unable to extract the information in a non-UNIDOC file. So that the RAFE server can assign the uploaded non-UNIDOC file to the customer's data at EDICENTER, the customer must specify his profile name.

Example 1: Uploading non-UNIDOC file order.txt.

curl -u USER01:pa$$w0rd --data-binary @order.txt \
    --header "Content-Type:application/octet-stream" \
    https://rafe.edicenter.de/files/USER01_PART01_S_ORDERS

Response

{
  "endpoint": "UploadFile",
  "status": "file received and saved",
  "file": {
    "profile": "USER01_PART01_S_ORDERS",    
    "sha256": "685D4A63BDADE527ADB826371E80D4154C1CF757202E7D9899990644CADD93AF",
    "size": 32
  }
}

Example 2: Uploading UNIDOC file order.xml.

curl -u USER01:pa$$w0rd --data-binary @order.xml \
    --header "Content-Type:application/octet-stream" \
    https://rafe.edicenter.de/files/unidoc

RESPONSE

STATUS CODE BODY DESCRIPTION
201 Created application/json File was successfully uploaded
400 Bad Request application/json Bad input parameter(s). The error message indicates which error is present.

TestAuthenticate

GET  /files/test-auth

With TestAuthenticate, clients can test wether authentication works.

PARAMETERS

none

Example: Replace --user arguments with the username and password you got from EDICENTER:

> curl --user testuser1:pa$$w0rd https://rafe.edicenter.de/files/test-auth
> User testuser1 successfully authenticated to the RAFE server.

In the curl command above colon : separates username from password.

Windows 10 1803 and older has curl pre-installed.

More about curl

RESPONSE

STATUS CODE BODY DESCRIPTION
200 OK text/plain Client successfully authenticated.
401 Unauthorized none Authorization header missing or wrong credentials.

Home Files API Filetracker API Impressum Datenschutz | AGB
EDICENTER logo