E-arveldaja operaatori SOAP API

Billberry toetab e-arveldaja SOAPi liidest, kus e-arve XML ja PDF saadetakse üle HTTP kasutades Simple Object Access Protocol v1.1 transporti. Kuna tegu on e-arveldaja API-ga, paiknevad kõik päringud ja vastused Äriregistri XML namespaces http://arireg-rmp.x-road.ee/producer/.

E-arveldaja SOAPi API veebiteenuste kirjelduse WSDLi leiab https://rmp-service.rik.ee/?WSDL lehelt, kuid arvete saatmiseks on oluline vaid üks funktsioon — ReceiveInvoiceService.

Arve saatmine

E-arve saatmiseks on ReceiveInvoiceService funktsioon, kuhu saab kaasa anda e-arve XMLi, olemasolul PDFi ning digiallkirja päringu kinnitamiseks.

<ReceiveInvoiceService xmlns="http://arireg-rmp.x-road.ee/producer/">
  <request>
    <provider_code>…</provider_code>
    <transfer_datetime>…</transfer_datetime>
    <sender_regcode>…</sender_regcode>
    <sender_name>…</sender_name>
    <receiver_regcode>…</receiver_regcode>
    <receiver_name>…</receiver_name>
    <sender_invoice_id>…</sender_invoice_id>
    <invoice_xml_file>…</invoice_xml_file>
    <invoice_pdf_file>…</invoice_pdf_file>
    <invoice_signature>…</invoice_signature>
  </request>
</ReceiveInvoiceService>

`ReceiveInvoiceService` funktsiooni parameetrid

Parameeter	Kirjeldus
`provider_code`	Operaatori kasutajatunnus.
`invoice_xml_file`	Eesti e-arve standardi XML base64 kodeeringus. Toetatud on e-arvete versioonid 1.1, 1.11 ja 1.2.
`invoice_pdf_file`	Arve PDF base64 kodeeringus. Ei ole kohustuslik ja võib jätta tühaks. Arve manust (`<AttachmentFile>`) ei tasu ka siia kopeerida. Nii läheks saajale kaks PDFi.
`sender_invoice_id`	Operaatori arve identifikaator. Kasutatakse duplikaatide tuvastamiseks kui ka logimiseks.
`transfer_datetime`	Päringu kellaaeg ISO 8601 formaadis UTC ajavööndis. Näiteks `2021-02-28T13:37:42Z`.
`sender_regcode`	E-arve saatja registrikood. Sama, mis `<Invoice sellerRegnumber>`.
`sender_name`	E-arve saatja nimi. Väärtus pole oluline.
`receiver_regcode`	E-arve saaja registrikood. Sama, mis `<Invoice regNumber>`.
`receiver_name`	E-arve saaja nimi. Väärtus pole oluline.
`invoice_signature`	Päringu digitaalne allkiri RSA PKCS 1.5 formaadis sinu avaliku võtmega.

Ühes päringus tohib korraga olla üks arve, ehk <E_Invoice> elemendis vaid üks <Invoice> element.

Päringu allkirjastamine

Päringu allkirjastamiseks tuleks esmalt järjestikku paigutada provider_code, päringu kellaaeg, invoice_xml_file ja invoice_pdf_file parameetrite väärtused, pannes iga parameetri vahele # märk (ehk bait 0x23). Teisisõnu, allkirjasta järgnevat ASCII baitide jada:

provider_code
# ehk bait 0x23.
Kellaaeg transfer_datetime parameetrist, kuid seekord DD.MM.YYYY HH:MM:SS formaadis.
Näiteks 28-02-2021 13:37:42. Jätkuvalt kasuta UTC-d, mitte kohalikku aega.
# ehk bait 0x23.
invoice_xml_file ehk base64 kodeeritud e-arve.
# ehk bait 0x23.
invoice_pdf_file ehk base64 kodeeritud PDF või ei midagi, kui PDF jäi tühjaks.

Seejärel allkirjasta päring RSA PKCS 1.5 meetodiga, kasutades SHA256 räsi. Tehniliselt tähendab see, et RSA allkiri antakse eelneva sisendi SHA256 räsile ja DigestInfo prefiksile, mis kirjeldab kasutatud räsialgoritmi. See ei ole sama, mis ainult räsi allkirjastamine.

OpenSSLiga saad RSA PKCS 1.5 allkirja anda näiteks openssl dgst käsuga:

openssl dgst -sha256 -sign example.key -out example.sig signable.txt

Päring

Paiguta arve saatmise päring SOAPi ümbrikusse ning postita https://api.billberry.ee/soap suunas. SOAP v1.1 Content-Type on text/xml.

HTTP päring võiks välja näha umbes selline, kui pikemad parameetrid välja jätta:

POST /soap HTTP/1.0
Host: api.billberry.ee
Content-Type: text/xml

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
    <ReceiveInvoiceService xmlns="http://arireg-rmp.x-road.ee/producer/">
      <request>
        <provider_code>tutikas-operaator</provider_code>
        <transfer_datetime>2021-02-28T13:37:42Z</transfer_datetime>
        <sender_regcode>1234567</sender_regcode>
        <sender_name>Sender Example OÜ</sender_name>
        <receiver_regcode>9876543</receiver_regcode>
        <receiver_name>Receiver Example OÜ</receiver_name>
        <sender_invoice_id>42</sender_invoice_id>
        <invoice_xml_file>…</invoice_xml_file>
        <invoice_pdf_file>…</invoice_pdf_file>
        <invoice_signature>…</invoice_signature>
      </request>
    </ReceiveInvoiceService>
  </Body>
</Envelope>

Vastus

Kui päring oli korrektselt vormistatud, leiad päringu vastuse SOAPi <Body> elemendis paiknevast ReceiveInvoiceServiceResponse elemendist. Sealne status väli märgib, kas arve võeti vastu või ebaõnnestus näiteks allkirja valideerimine.

Kui kõik sobis, on staatus OK:

<ReceiveInvoiceServiceResponse xmlns="http://arireg-rmp.x-road.ee/producer/">
  <response>
    <status>OK</status>
    <message>E-invoice received</message>
    <sender_invoice_id>42</sender_invoice_id>
    <receiver_invoice_id>69</receiver_invoice_id>
  </response>
</ReceiveInvoiceServiceResponse>

receiver_invoice_id parameeter on Billberry-poolne arvele antud identifikaator.

Ebaõnnestumise korral on status väli FAIL:

<ReceiveInvoiceServiceResponse xmlns="http://arireg-rmp.x-road.ee/producer/">
  <response>
    <status>FAIL</status>
    <message>Invoice with the given sender id already exists</message>
    <sender_invoice_id>42</sender_invoice_id>
  </response>
</ReceiveInvoiceServiceResponse>