Difference between revisions of "Freeside:3:Documentation:Developer/FS/API"
m (Edit via perl MediaWiki framework (1.13)) |
m (Edit via perl MediaWiki framework (1.13)) |
||
(One intermediate revision by the same user not shown) | |||
Line 9: | Line 9: | ||
This module implements a backend API for advanced back-office integration. | This module implements a backend API for advanced back-office integration. | ||
− | In contrast to the self-service API, which authenticates an end-user and offers functionality to that end user, the backend API performs a simple shared-secret authentication and offers full, administrator functionality, enabling integration with other back-office systems. | + | In contrast to the self-service API, which authenticates an end-user and offers functionality to that end user, the backend API performs a simple shared-secret authentication and offers full, administrator functionality, enabling integration with other back-office systems. Only ccess this API from a secure network from other backoffice machines. DON'T use this API to create customer portal functionality. |
If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block the port by default, only allow access from back-office servers with the same security precations as the Freeside server, and encrypt the communication channel (for example, with an SSH tunnel or VPN) rather than accessing it in plaintext. | If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block the port by default, only allow access from back-office servers with the same security precations as the Freeside server, and encrypt the communication channel (for example, with an SSH tunnel or VPN) rather than accessing it in plaintext. | ||
Line 141: | Line 141: | ||
:; invoicing_list | :; invoicing_list | ||
::comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses), postal_invoicing Set to 1 to enable postal invoicing | ::comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses), postal_invoicing Set to 1 to enable postal invoicing | ||
+ | :; payby | ||
+ | ::CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY | ||
+ | :; payinfo | ||
+ | ::Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL | ||
+ | :; paycvv | ||
+ | ::Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch) | ||
+ | :; paydate | ||
+ | ::Expiration date for CARD/DCRD | ||
+ | :; payname | ||
+ | ::Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK | ||
:; referral_custnum | :; referral_custnum | ||
::Referring customer number | ::Referring customer number | ||
Line 184: | Line 194: | ||
::Mobile number | ::Mobile number | ||
:; invoicing_list | :; invoicing_list | ||
− | ::Comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses), | + | ::Comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses) |
+ | :; payby | ||
+ | ::CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY | ||
+ | :; payinfo | ||
+ | ::Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid +"pin" for PREPAY, purchase order number for BILL | ||
+ | :; paycvv | ||
+ | ::Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch) | ||
+ | :; paydate | ||
+ | ::Expiration date for CARD/DCRD | ||
+ | :; payname | ||
+ | ::Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK | ||
:; referral_custnum | :; referral_custnum | ||
::Referring customer number | ::Referring customer number | ||
Line 191: | Line 211: | ||
:; agentnum | :; agentnum | ||
::Agent number | ::Agent number | ||
− | ; customer_info | + | ; customer_info |
:Returns general customer information. Takes a list of keys and values as parameters with the following keys: custnum, secret | :Returns general customer information. Takes a list of keys and values as parameters with the following keys: custnum, secret | ||
; location_info | ; location_info |
Latest revision as of 07:14, 28 September 2015
Contents
NAME
FS::API - Freeside backend API
SYNOPSIS
use FS::API;
DESCRIPTION
This module implements a backend API for advanced back-office integration.
In contrast to the self-service API, which authenticates an end-user and offers functionality to that end user, the backend API performs a simple shared-secret authentication and offers full, administrator functionality, enabling integration with other back-office systems. Only ccess this API from a secure network from other backoffice machines. DON'T use this API to create customer portal functionality.
If accessing this API remotely with XML-RPC or JSON-RPC, be careful to block the port by default, only allow access from back-office servers with the same security precations as the Freeside server, and encrypt the communication channel (for example, with an SSH tunnel or VPN) rather than accessing it in plaintext.
METHODS
- insert_payment OPTION => VALUE, ...
- Adds a new payment to a customers account. Takes a list of keys and values as paramters with the following keys:
- secret
- API Secret
- custnum
- Customer number
- payby
- Payment type
- paid
- Amount paid
- _date
- Option date for payment
- Example:
my $result = FS::API->insert_payment( 'secret' => 'sharingiscaring', 'custnum' => 181318, 'payby' => 'CASH', 'paid' => '54.32', #optional '_date' => 1397977200, #UNIX timestamp ); if ( $result->{'error'} ) { die $result->{'error'}; } else { #payment was inserted print "paynum ". $result->{'paynum'}; }
- insert_credit OPTION => VALUE, ...
- Adds a a credit to a customers account. Takes a list of keys and values as parameters with the following keys
- secret
- API Secret
- custnum
- customer number
- amount
- Amount of the credit
- _date
- The date the credit will be posted
- Example:
my $result = FS::API->insert_credit( 'secret' => 'sharingiscaring', 'custnum' => 181318, 'amount' => '54.32', #optional '_date' => 1397977200, #UNIX timestamp ); if ( $result->{'error'} ) { die $result->{'error'}; } else { #credit was inserted print "crednum ". $result->{'crednum'}; }
- insert_refund OPTION => VALUE, ...
- Adds a a credit to a customers account. Takes a list of keys and values as parmeters with the following keys: custnum, payby, refund
- Example:
my $result = FS::API->insert_refund( 'secret' => 'sharingiscaring', 'custnum' => 181318, 'payby' => 'CASH', 'refund' => '54.32', #optional '_date' => 1397977200, #UNIX timestamp ); if ( $result->{'error'} ) { die $result->{'error'}; } else { #refund was inserted print "refundnum ". $result->{'crednum'}; }
- new_customer OPTION => VALUE, ...
- Creates a new customer. Takes a list of keys and values as parameters with the following keys:
- secret
- API Secret
- first
- first name (required)
- last
- last name (required)
- ss
- (not typically collected; mostly used for ACH transactions)
- company
- Company name
- address1 (required)
- Address line one
- city (required)
- City
- county
- County
- state (required)
- State
- zip (required)
- Zip or postal code
- country
- 2 Digit Country Code
- latitude
- latitude
- Longitude
- longitude
- geocode
- Currently used for third party tax vendor lookups
- censustract
- Used for determining FCC 477 reporting
- censusyear
- Used for determining FCC 477 reporting
- daytime
- Daytime phone number
- night
- Evening phone number
- fax
- Fax number
- mobile
- Mobile number
- invoicing_list
- comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses), postal_invoicing Set to 1 to enable postal invoicing
- payby
- CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
- payinfo
- Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
- paycvv
- Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
- paydate
- Expiration date for CARD/DCRD
- payname
- Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
- referral_custnum
- Referring customer number
- salesnum
- Sales person number
- agentnum
- Agent number
- agent_custid
- Agent specific customer number
- referral_custnum
- Referring customer number
- update_customer
- Updates an existing customer. Passing an empty value clears that field, while NOT passing that key/value at all leaves it alone. Takes a list of keys and values as parameters with the following keys:
- secret
- API Secret (required)
- custnum
- Customer number (required)
- first
- first name
- last
- last name
- company
- Company name
- address1
- Address line one
- city
- City
- county
- County
- state
- State
- zip
- Zip or postal code
- country
- 2 Digit Country Code
- daytime
- Daytime phone number
- night
- Evening phone number
- fax
- Fax number
- mobile
- Mobile number
- invoicing_list
- Comma-separated list of email addresses for email invoices. The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses)
- payby
- CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY
- payinfo
- Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid +"pin" for PREPAY, purchase order number for BILL
- paycvv
- Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
- paydate
- Expiration date for CARD/DCRD
- payname
- Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
- referral_custnum
- Referring customer number
- salesnum
- Sales person number
- agentnum
- Agent number
- customer_info
- Returns general customer information. Takes a list of keys and values as parameters with the following keys: custnum, secret
- location_info
- Returns location specific information for the customer. Takes a list of keys and values as paramters with the following keys: custnum, secret
- bill_now OPTION => VALUE, ...
- Bills a single customer now, in the same fashion as the "Bill now" link in the UI.
- Returns a hash reference with a single key, 'error'. If there is an error, the value contains the error, otherwise it is empty. Takes a list of keys and values as parameters with the following keys:
- secret
- API Secret (required)
- custnum
- Customer number (required)