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": [
"no",
"obranome"
],
"reportName": "Encomenda de Cliente Minimal"
},
"internalDocument": {
"docType": 1,
"salesmanName": "Gary",
"description": "Order",
"issuingAddress1": "Issue Address 1",
"issuingPostalCode": "2010-152",
"issuingLocality": "Issue locality",
"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 **/
}
-
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 Internal 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
|
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 |
- |
- |
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 internal dossier, in case the respective data is missing in the "internalDocument" section. |
Supplier2
Name |
Type |
PHC GO Entity |
PHC GO Field |
Observations |
number2 |
Integer |
Fl |
no |
|
estab |
Integer |
Fl |
estab |
By default it goes 0 |
name2 |
String |
Fl |
nome |
|
address2 |
String |
Fl |
morada |
|
postalCode2 |
String |
Fl |
codpost |
|
city2 |
String |
Fl |
local |
|
country2 |
String |
Fl |
pais |
Can be set with the full name or the alpha-2 letter ISO3166 format.
Ex. “PT”, “ES”,”US” (See here)
|
email2 |
String |
Fl |
email |
|
taxNumber2 |
String |
Fl |
ncont |
|
abbreviatedName2 |
String |
Fl |
nome2 |
|
notUpdate |
Boolean |
- |
- |
When setting this parameter "true", the customer data will not be updated in the supplier register itself, they will only be used to create a new supplier or in the internal dossier, in case the respective data is missing in the "internalDocument" section. |
Internal Document
Name |
Type |
PHC GO Entity |
PHC GO Field |
Observations |
docType1 |
Integer |
Ts |
ndos |
Type of document to create.
Defaults:
1 – Client Order
2 – Internal Consumption
3 – Worksheet
4 – Stock Transfer
5 – Order to Supplier
6 – Initial Stock
|
number |
Integer |
Bo |
obrano |
Important: The number can only be set for internal documents that can’t be communicated to
SAFT(must be type Internal Document/Others).
The document type alsoneeds to have:
– The parameter “Permite alterar o Número do Dossier” (Allows for changing the
Binder Number) set to true
– The parameter “Permite ter dossiers Rascunho” (Enables Draft binders) set to false
|
customerName |
String |
Bo |
nome |
|
customerNumber2 |
Integer |
Cl |
no |
|
customerEstab |
Integer |
Cl |
estab |
By default it goes 0 |
supplierName |
String |
Bo |
nome |
|
supplierNumber |
Integer |
Fl |
no |
|
supplierEstab |
Integer |
Fl |
estab |
By default it goes 0 |
salesmanName |
String |
Bo |
vendnm |
|
issuingAddress1 |
String |
Bo |
morada |
|
issuingAddress2 |
String |
Bo |
morada2 |
|
issuingPostalCode |
String |
Bo |
codpost |
|
issuingLocality |
String |
Bo |
local |
|
documentDate |
String |
Bo |
dataobra |
Format: “1900-01-01 00:00:00Z” |
documentTime |
String |
Bo |
horaobra |
Format: “00:00:00” |
description |
String |
Bo |
obranome |
|
documentObservations |
String |
Bo |
obs |
|
unloadAddress1 |
String |
Bo |
moradato |
|
unloadAddress2 |
String |
Bo |
morada2to |
|
unloadPostalCode |
String |
Bo |
codpostto |
|
unloadLocality |
String |
Bo |
localto |
|
unloadCountry |
String |
Bo |
paisto |
Can be set with the full name or the alpha-2 letter ISO3166 format.
Ex. “PT”, “ES”,”US” (See here)
|
loadAddress1 |
String |
Bo |
moradafrom |
|
loadAddress2 |
String |
Bo |
morada2from |
|
loadPostalCode |
String |
Bo |
codpostfrom |
|
loadLocality |
String |
Bo |
localfrom |
|
loadCountry |
String |
Bo |
paisfrom |
Can be set with the full name or the alpha-2 letter ISO3166 format.
Ex. “PT”, “ES”,”US” (See here)
|
financialDiscount |
Double |
Bo |
efinv |
Financial discount (not including tax).
IMPORTANT: When this value is set there is no need to set the financialDiscountInPercentage.
|
financialDiscountInPercentage |
Double |
Bo |
fin |
Percentage of financial discount (not including tax).
IMPORTANT: When this value is set there is no need to set the financialDiscount.
|
customerAbbreviatedName |
String |
Bo |
name2 |
|
refint |
String |
Bo |
refInt |
Internal reference |
taxExemptionCode |
String |
Bo |
codmotiseimp |
|
Products
Name |
Type |
PHC GO Entity |
PHC GO Field |
Observations |
reference1 |
String |
Bi |
ref |
Product reference |
customerReference |
String |
Bi |
cliref |
Customer reference |
designation1 |
String |
Bi |
design |
|
unitCode |
String |
Bi |
unidade |
|
unitPrice1 |
Double |
Bi |
epv |
|
discount1 |
Integer |
Bi |
desconto |
|
discount2 |
Integer |
Bi |
desc2 |
|
quantity1 |
Integer |
Bi |
qtt |
|
warehouse |
Integer |
Bi |
armazem |
Number of the origin warehouse of the product |
targetWarehouse |
Integer |
Bi |
ar2mazem |
Number of the destination warehouse of the product |
taxIncluded |
Boolean |
Bi |
ivaincl |
Indicates if the unit price includes tax |
taxPercentage |
Integer |
– |
– |
Percentage of tax. Used with taxRegion to define the Bi tabiva field |
taxRegion |
String |
– |
– |
Accepts one of the following regions: ‘PT’, ‘PT-AC’, ‘PT-MA’. Used
with taxPercentage to define the Bi tabiva field |
originDocumentNumber3 |
Integer |
– |
– |
The number of the internal document we want to copy from |
originDocumentType3 |
Integer |
– |
– |
The type of the internal document we want to copy from |
item |
String |
Bo |
Iitem |
Free additional fields |
item2 |
String |
Bo |
Iitem2 |
Free additional fields |
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 |
Bo |
Iitem |
Free additional fields |
ship_item2 |
String |
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/Supplier can be referenced in two ways:
- On the Internal Document’s customerNumber/supplierNumber field (referencing an existent Customer/Supplier)
- As an object (passing this object will also create/update the customer/suppleir on PHC GO)
3 - Required when copying products from another internal document
Example