Invoice Sending

Overview

When creating an invoice, you can add an optional Send node to control how and when the invoice is delivered to the customer. This allows you to override default sending behavior and use specific channels or scheduling.

Send Configuration

Basic Send Properties

Property	Type	Description	Values
`Channel`	string	Delivery channel	`sms`, `email`, `xml`, `print`
`Status`	string	Send status	`Queue` (only valid value)
`ToAddress`	string	Delivery address	Varies by channel
`ScheduleSendDate`	DateTime	Scheduled send date/time	YYYY-MM-DD HH:MM
`Note`	string	Additional message	Custom text

Channel-Specific Address Formats

Channel	Address Format	Example
SMS	Phone number	`+4533445566`
Email	Email address	`[email protected]`
XML	GLN number	`5790000123456`
Print	Not required	(empty)

Send Examples

SMS Delivery

{
  "Channel": "SMS",
  "Status": "Queue",
  "ToAddress": "+4533445566",
  "ScheduleSendDate": "2024-05-31 15:55",
  "Note": "Here is your invoice - Cheers!"
}

Email Delivery

{
  "Channel": "Email",
  "Status": "Queue",
  "ToAddress": "[email protected]",
  "ScheduleSendDate": "2024-05-31 10:00",
  "Note": "Please find your invoice attached. Thank you for your business!"
}

XML Delivery (E-boks)

{
  "Channel": "XML",
  "Status": "Queue",
  "ToAddress": "5790000123456",
  "ScheduleSendDate": "2024-05-31 09:00"
}

Print Delivery

{
  "Channel": "Print",
  "Status": "Queue",
  "ScheduleSendDate": "2024-05-31 08:00"
}

Send Status Tracking

Status Values and Meanings

Status	Value	Description
`Queue`	100	Invoice has just been created, not handled by FarPay yet
`PendingApproval`	110	Future states for invoices with approval workflow
`ReadyToPrint`	150	Invoice is placed in print queue (due to configuration or missing email)
`Sent`	200	Invoice has been sent successfully
`Error`	300	Invoice is halted and will not be processed
`ErrorSendingEmail`	310	Technical issues (e.g., bad SMTP connection)
`WrongEmailAddress`	320	No mailbox found with that email address
`EmailBounced`	330	Email bounced (e.g., full mailbox)
`EmailMarkedAsSpam`	340	Email was sent but marked as spam
`EmailRejected`	350	Email was rejected by recipient server
`MissingEmailAddress`	400	Email address was missing from invoice
`NA`	1000	General configuration indicates nothing should be sent
`NotSent`	9999	Invoice will not be sent

Implementation Examples

JavaScript Example

async function createInvoiceWithSend(invoiceData, sendConfig) {
  const invoiceWithSend = {
    ...invoiceData,
    Send: sendConfig
  };

  const response = await fetch('https://api.farpay.io/v2/invoices', {
    method: 'POST',
    headers: {
      'X-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(invoiceWithSend)
  });

  return await response.json();
}

// Create invoice with SMS delivery
const invoiceData = {
  CustomerNumber: "12345",
  InvoiceNumber: "INV-001",
  Amount: 125.50,
  Currency: "DKK",
  DueDate: "2023-02-15",
  Description: "Monthly subscription"
};

const smsSendConfig = {
  Channel: "SMS",
  Status: "Queue",
  ToAddress: "+4533445566",
  ScheduleSendDate: "2024-05-31 15:55",
  Note: "Your invoice is ready for payment"
};

createInvoiceWithSend(invoiceData, smsSendConfig)
  .then(result => {
    console.log('Invoice created with SMS delivery:', result);
  })
  .catch(error => {
    console.error('Failed to create invoice:', error);
  });

Python Example

import requests
from datetime import datetime, timedelta

def create_invoice_with_send(invoice_data, send_config, api_key):
    invoice_with_send = {
        **invoice_data,
        "Send": send_config
    }
    
    response = requests.post(
        'https://api.farpay.io/v2/invoices',
        headers={
            'X-API-KEY': api_key,
            'Content-Type': 'application/json'
        },
        json=invoice_with_send
    )
    
    return response.json()

# Create invoice with email delivery
invoice_data = {
    "CustomerNumber": "12345",
    "InvoiceNumber": "INV-001",
    "Amount": 125.50,
    "Currency": "DKK",
    "DueDate": "2023-02-15",
    "Description": "Monthly subscription"
}

# Schedule for tomorrow at 10:00 AM
tomorrow = datetime.now() + timedelta(days=1)
schedule_time = tomorrow.strftime("%Y-%m-%d 10:00")

email_send_config = {
    "Channel": "Email",
    "Status": "Queue",
    "ToAddress": "[email protected]",
    "ScheduleSendDate": schedule_time,
    "Note": "Please find your invoice attached. Thank you for your business!"
}

result = create_invoice_with_send(invoice_data, email_send_config, 'your-api-key')
print('Invoice created with email delivery:', result)

Scheduling Considerations

Schedule Send Date

Format: YYYY-MM-DD HH:MM
Approximate timing: Send schedules run on minute intervals
Peak handling: High volume may cause slight delays
Timezone: Uses system timezone

Best Practices for Scheduling

Avoid peak hours - Schedule during off-peak times for better reliability
Consider timezone - Account for customer timezone when scheduling
Test scheduling - Verify scheduling works in your environment
Monitor status - Check send status after scheduled time

Channel-Specific Considerations

SMS Channel

Character limits - Long messages may result in higher charges
International numbers - Use proper country code format
Delivery confirmation - SMS delivery is generally reliable

Email Channel

Attachment size - Large attachments may affect delivery
Spam filters - Ensure proper email configuration
Bounce handling - Monitor for bounced emails

XML Channel (E-boks)

GLN validation - Ensure GLN number is valid
Format compliance - XML must comply with E-boks standards
Delivery tracking - E-boks provides delivery confirmation

Print Channel

No address required - Uses default print configuration
Queue management - Prints are queued for batch processing
Physical delivery - Requires manual handling

Error Handling

Common Send Errors

Error Status	Description	Solution
`ErrorSendingEmail`	SMTP connection issues	Check email server configuration
`WrongEmailAddress`	Invalid email address	Validate email format
`EmailBounced`	Recipient mailbox full	Contact customer for alternative email
`EmailMarkedAsSpam`	Spam filter blocked	Improve email reputation
`EmailRejected`	Server rejected email	Check recipient server settings

Error Recovery

async function handleSendError(invoiceId, errorStatus) {
  switch (errorStatus) {
    case 310: // ErrorSendingEmail
      console.log('Technical email issue - retry later');
      break;
    case 320: // WrongEmailAddress
      console.log('Invalid email - update customer record');
      break;
    case 330: // EmailBounced
      console.log('Mailbox full - contact customer');
      break;
    case 340: // EmailMarkedAsSpam
      console.log('Spam filter issue - review email content');
      break;
    case 350: // EmailRejected
      console.log('Server rejection - check recipient settings');
      break;
    default:
      console.log('Unknown send error:', errorStatus);
  }
}

Monitoring Send Status

Check Send Status

async function checkSendStatus(invoiceId) {
  const response = await fetch(`https://api.farpay.io/v2/invoices/${invoiceId}`, {
    headers: {
      'X-API-KEY': 'your-api-key',
      'Accept': 'application/json'
    }
  });
  
  const invoice = await response.json();
  return invoice.SendStatus; // Returns numeric status value
}

// Monitor send status
const status = await checkSendStatus(12345);
console.log('Send status:', status);

if (status === 200) {
  console.log('Invoice sent successfully');
} else if (status >= 300) {
  console.log('Send error occurred');
}

Best Practices

Send Configuration

Validate addresses - Ensure correct format for each channel
Test channels - Verify each channel works in your environment
Monitor status - Regularly check send status for errors
Handle errors - Implement proper error handling for failed sends

Scheduling

Avoid conflicts - Don't schedule multiple sends to same customer
Consider timezone - Account for customer timezone
Plan for delays - Allow time for processing and delivery
Monitor queues - Check for queued sends regularly

Content

Keep SMS short - Avoid long messages that increase costs
Professional emails - Use proper email formatting and content
Clear messaging - Ensure send notes are clear and professional
Brand consistency - Maintain consistent messaging across channels

Related Endpoints

Invoices - Invoice creation and management
Customers - Customer information and preferences
Deliveries - Batch file processing