PHC GO Help Center

Create Document

Texto

Method
- The method to be called is:
  - https://interface.phcsoftware.com/v3/createDocument

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

(…)

Download script example