Supplier

HTTP	Operation	Type	Object	DTO Why-DTOs?
POST	Create	Mutation	`createSupplier`	`SupplierCreateGLDtoInput`
POST	Update	Mutation	`updateSupplier`	`SupplierUpdateGLDtoInput`
POST	Delete	Mutation	`deleteSupplier`	`SupplierDeleteGLDtoInput`
POST	Read	Query	`suppliers filtered by id` Why?
POST	List	Query	`suppliers`

Description

Supplier management.

Allows the identification of a third-party Supplier within an organization.
It offers the option to add contacts within the Supplier and their details, as well as define the Supplier’s default payment conditions.

Every Supplier must have a code, which, depending on the organization’s settings, can be manually entered or automatically generated.
In the DE (German) legislation, automatic numbering is mandatory.

How to easily Create a Supplier ?

Specific rules pertaining to a legislation and/or the Supplier’s country.

Creating a Supplier record involves multiple variables, including the legislation FR, ES or DE and the country of the Supplier :

Legislation-Specific Fields
Certain mandatory fields will depend on the legislation you are operating under (FR, ES or DE).
Country of the Supplier
Understanding the country of the Supplier is crucial as it introduces additional variables that can affect the mandatory and optional fields needed for Supplier creation.
- Same as Operating Legislation: If the Supplier’s country is the same as your operating legislation.
- Member of VIES: If the Supplier’s country is different from your operating legislation and is a member of the VAT Information Exchange System (VIES).
- Different from Legislation and VIES: If the Supplier’s country doesn’t fall under your operating legislation and is not a member of VIES.

Common rules

countryIsoCodeAlpha2 is a simple alternative to assign the country of the address by using the ISO2 code directly, rather than the country ID in the Countries resource.
code is optional if the automatic numbering option (Sequence number) is enabled for the Supplier resource.
However, it can be set to enforce a specific value instead of requesting the assignment of a new sequential number.
documentType allows you to define the type of identification document for the Supplier.
It is automatically set by default based on the legislation and country, and, with few exceptions, does not need to be filled in during creation.

Examples of Creation

Below, for each legislation FR, ES and DE, the specific rules and differences depending on the Supplier’s country.
These examples assume that automatic numbering for the Supplier resource is not inactive in Sequence Numbers, otherwise it is a mandatory value.
So the Code field is not provided. However, you always have the option to assign specific values.
These examples focus on the differences according to legislations and countries, they do not include the addition of contacts or payment conditions.
You can find more comprehensive examples that include adding contacts and payment conditions in the Postman collection Quick start / 5. Test your first query in Postman.

To assist you in testing creations with valid documentId, you can use the generator for random identification numbers that are consistent with the rules.

DocumentId generator for your tests in legislation

graphQL Mutation

mutation ($values: SupplierCreateGLDtoInput!) {  
    createSupplier(input: $values) {
    id
    code
  }
}

Legislation = `FR` -> Country of Supplier = `FR`

The documentId field corresponds to the SIRET or SIREN number. This value is not mandatory.
For the qualification of the Supplier, it is recommended to assign the VATNumber.

{
  "values": {
    "socialName": "DUPONT SA",
    "tradeName": "Dupont",
    "documentId": "323456789",
    "vatNumber": "FR33323456789",
    "addresses": [
      {
        "firstLine": "72 rue Joffre",
        "city": "PARIS",
        "zipCode": "75001",
        "countryIsoCodeAlpha2": "FR"
      }
    ]
  }
}

Legislation = `FR` -> Country of Supplier = member of VIES and not `FR`

The documentId field is not mandatory.
For the qualification of the Supplier, it is recommended to assign the VATNumber.
For the particular case of Northern Ireland countryIsoCodeAlpha2 should contain XI and not GB

{
  "values": {
    "socialName": "BelgiumCorp SA",
    "tradeName": "BelgiumCorp",
    "vatNumber": "BE1489052515",
    "addresses": [
      {
        "firstLine": "1 Grand Place",
        "city": "BRUXELLES",
        "zipCode": "1000",
        "countryIsoCodeAlpha2": "BE"
      }
    ]
  }
}

Legislation = `FR` -> Country of Supplier is neither `FR` nor VIES

The documentId field is not mandatory.
The VATNumber field is not used.

{
  "values": {
    "socialName": "Smiths Corporation",
    "tradeName": "Smiths",
    "addresses": [
      {
        "firstLine": "456 Oak S",
        "city": "NEW YORK",
        "zipCode": "10001",
        "countryIsoCodeAlpha2": "US"
      }
    ]
  }
}

Legislation = `ES` -> Country of Supplier = `ES`

The documentId field corresponds to the NIF or DNI or NIE number. This value is mandatory.
For the qualification of the Supplier, it is recommended to assign the VATNumber.

{
  "values": {
    "socialName": "Martinez SA",
    "tradeName": "Martinez",
    "documentId": "Z4660201S",
    "vatNumber": "ESZ4660201S",
    "addresses": [
      {
        "firstLine": "Calle Mayor 10",
        "city": "MADRID",
        "zipCode": "28001",
        "countryIsoCodeAlpha2": "ES"
      }
    ]
  }
}

Legislation = `ES` -> Country of Supplier = member of VIES and not `ES`

The documentId field is not mandatory.
The vatNumber is mandatory.
For the particular case of Northern Ireland countryIsoCodeAlpha2 should contain XI and not GB

{
  "values": {
    "socialName": "BelgiumCorp SA",
    "tradeName": "BelgiumCorp",
    "vatNumber": "BE1489052515",
    "addresses": [
      {
        "firstLine": "1 Grand Place",
        "city": "BRUXELLES",
        "zipCode": "1000",
        "countryIsoCodeAlpha2": "BE"
      }
    ]
  }
}

Legislation = `ES` -> Country of Supplier is neither `ES` nor VIES

If documentTypeId is not mentioned, the document type Otro documento probatorio will be automatically filled in. Otherwise, you can provide an Id of and authorized document type (Pasaporte, Documento oficial emitido en el país de residencia, Certificado de residencia).
The documentId field is not mandatory.
The VATNumber field is not used.

{
  "values": {
    "socialName": "Smiths Corporation",
    "tradeName": "Smiths",
    "addresses": [
      {
        "firstLine": "456 Oak S",
        "city": "NEW YORK",
        "zipCode": "10001",
        "countryIsoCodeAlpha2": "US"
      }
    ]
  }
}

Legislation = `DE` -> Country of Supplier = `DE`

The documentId field corresponds to an identification number. This value is not mandatory.
For the qualification of the Supplier, it is recommended to assign the VATNumber.

{
  "values": {
    "socialName": "Müsller GmbH",
    "tradeName": "Müsller",
    "documentId": "80715887835",
    "vatNumber": "DE807158878",
    "addresses": [
      {
        "firstLine": "Friedrichstraße 501",
        "city": "BERLIN",
        "zipCode": "10117",
        "countryIsoCodeAlpha2": "DE"
      }
    ]
  }
}

Legislation = `DE` -> Country of Supplier = member of VIES and not `DE`

The documentId field is not mandatory.
The vatNumber is mandatory.
For the particular case of Northern Ireland countryIsoCodeAlpha2 should contain XI and not GB

{
  "values": {
    "socialName": "BelgiumCorp SA",
    "tradeName": "BelgiumCorp",
    "vatNumber": "BE1489052515",
    "addresses": [
      {
        "firstLine": "1 Grand Place",
        "city": "BRUXELLES",
        "zipCode": "1000",
        "countryIsoCodeAlpha2": "BE"
      }
    ]
  }
}

Legislation = `DE` -> Country of Supplier is neither `DE` nor VIES

The value of the documentId field is not necessary.
The VATNumber field is not used.

{
  "values": {
    "socialName": "Smiths Corporation",
    "tradeName": "Smiths",
    "addresses": [
      {
        "firstLine": "456 Oak S",
        "city": "NEW YORK",
        "zipCode": "10001",
        "countryIsoCodeAlpha2": "US"
      }
    ]
  }
}

Example of Response

{
    "data": {
        "createSupplier": {
            "id": "e451aff7-0560-4e72-a6fb-4ea25e9d9c64",
            "code": "3"
        }
    }
}

Explore Efficient Record Updates: For comprehensive insights into making precise modifications to records, check out our dedicated page on updates : Key concepts / Updating records

Key	Value
`Authorization`	Bearer Current access Token How to find?
`X-TenantId`	Current tenant id How to find?
`X-OrganizationId`	Current organization Id How to find?
`x-api-key`	Primary or secondary subscription key of your app How to find?

suppliers

Common to customers and suppliers

Fields	Type	Description	Length
idSSystem field that cannot be assigned	UUID	Id
modificationDate SSystem field that cannot be assigned	Datetime	Modification date
creationDate SSystem field that cannot be assigned	Datetime	Creation date

*General Infos*
code NThe value of this field cannot be modified after the record is created	String	Code supplier	17
socialName *The value of the field or object is mandatory	String	supplier Name	70
tradeName	String	Trade Name See InfoAdditional information is available in the Info block below	70
countryAcronym NThe value of this field cannot be modified after the record is created	String	Country See InfoAdditional information is available in the Info block below	2
documentType DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	DocumentType	Fields of DocumentType
documentTypeIdNThe value of this field cannot be modified after the record is created	UUID	DocumentType Id See InfoAdditional information is available in the Info block below
documentId	String	Identification number See InfoAdditional information is available in the Info block below	25
vatNumber	String	EU VAT Number See InfoAdditional information is available in the Info block below	25
defaultAccountingAccount DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	AccountingAccount	Fields of AccountingAccount
defaultAccountingAccountId	UUID	Ledger general account ID See InfoAdditional information is available in the Info block below
businessArea DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	BusinessArea	Fields of BusinessArea
businessAreaId	UUID	Business areas Id
nafApeCode	String	Code NAF/APE	7
comments	String	Comments	2000
status RThis field is read-only, its value cannot be assigned	NONE DISABLED ENABLED GDPR_APPLIED	Status
gdprApplied	Boolean	GDPR action
gdprAppliedDate	Datetime DateThe GraphQL field type is DateTime, but only the date value is considered, the time value is ignored if provided.	GDPR date action
disabled	Boolean	Inactive See InfoAdditional information is available in the Info block below
disabledDate	DatetimeDateThe GraphQL field type is DateTime, but only the date value is considered, the time value is ignored if provided.	Inactive date

*Addresses* / *Contacts* / *payment conditions*
addresses[]	Array	List of addresses
contacts[]	Array	List of contacts
paymentTermLines[]	Array	List of payement terms lines

Info

countryAcronym : ISO2 country code. In creation, it is optional as it is automatically assigned by the country code of the address.

documentTypeId : allows you to define the type of identification document for the Customer.
In creation, it is automatically set by default based on the legislation and country, and, with few exceptions, does not need to be filled in during creation. Otherwise, to assign a value, retrieve the desired ID from document type.

Country	Allowed document types (code name)
FR	01 SIRET
VIES not FR	02 TVA Intracommunautaire
Other	06 Autre document justificatif

Country	Allowed document types (code name)
ES	01 NIF/DNI
VIES not ES	02 NIF/IVA
Other	03 Pasaporte
Other	04 Documento oficial emitido en el país de residencia
Other	05 Certificado de residencia
Other	06 Otro documento probatorio

Country	Allowed document types (code name)
DE	01 Steur-IdN
VIES not DE	02 USt-IdNr
Other	06 Another supporting document

DocumentId generator for your tests in legislation

documentId : Identification number, value formats may differ depending on legislationCode.
- For a French Supplier, you can fill any SIREN of 9 characters or any SIRET of 14 characters.
  The value is not mandatory.
- For a German Supplier, you may enter either a Steuer-IdNr with exactly 11 characters or another value ranging from 11 to 14 characters.
  The value is not mandatory.
- For a Spanish Supplier, you need to fill a valid NIF/DNI/NIE number.
  The value is mandatory.
vatNumber : An EU VAT Number is a unique identifier for tax purposes within the European Union, used primarily for cross-border transactions. It starts with a two-letter country code followed by a series of numbers and sometimes letters, varying by country.
- This field is not applicable for Supplier that are not registered in the VIES system.
- For VIES Supplier, the format is described at this FAQ N° 11 https://ec.europa.eu/taxation_customs/vies/#/faq
- If the Supplier is FR, the VAT number is recommended but not mandatory.
- If the Supplier is VIES but not FR, the VAT number is recommended but not mandatory.
- If the Supplier is neither VIES nor FR, the VAT number is not used.
- If the Supplier is ES, the VAT number is recommended but not mandatory.
- If the Supplier is VIES but not ES, the VAT number is mandatory.
- If the Supplier is neither VIES nor ES, the VAT number is not used.
- If the Supplier is DE, the VAT number is recommended but not mandatory.
- If the Supplier is VIES but not DE, the VAT number is mandatory.
- If the Supplier is neither VIES nor DE, the VAT number is not used.

code : Code of the Supplier. During creation, it is automatically calculated if the option is not inactive in Sequence Numbers, otherwise it is a mandatory value.
In any cases, it is still possible to assign it to enforce a specific value.
Forcing a value allows you to retrieve an alphanumeric code that can already identify the Supplier, even if automatic numbering mode is active.

Forcing a value allows you to retrieve an alphanumeric code that can already identify the Supplier, even if automatic numbering mode is active.
- For this legislation DE, automatic numbering is mandatory and cannot be disabled from Sequence Numbers.
- If you force a value, it must be strictly numeric and adhere to the rule of a number being between 10000 and 69999 for customers, and between 70000 and 99999 for suppliers or employees.

tradeName : Can be used to fill in a shorter name than socialName
disabled : If true the third can no longer be used, but will remain in the existing information.
defaultAccountingAccountId : Id of the general account in accountingAccount associated with the Supplier.
The subAccountType of the account must be PROVIDER.

In creation, if defaultAccountingAccountId is not specified, the account defined in Accounting Configuration will be automatically assigned.

In creation, if defaultAccountingAccountId is not specified, the account defined in Accounting Configuration will be automatically assigned.

In creation, if defaultAccountingAccountId is not specified, the account defined in Accounting Configuration will be automatically assigned.

Caution, as per DE legislation, assigning a defaultAccountingAccountId is mandatory, if a default value is not provided, it will then be necessary to specify in defaultAccountingAccountId the Supplier collective account ID.

suppliers/addresses

Common to customers, suppliers

Fields	Type	Description	Length
idSSystem field that cannot be assigned	UUID	Id

countryId	UUID	Country Id
country DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.COMING SOON This feature is currently in development and will be available in the next version. It’s already documented to keep you informed about its upcoming availability	String	Fields of Country
countryIsoCodeAlpha2	String	Country Code See InfoAdditional information is available in the Info block below	2
countryNameRThis field is read-only, its value cannot be assigned	String	CountryName
name	String	Code	50
firstLine	String	First Line	35
secondLine	String	Second Line	35
city	String	Town	35
zipCode	String	Postal Code	9
province	String	Province	25
isDefaultDeliveryAddress	Boolean	Is the default delivery/shipping Address
isMainAddress RThis field is read-only, its value cannot be assigned	Boolean	Is the main address
isDeliveryAddress RThis field is read-only, its value cannot be assigned	Boolean	Is a delivery/shipping Address

Info

countryIsoCodeAlpha2 : ISO2 country code.
This field can be used for creation and serves as a simple alternative to assign the country of the address by using the ISO2 code directly, rather than the country ID in the Countries resource.

Specific to suppliers

Delivery / Main Address:
1. isDefaultDeliveryAddress: Unused in this version.
2. isMainAddress: Unused in this version.
3. isDeliveryAddress: Unused in this version.

suppliers/contacts

Common to customers, suppliers, employees

Fields	Type	Description	Length
idSSystem field that cannot be assigned	UUID	Id

courtesy	NONE MR MISS	Courtesy
name	String	First name (John)	35
surname	String	Family name (Smith)	35
jobName	String	Job name	35
jobArea DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	JobArea	Fields of JobArea
jobAreaId	UUID	Job areas Id
isDefault	Boolean	Main contact
emails[]	Array	List of emails
phones[]	Array	List of phones
socialMedias[]	Array	List Social Networking

suppliers/contacts/emails

Fields	Type	Description	Length
idSSystem field that cannot be assigned	UUID	Id

emailAddress	String	Email address	70
usage	NOT_SET EMPTY INVOICES PAYMENTS OTHERS	Type
isDefault	Boolean	Main mail

suppliers/contacts/phones

Fields	Type	Description	Length
idSSystem field that cannot be assigned	UUID	Id

number	String	Phone	20
type	NOT_SET EMPTY LANDLINE MOBILE FAX SKYPE WHATS_APP	Type
isDefault	Boolean	Main phone

suppliers/contacts/socialMedias

Fields	Type	Description	Length
idSSystem field that cannot be assigned	UUID	UUID

name	String	Name	30
link	String	Link	100

suppliers/paymentTermLines

Common to customers, suppliers

Payment terms, used to define the list of payment terms for Supplier
Example :

Advance payment by check 30%
30% by transfer at 30 days net
the balance of 40% by bank transfer at 60 days end of month

Fields	Type	Description
idSSystem field that cannot be assigned	UUID	Id

order *The value of the field or object is mandatory	Int	classification of lines from 0 to n. See InfoAdditional information is available in the Info block below
paymentMean DATALOADERUtilize the DATALOADER feature to enrich your query by adding additional resource fields directly in the query.	PaymentMean	Fields of PaymentMean
paymentMeanId	UUID	Id of the payment mean
type	NONE LINEAL PERCENTAGE FIXED_AMOUNT REMAINING_AMOUNT	Type of calculation
value *The value of the field or object is mandatory	Decimal	Value
condition	NONE DAY_OF_PAYMENT END_OF_MONTH	To calculate due date
day	Int	Number of days
payDays[]	Array	optional due days See InfoAdditional information is available in the Info block below

Info

order : If REMAINING_AMOUNT, must always be last with the code 9999.
payDays : Array of optional due days. The day contained in the array closest to the number of days defined in day will be used to calculate the Due Date.

Description

How to easily Create a Supplier ?

Specific rules pertaining to a legislation and/or the Supplier’s country.

Common rules

Examples of Creation

graphQL Mutation

Legislation = FR -> Country of Supplier = FR

Legislation = FR -> Country of Supplier = member of VIES and not FR

Legislation = FR -> Country of Supplier is neither FR nor VIES

Legislation = ES -> Country of Supplier = ES

Legislation = ES -> Country of Supplier = member of VIES and not ES

Legislation = ES -> Country of Supplier is neither ES nor VIES

Legislation = DE -> Country of Supplier = DE

Legislation = DE -> Country of Supplier = member of VIES and not DE

Legislation = DE -> Country of Supplier is neither DE nor VIES

Example of Response

Header

suppliers

Info

suppliers/addresses

Info

suppliers/contacts

suppliers/contacts/emails

suppliers/contacts/phones

suppliers/contacts/socialMedias

suppliers/paymentTermLines

Info

Legislation = `FR` -> Country of Supplier = `FR`

Legislation = `FR` -> Country of Supplier = member of VIES and not `FR`

Legislation = `FR` -> Country of Supplier is neither `FR` nor VIES

Legislation = `ES` -> Country of Supplier = `ES`

Legislation = `ES` -> Country of Supplier = member of VIES and not `ES`

Legislation = `ES` -> Country of Supplier is neither `ES` nor VIES

Legislation = `DE` -> Country of Supplier = `DE`

Legislation = `DE` -> Country of Supplier = member of VIES and not `DE`

Legislation = `DE` -> Country of Supplier is neither `DE` nor VIES