Method
The method to be called is:
Parameters
In the request headers the Authorization header must have the Access Token:
- Authorization: {{accessToken}}
JSON body
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"
}
-
In case of success but with printing error:
{
"code": 50,
"message": "Information saved with success. Error printing the document."
}
JSON Specification for Create Document
Request Options
Name | Type | PHC GO Entity | PHC GO Field | Observations |
option1 | 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 |
clearWrongTaxNum | Boolean | – | – | This option allows the newly created clients to have their tax number deleted, in case it is invalid. This allows the creation of the client and the invoice, without the fiscal number. In case the new parameter is not indicated or has the value "false", the billing routine will ignore the new possibility.
|
requestedFields | String Array | – | – | The PHC GO 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
|
Customer2
Name | Type | PHC GO Entity | PHC GO Field | Observations |
number2 | Integer | Cl | no | |
estab | Integer | Cl | estab | By default it goes 0. |
name2 | String | Cl | nome | |
address2 | String | Cl | morada | |
postalCode2 | String | Cl | codpost | |
city2 | String | Cl | local | |
country2 | String | Cl | pais | Can be set with the full name or the alpha-2 letter ISO3166 format.
Ex. “PT”, “ES”,”US” (See here) |
email2 | String | Cl | email | |
taxNumber2 | String | Cl | ncont | |
abbreviatedName2 | String | Cl | nome2 | |
province (required field for Spain and Angola) | String | Cl | provincia | Customer Province. |
county (required field for Angola) | String | Cl | municipio | Customer county. |
notUpdate | Boolean | - | - | Observations: When setting this parameter "true", the customer data will not be updated in the customer register itself, they will only be used to create a new customer or in the invoice, in case the respective data is missing in the "document" section. |
Document
Name | Type | PHC GO Entity | PHC GO Field | Observations |
docType1 | 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 | |
customerNumber2 | 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 | |
documentDate4 | 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 | |
issueAsWaybillDoc | Boolean | Ft | issueAsWaybill | |
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 | |
blAccount | Integer | Ft | vdcontado | Used in documents that move treasury
Can be used when we want to use a treasury account different from the one configured in the series.
|
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”
|
taxExemptionCode | String | Ft | codmotiseimp | |
keyVersion | String | Ft | versaochave | |
refInt5 | String | Ft | refInt | Internal reference
|
rectificationReason | String | Ft | ncreason | It´s mandatory in NC and ND documents. |
regType6 | 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 |
reference1 | String | Fi | ref | Product reference
|
customerReference | String | Fi | cliref | Customer reference
|
designation | String | Fi | design | |
unitCode | String | Fi | unidade | |
unitPrice1 | 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
|
quantity1 | 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
|
originDocumentNumber3 | Integer | – | – | The type of the document we want to copy from
|
originDocumentType3 | 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
|
sncCode | Integer | Fi | cpoc | It serves to indicate the SNC code that allows the article to be integrated into CS Accounting.
|
Shipping
- This object is optional and can be added to the JSON body, if you have to use shipping data.
- Shipping data goes in PHC GO invoice as another product line (Fi).
Name | Type | PHC GO Entity | PHC GO Field | Observations |
ship_reference | String | Fi | ref | Shipping Reference
|
ship_designation | String | Fi | design | Shipping Designation
|
ship_unitPrice | Double | Fi | epv/pvmoeda | The unit price of the shipping fee.By default the unitPrice is in Euros.
The ship_unitPrice will be set in the currency provided through the Document object Currency field. |
ship_quantity | Integer | Fi | qtt | Shipping Quantity. By default, this field has a preset value of 1. |
ship_taxIncluded | Boolean | Fi | ivaincl | Indicates if the unit price includes tax. |
ship_taxPercentage | Integer | - | - | Percentage of tax. Used with taxRegion to define the Fi tabiva field. |
ship_taxRegion | String | - | - | Accepts one of the following regions: ‘PT’, ‘PT-AC’, ‘PT-MA’. Used with taxPercentage to define the Fi tabiva field |
ship_discount1 | Integer | Fi | desconto | |
ship_discount2 | Integer | Fi | desc2 | |
ship_item | String | Ft/Bo | Iitem | Free additional fields |
ship_item2 | String | Ft/Bo | Iitem2 | Free additional fields |
(…)
"shippings":[
{
"ship_reference": "3127425663141",
"ship_designation": "Taxa Fixa",
"ship_unitPrice": 5,
"ship_quantity": 1,
"ship_taxIncluded": true,
"ship_taxPercentage": 23,
"ship_taxRegion": "PT",
"ship_discount1": 20,
"ship_discount2": 10,
"ship_item": "some data",
"ship_item2": "some other data"
}
]
(...)
Footnotes
1 - Required
2 - 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)
3 - Required when copying products from another document
4 - 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
5 - Only available in Advanced plan or greater
6 - Optional field to the type of document invoice, required field to the type of document Credit note (if the Accounting connection is enable)
Example
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
- designation (optional) – Product designation
- 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",
"designation": "Concertina",
"originDocumentNumber": 112,
"originDocumentType": 1
}
]
(…)