- Method
- The method to be called is:
- Parameters
- In the request headers the Authorization header must have the Access Token:
- Authorization: {{accessToken}}
- In the body of the POST a JSON structure like this one has to be passed:
{
"customer":{
"number": 1,
"name": "Test",
"address": "Grand Boulevard 1",
"postalCode": "1234-100",
"city": "Town",
"country": "UK",
"email": "test@test.com",
"taxNumber": "123456789"
},
"requestOptions": {
"option": 1,
"requestedFields": [
"fno",
"ftstamp",
"etotal",
"ettiva"
],
"reportName":"Impressão Minimal Simples"
},
"document":{
"docType": 1,
"customerName":"Test",
"salesmanName":"Gary",
"invoicingAddress1":"Invoice Address 1",
"invoicingPostalCode":"2010-152",
"invoicingLocality":"Invoice Locality",
"dueDate":"2020-01-27 00:00:00Z",
"documentObservations": "This is an observation"
},
"products":[
{
"reference": "C021",
"designation": "Test2",
"unitCode": "M",
"unitPrice": 15.55,
"discount1": 20,
"discount2": 0,
"quantity": 1,
"taxIncluded": true,
"taxPercentage": 23,
"taxRegion": "PT"
}
]
}
- Return Information
- Any call made to this method will return a JSON information with this structure
If the option value is “0”:{
"code": 0,
"message": "Information saved with success and mail sent to client",
"requestedFields": {} /** OBJECT CONTAINING THE REQUESTED FIELDS FROM requestOptions **/
}
If the option value is “1”:{
"code": 1,
"message": "Information saved with success",
"pdf": "LINK FOR THE DOCUMENT PDF",
"requestedFields": {} /** OBJECT CONTAINING THE REQUESTED FIELDS FROM requestOptions **/
}
If the option value is “2”:{
"code": 2,
"message": "Information saved with success",
"requestedFields": {} /** OBJECT CONTAINING THE REQUESTED FIELDS FROM requestOptions **/
}
In case of error:{
"code": 100,
"message": "Error message"
}
- JSON Specification for Generate Access Token
Request Options
Name | Type | PHC GO Entity | PHC GO Field | Observations |
option* | Integer | – | – | 0 – Send document by email 1 – Return document pdf link to print 2 – Create document without signing (WARNING: For this to work the Document Type must allow drafts. If the document type does not allow drafts the document WILL BE SIGNED) 3 – Create document with signing but does not produce pdf and email with pdf for client |
requestedFields | String Array | – | – | The DriveFX document entity fields to be returned on Success |
reportName | String | – | – | Name of the report type the document should have. If not defined will use one of the reports the user has access to
Ex. “Impressão Minimal Simples” |
emailBody | String | – | – | Send document by email with specific body |
emailSubject | String | – | – | Send document by email with specific subject |
Customer **
Name | Type | PHC GO Entity | PHC GO Field | Observations |
number** | Integer | Cl | no | |
estab | Integer | Cl | estab | By default it goes 0 |
name** | String | Cl | nome | |
address** | String | Cl | morada | |
postalCode** | String | Cl | codpost | |
city** | String | Cl | local | |
country** | String | Cl | pais | Can be set with the full name or the alpha-2 letter ISO3166 format
Ex. “PT”, “ES”,”US” (See here) |
email** | String | Cl | email | |
taxNumber** | String | Cl | ncont | |
abbreviatedName** | String | Cl | nome2 | |
Document
Name | Type | PHC GO Entity | PHC GO Field | Observations |
docType* | Integer | Td | ndoc | Type of document to create
Defaults: 1 – Invoice 2 – Invoice/Receipt 3 – Simple Invoice 4 – Delivery Note 5 – Credit Note 6 – Debit Note 7 – Other Documents 8 – Credit Note |
customerName | String | Cl | nome | |
customerNumber** | Integer | Cl | no | |
customerEstab | Integer | Cl | estab | By default it goes 0 |
currency | String | Ft | moeda | ISO4217 code of the currency to be used (See codes here)
When not set the default value is ‘EUR’.
IMPORTANT: If the set value is not ‘EUR’ the Product’s unitPrice will be set with this currency |
salesmanName | String | Ft | vendnm | |
invoicingAddress1 | String | Ft | morada | |
invoicingAddress2 | String | Ft | morada2 | |
invoicingPostalCode | String | Ft | codpost | |
invoicingLocality | String | Ft | local | |
documentDate**** | String | Ft | fdata | Format: “1900-01-01 00:00:00Z” |
documentTime | String | Ft | fhora | Format: “00:00:00” |
dueDate | String | Ft | pdata | Format: “1900-01-01 00:00:00Z” |
documentObservations | String | Ft | obs | |
financialDiscount | Double | Ft | efinv | Financial discount (not including tax)
IMPORTANT: When this value is set there is no need to set the financialDiscountInPercentage |
financialDiscountInPercentage | Double | Ft | fin | Percentage of financial discount (not including tax)
IMPORTANT: When this value is set there is no need to set the financialDiscount |
requisitionNumber | String | Ft | encomenda | |
unloadAddress1 | String | Ft | moradato | |
unloadAddress2 | String | Ft | morada2to | |
unloadPostalCode | String | Ft | codpostto | |
unloadLocality | String | Ft | localto | |
unloadCountry | String | Ft | paisto | Can be set with the full name or the alpha-2 letter ISO3166 format
Ex. “PT”, “ES”,”US” (See here) |
loadAddress1 | String | Ft | moradafrom | |
loadAddress2 | String | Ft | morada2from | |
loadPostalCode | String | Ft | codpostfrom | |
loadLocality | String | Ft | localfrom | |
loadCountry | String | Ft | paisfrom | Can be set with the full name or the alpha-2 letter ISO3166 format
Ex. “PT”, “ES”,”US” (See here) |
loadDate | String | Ft | datacarga | Format: “1900-01-01 00:00:00Z” |
loadTime | String | Ft | hcarga | Format:”00:00” |
unloadDate | String | Ft | datadescarga | Format: “1900-01-01 00:00:00Z” |
unloadTime | String | Ft | hdescarga | Format:”00:00” |
registration | String | Ft | matricula | |
paymentTerms | String | Ft | tpdesc | Name of the payment term on PHC GO.
IMPORTANT: If the set value doesn’t exist the invoice will be created with no payment terms |
customerAbbreviatedName | String | Ft | nome2 | |
isImportSeries | Boolean | – | | Parameter that specifies if document series is of type import or not |
signature | String | Ft | assinatura | |
impUniqueID | String | Ft | impUniqueID | |
signatureDate | String | Ft | signatureDate | Format: “1900-01-01 00:00:00Z” |
signatureHour | String | Ft | signatureHour | Format:”00:00” |
keyVersion | String | Ft | versaochave | |
refInt***** | String | Ft | refInt | Internal reference |
regType****** | String | Ft | codigo4041 | Regularization Type
Options: – Previous invoices not exact (78º, nº3) – Cancellations, Discounts or Returns (78º, nº4) – Calculation errors on previous invoices (78º, nº6) |
Products
Name | Type | PHC GO Entity | PHC GO Field | Observations |
reference* | String | Fi | ref | Product reference |
customerReference | String | Fi | cliref | Customer reference |
designation | String | Fi | design | |
unitCode | String | Fi | unidade | |
unitPrice* | Double | Fi | epv/pvmoeda | The unit price of the product.
By default the unitPrice is in Euros
The unitPrice will be set in the currency provided through the Document object Currency field |
discount1 | Integer | Fi | desconto | |
discount2 | Integer | Fi | desc2 | |
discount3 | Integer | Fi | desc3 | IMPORTANT: In order to see more than 2 discounts it is needed to change the “Number of discounts on invoicing documents” parameter |
discount4 | Integer | Fi | desc4 | IMPORTANT: In order to see more than 2 discounts it is needed to change the “Number of discounts on invoicing documents” parameter |
discount5 | Integer | Fi | desc5 | IMPORTANT: In order to see more than 2 discounts it is needed to change the “Number of discounts on invoicing documents” parameter |
discount6 | Integer | Fi | desc6 | IMPORTANT: In order to see more than 2 discounts it is needed to change the “Number of discounts on invoicing documents” parameter |
quantity* | Integer | Fi | qtt | |
taxIncluded | Boolean | Fi | ivaincl | Indicates if the unit price includes tax |
taxExemptionCode | String | Fi | codmotiseimp | |
taxPercentage | Integer | – | – | Percentage of tax. Used with taxRegion to define the Fi tabiva field |
taxRegion | String | – | – | Accepts one of the following regions: ‘PT’, ‘PT-AC’, ‘PT-MA’. Used with taxPercentage to define the Fi tabiva field |
originDocumentNumber*** | Integer | – | – | The type of the document we want to copy from |
originDocumentType*** | Integer | – | – | The type of the document we want to copy from |
warehouse | Integer | Fi | armazem | Number of the origin warehouse of the product |
item | String | Ft / Bo | Iitem | Free additional fields |
item2 | String | Ft / Bo | Iitem2 | Free additional fields |
* – Required
** – Customer can be referenced in two ways:
- On the Document’s customerNumber field (referencing an existent Customer)
- As an object (passing this object will also create/update the customer on PHC Go)
*** – Required when copying products from another document
**** – WARNING: Documents have to be issued sequentially, meaning:- If you issue a document with today’s date, you can’t issue a document for yesterday
- If you issue a document with tomorrow’s date you can only issue documents from that day forwar
***** – Only available in Pro Plan or greater
****** – Optional field to the type of document invoice, required field to the type of document Credit note [if the Accounting connection is enable]
Examples
Credit Notes:
The JSON structure for a credit note is slightly different, mainly on the Product side
Firstly we need to change the docType field from the Document request object to 5 (Credit Note).
On Product we only have to pass the following fields:
- reference (required) – Product reference
- originDocumentNumber (required) – Origin document’s Number
- originDocumentType (required) – Origin document’s Type
- quantity(optional) – Product Quantity
Note: You can find the document type values by going to Company Settings page and selecting Invoicing Types.
(…)
"document": {
"docType": 5,
"customerName": "Test",
"salesmanName": "Gary",
"invoicingAddress1": "Invoice Address 1",
"invoicingPostalCode": "2010-152",
"invoicingLocality": "Invoice Locality",
"dueDate": "2020-01-27 00:00:00Z",
"documentObservations": "This is an observation"
},
"products": [
{
"reference": "C003",
"originDocumentNumber": 112,
"originDocumentType": 1
}
]
(…)