@spec acknowledge_document(Xero.Auth.Token.t(), String.t(), String.t()) ::
  :ok | {:error, Xero.Error.t()}

Acknowledges receipt of an inbound e-invoice.

Acknowledge inbound documents once processed to prevent re-delivery. Should be called after successfully importing the invoice into your system.

@spec download_document(Xero.Auth.Token.t(), String.t(), String.t()) ::
  {:ok, binary()} | {:error, Xero.Error.t()}

Downloads the raw UBL 2.1 XML for an e-invoicing document.

Returns binary XML suitable for archiving, forwarding, or compliance storage.

@spec get_document(Xero.Auth.Token.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, Xero.Error.t()}

Retrieves a single e-invoicing document by ID.

@spec get_document_status(Xero.Auth.Token.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, Xero.Error.t()}

Gets the delivery status of a sent e-invoice.

Poll this after send_document/3 until status is "DELIVERED" or "FAILED". Recommended polling interval: 30 seconds for first 5 minutes, then 5 minutes.

@spec get_organisation_participant(Xero.Auth.Token.t(), String.t()) ::
  {:ok, map()} | {:error, Xero.Error.t()}

Returns the PEPPOL registration details for the connected organisation itself. Use this to check if your organisation is properly registered on the PEPPOL network.

@spec list_documents(Xero.Auth.Token.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Xero.Error.t()}

Lists sent and/or received e-invoicing documents.

Options

• :direction — "SENT" | "RECEIVED" (omit for both)

• :status — "SENT" | "DELIVERED" | "FAILED" | "REJECTED"

• :date_from / :date_to — Date range (YYYY-MM-DD)
• :page — Page number
• :page_size — Items per page (max 100)

@spec lookup_participant(Xero.Auth.Token.t(), String.t(), String.t()) ::
  {:ok, map()} | {:error, Xero.Error.t()}

Checks if a business is registered as a PEPPOL participant.

Parameters

• participant_id — PEPPOL participant ID in scheme:value format e.g. "0151:12345678901" (AU ABN) or "0088:1234567890123" (GLN)

Returns participant details if registered, or :not_found error if not.

@spec reject_document(Xero.Auth.Token.t(), String.t(), String.t(), map()) ::
  :ok | {:error, Xero.Error.t()}

Rejects an inbound e-invoice.

Use this when you receive an invoice that you cannot process (e.g. wrong recipient, duplicate, incorrect details).

Required fields

• "rejectReason" — Reason code for rejection
• "rejectDescription" — Human-readable rejection description

@spec send_document(Xero.Auth.Token.t(), String.t(), map()) ::
  {:ok, map()} | {:error, Xero.Error.t()}

Sends an AUTHORISED Xero invoice as a PEPPOL e-invoice to the recipient.

The invoice must already exist in Xero with status AUTHORISED. The contact must have a valid PEPPOL participant ID configured.

Required fields

• "invoiceId" — UUID of the AUTHORISED Xero invoice to send

Optional fields

• "documentType" — PEPPOL document type code (default: standard invoice)