Upload File to Ap Automation

Description

This mutation allows you to upload a PDF or image file (or XML file for DE legislation) of a purchase invoice for automated OCR analysis.
AP AUTOMATION (Accounts Payable Automation) is a variant of UploadFileToEntity, specifically designed for the case where entityType = "AP_AUTOMATION".
When this value is used, the system analyzes the file to automatically create a purchase invoice draft based on the content extracted by the OCR engine.

Unlike uploads to existing business records, here:

• no entityId is provided, since the purchase invoice does not yet exist at upload time;
• only specific file types are allowed (pdf, jpg, jpeg, png).
  For the DE legislation, XML invoice files (.xml) are also supported.

The generated purchase invoice will appear in the Purchase Invoices module after the OCR process completes, ready for validation and accounting posting.

Required Parameters

• file: Must be set to null in the GraphQL variables (GraphQL Upload scalar).
  The actual file content is sent separately using the multipart/form-data protocol according to the GraphQL multipart request specification.
• entityType: Must be "AP_AUTOMATION".
• fileName: (Optional), allows assigning a more explicit or meaningful name to the uploaded file than its original filename.
• businessDate: (Optional) A business-relevant date associated with the file.
• comment: (Optional) description or note.

Upload logic and multipart structure

The upload process follows the GraphQL multipart request specification, supported by HotChocolate.

You must send:

• operations: JSON string containing the mutation and variables (file: null)
• map: Mapping of the file index to the variable path
• file part: The actual file data

Header

mutation($input: UploadFileInput!) {
  uploadFileToEntity(input: $input) {
    id
  }
}

{
  "input": {
    "file": null,
    "entityType": "AP_AUTOMATION",
    "fileName": "supplier-invoice",
    "businessDate": "2025-10-30",
    "comment": "Purchase invoice sent for OCR analysis"
  }
}

{
  "0": ["variables.input.file"]
}

--boundary
Content-Disposition: form-data; name="0"; filename="supplier-invoice.pdf"
Content-Type: application/pdf

(binary file content here)
--boundary--

{
  "data": {
    "uploadFileToEntity": {
      "id": "f3a28b79dce24f129e7e4a4a98b4b13f.pdf"
    }
  }
}

{
  "query": "mutation($input: UploadFileInput!) { uploadFileToEntity(input: $input){id}}",
  "variables": {
    "input": {
      "file": null,
      "entityType": "AP_AUTOMATION",
      "fileName": "invoice-q1",
      "businessDate": "2025-10-30",
      "comment": "Purchase invoice sent for OCR"
    }
  }
}

UploadFileInput Input Parameters (AP_AUTOMATION context)

uploadFileToEntity Response

Returns the unique file ID (including the extension):

Example Response

{
  "data": {
    "uploadFileToEntity": {
      "id": "f3a28b79dce24f129e7e4a4a98b4b13f.pdf"
    }
  }
}

Link between the created purchase invoice and the uploaded file

Once the OCR analysis is complete, a purchase invoice is automatically created from the uploaded document.
This invoice record contains the fields fileId and fileName, which reference the uploaded file that triggered its creation.

You can retrieve the purchase invoice linked to a file in two ways:

1. Retrieve the purchase invoice directly from the uploaded file ID (the file ID is a String value, for example “a2b68ae9be594c1fbde5a60b77612506.pdf”)

   where: { fileId: { eq: "a2b68ae9be594c1fbde5a60b77612506.pdf" } }
   

2. Retrieve a specific purchase invoice by its ID (the purchase invoice ID is a standard UUID, for example “12207dc9-97d8-49e4-acde-d2f7ae6f9a37”)

   where: { id: { eq: "12207dc9-97d8-49e4-acde-d2f7ae6f9a37" } }
   

Below is a complete example of reading a purchase invoice by its ID, followed by a second query that retrieves information about the uploaded file associated with this invoice.

query ($purchaseInvoiceId: UUID!) {
  purchaseInvoices(
    where: {
      id: { eq: $purchaseInvoiceId }
    }
  ) {
    edges {
      node {
        id
        sourceType
        status
        description
        fileId
        fileName
        invoiceNumber
        invoiceDate
        operationDate
        firstDueDate
        totalLiquid
        pendingAmount
        hasCashVat
        supplier {
          socialName
        }
      }
    }
  }
}

Example Variables

{
  // ID of the purchase invoice created by the OCR upload
  "purchaseInvoiceId": "12207dc9-97d8-49e4-acde-d2f7ae6f9a37"
}

Example Response

{
  "data": {
    "purchaseInvoices": {
      "edges": [
        {
          "node": {
            "id": "12207dc9-97d8-49e4-acde-d2f7ae6f9a37",
            "sourceType":"AP_AUTOMATION",
            "status": "Pending",
            "description": "sales.businessErrors.simplifiedPurchaseInvoiceManuallyAddedMessage",

             // These fields reference the uploaded file linked to this invoice
            "fileId": "a2b68ae9be594c1fbde5a60b77612506.pdf",
            "fileName": "Amazon.pdf",

            "invoiceNumber": "INV-2025-0042",
            "invoiceDate": "2025-10-23",
            "operationDate": "2025-10-23",
            "firstDueDate": "2025-11-30",
            "totalLiquid": 1450.75,
            "pendingAmount": 1450.75,
            "hasCashVat": false,
            "supplier": {
              "socialName": "Amazon EU SARL"
            }
          }
        }
      ]
    }
  }
}

Once the fileId value is known, you can use it to retrieve detailed information about the uploaded file using the files query.
This also allows you to access the previewPath field, which provides the URL needed to preview the uploaded file (for example, to display the PDF or image in a viewer).

query ($fileId: String!) {
  files(
    where: { id: { eq: $fileId } }
  ) {
    edges {
      node {
        id
        status
        entityId
        entityType
        uploadDate
        businessDate
        fileName
        type
        comment
        mimeType
        size
        previewPath
      }
    }
  }
}

Example Variables

{
  // fileId value obtained from the previous purchase invoice query
  "fileId": "a2b68ae9be594c1fbde5a60b77612506.pdf"
}

Example Response

{
  "data": {
    "files": {
      "edges": [
        {
          "node": {
            "id": "a2b68ae9be594c1fbde5a60b77612506.pdf",
            "status": "Done",
            "entityId": "12207dc9-97d8-49e4-acde-d2f7ae6f9a37",
            "entityType": "AP_AUTOMATION",
            "uploadDate": "2025-10-23T15:51:40.218Z",
            "businessDate": "2025-10-23",
            "fileName": "Amazon",
            "type": "pdf",
            "comment": "Purchase invoice sent for OCR analysis",
            "mimeType": "application/pdf",
            "size": 245678,
            "previewPath": "/files/pR4mGwVe"
          }
        }
      ]
    }
  }
}

See also Purchase invoices for more details on this entity and its fields.

Errors depending on the uploaded file

How to verify that a file was successfully uploaded

File uploads are processed asynchronously.
After the upload request is received, the file is placed in a queue for antivirus scanning to ensure it is not infected.
A file passes through several status values during this process:

To check the status of a file, use the files query, filtering by the file id, and check the value of the status field.

• If status is Pending or ToCheck, processing is still in progress.
• When status is Done, the file has been successfully uploaded and is available.
• If status is Rejected, the file was not stored due to infection.

GraphQL Query Example (filtering by file ID)

query {
  files(
    where: {
      id: { eq: "98f7adc7dd104cd984f9c113ef9a8e54.pdf" }
    }
  ) {
    edges {
      node {
        fileName
        status
      }
    }
  }
}

Example Response

{
  "data": {
    "files": {
      "edges": [
        {
          "node": {
            "fileName": "invoice-q1",
            "status": "Done"
          }
        }
      ]
    }
  }
}