Generic Document Import

Request

Webhook for importing documents and attaching them to existing orders in Qargo.

How it works

An external system sends a file to this endpoint with metadata as query parameters.
The system matches the document to an order in Qargo using the provided query parameters.
The document is created and attached to the matched order.

Query parameters

The filename parameter is always required. Additional query parameters are configurable per integration during setup and are used to pass metadata about the file and to match the document to an order.

Query parameters can carry two types of information:

File metadata

Information about the document itself, for example:

filename (required) — Name of the uploaded file including extension
document_type — The type of document, see the Document types section below
document_name — Display name for the document in Qargo

Matching to Qargo orders

Information used to resolve which order the document should be attached to. The following order fields can be matched against:

customer_reference_number — The customer reference number on the order
name — The order name (e.g. OR-12345)
id — The order UUID

The match must resolve to exactly one order. If no order or multiple orders match, the import will be discarded.

The actual set of query parameters and how they map to the above is configured per integration.

Document types

The document_type parameter must be one of the following values:

Document type
`ADDRESS_LABEL`
`ANALYSIS_CERTIFICATE`
`ANNEX_VII_WASTE_SHIPMENT`
`APPROVAL_LOADING_LIST`
`ATR`
`AUTHORIZATION_PREFERENTIAL_ORIGIN`
`BILL_OF_LADING_INSTRUCTIONS`
`CATTLE_TRANSPORT_JOURNAL`
`CERTIFICATE_OF_ORIGIN`
`CERTIFICATE_OF_SHIPMENT`
`CLAIM`
`CMR_INSURANCE`
`COMMERCIAL_INVOICE`
`CONFIRMATION_TARIFF_SHIPPING_LINE`
`CONSIGNEE_SIGNATURE`
`CONSIGNOR_SIGNATURE`
`CONTAINER_CLEANING_CERTIFICATE`
`CUSTOMER_PAPERWORK`
`CUSTOMS_DECLARATION_INSTRUCTIONS`
`CUSTOMS_DOCUMENT`
`CUSTOMS_INVOICE`
`DANGEROUS_GOODS_DECLARATION`
`DEFENSE_MUNITIONS_VEHICLE_STABLING_REQUEST_FORM`
`DISPATCH_CONFIRMATION`
`DRAFT_BILL_OF_LADING`
`DRIVER_SIGNATURE`
`DUTCH_CUSTOMS_RELEASE`
`EQUIPMENT_INTERCHANGE_RECEIPT`
`EUR1`
`EUR_MED`
`EXPORT_ACCOMPANYING_DOCUMENT`
`EXPORT_DECLARATION`
`EXPORT_DOCUMENT`
`EXTRA_COST_CONFIRMATION`
`EXTRA_PERMITTED_WEIGHT`
`EX_A_EXPORT_DECLARATION`
`FINAL_BILL_OF_LADING`
`GOODS_IN`
`GOODS_OUT`
`GPS_TRACKER_REPORT`
`IFP`
`IMDG`
`IMPORT_DECLARATION`
`IMPORT_DOCUMENT`
`IM_A`
`INSURANCE_DOCUMENT`
`LOCATION_INFO`
`LUMPER_RECEIPT`
`MANIFEST`
`MULTIMODAL_DANGEROUS_GOODS_DECL`
`ORDER_ACCEPTANCE`
`ORDER_CONFIRMATION`
`ORIGINAL_CMR`
`OTHER_ADMINISTRATION`
`PALLET_LABEL`
`PALLET_LABEL_EXTERNAL`
`PALLET_NOTE`
`PHOTO_DAMAGED_GOODS`
`PHOTO_OF_GOODS_DELIVERY`
`PHOTO_OF_GOODS_PICKUP`
`PHOTO_SEAL_NUMBER`
`PICKUP_CMR`
`PICKUP_NOTE`
`PREFILLED_CMR`
`PRICE_OFFER_CUSTOMER`
`PROOF_OF_DELIVERY`
`PROOF_OF_DELIVERY_DRIVER_APP`
`PROOF_OF_DELIVERY_SIGNED`
`PROOF_OF_PICKUP`
`PROOF_OF_PICKUP_SIGNED`
`QUOTE`
`RECEIPT`
`SAFETY_SECURITY_DECLARATION`
`SECURITY_PLAN_FORM`
`SINGLE_ADMINISTRATIVE_DOCUMENT`
`STANDARD_OPERATING_PROCEDURE`
`STICKER_LABEL`
`T1_DOCUMENT`
`T2_DOCUMENT`
`TEMPERATURE_REPORT`
`TIMESLOT_CONFIRMATION`
`TRANSIT_DOCUMENT`
`UK_EXPORTER_DRA`
`UK_IMPORTER_DRA`
`VGM_CONTAINER`
`VISITOR_SAFETY_INSTRUCTION`
`WAITING_HOURS_INFORMATION`
`WASTE`
`WAYBILL`
`WEIGHING_TICKET`

Content encoding

Content format	Content-Type header	Behavior
Binary (e.g. PDF, image)	`application/pdf`, `image/png`, etc.	Passed through as-is
Text	`text/plain`, `text/xml`, etc.	Encoded as UTF-8 bytes
Base64-encoded string	Non-text or no header	Base64 decode attempted; raw string used on failure

Please provide the Content-Type header matching the file format.

Error handling

Scenario	Behavior
No order matches the provided criteria	Import is discarded
Multiple orders match the criteria	Import is discarded
Document metadata not provided	Import is discarded

Security

BasicAuthWebhookCredentials

Query

filenamestring(Filename)required

Name of the file being uploaded, including extension. This is used as the primary source for the file name in Qargo.

Bodyapplication/jsonrequired

Any of:

The document content as binary file data or a JSON message.

string (binary)

POST

/v1/webhook/document-import

"string"

Responses

Successful Response

Bodyapplication/json

errorsArray of objects or null(Errors)

Any of:

List of errors that occurred during the webhook processing. If empty/omitted, the webhook was processed successfully.

Response

{
  "errors": {
    "error_message": "The payload is invalid.",
    "error_type": "USER_INPUT_ERROR"
  }
}