I'd like to hear your comments!
--- begin of document --- THE SIMPLE INVOICING PROTOCOL - REQUEST FOR COMMENTS 19.04.2009
AUTHOR Juhani Jaakola e-mail email@example.com tel +358-40-5015182
The design goals of the Simple Invoicing Protocol (SINV) are:
- Simplicity and ease of implementation and use - Unambiguous protocol - The receiver can read all essential information automatically into their systems - Peer-to-peer protocol, no hubs or exchanges needed - SPAM protection - Invoices can even be sent by typing them manually
Invoices are sent as e-mail messages. Both the receiver and sender must have an e-mail address. The receiving mailbox must be dedicated to handle only SINV messages.
2. BASIC PRINCIPLE
First the invoice sender must send a PARTNER message which contains basic information of the sender. The receiver must check the information manually and create an account for the sender - either manually or (semi)automatically. The receiver must reply to the sender when the account was created or if the registration is rejected.
Registered senders can then send INVOICE messages. The receiver MUST reply to an INVOICE message whether it was successfully parsed and invoice processing in the receiving organization has been started. The receiver SHOULD inform the sender when the invoice is paid or if there are problems.
3. MODIFICATIONS NEEDED FOR EXISTING SYSTEMS
The sender must modify the invoicing system to send PARTNER and INVOICE messages via e-mail.
The receiver must dedicate a mailbox for incoming invoices. The receiver needs a program which can read the mailbox (via POP3 or IMAP for example) and parse the PARTNER and INVOICE messages. For each PARTNER message a work flow for a new account must be started. For each INVOICE message a work flow for approving a purchase invoice must be started.
4. MESSAGE SYNTAX
A message contains elements. An element contains a tag which begins with a period, such as .INVOICE. All tags are in UPPER CASE.
An element may contain a value. The value might be only one line, in which case in can be typed after the tag, separated by white space. If the value contains many lines, the lines can be typed after the tag. The value MUST NOT contain a line which begins with a dot.
All dates are represented as YYYYMMDD. All numbers are represented as digits with a leading sign, digits, decimal point (dot) and digits. The sign and decimal part (the dot and digits) are optional.
5. PARTNER MESSAGE
.PARTNER version Starts a partner message and indicates the version of the protocol.
.ID email Identifies a partner. Partners are identified by unique e-mail addresses.
.BUSINESSCODE Identifier of the company given by local authorities. In Finland this is the Y-tunnus.
.NAME Name of the company.
.ADDRESS Address of the company. Usually multiple lines. Format according to receiver's country.
.EMAIL Contact e-mail if diferent from ID.
.PHONE Contact phone.
.IBAN Bank account in IBAN format.
.ADRESSEE person Name of the person who should approve the partner account.
.ENDPARTNER Ends a PARTNER message.
.PARTNER 0.1 .ID firstname.lastname@example.org .BUSINESSCODE FI13727719 .NAME Dot Com Consulting .ADDRESS Solvikinkatu 11 B 28 00990 Helsinki Finland .EMAIL email@example.com .PHONE +358-40-5015182 .IBAN FI991234567890 .ADRESSEE Helena Takalo .ENDPARTNER
6. INVOICE MESSAGE
6.1. INVOICE HEADER
.INVOICE version Starts the INVOICE message and indicates the version of the protocol.
.ID number Unique identifier of the invoice - the invoice number.
.PAYMENTCODE 1234567890 OPTIONAL code that is returned via bank when this invoice is paid. Viitenumero in Finland.
.SENDER email Identifies the sending PARTNER.
.RECEIVER email Identified the receiving PARTNER.
.DATE yyyymmdd Date of the invoice.
.DUEDATE yyyymmdd Due date.
.CURRENCY ccc Three-character currency code.
.ADRESSEE person Name of the person who should check or approve the invoice.
.CUSTOMERREFERENCE text Customer's project number or any accounting information
.TEXT Free text.
.ENDINVOICE Ends the INVOICE message.
6.2. INVOICE ROW
.ROW Starts a new row in the invoice. All amounts are in ROWs.
.DESCRIPTION text One-line description of the item in this row.
.COUNT ddd.dd OPTIONAL how many items in this row?
.UNIT ccc OPTIONAL unit for .COUNT.
.AMOUNT ddd.dd Amount without VAT.
.DISCOUNT ddd.dd OPTIONAL Discount amount.
.VATPERCENT ddd.dd VAT percent.
.VAT ddd.dd VAT amount.
.TOTAL ddd.dd Total to be paid for this row.
.TEXT Free text.
.ENDROW Ends a ROW.
.INVOICE 0.1 .ID 123 .PAYMENTCODE 1234567890 .SENDER firstname.lastname@example.org .RECEIVER email@example.com .DATE 20090419 .DUEDATE 20090503 .CURRENCY EUR .ADRESSEE Helena Takalo .CUSTOMERREFERENCE XYZ123 .ROW .DESCRIPTION Invoicing seminar after Easter .COUNT 1 .AMOUNT 500.00 .DISCOUNT 0.00 .VATPERCENT 22.00 .VAT 11.00 .TOTAL 511.00 .ENDROW .ROW .DESCRIPTION Train ticket a 33.60 .COUNT 2 .AMOUNT 67.20 .DISCOUNT 0.00 .VATPERCENT 22.00 .VAT 14.78 .TOTAL 81.98 .ENDROW .ENDINVOICE
The total amount to be paid is 592.98, and it has to be paid on 3rd of May, 2009 to the account that belongs for " firstname.lastname@example.org". The actual account number was given by a preceding PARTNER message. --- end of document ---