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`	`Annotated[str, Form()]`	The message id provided by you (should be unique).	required
`party_id`	`Annotated[str \| None, Form()]`	The party identifier. This identifies, which template should be used. This is mutually exclusive to `template`. Prefer using `template` if possible.	`None`
`template`	`Annotated[str \| None, Form()]`	The explicitly provided template name. This is mutually exclusive to `party_id`.	`None`
`subject`	`Annotated[str, Form()]`	The subject of the email the file was attached to.	required
`result_mode`	`Annotated[ResultMode \| None, Form()]`	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.	`None`

NOTE: template and party_id are mutually exclusive. Prefer using template if possible.

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="template"

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

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

Example Request (with `party_id` instead of `template`)

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="template"

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

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

JSON variant of the endpoint

In addition to the multipart/form-data endpoint described above we also provide a variant which expects JSON in its request body. We still recommend using the multipart variant if possible. Its URL: https://api.semadox.net/incoming-json.

Request payload (JSON variant)

incoming_json endpoint request payload.

Attributes:

Name	Type	Description
`file_base64`	`Base64Bytes`	The pdf file we take care of encoded as base64.
`filename`	`str \| None`	The name of the input file (optional).
`message_id`	`str`	The message id provided by you (should be unique).
`template`	`str`	The name of the template to use when processing the file.
`subject`	`str`	The subject of the email the file was attached to.
`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.

Example Request (JSON variant)

POST /incoming-json HTTP/1.1
Host: api.semadox.net
Content-Type: application/json
Content-Length: 1234
Authorization: Bearer 1234abcd

{
  "file_base64": "JVBERi0xLjMgZmFrZSBwZGY=",
  "filename": "abc.pdf",
  "message_id": "123abcdef",
  "template": "the_template_name",
  "subject": "the subject"
}

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`	`date \| None`	date of the document
`source_path`	`str \| None`	path to the source document (a .pdf file - if archived)
`result_json_path`	`str \| None`	path to the result json file (if processed correctly)
`result_path`	`str \| None`	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.

HTTP Endpoint

The Endpoint

Request payload

Example Request

Example Request (with party_id instead of template)

Example Request ("no items" mode)

JSON variant of the endpoint

Request payload (JSON variant)

Example Request (JSON variant)

Response payload

HTTP Status Codes

Example Response

Document details endpoint

Example Request

Response payload

Example Response

Example Request (with `party_id` instead of `template`)