Manuais
PHC GO Create Internal 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": [
"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:

  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. In case of error:

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

  4. 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)StringClprovinciaCustomer Province.
county (required field for Angola)StringClmunicipioCustomer 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:

 

 

  1. On the Internal Document’s customerNumber/supplierNumber field (referencing an existent Customer/Supplier)
  2. 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

PHC GO