Manuais
PHC GO Create Document
 

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:

  1. 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 **/
    }


  2. 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 **/
    }


  3. If the option value is “2”:


    {
    "code": 2,
    "message": "Information saved with success",
    "requestedFields": {} /** OBJECT CONTAINING THE REQUESTED FIELDS FROM requestOptions **/
    }


  4. In case of error:


    {
    "code": 100,
    "message": "Error message"
    }

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


 
NameTypePHC GO EntityPHC GO FieldObservations
option1Integer0 – 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
clearWrongTaxNumBooleanThis 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.
requestedFieldsString ArrayThe PHC GO 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

 

Customer2


 
NameTypePHC GO EntityPHC GO FieldObservations
number2IntegerClno
estabIntegerClestabBy default it goes 0.
name2StringClnome
address2StringClmorada
postalCode2StringClcodpost
city2StringCllocal
country2StringClpaisCan be set with the full name or the alpha-2 letter ISO3166 format.

Ex. “PT”, “ES”,”US” (See here)
email2StringClemail
taxNumber2StringClncont
abbreviatedName2StringClnome2
province (required field for Spain and Angola)StringClprovinciaCustomer Province.
county (required field for Angola)StringClmunicipioCustomer county.
notUpdateBoolean--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


 
NameTypePHC GO EntityPHC GO FieldObservations
docType1IntegerTdndocType 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
customerNumber2IntegerClno
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
documentDate4StringFtfdataFormat: “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
issueAsWaybillDocBooleanFtissueAsWaybill
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
blAccountIntegerFtvdcontadoUsed in documents that move treasury
Can be used when we want to use a treasury account different from the one configured in the series.

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”
taxExemptionCodeStringFtcodmotiseimp
keyVersionStringFtversaochave
refInt5StringFtrefIntInternal reference
rectificationReasonStringFtncreasonIt´s mandatory in NC and ND documents.
regType6StringFtcodigo4041Regularization 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
reference1StringFirefProduct reference
customerReferenceStringFiclirefCustomer reference
designationStringFidesign
unitCodeStringFiunidade
unitPrice1DoubleFiepv/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
quantity1IntegerFiqtt
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
originDocumentNumber3IntegerThe type of the document we want to copy from
originDocumentType3IntegerThe 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
sncCodeIntegerFicpocIt 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).

 
NameTypePHC GO EntityPHC GO FieldObservations
ship_referenceStringFirefShipping Reference
ship_designationStringFidesignShipping Designation
ship_unitPriceDoubleFiepv/pvmoedaThe 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_quantityIntegerFiqttShipping Quantity. By default, this field has a preset value of 1.
ship_taxIncludedBooleanFiivainclIndicates if the unit price includes tax.
ship_taxPercentageInteger--Percentage of tax. Used with taxRegion to define the Fi tabiva field.
ship_taxRegionString--Accepts one of the following regions: ‘PT’, ‘PT-AC’, ‘PT-MA’. Used with taxPercentage to define the Fi tabiva field
ship_discount1IntegerFidesconto
ship_discount2IntegerFidesc2
ship_itemStringFt/BoIitemFree additional fields
ship_item2StringFt/BoIitem2Free 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
}
]

(…)