Create Document
Texto


  • 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
 
NameTypePHC GO EntityPHC GO FieldObservations
option*Integer0 – 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
requestedFieldsString ArrayThe DriveFX document entity fields to be returned on Success
reportNameStringName 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”
emailBodyStringSend document by email with specific body
emailSubjectStringSend document by email with specific subject

 
Customer **
 
NameTypePHC GO EntityPHC GO FieldObservations
number**IntegerClno
estabIntegerClestabBy default it goes 0
name**StringClnome
address**StringClmorada
postalCode**StringClcodpost
city**StringCllocal
country**StringClpaisCan be set with the full name or the alpha-2 letter ISO3166 format

Ex. “PT”, “ES”,”US” (See here)
email**StringClemail
taxNumber**StringClncont
abbreviatedName**StringClnome2

 
Document
 
NameTypePHC GO EntityPHC GO FieldObservations
docType*IntegerTdndocType 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
customerNameStringClnome
customerNumber**IntegerClno
customerEstabIntegerClestabBy default it goes 0
currencyStringFtmoedaISO4217 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
salesmanNameStringFtvendnm
invoicingAddress1StringFtmorada
invoicingAddress2StringFtmorada2
invoicingPostalCodeStringFtcodpost
invoicingLocalityStringFtlocal
documentDate****StringFtfdataFormat: “1900-01-01 00:00:00Z”
documentTimeStringFtfhoraFormat: “00:00:00”
dueDateStringFtpdataFormat: “1900-01-01 00:00:00Z”
documentObservationsStringFtobs
financialDiscountDoubleFtefinvFinancial discount (not including tax)

IMPORTANT: When this value is set there is no need to set the financialDiscountInPercentage
financialDiscountInPercentageDoubleFtfinPercentage of financial discount (not including tax)

IMPORTANT: When this value is set there is no need to set the financialDiscount
requisitionNumberStringFtencomenda
unloadAddress1StringFtmoradato
unloadAddress2StringFtmorada2to
unloadPostalCodeStringFtcodpostto
unloadLocalityStringFtlocalto
unloadCountryStringFtpaistoCan be set with the full name or the alpha-2 letter ISO3166 format

Ex. “PT”, “ES”,”US” (See here)
loadAddress1StringFtmoradafrom
loadAddress2StringFtmorada2from
loadPostalCodeStringFtcodpostfrom
loadLocalityStringFtlocalfrom
loadCountryStringFtpaisfromCan be set with the full name or the alpha-2 letter ISO3166 format

Ex. “PT”, “ES”,”US” (See here)
loadDateStringFtdatacargaFormat: “1900-01-01 00:00:00Z”
loadTimeStringFthcargaFormat:”00:00”
unloadDateStringFtdatadescargaFormat: “1900-01-01 00:00:00Z”
unloadTimeStringFthdescargaFormat:”00:00”
registrationStringFtmatricula
paymentTermsStringFttpdescName of the payment term on PHC GO.

IMPORTANT: If the set value doesn’t exist the invoice will be created with no payment terms
customerAbbreviatedNameStringFtnome2
isImportSeriesBooleanParameter that specifies if document series is of type import or not
signatureStringFtassinatura
impUniqueIDStringFtimpUniqueID
signatureDateStringFtsignatureDateFormat: “1900-01-01 00:00:00Z”
signatureHourStringFtsignatureHourFormat:”00:00”
keyVersionStringFtversaochave
refInt*****StringFtrefIntInternal reference
regType******StringFtcodigo4041Regularization 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
 
NameTypePHC GO EntityPHC GO FieldObservations
reference*StringFirefProduct reference
customerReferenceStringFiclirefCustomer reference
designationStringFidesign
unitCodeStringFiunidade
unitPrice*DoubleFiepv/pvmoedaThe 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
discount1IntegerFidesconto
discount2IntegerFidesc2
discount3IntegerFidesc3IMPORTANT: In order to see more than 2 discounts it is needed to change the “Number of discounts on invoicing documents” parameter
discount4IntegerFidesc4IMPORTANT: In order to see more than 2 discounts it is needed to change the “Number of discounts on invoicing documents” parameter
discount5IntegerFidesc5IMPORTANT: In order to see more than 2 discounts it is needed to change the “Number of discounts on invoicing documents” parameter
discount6IntegerFidesc6IMPORTANT: In order to see more than 2 discounts it is needed to change the “Number of discounts on invoicing documents” parameter
quantity*IntegerFiqtt
taxIncludedBooleanFiivainclIndicates if the unit price includes tax
taxExemptionCodeStringFicodmotiseimp
taxPercentageIntegerPercentage of tax. Used with taxRegion to define the Fi tabiva field
taxRegionStringAccepts one of the following regions: ‘PT’, ‘PT-AC’, ‘PT-MA’. Used with taxPercentage to define the Fi tabiva field
originDocumentNumber***IntegerThe type of the document we want to copy from
originDocumentType***IntegerThe type of the document we want to copy from
warehouseIntegerFiarmazemNumber of the origin warehouse of the product
itemStringFt / BoIitemFree additional fields
item2StringFt / BoIitem2Free 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
}
]

(…)