HTTP Endpoint

The Endpoint

POST https://api.semadox.net/incoming

Request payload

Receive Files to process asynchronously.

We use multipart/form-data requests to submit data to our API for the case of transmitting PDF files.

Parameters:

Name	Type	Description	Default
`file`	`UploadFile`	The pdf file we take care of.	required
`message_id`	`str`	The message id provided by you (should be unique).	`Form()`
`party_id`	`str`	The party identifier. This identifies, which template should be used.	`Form()`
`subject`	`str`	The subject of the email the file was attached to.	`Form()`
`result_mode`	`ResultMode \| None`	Optional result mode to use. Possible values are `default` and `no_items`. Use `no_items` if you don't want to process the document items. If not provided, the default mode is used.	`Form(None)`

Example Request

POST /incoming HTTP/1.1
Host: api.semadox.net
Content-Type: multipart/form-data; boundary=example-part-boundary
Content-Length: 1234
Authorization: Bearer 1234abcd

--example-part-boundary
Content-Disposition: form-data; name="subject"

A subject from email
--example-part-boundary
Content-Disposition: form-data; name="message_id"

1234abced
--example-part-boundary
Content-Disposition: form-data; name="party_id"

your assigned party id
--example-part-boundary
Content-Disposition: form-data; name="file"; filename="invoice123.pdf"
Content-Type: application/pdf

<binary pdf data>
--example-part-boundary--

Example Request ("no items" mode)

POST /incoming HTTP/1.1
Host: api.semadox.net
Content-Type: multipart/form-data; boundary=example-part-boundary
Content-Length: 1234
Authorization: Bearer 1234abcd

--example-part-boundary
Content-Disposition: form-data; name="result_mode"

no_items
--example-part-boundary
Content-Disposition: form-data; name="subject"

A subject from email
--example-part-boundary
Content-Disposition: form-data; name="message_id"

1234abced
--example-part-boundary
Content-Disposition: form-data; name="party_id"

your assigned party id
--example-part-boundary
Content-Disposition: form-data; name="file"; filename="invoice123.pdf"
Content-Type: application/pdf

<binary pdf data>
--example-part-boundary--

Response payload

The response will come as application/json.

incoming endpoint response.

Attributes:

Name	Type	Description
`log_id`	`str`	log id of the processed message
`status`	`str`	status message

HTTP Status Codes

Code	Meaning
202	Accepted - The PDF will be processed.
400	Further details in the JSON `code` field of the response. Most probably this is returned because there is no template configured.
415	The file you passed is not a PDF file.
422	One of the fields is missing.

Example Response

HTTP/1.1 202 OK
Content-Type: application/json

{"log_id": "13123", "status": "processing data"}

Document details endpoint

GET https://api.semadox.net/documents/{log_id}

log_id parameter should equal to the log_id field returned from the POST /incoming endpoint.

Example Request

GET /documents/296791909332963328 HTTP/1.1
Host: api.semadox.net
Authorization: Bearer 1234abcd

Response payload

The response will come as application/json.

Document details model for api responses.

Attributes:

Name	Type	Description
`id`	`str`	database id of the document
`filename`	`str`	name of the file
`message_id`	`str`	id of the message
`document_date`	`Optional[date]`	date of the document
`source_path`	`Optional[str]`	path to the source document (a .pdf file - if archived)
`result_json_path`	`Optional[str]`	path to the result json file (if processed correctly)
`result_path`	`Optional[str]`	path to the result file (if processed correctly)
`document_state`	`DocumentState`	state of the document

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "296791909332963328",
  "filename": "Rechnung_380086835.1_5.2024.pdf",
  "message_id": "<d42b85f6-aeac-4ef2-bfa5-681a3a195ef0@zeus.a1.net>",
  "document_date": "2024-05-24",
  "source_path": "/documents/296791909332963328.pdf",
  "result_json_path": "/documents/296791909332963328/result.json",
  "document_state": "processed_success"
}

The possible values of the document_state field are described below (they will be lowercased in the response):

Document state.

Attributes:

Name	Type	Description
`DEFERRED_FOR_RETRY`		the document processing failed because of mapping errors and it will be retried later.
`DLQ`		the document processing failed and it will be checked manually.
`PROCESSED_IGNORED`		the document was ignored according to its processing rules.
`PROCESSED_REJECTED`		the document was rejected according to its processing rules. The details were not yet sent to the client.
`PROCESSED_SUCCESS`		the document was successfully processed. The result was not sent yet.
`RECEIVED`		the document was received, but the processing has not started yet.
`SENT_REJECTED`		the document was rejected according to its processing rules and its details were sent to the client.
`SENT_SUCCESS`		the document was successfully processed and its result was sent successfully.
`UNKNOWN`		and unknown state. Shouldn't happen in practice.