Verbinding met lokale map via ClientConnector tool

Indien de financiële software geen embedded e-facturatie functionaliteit heeft, maar het wegschrijven in of uitlezen uit een map wel ondersteunt, bieden we de mogelijkheid te verbinden met een lokale map.

In deze instructiepagina behandelen we de inrichting van de ClientConnector tool. Dit is een commandline programma wat nieuwe documenten ontvangt en verzendt op basis van een mappenstructuur per bedrijf en documenttype. Hiermee blijft de uitwisseling met het eVerbinding platform optimaal veilig.

Let op! Voor het inrichten van de ClientConnector is uitgebreide kennis van IT vereist.

Wat zijn de requirements van de ClientConnector?

  • Moet op een Windows machine draaien;
  • .NET framework 4.6.1 of hoger dient aanwezig te zijn;
  • Er verbinding naar buiten mogelijk zijn over poort 443 richting het eVerbinding endpoint (wordt vermeld in de subscription key);
  • Zorg dat de software gestart mag worden en lees- en schrijfrechten heeft in de werkmap;
  • Voor de tool is 1 MB schijfruimte vereist plus ruimte voor het downloaden van de bestanden (variabel op basis van aantal te verwerken documenten eventueel inclusief de pdf;
  • Er zijn geen verder systeemvereisten qua processor, geheugen etc.

Stap 1 – Maak de werkomgeving aan

Stap 2 – Genereer de beveiligingssleutels

Ga hiervoor naar stap 1 om een Verbinding te maken

Stap 3 – Selecteer Organisatie-ID

Selecteer ‘Organisaties‘ en daarna de organisatie waarvoor documenten moeten worden opgehaald of verzonden. Er kan ook direct een organisatie gekozen worden.

Organisaties

Bij de organisatie is het Extern-ID te vinden wat u nodig heeft tijdens het instellen van de config als CompanyId.

 

Stap 4 – Stel de configuratie in

Vul de waarden in de application settings in en controleer deze. Gebruik de beveiligingssleutels uit stap 2. De waarden kunnen overruled worden door deze mee te geven als argument.

De volgende waarden dienen aangepast te worden voor het gebruik.

Vul de beveiligingsgegevens uit Stap 2 in bij ConsumerKey, ConsumerSecret en RequesterId.

Vul Organisatie-ID in uit Stap 3 in bij CompanyId.

Vul de locatie in voor de documenten moeten komen die opgehaald worden of waar de documenten vandaan komen voor verzending in bij WorkingDirectory. Deze directory behoort voor gebruik aangemaakt te worden. Bijvoorbeeld: {{ComapnyId}}\{{DocumentType}}  of XCNL100019\Inbox (Deze locatie is relatief ten opzichte van de huidige directory.)

Met DocumentType wordt aangeven welke documenten gedownload moeten worden (Inbox of Outbox) of dat documenten verzonden dienen te worden (Send)

Geef met PDFDownload of het document ook als .pdf file moet worden opgehaald.

Standaard waarden (alleen aanpassen in overleg): MasterTemplateId, ConversionPartnerGroupId, ConversionFileExtensions, ConversionPartner, TransformXSLT, AddExternalId, CleanXML, Action

Sinds versie 1.0.1 is er een subscriptionKey nodig. Deze wordt op aanvraag toegezonden, hiervoor is een API abonnement vereist. De subscriptionKey moet worden ingevuld in de sectie //system.serviceModel/client/endpoint  onderaan de configuratie file.

Voorbeeld van configuratie file:

<?xml version="1.0" encoding="utf-8"?>
<!--  Release
# Everbindings Command Line Tool

## Usage info: 
```
EConnectCommandLine.exe -help
```

## How to: 
Download invoice from inbox and oubox or send documents for a single company

1. Get access keys from https://platform.everbinding.nl
2. Setup this this config file (EConnectCommandLine.exe.config)
   # Set endpoint at the end of this config with the endpoint supplied with subscriptionKey
3. Create working directory to store or read files from.
   The application must have write rights in this directory
   
   In my case I created: C:/EConnect/Inbox/XCNL10019/ and C:/EConnect/Outbox/XCNL10019/
   And for sending: C:/EConnect/Send/XCNL10019/
4. Run application to:

    - download inbox documents:
        ```
        EConnectCommandLine.exe -w C:/EConnect/XCNL10019/Inbox/ -t inbox -c XCNL10019 -d 2016-03-01
        ```
    - download outbox documents:
        ```
        EConnectCommandLine.exe -w C:/EConnect/[CompanyId]/[DocumentType]/ -t outbox -c XCNL10019 -d 2016-03-01
        ```
    - send documents:
        ```
        EConnectCommandLine.exe -w C:/EConnect/XCNL10019/Send/ -t send -c XCNL10019
        ```
    - upload documents (conversion task):
        ```
        EConnectCommandLine.exe -w C:/EConnect/[CompanyId]/[DocumentType]/[Action]/ -t inbox -c XCNL10019 -a Upload - -template=GLDT9223370606989915978RA000000006DTP2000109 - -partnerid=XGC4144005987345172
        ```   
## Notes:
 
- The application will create a .econnect file to store the created date of the most recent downloaded 
  file Contents of the file can be modified in order to get document with an earlier date.

- Have two copies for the executable and config file, if you cannot pass the arguments 
  to the executeable.
  
- Application will not detect if it runs multiple times.

- A log file is created in the same directory of this executable by default. 
  This can be changed in the log4net section.
  See https://logging.apache.org for config examples.

- Only *.xml files are fetched for sending and uploading in the working directory. 
  The filename will be appended after sending with ".done" or when sending fails to ".error".

The following special functions are available
- AddExternalId  If set to true will add the eVerbinding ExternalId in the document. 
  This is only needed when the receiving software can use this
- CleanXML If set to true will remove the namespace declaration per element.
  This is only needed when the receiving software has problems with this use of namespaces.
- TransformXSLT will do a transformation base on XSLT file.
  

-->
<configuration>
  <configSections>
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" requirePermission="false"/>
    <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">
      <section name="EConnectCommandLine.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false"/>
      <section name="EConnectApi.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false"/>
    </sectionGroup>
  </configSections>
  <applicationSettings>
    <EConnectCommandLine.Properties.Settings>
      <setting name="MasterTemplateId" serializeAs="String">
        <value>GLDT9223370666504283001RA000000006DTP2000001</value>
      </setting>
      <setting name="CompanyId" serializeAs="String">
        <value>{{CompanyId like XCNL10019}}</value>
      </setting>
      <setting name="ConversionPartnerGroupId" serializeAs="String">
        <value>XGC4144005987345172</value>
      </setting>
      <setting name="ConversionFileExtensions" serializeAs="String">
        <value>pdf,png,jpg,jpeg,tiff</value>
      </setting>
      <setting name="RequesterId" serializeAs="String">
        <value>{{email address}}</value>
      </setting>
      <setting name="ConversionPartner" serializeAs="String">
        <value>ConversionPartner</value>
      </setting>
      <setting name="ConsumerKey" serializeAs="String">
        <value>{{ConsumerKey}}</value>
      </setting>
      <setting name="ConsumerSecret" serializeAs="String">
        <value>{{ConsumerSecret}}</value>
      </setting>
      <setting name="WorkingDirectory" serializeAs="String">
        <value>{{ComapnyId}}\{{DocumentType}}</value>
      </setting>
      <setting name="Action" serializeAs="String">
        <value>Download</value>
      </setting>
      <setting name="DocumentType" serializeAs="String">
        <value>{{ DocumentType Inbox or Outbox or Send}}</value>
      </setting>
      <setting name="PDFDownload" serializeAs="String">
        <value>True</value>
      </setting>
      <setting name="TransformXSLT" serializeAs="String">
        <value />
      </setting>
      <setting name="AddExternalId" serializeAs="String">
        <value>False</value>
      </setting>
      <setting name="CleanXML" serializeAs="String">
        <value>False</value>
      </setting>
    </EConnectCommandLine.Properties.Settings>
  </applicationSettings>
  <log4net>
    <appender name="TraceAppender" type="log4net.Appender.TraceAppender">
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="[%property{company}] %-5level %logger{1} - %message%newline"/>
      </layout>
    </appender>
    <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="[%property{company}] %message%newline"/>
      </layout>
    </appender>
    <appender name="FileAppender" type="log4net.Appender.FileAppender">
      <file value="log-file.txt" />
      <appendToFile value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date [%thread] %-5level %logger [%property{NDC}] - %message%newline" />
      </layout>
    </appender>
    <!-- Uncomment when needed. The Appender also needs to be uncommented -->
    <!-- Maybe needs to be run as Administrator for the first time-->
<!--    
    <appender name="EventLogAppender" type="log4net.Appender.EventLogAppender" >
      <applicationName value="EConnectCommandLine" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date [%thread] %-5level %logger [%property{NDC}] - %message%newline" />
      </layout>
    </appender>
-->    
    <root>
      <level value="DEBUG"/>
      <appender-ref ref="ConsoleAppender"/>
      <appender-ref ref="TraceAppender"/>
      <appender-ref ref="FileAppender"/>
      <!-- Uncomment when needed. The Appender also needs to be uncommented -->
      <!-- Maybe needs to be run as Administrator for the first time-->
      <!-- http://logging.apache.org/log4net/release/faq.html#trouble-EventLog -->
<!--
      <appender-ref ref="EventLogAppender"/>
-->      
    </root>
  </log4net>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6.1"/>
  </startup>
  <system.serviceModel>
    <bindings>
      <basicHttpBinding>
        <binding name="EConnectServiceSoap" maxBufferSize="2147483647" maxBufferPoolSize="524288" maxReceivedMessageSize="2147483647">
          <security mode="Transport" />
        </binding>
        <binding name="EConnectServiceSoap1" />
      </basicHttpBinding>
    </bindings>
    <client>
      <endpoint address="https://api.everbinding.nl/soap/v3.1/?subscriptionKey={{subscriptionKey}}"
          binding="basicHttpBinding" bindingConfiguration="EConnectServiceSoap"
          contract="EConnectService.EConnectServiceSoap" name="EConnectServiceSoap" />
    </client>
  </system.serviceModel>
</configuration>

Stap 5 – Test de werking

Start de ClientConnector via de commandline of snelkoppeling als volgt: EConnectCommandLine.exe -help

  • Voorbeeld: download inbox documenten
    EConnectCommandLine.exe -w C:/EConnect/XCNL10019/Inbox/ -t inbox -c XCNL10019 -d 2016-03-01
  • Voorbeeld: download outbox documenten
    EConnectCommandLine.exe -w C:/EConnect/[CompanyId]/[DocumentType]/ -t outbox -c XCNL10019 -d 2016-03-01
  • Voorbeeld: Verstuur documenten
    EConnectCommandLine.exe -w C:/EConnect/XCNL10019/Send/ -t send -c XCNL10019

 Enkele opmerkingen bij het gebruik

  • De ClientConnector zal een .econnect bestand aanmaken waarin wordt bijgehouden wat het laatste moment van bijwerken is geweest. De inhoud van dit bestand kan worden aangepast op documenten met een eerdere datum en tijd op te halen.
  • Er wordt na het downloaden en opslaan van de XML-factuur ook een PDF-factuur aangemaakt met de zelfde naam maar met de .PDF extensie in dezelfde map. Indien de PDF in de XML als ‘primary file’ aanwezig is wordt deze hiervoor gebruikt en in de andere gevallen wordt de PDF gegenereerd op basis van de informatie in de XML. Dit is uit te zetten doormiddel van de optie -p false of de value bij PDFDownload op false te zetten in de config file.
  • De ClientConnector kan meerdere keren worden opgestart. Hier is geen controle op.
  • Alle applicationSettings uit  config file zijn ook mee te geven als optie. Gebruik  EConnectCommandLine -? om alle mogelijke opties te weer te geven.
  • Er wordt een log-bestand aangemaakt in de map waar de programmabestanden staan. Dit kan aangepast worden in de config in de log4net sectie. Zie ook https://logging.apache.org voor meer voorbeelden. Zie hiervoor in het //log4net deel in het config bestand. In dit deel kan er ook gekozen worden om via EventLogAppender de logs in de Windows Event logs te laten komen.
  • Alleen *.xml bestanden worden behandeld bij het versturen in de werkmap.
  • De bestandsnaam wordt hernoemd na het versturen door een toevoeging, ‘.done’ indien succesvol, of ‘.error’ als er iets fout is gegaan.

Belangrijke verzendvelden in de SI-UBL

De gegevens voor de ontvanger staan in (volgorde van belangrijkheid):

//cac:AccountingCustomerParty/cac:Party/cbc:EndpointID

//cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID

//cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID

E-mail adres:

//cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail

//cac:AccountingCustomerParty/cac:AccountingContact

//cac:AccountingCustomerParty/cac:BuyerContact

Er dient minimaal bij voorkeur 1 ID en 1 E-mail adres ingevuld te worden. Het E-mail adres is optioneel maar kan leiden tot een foutmelding tijdens het verzenden als het document niet op basis van het ID afgeleverd kan worden. Om goede controle te houden over de routering van het document is het advies om cbc:EndpointID te gebruiken. Dit geeft de mogelijkheid om te versturen op basis van btw (VAT) nummer en ook het KvK nummer ingevuld te hebben. Zonder cbc:EndpointID wordt er verstuurd op KvK nummer als deze aanwezig is.

Sinds versie 1_0_4_2 is het ook mogelijk om NLCIUS te versturen met getallen als identifiers. Zoals 0106: voor de NL:KVK: en de 0190: voor de NL:OIN:.

TIP – Stel een automatische taak in (Windows)