API Versions

The Billink API is available in two versions, Legacy API (v1) and Actual API (v2), with distinct data formats and potential differences in endpoint naming:

Actual API (v2)

• Format: JSON
• Request: Uses JSON for requests.
• Response: Returns JSON responses.
• Endpoint Naming: Endpoints may differ in naming from the Legacy API. Ensure you reference the appropriate documentation for v2 endpoints.

Legacy API (v1)

• Format: mostly XML
• Request: Uses XML for requests.
• Response: Returns XML responses.
• Endpoint Naming: Some endpoints may have different names compared to the Actual API. Refer to the Legacy section of the documentation for specific details.

Important Notes

• Backward Compatibility: Both versions coexist, but the Legacy API is primarily maintained for backward compatibility. You should verify compatibility with your application before switching to the Actual API.
• Endpoint URLs: Specify the desired version in the endpoint URL:
• Legacy API: https://api.example.com/v1/endpoint
• Actual API: https://api.example.com/v2/endpoint

Example Request and Response

Actual API:

• URL: https://api-staging.billink.nl/v2/client/invoice/credit
• Request:

 
curl --location 'https://api-staging.billink.nl/v2/client/invoice/credit' \
--data '{
  "billinkID": "d38a3439590889df026367bf01ddar621e687b8d278",
  "billinkUsername": "usertest",
  "invoices": [
    {
      "creditAmount": 1.5,
      "description": "test credit",
      "number": "KRKND-0001"
    }
  ]
}'

• Response:

 
{
  "result": "MSG",
  "statuses": [
    {
      "code": 200,
      "invoiceNumber": "KRKND-0001",
      "message": "Credit applied: 1.50 EURO.; step restarted."
    }
  ]
}

Legacy API:

• URL: https://api-staging.billink.nl/v1/client/credit
• Request:

 
curl --location 'https://api-staging.billink.nl/v1/client/credit' \
--data '<API>
  <VERSION></VERSION>
  <CLIENTUSERNAME></CLIENTUSERNAME>
  <CLIENTID></CLIENTID>
  <ACTION></ACTION>
  <INVOICES>
    <ITEM>
      <INVOICENUMBER></INVOICENUMBER>
      <CREDITAMOUNT></CREDITAMOUNT>
      <DESCRIPTION></DESCRIPTION>
    </ITEM>
  </INVOICES>
</API>'

• Response:

<?xml version="1.0" encoding="UTF-8"?>
<API>
  <RESULT>MSG</RESULT>
  <MSG>
    <STATUSES>
      <ITEM>
        <INVOICENUMBER>123456</INVOICENUMBER>
        <MESSAGE>Credit applied: 10.95 EURO.; Order paid.</MESSAGE>
        <CODE>200</CODE>
      </ITEM>
    </STATUSES>
  </MSG>
</API>