PHC GO Help Center

Manuais

Create Document

Method

The method to be called is:

createDocument

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
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
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

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
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
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
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
refInt⁵	String	Ft	refInt	Internal reference
rectificationReason	String	Ft	ncreason	It´s mandatory in NC and ND documents.
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
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
}
]

(…)

Download script example

Method

Parameters

JSON body

Return Information

If the option value is “0”:

If the option value is “1”:

If the option value is “2”:

In case of error:

In case of success but with printing error: