Integration and API Spec

Integration and API Spec

Receivables and Invoice Chasing

Connected via the Xero OAuth 2.0 API. Used to poll aged receivables, read invoice status, apply payments, and mark invoices reconciled. Two agents consume this integration: Chase Scheduler and Payment Reconciliation.

// Poll input
GET /Invoices?where=Status=="AUTHORISED"&&DueDate<={today}&page=1
Headers: { Authorization: Bearer {access_token}, Xero-tenant-id: {tenantId} }

// Invoice object (key fields)
{ InvoiceID, InvoiceNumber, Contact.ContactID, Contact.EmailAddress,
  AmountDue, AmountPaid, DueDate, Status, LineItems[] }

// Payment POST body
{ Invoice: { InvoiceID }, Account: { Code: "090" },
  Date: "{payment_date}", Amount: {amount_paid} }

Connected via the Google Gmail API using OAuth 2.0. Used exclusively by the Reminder Sender Agent to dispatch staged reminder emails with invoice PDFs and Stripe pay links.

// Send input (n8n Gmail node)
{ to: contact_email, subject: "Invoice {InvoiceNumber} - Payment reminder",
  html: reminder_html_body, attachments: [ { name: "invoice.pdf", data: pdf_base64 } ] }

// Reply poll query
GET /messages?q=in:inbox from:{contact_email} after:{unix_send_time}

// Output: message ID for activity log
{ id: "17abc1234def", threadId: "17abc1234def", labelIds: ["SENT"] }

Connected via the Stripe REST API using a secret API key. Used by the Reminder Sender Agent to generate a one-time Payment Link for each invoice, which is embedded in the reminder email.

// Create price (ad-hoc per invoice)
POST /v1/prices
{ unit_amount: amount_due_cents, currency: "usd",
  product_data: { name: "Invoice {InvoiceNumber}" } }

// Create payment link
POST /v1/payment_links
{ line_items: [{ price: price_id, quantity: 1 }],
  metadata: { invoice_id: xero_invoice_id, contact_id: xero_contact_id } }

// Webhook payload (checkout.session.completed, key fields)
{ id, type: "checkout.session.completed",
  data.object: { payment_status: "paid", amount_total,
    metadata: { invoice_id, contact_id } } }

The orchestration layer. Hosts and executes all n8n workflows, manages scheduling, stores credentials, maintains the activity log, and surfaces monitoring alerts. All inter-agent handoffs route through this platform.

// Trigger: Cron node fires every 15 min
-> HTTP Request: GET Xero /Invoices (overdue filter)
-> IF node: AmountDue > 0 AND DueDate < today
   TRUE -> Chase Scheduler sub-workflow
   FALSE -> No-op end

// Activity log write
POST https://api.fullspec.io/v1/log
Headers: { Authorization: Bearer {fs_api_key} }
{ event_type: "reminder_sent", invoice_id, contact_id,
  timestamp: ISO8601, outcome: "success", agent_name: "Reminder Sender Agent" }

// Xero OAuth2 API
Credential name : xero_oauth2
Type            : OAuth2 API (Xero)
Client ID       : {XERO_CLIENT_ID}
Client Secret   : {XERO_CLIENT_SECRET}
Authorization URL: https://login.xero.com/identity/connect/authorize
Access Token URL : https://identity.xero.com/connect/token
Scope           : openid profile email accounting.transactions accounting.contacts.read offline_access
Tenant ID       : {XERO_TENANT_ID}  // stored as additional field

// Gmail OAuth2 API
Credential name : gmail_oauth2
Type            : Gmail OAuth2 API
Client ID       : {GOOGLE_CLIENT_ID}
Client Secret   : {GOOGLE_CLIENT_SECRET}
Scope           : https://www.googleapis.com/auth/gmail.send https://www.googleapis.com/auth/gmail.readonly

// Stripe API
Credential name : stripe_api
Type            : Stripe API
Secret Key      : {STRIPE_SECRET_KEY}  // sk_live_... in production
Webhook Secret  : {STRIPE_WEBHOOK_SIGNING_SECRET}  // whsec_...
API Version     : 2023-10-16

// FullSpec Automation internal API
Credential name : fullspec_api
Type            : Header Auth
Header Name     : Authorization
Header Value    : Bearer {FULLSPEC_API_KEY}

// Slack alerting (optional)
Credential name : slack_alert_webhook
Type            : HTTP Header Auth
Header Name     : Content-Type
Webhook URL     : {SLACK_INCOMING_WEBHOOK_URL}  // stored as node parameter