Developer Handover Pack

Developer Handover Pack

Accounts Payable Management

Monitors the designated AP Gmail inbox and the Dext document queue for new invoice documents. When a document is detected, the agent triggers the Dext OCR extraction pipeline to pull structured fields including supplier name, invoice number, invoice date, due date, currency, line item descriptions, quantities, unit prices, and totals. The extracted record is then compared against existing Xero bills using the invoice number and supplier name as a composite key. If no duplicate is found the record is passed downstream with a duplicate-clear flag. If a duplicate is detected the record is flagged and a Slack notification is sent to the bookkeeper for manual resolution. This agent handles all intake volume without any manual sorting. Estimated build time: 10 hours. Complexity: Moderate.

// Input
dext.webhook_payload {
  document_id: string,
  supplier_name: string,
  invoice_number: string,
  invoice_date: ISO8601,
  due_date: ISO8601,
  currency: string,          // default 'USD'
  line_items: [
    { description: string, quantity: number, unit_price: number, total: number }
  ],
  total_amount: number,
  document_url: string        // hosted PDF link from Dext
}

// OR gmail.trigger_payload {
  message_id: string,
  from_email: string,
  subject: string,
  attachment_name: string,
  attachment_mime: string,    // must be 'application/pdf'
  attachment_base64: string
}

// Output (duplicate-clear)
invoice_record {
  source: 'dext' | 'gmail',
  document_id: string,
  supplier_name: string,
  invoice_number: string,
  invoice_date: ISO8601,
  due_date: ISO8601,
  currency: string,
  line_items: [ { description, quantity, unit_price, total } ],
  total_amount: number,
  document_url: string,
  duplicate_flag: false
}

// Output (duplicate detected, routed to Slack exception)
exception_record {
  invoice_number: string,
  supplier_name: string,
  duplicate_flag: true,
  existing_xero_bill_id: string,
  slack_alert_sent: true
}

Receives the duplicate-clear invoice record from the Invoice Intake Agent. The agent queries Xero's transaction history for the identified supplier and uses description-matching logic against the chart of accounts to suggest the most probable account code for each line item. The suggestion is scored by frequency of prior use for that supplier-description pair. The structured invoice record, suggested codes, and a confidence label (High, Medium, or Low) are assembled into a Slack Block Kit approval message and posted to the configured approver channel. If no response is received within the configured window (default 24 hours) the agent sends one automated reminder. A second non-response after 48 hours routes the invoice to the bookkeeper as a priority exception. Approved responses pass the confirmed codes downstream. Rejected or queried responses route to a bookkeeper exception thread. Estimated build time: 16 hours. Complexity: Complex.

// Input
invoice_record {
  supplier_name: string,
  invoice_number: string,
  due_date: ISO8601,
  currency: string,
  line_items: [ { description, quantity, unit_price, total } ],
  total_amount: number,
  document_url: string,
  duplicate_flag: false
}

// Coding lookup (internal, Xero GET /Reports/AgedPayablesByContact)
xero_history {
  contact_id: string,
  prior_line_items: [
    { description: string, account_code: string, frequency: number }
  ]
}

// Output (approved)
approved_invoice {
  invoice_record: { ...all fields above },
  coded_lines: [
    { description, account_code, account_name, confidence: 'High'|'Medium'|'Low' }
  ],
  approver_slack_id: string,
  approved_at: ISO8601,
  approval_status: 'approved'
}

// On approval rejection or query
exception_record {
  invoice_record: { ...all fields },
  coded_lines: [ ... ],
  approval_status: 'rejected' | 'queried',
  approver_note: string,
  routed_to_bookkeeper: true
}

// On approval timeout (48 hours, no response)
timeout_record {
  invoice_record: { ...all fields },
  approval_status: 'timeout',
  reminders_sent: number,
  routed_to_bookkeeper: true
}

Receives the approved invoice record from the Coding and Approval Agent and executes the final three steps of the AP cycle without manual intervention. The agent creates the bill in Xero using the Xero Bills API, attaching the original invoice PDF and all confirmed line codes. It then schedules the payment against the business's configured payment run date, using the due date from the invoice record and a configurable payment-run-day offset. If the due date falls within 48 hours of the current date, the bill is flagged as urgent in Xero and a Slack alert is sent to the bookkeeper. Once Xero confirms the payment record, the agent composes and sends a remittance advice email via Gmail to the supplier's email address on file in Xero, referencing the invoice number and amount paid. Estimated build time: 12 hours. Complexity: Moderate.

// Input
approved_invoice {
  supplier_name: string,
  invoice_number: string,
  invoice_date: ISO8601,
  due_date: ISO8601,
  currency: string,
  coded_lines: [
    { description, quantity, unit_price, total, account_code }
  ],
  total_amount: number,
  document_url: string,
  approver_slack_id: string,
  approved_at: ISO8601
}

// Xero bill creation (POST /api.xro/2.0/Invoices)
xero_bill_payload {
  Type: 'ACCPAY',
  Contact: { Name: supplier_name },
  Date: invoice_date,
  DueDate: due_date,
  LineItems: [ { Description, Quantity, UnitAmount, AccountCode } ],
  Attachments: [ { FileName, MimeType: 'application/pdf', Content: base64 } ]
}

// Output: Xero bill created
xero_bill_result {
  InvoiceID: string,
  Status: 'AUTHORISED',
  AmountDue: number,
  DueDate: ISO8601
}

// Output: payment scheduled
xero_payment_result {
  PaymentID: string,
  Date: ISO8601,         // next configured payment run date
  Amount: number,
  Status: 'AUTHORISED'
}

// Output: remittance email (Gmail send)
gmail_send_payload {
  to: supplier_email,    // from Xero Contact.EmailAddress
  subject: 'Remittance Advice: Invoice {invoice_number}',
  body_template: 'remittance_advice_v1',
  template_vars: { supplier_name, invoice_number, amount_paid, payment_date, payer_name }
}

// On urgent invoice (due within 48 hours)
urgent_flag {
  invoice_number: string,
  due_date: ISO8601,
  hours_until_due: number,
  slack_alert_sent: true,
  xero_bill_id: string
}

// ============================================================
// TRIGGER: New invoice detected
// ============================================================
SOURCE: dext.webhook OR gmail.label_monitor('AP-Invoices')

IF source == 'dext':
  raw_payload = dext.webhook_payload {
    document_id, supplier_name, invoice_number, invoice_date,
    due_date, currency, line_items[], total_amount, document_url
  }

IF source == 'gmail':
  raw_payload = gmail.message {
    message_id, from_email, subject,
    attachment_name, attachment_mime,  // must be 'application/pdf'
    attachment_base64
  }
  -> forward to dext.upload_document(attachment_base64)
  -> await dext.extraction_result { document_id, ...fields }

// ============================================================
// AGENT 1: Invoice Intake Agent
// ============================================================
idempotency_check(invoice_number, TTL=10min) -> SUPPRESS if duplicate trigger

xero_duplicate_query = GET /api.xro/2.0/Invoices
  ?InvoiceNumber={invoice_number}
  &Contact.Name={supplier_name}
  -> result_count: number

IF result_count > 0:
  -> exception_record { invoice_number, supplier_name,
       duplicate_flag: true, existing_xero_bill_id }
  -> slack.post_dm(bookkeeper_slack_id,
       text: 'Duplicate invoice detected: {invoice_number} from {supplier_name}')
  -> HALT flow for this invoice

IF result_count == 0:
  -> invoice_record {
       source, document_id, supplier_name, invoice_number,
       invoice_date, due_date, currency, line_items[],
       total_amount, document_url, duplicate_flag: false
     }
  -> PASS to Agent 2

// ============================================================
// AGENT 2: Coding and Approval Agent
// ============================================================
xero_history_query = GET /api.xro/2.0/Reports/AgedPayablesByContact
  + GET /api.xro/2.0/Invoices?ContactID={contact_id}&Status=AUTHORISED
  -> prior_line_items[] { description, account_code, frequency }

FOR each line_item in invoice_record.line_items[]:
  match = find(prior_line_items, where description ~= line_item.description)
  coded_line = {
    description: line_item.description,
    account_code: match.account_code OR 'REVIEW_REQUIRED',
    account_name: xero.chart_of_accounts[account_code].name,
    confidence: match.frequency >= 5 ? 'High'
               : match.frequency >= 2 ? 'Medium' : 'Low'
  }

// PO matching check (optional, if invoice contains PO reference)
IF invoice_number MATCHES po_prefix_regex:
  po_doc = google_drive.search(folder_id=AP_PO_FOLDER,
             query: invoice_number)
  IF po_doc NOT FOUND OR ABS(po_doc.total - total_amount) / total_amount > 0.02:
    -> exception_record { invoice_record, reason: 'PO mismatch or not found' }
    -> slack.post_dm(bookkeeper_slack_id) -> HALT

// Approval routing
approver_slack_id = approval_matrix[
  total_amount >= 2000 ? 'finance_manager' : 'bookkeeper'
]

slack.post_block_kit(channel=approver_slack_id, blocks={
  supplier_name, invoice_number, total_amount, due_date,
  coded_lines[], document_url,
  actions: [ { action_id: 'approve' }, { action_id: 'query_reject' } ]
})

// Reminder and timeout logic
WAIT 24h -> IF no response: slack.post_reminder(approver_slack_id)
WAIT 48h -> IF no response: timeout_record -> slack.post_dm(bookkeeper_slack_id) -> HALT

// Handle Slack interaction callback
ON slack.action_callback { action_id, user_id, response_text }:
  IF action_id == 'approve':
    -> approved_invoice {
         invoice_record, coded_lines[], approver_slack_id,
         approved_at: ISO8601, approval_status: 'approved'
       }
    -> PASS to Agent 3
  IF action_id == 'query_reject':
    -> exception_record { invoice_record, coded_lines[],
         approval_status: 'rejected' | 'queried',
         approver_note: response_text,
         routed_to_bookkeeper: true }
    -> slack.post_dm(bookkeeper_slack_id) -> HALT

// ============================================================
// AGENT 3: Payment and Remittance Agent
// ============================================================
// Step 1: Create bill in Xero
xero_bill = POST /api.xro/2.0/Invoices {
  Type: 'ACCPAY',
  Contact: { Name: supplier_name },
  Date: invoice_date,
  DueDate: due_date,
  LineItems: coded_lines[],
  Status: 'AUTHORISED',
  Attachments: [ { FileName, MimeType: 'application/pdf',
                   Content: base64(document_url) } ]
}
-> xero_bill_result { InvoiceID, Status, AmountDue, DueDate }

// Step 2: Urgent check
hours_until_due = (due_date - now()) / 3600
IF hours_until_due < 48:
  -> slack.post_dm(bookkeeper_slack_id,
       text: 'Urgent: invoice {invoice_number} due in {hours_until_due}h')

// Step 3: Schedule payment
next_payment_run_date = next_occurrence(PAYMENT_RUN_DAY env var)
xero_payment = POST /api.xro/2.0/Payments {
  Invoice: { InvoiceID: xero_bill_result.InvoiceID },
  Account: { Code: BANK_ACCOUNT_CODE env var },
  Date: next_payment_run_date,
  Amount: xero_bill_result.AmountDue
}
-> xero_payment_result { PaymentID, Date, Amount, Status }

// Step 4: Fetch supplier email from Xero
supplier_email = GET /api.xro/2.0/Contacts
  ?Name={supplier_name} -> Contact.EmailAddress
IF supplier_email IS EMPTY:
  -> slack.post_dm(bookkeeper_slack_id,
       text: 'Remittance skipped: no email on file for {supplier_name}')
  -> HALT remittance only; payment proceeds

// Step 5: Send remittance via Gmail
gmail.send {
  to: supplier_email,
  subject: 'Remittance Advice: Invoice {invoice_number}',
  template: 'remittance_advice_v1',
  vars: { supplier_name, invoice_number, amount_paid: xero_payment_result.Amount,
          payment_date: xero_payment_result.Date, payer_name: PAYER_NAME env var }
}

// ============================================================
// END STATE: Bill posted, payment scheduled, remittance sent
// ============================================================
audit_log.write {
  invoice_number, supplier_name, total_amount,
  xero_bill_id: xero_bill_result.InvoiceID,
  xero_payment_id: xero_payment_result.PaymentID,
  remittance_sent_to: supplier_email,
  completed_at: ISO8601
}