Introduction

There are three mechanisms to integrate with the B2B Router platform:

  • SOAP API

This API provides SOAP access to B2B Router transactions. It should be used to integrate ERP systems or peering with other networks. It is not intended for direct manipulation of entities in the Web Application, as it only proveides an integration point for transactions.

  • Electronic Invoice REST API

This API allows users to interact with the B2B Router portal, managing different entities such as Invoices, Customers, Channels, etc. Allows to integrate data from an external application (such as an ERP system) to create and send electronic invoices and to get data from status and graphics.

  • File transfer

The simplest way to interact with the B2B Router is to use the File Transfer utility. Installing this client allows users to drop files in a folder instead of programming any of the APIs above.

SOAP API guide

SOAP access to B2B Router transactions

The endpoints and WSDL are:

The Administration Console is located at /transactions URL

WSSE Authentication

The SOAP API uses WSSE with a Username Token Profile of PasswordText. TLS provides security for the password. There is no need to add a time stamp or a nonce.

Example of WSSE headers:

<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
  <wsse:UsernameToken>
    <wsse:Username>owner</wsse:Username>
    <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">api_key</wsse:Password>
  </wsse:UsernameToken>
</wsse:Security>

Return values

All methods include three common output values:

  • success boolean It is set to 'true' if the method call was successful of 'false' in case of error.

  • returnCode string A categorization of the error if any:

    • '1' - Generic error

    • '2' - Missing input parameters

    • '3' - Entity not found

  • returnMessage string A textual description of the outcome

Upload

The upload method creates a Transaction. Once you upload a Transaction B2B Router works asynchronously.

Input parameters:

  • action string Action or process to perform. The available actions depend on your configuration. For instance the peppol action will send the payload using the PEPPOL Network

  • payload base64Binary Payload or document subject to the action. File content must be encoded using Base64

  • fromNetId string optional An optional reference for this Transaction in your network. This is "your reference" to the Transaction.

  • email string optional An optional email for notifications of errors

Output:

  • transactionId string The identifier of this Transaction in B2B Router. This is "our reference" for the Transaction.

Note that this method may succeed in creating the Transaction, but this does not mean the Transaction is successful. See the status method.

Status

The status method retrieves the status of a transaction created with upload

Input parameters:

  • transactionId string The identifier of the Transaction in B2B Router. This is the identifier returned by 'upload'

Returns:

  • done boolean Is contains 'true' if it it was performed with success. Otherwise is contains 'false'

  • doneAt dateTime When it was performed successfully. Empty if this Transaction did not perform successfully.

  • errorCount integer If there has been any error, the error count. The transaction may be retried using the Administration Console.

  • lastError string The message of the last error

  • lastErrorAt dateTime When the last error has occurred

  • toNet string The destination network. For instance, peppol for PEPPOL Network.

  • toNetId string The identifier in the destination network. Some networks or recipients provide a registration code, or a trace identifier.

Note that errors may be temporal and the Transaction have done set to true at the end

Download

The dowload method downloads all pending incoming payloads or documents.

Input parameters:

  • ack boolean Mark documents as downloaded. Will not download again. In case of error in the integration code, setting ack to false may allow a future retry. See the ack method.

  • max integer Maximum number of document to download. Defaults to 10 and the maximum number allowed is 1000. The order is LIFO, so the most recent will come first.

Returns a list of:

  • transactionId string The transaction identifier in B2B Router

  • payload base64Binary The payload or document

  • created_at dateTime When it was received

Ack

The ack method marks an specific document as downloaded. Will not download again. This method may be used after a successful download, called with ack set to false.

Input parameters:

  • transactionId string The transaction identifier in B2B Router

API REST

This API provides CRUD access to the B2B Router entities. Supports XML and JSON formats.

API Description

Projects / Companies

List projects
GET /projects.xml

Returns all the projects to which the user has access to.

XML Response:

<projects type="array">
  <project>
    <id>1</id>
    <name>Invinet Sistemas SL</name>
    <identifier>invinet-sl</identifier>
    <description>descripción del proyecto</description>
    <is_public>false</is_public>
  </project>
  <project>
    <id>2</id>
    ...
  </project>
</projects>
Details of the Company
GET /projects/[project_identifier]/my_company.json

Returns the data setup in "My Company", this information cannot be modified.

XML Response:

<my_company>
  <taxcode>77310058C</taxcode>
  <name>Company1</name>
  <email>test@example.com</email>
  <phone/>
  <address/>
  <city>Barcelona</city>
  <postalcode>08720</postalcode>
  <province/>
  <country>es</country>
  <website/>
  <invoice_format/>
  <currency>EUR</currency>
  <company_identifier/>
  <logo>/companies/logo/onlinestore</logo>
</my_company>

Invoices

List invoices
GET /projects/[project]/invoices.[format]

Returns a paginated list of the submitted invoices of the company.

Optional parameters:

  • offset: offset to the first invoice to be retrieved

  • limit: maximum number of invoices in the response

  • Filtered on status: new, sending, error, discarded, sent, refused, closed, registered, accepted, allegedly_paid. Indicates the status to be received using a "1" (True)

  • date_from & date_to: filter on submission dates

  • due_date_from & due_date_to: filter on due dates

  • number: filter on invoice number. Use as a string search, for example, searching "00" lists all the invoices containing "00" in the invoice number

  • state_updated_at_from: filter on change status date. Invoices with change status date later than the specified date are returned

  • taxcode: filter on customer VAT code

Invoice status:

An invoice can have any of the following status:

  • new - created and ready to be sent

  • sending - invoice is being sent

  • error - an error has been raised when sending the invoice to its recipient

  • discarded - maximum number of submission retries reached

  • sent - successfully sent to its recipient

  • refused - the recipient has refused the invoice. Usually, the reason for the rejection is provided

  • closed - the sender considers that the invoice is closed and does not want to perform further operations

  • registered - the receiver has registered the invoice. Some receivers may indicate a registration number

  • accepted - the receiver has accepted the invoice

  • allegedly_paid - the receiver has indicated that he has ordered the payment of the invoice

Examples:

GET /projects/onlinestore/invoices.json

Only registered or accepted invoices:

GET /projects/onlinestore/invoices.json?registered=1&accepted=1

Between dates:

GET /projects/onlinestore/invoices.json?date_from=2015-01-01&date_to=2015-06-26

With pagination:

GET /projects/onlinestore/invoices.json?offset=5&limit=2
GET /projects/onlinestore/invoices.xml?offset=5&limit=2

JSON Response:

{
  "invoices": [
    {
      "id": 9,
      "project": {
        "id": 2,
        "name": "OnlineStore"
      },
      "client": {
        "id": 1,
        "name": "Client1",
        "taxcode": "A13585625"
      },
      "state": "new",
      "date": "2013-04-04",
      "total": 100.0,
      "currency": "EUR",
      "created_at": "2015-06-23T12:48:25Z",
      "updated_at": "2015-06-26T10:05:08Z",
      "state_updated_at": "2015-06-26T10:05:08Z"
    },
    {
      ...
    }
  ],
  "total_count": 13,
  "offset": 5,
  "limit": 2
}

XML Response:

<?xml version="1.0" encoding="UTF-8"?>
<invoices total_count="13" offset="5" limit="2" type="array">
  <invoice>
    <id>9</id>
    <project id="2" name="OnlineStore"/>
    <client id="1" name="Client1" taxcode="A13585625"/>
    <state>new</state>
    <date>2013-04-04</date>
    <total>100.0</total>
    <currency>EUR</currency>
    <created_at>2015-06-23T12:48:25Z</created_at>
    <updated_at>2015-06-26T10:05:08Z</updated_at>
    <state_updated_at>2015-06-26T10:05:08Z</state_updated_at>
  </invoice>
  <invoice>
    ...
  </invoice>
</invoices>
View invoice
GET /invoices/[id].[format]

The attribute download_legal_url in the response includes the URL where you can download the "legal invoice". The "legal invoice" is the last successfully submitted invoice. The URL provides a signed PDF or XML file.

The response includes information about the "customer" (recipient) and the supplier (sender): identifier, name and VAT code.

The response also includes the totals of the invoice.

Formats:

Valid visualization formats for an invoice are:

  • json - JSON basic information of the invoice.

  • xml - XML basic information of the invoice.

  • pdf - PDF format.

  • Facturae 32 - Spanish XML format.

  • PEPPOL UBL - International standard UBL according to PEPPOL BIS.

  • Svefaktura - Swedish format.

  • OIO UBL - Danish UBL customization.

  • eFFF UBL - Belgian UBL customization.

Parameters:

  • disposition: in PDF, view the PDF file instead of downloading.

  • include: in XML or JSON, downloads additional information (optional). Possible values:

    • lines - Includes the lines

Examples:

GET /invoices/2.xml
GET /invoices/2.json
GET /invoices/2.pdf
GET /invoices/2.facturae32

GET /invoices/2.xml?include=lines

JSON Response:

{
  "invoice": {
    "id": 1,
    "project": {
      "id": 2,
      "name": "OnlineStore"
    },
    "company": {
      "id": 636488896,
      "name": "Company1",
      "taxcode": "ES77310058C"
    },
    "client": {
      "id": 1,
      "name": "Client1",
      "taxcode": "A13585625"
    },
    "state": "sent",
    "date": "2011-09-13",
    "due_date": "2011-09-13",
    "subttotal": 225.0,
    "taxes": [
      {
        "name": "IRPF -15,00%",
        "base": 75.0,
        "amount": -11.25
      },
      {
        "name": "IVA 18,00%",
        "base": 75.0,
        "amount": 13.5
      },
      {
        "name": "IRPF -8,00%",
        "base": 75.0,
        "amount": -6.0
      },
      {
        "name": "IVA 8,00%",
        "base": 75.0,
        "amount": 6.0
      }
    ],
    "total": 227.25,
    "currency": "EUR",
    "download_legal_url": "/attachments/download/770/Invoice.pdf",
    "created_at": "2011-09-13T12:01:11Z",
    "updated_at": "2011-09-13T12:01:11Z",
    "state_updated_at": "2011-09-13T12:01:11Z"
  }
}
Create an invoice
POST /projects/[project]/invoices.[format]

Creates an invoice and its lines.

The client_id of the Customer must be specified and it must exist.

send_after_import: send th invoice after the import (default false)

See the reference of fields available in the invoice.

JSON Example:

POST /projects/onlinestore/invoices.json
{
  "send_after_import": "true",
  "invoice": {
     "number": "a1236",
     "client_id": 14898,
     "date": "2015-07-30",
     "invoice_lines_attributes": [
         {
           "description": "line",
           "price": 123,
           "quantity": 1
         }
     ]
  }
}
Create an invoice from a file
POST /projects/[project]/invoices/[import_type].[format]

When a file is imported, the request payload must be the file contents to be imported and the Content-Type header must be application/octet-stream . If you do not use this header, the API will return 406 Not Acceptable . On success, you will get a 201 response and the summary according to the requested format (XML or JSON).

Import types:

Supported types of import:

  • facturae - The invoice is created based on an XML Facturae.

  • UBL - The invoice is created based on an XML UBL Invoice.

  • csv - The invoice is created based on a CSV file.

  • xls - The invoice is created based on an Excel file.

Facturae example:

POST /projects/onlinestore/invoices/facturae.xml
<?xml version="1.0"?>
... facturae example ...

Response with errors example:

<?xml version="1.0" encoding="UTF-8"?>
<errors type="array">
  <error>Number has already been taken</error>
</errors>
Note

The language of the text for the errors is the one the user has set up in "My account"

Example with cURL:

curl -v -H "Content-Type: application/octet-stream" -X POST --data "@facturae32.xml" \
        -H "X-Redmine-API-Key: 7baf59f9acadbd9419e43b7e80b966216e3c122e" "https://www.b2brouter.net/projects/onlinestore/invoices/facturae.json"
Delete invoice
DELETE /invoices/[id].[format]
Update an invoice
PUT /invoices/[id].[format]
{
  "invoice": {
    state: 'new'
  }
}
Send an invoice
GET /invoices/send_invoice/[id].[format]

Returns HTTP 200 on success.

On error returns HTTP 422 with the text of the error with the language of the user:

{ "errors":["No es poden reenviar les factures en estat Enviant-se"] }

Customers

List the customers in a project
GET /projects/[project]/clients.[format]

Retuns the paginated list of customers for the project.

Optional parameters:

  • offset: offset to the first customer in the set

  • limit: maximum number of customers in the response

  • name: search field. Searches on the customer name, address and VAT code

Examples:

GET /projects/onlinestore/clients.json
GET /projects/onlinestore/clients.json?name=Invinet

JSON Response:

Create a customer
POST /projects/[project]/clients.[format]

Creates a customer

Parameters:

  • client (mandatory): a list of customer attributes. The most relevant are:

    • name (mandatory): name of the customer

    • taxcode (mandatory): VAT code of the customer

    • language (mandatory): language of the customer. The two ISO_639-1 letter code: es, en, ca, …​

    • country: country of the customer. Two letter ISO 3166-1 code: es, fr, it, pt, gb, …​ By default, assigns "es". It is used to verify the taxcode and when the taxcode is not in European format, it prepends the code, for example "B10317980" will become "ESB10317980"

See the reference of [additional fields for the customer].

POST /projects/onlinestore/clients.xml
<?xml version="1.0"?>
<client>
  <name>cliente 1 SL</name>
  <taxcode>ESB10317980</taxcode>
  <language>ca</language>
</client>

Response:

201 Created : the customer has been created 422 Unprocessable Entity : the customer has not been created due to validation errors (the payload of the response contains the error message)

<?xml version="1.0" encoding="UTF-8"?>
<errors type="array">
  <error>VAT Id Number has already been taken</error>
  <error>Language can't be blank</error>
</errors>
View a customer
GET /clients/[id].[format]

JSON Response:

{
  "client": {
    "id": 1,
    "taxcode": "ESA13585625",
    "name": "Client1",
    "email": "mail@client1.com",
    "address": "",
    "address2": "",
    "postalcode": "08080",
    "city": "Barcelona",
    "province": "",
    "country": "es",
    "language": "en",
    "currency": "EUR",
    "invoice_format": "facturae_32",
    "iban": "ES9600001233333333333333",
    "payment_method": 1,
    "terms": "0",
    "sepa_type": "CORE",
    "created_at": "2011-09-13T11:50:02Z",
    "updated_at": "2011-09-13T11:50:02Z",
    "phone": "931111111"
  }
}
Update a customer
PUT /clients/[id].[format]
<?xml version="1.0" encoding="UTF-8"?>
<client>
  ... update data ...
</client>
Delete a customer
DELETE /clients/[id].[format]

Channels

An attribute of the Customer is the invoice_format. To get the list of possible values:

GET /users/channels.[format]

Example:

GET /users/channels.json

JSON Response:

{
  "channels":
  [
  {
    "name": "e-FACT - Punt general d'entrada de Catalunya",
    "key": "aoc32"
  },
  {
    "name": "e-FACT - Punt general d'entrada de Catalunya, signat amb certificat local",
    "key": "efact_local_cert"
  },
(...)

Graphics

Total invoiced
GET /projects/[project]/invoices/total_chart.[format]

Returns the total amount invoiced grouped by currency and period of time.

Parameters:

pref the preference of grouping. Can take one value from the following:

  • all_by_year - Everything per year; gets total by year

  • all_by_month - Everything per month: gets totals by month

  • last_month_by_week - Last month: groups per week data from last month

  • last_year_by_month - Last year: groups per month data from the last year. This is the default value.

Example:

GET /projects/onlinestore/invoices/total_chart.json?pref=all_by_year

JSON Response:

[
{
    "name": "EUR",
    "data":
    {
        "2008": "1851.36",
        "2009": 0,
        "2010": 0,
        "2011": "1888.0",
        "2012": 0,
        "2013": "110.0",
        "2014": "0"
    }
},
{
    "name": "USD",
    "data":
        {
            "2013": "240.0"
        }
    }
]

Final result with Google charts:

chart
More invoiced customers
GET /projects/[project]/top_clients_chart.[format]

Returns the customers with more revenue grouped per period of time. Maximum 5 customers.

Parameters:

  • pref grouping preferences (same values as th previous method)

  • currency currency code

Example:

GET /projects/onlinestore/top_clients_chart.json?pref=all_by_year&currency=EUR

JSON Response:

[
    {
        "data": [
            [ "2011", "5346.0" ],
            [ "2012", "5382.04" ],
            [ "2013", "5464.0" ],
            [ "2014", "5464.0" ],
            [ "2015", "2759.32" ]
        ],
        "name": "Client Name, SL"
    },
    {
        "data": [ ...  ],
        "name": "Other client name, S.A."
    }

 ...

]

Final result with Google charts:

chart
Total invoice per status
GET /projects/[proyecto]/invoice_status_chart.[formato]

Returns the total amount invoiced, according to the actual status of the invoices, grouped by period.

Parameters:

  • pref grouping preferences (same values as the previous method)

  • currency currency code

Example:

GET /projects/onlinestore/invoice_status_chart.json?pref=all_by_year&currency=EUR

JSON Response:

Note: status literals appear in the language of the user.

[
    {
        "data": [
            [ "2011", "7684.72" ],
            [ "2012", "10166.85" ],
            [ "2013", "10040.1" ],
            [ "2014", "11718.51" ],
            [ "2015", "3717.21" ]
        ],
        "name": "Tancada"
    },
    {
        "data": [ ... ],
        "name": "Nova"
    },
    {
        "data": [ ... ],
        "name": "Enviada"
    }
]

Final result with Google charts:

chart
Cash flow
GET /projects/[project]/cash_flow.[format]

Lists pending invoices and their total amount, grouped per currency and depending on whether they due date has expired or not.

Parameters:

pref grouping preferences. Can take one of the following values:

  • last_year - Invoices issues last year

  • last_3_months - Invoices issued during the last three months

  • all - All the invoices. This is the default value.

Example:

GET /projects/onlinestore/cash_flow.json?pref=all

JSON Response:

  • invoices = invoices due but not expired

  • due_invoices = invoices due and expired

{
    "cash_flow": {
      "EUR": {
        "currency": "EUR",
        "due_invoices_id": [ 307, 3555, 5746 ],
        "due_invoices_sum": 2904.75,
        "invoices_id": [ 7683 ],
        "invoices_sum": 100.0
      },
      "USD": {
        "due_invoices_sum": 0.0,
        "invoices_sum": 0.0,
        "currency": "USD"
      }
    }
}

Countries

List of countries and codes

GET /users/countries.[formato]

Example:

GET /users/countries.json

JSON Response:

{
  "countries":
  [
    {
      "code": "af",
      "name": "Afganistan"
    },
    {
      "code": "ax",
      "name": "Åland islands"
    },
    { "code": "al",
      "name": "Albània"
    },
(...)

Currencies

List of currencies

GET /users/currencies.[format]

Example:

GET /users/currencies.json

JSON Response:

{
    "currencies": [
      {
        "id": "eur",
        "priority": 2,
        "iso_code": "EUR",
        "name": "Euro",
        "symbol": "€",
        "subunit": "Cent",
        "subunit_to_unit": 100,
        "symbol_first": true,
        "html_entity": "&#x20AC;",
        "decimal_mark": ",",
        "thousands_separator": ".",
        "iso_numeric": "978"
      },
(...)

Events

List of events

GET /projects/[project]/events.[format]

Returns a paginated list of the events of a project.

Optional parameters:

  • invoice_id: filtered per invoice

  • offset: to the first element

  • limit: maximum number of events in the response

  • from_time: filtered per creation dates

Examples:

GET /projects/onlinestore/events.json

A single invoice

GET /projects/onlinestore/events.json?invoice_id=5

From a date:

GET /projects/onlinestore/events.json?from_time=2015-12-01

Paginated:

GET /projects/onlinestore/events.json?offset=5&limit=2
GET /projects/onlinestore/events.xml?offset=5&limit=2

JSON Response:

{
  "events":
    [
    {
      "name": "delivered_notification",
        "invoice":
        {
          "id": 292100,
          "number": "1502002304",
          "state": "registered",
          "state_updated_at": "2015-12-01T10:42:28Z"
        },
        "text": "Notification: Sent invoice",
        "description": "Notification: Sent invoice\n<a href=\"/events/file/2305470\">Download notification</a>\n",
        "created_at": "2015-12-01T11:15:03Z",
        "updated_at": "2015-12-01T11:15:03Z"

    },
    {
      "name": "new",
      "client":
      {
        "id": 15000,
        "name": "INSTITUT MUNICIPAL D'EDUCACIO"
      },
      "text": "Created",
      "description": "Created by Soporte B2Brouter",
      "created_at": "2015-11-19T13:37:41Z",
      "updated_at": "2015-11-19T13:37:41Z"
    },
    {
      "name": "deleted_issued_invoice",
      "info": "6397619",
      "text": "Deleted issued invoice",
      "description": "6397619:\n6397619\n\n",
      "created_at": "2015-11-19T12:55:02Z",
      "updated_at": "2015-11-19T12:55:02Z"
    }
  ]
}

an event can be related with an invoice or with a customer. We add the information to the event when the related object does not exist. In the last example we add the info field, where we will find information about the object (the invoice number for the invoices, the name for the customer) For the invoices, the state_updated_ati field indicates the date of the last status change

Languages

List of languages

GET /users/languages.[formato]

Example:

GET /users/languages.json

JSON Response:

{
  "languages":
  [
    {
        "code": "ca",
        "name": "Català"
    },
    {
        "code": "es",
        "name": "Español"
    },
    {
        "code": "gl",
        "name": "Galego"
    },
    {
        "code": "en",
        "name": "English"
    },
    {
        "code": "fr",
        "name": "Français"
    },
    {
        "code": "sv",
        "name": "Svenska"
    },
    {
        "code": "da",
        "name": "Dansk"
    }
  ]
}

Tokens

Tokens API

Add token
PUT /users/add_token.[format]

Adds a token to a user, if the token is assigned to another user, it is reassigned.

Parameters:

token (required): token to be added

Response:

  • 200 OK: token has been added

  • 422 Unprocessable Entity: token not added due to validation errors (response payload contains the error message)

Remove token
DELETE /users/remove_token.[format]

Removes the token from the user

Parameters:

token (required): token to be deleted

Response:

  • 200 OK: token has been removed

  • 404 Not Found: token not found for the current user

Test message
POST /users/test_gcm.[format]

Sends a message to all user devices

Parameters:

  • title: message title

  • body: message body

Response:

  • 200 OK: message sent

  • 404 Not Found: the user does not have devices to which the message can be send

Invoice status

List of Invoice Status

GET /users/invoice_states.[format]

Example:

GET /users/invoice_states.json

JSON Response:

{
    "invoice_states": [
        {
            "state": "new",
            "name": "Nova"
        },
        {
            "state": "sending",
            "name": "Enviant-se"
        },
(...)

General integration

Test environment

The test environment can be found at http://test.b2brouter.net

Company

A user has access to one or more Companies. A Company has a unique VAT code that issues invoices. The company identifier is the element following the /projects in the URLs. See an example here:

invinet is in this case the company (or project) identifier. Project and company can be treated as synonyms.

The Company is the container for the rest of entities: Invoice, Customer, etc.

ID fields

Every B2B Router entity has an internal identifier that uniquely identifies them. Those identifiers are used in the API to perform operations on the entities. For example:

GET /invoices/173179

Refers to the invoice with the unique internal identifier 173179.

Specify Content-Type in POST/PUT calls

When a remote entity is created or updated, the Content-Type of the request MUST be specified even if the remote URL has the corresponding suffix (e.g. POST ../clients.json).

  • When using JSON contents: Content-Type: application/json

  • When using XML contents: Content-Type: application/xml

Authentication

This API requires authentication for every operation. You can get authentication using two different methods:

  1. Using your user and password through HTTP Basic authentication

  2. Using the API access key. The access key can be used with the following methods:

    1. as the param key

    2. as the username in a HTTP Basic authentication and a random passord

    3. as an HTTP "X-B2B-API-Key" header

The API access key can be found in My Account option, under the API Access Key section.

Lists and pagination

A GET request on a set of entities does not normally return the whole set of objects in the database. These sets can be obtained with the following parameters:

  • offset: jump to the first object.

  • limit: number of items in the response (25 by default, 100 maximum)

Examples:

GET /invoices.json
=> gets the first 25 invoices

GET /invoices.json?limit=100
=> gets the initial 100 invoices

GET /invoices.json?offset=30&limit=10
=> gets 10 invoices starting on the 30th

The responses to GET requests in data sets provid information on the total number of available objects in B2B Router and the offset/limit used in the response. Examples:

GET /invoices.xml

<invoices type="array" total_count="1714" limit="25" offset="0">
  ...
</issues>

GET /invoices.json

{ "invoices":[...], "total_count":1714, "limit":25, "offset":0 }

Associated data

If you want to get the associations with the entities, this has to be explicitly specified, adding the include parameter in the query UURL.

GET /invoices/296.json?include=lines

{"invoice":
  {"id":296,
  ...
  "lines":[
      {"quantity":20.0, "description": "Tornillos", "price":100.0},
      ...
    ]
  }
}

Validation errors

When you try to create or modify an object with invalid data, you get a 422 Unprocessable Entity which means that the object has not been created or modified.

In those cases, the response will include the error messages.

Using the API in different languages and tools

Ruby

Using the REST API with Ruby Redmine REST API follows the Rails’s RESTful conventions, so using it with ActiveResource is pretty straightforward.

======= ActiveResource

Here is a simple ruby script that demonstrates how to use the Redmine REST API:

require 'rubygems'
require 'active_resource'

# Issue model on the client side
class Issue < ActiveResource::Base
  self.site = 'http://redmine.server/'
  self.user = 'foo'
  self.password = 'bar'
end

# Retrieving issues
issues = Issue.find(:all)
puts issues.first.subject

# Retrieving an issue
issue = Issue.find(1)
puts issue.description
puts issue.author.name

# Creating an issue
issue = Issue.new(
  :subject => 'REST API',
  :assigned_to_id => 1,
  :project_id => 1
)
issue.custom_field_values = {'2' => 'Fixed'}
if issue.save
  puts issue.id
else
  puts issue.errors.full_messages
end

# Updating an issue
issue = Issue.find(1)
issue.subject = 'REST API'
issue.save

# Deleting an issue
issue = Issue.find(1)
issue.destroy

You may need to set ´include_root_in_json = true´ in your ActiveResource class

cURL

Using the REST API with cURL curl is a command-line tool for transferring data using various protocols. It can be used to interact with the REST API.

Using JSON

Here is a simple example of a command that can be used to update an invoice:

curl -v -H "Content-Type: application/json" -X PUT --data "@388.json" -u login:password https://www.b2brouter.net/invoices/388.json
curl -v -H "Content-Type: application/json" -X PUT --data "@388.json" -H "X-B2B-API-Key: xxxx" https://www.b2brouter.net/invoices/388.json

The file that contains the data sent to b2brouter.net (388.json in the example above) would look like this:

{
  "invoice": {
    "subject": "subject123",
    "notes": "Changing the subject"
  }
}

Note: it’s required to set the Content-Type header according to the format of the data you are sending. It must be set to one the following values:

  • application/json

  • application/xml

Using XML

Here is a simple example of a command that can be used to create an issue with custom fields:

curl -v -H "Content-Type: application/xml" -X POST --data "@invoice_fields.xml" -u login:password https://www.b2brouter.net/invoices/388.xml
curl -v -H "Content-Type: application/xml" -X POST --data "@invoice_fields.xml" -H "X-B2B-API-Key: xxxx" https://www.b2brouter.net/invoices/388.xml
Uploading files

If you want to create an invoice form a Facturae file:

curl --data-binary "@facturae.xml" -H "Content-Type: application/octet-stream" -X POST -u login:password https://www.b2brouter.net/invoices/facturae

B2B Win

The process of importing invoices to B2B Router can be done through the B2B Win application. This section describes how to install and use this application.

Introduction

The B2B Win application provides a simple and efficient way to import and submit of invoices through B2B Router.

All communications use the HTTPS protocol. This guarantees the security and confidentiality between the server and B2B Win. The port is 443 / TCP.

The application reads its configuration from the config.json, located in the installation folder (by default Program Files\B2B Router for Windows). In this folder we also find the b2brouter.log file that will be useful if we experiment issues with the process.

Once installed a Scheduled Task is created. This task checks if there are documents in the outgoing folders. If so, it imports them using the Web Service footnote: [The API documentation is available at https://ws.b2brouter.com/doc.] at https://ws.b2brouter.com/. This scheduled task also checks if it is necessary to download any documents from B2B Router into the INBOX folder, using the same technology.

The application also checks daily for new versions and downloads and installs them automatically.

It is compatible with Windows Vista and higher. It is not compatible with Windows XP or Windows Server 2003.

Download

The B2B Win application can be downloaded from https://ws.b2brouter.com/es/.

To download the installer you must click on download. Windows may identify the downaload as being not safe and may suggest to discard it. You should ignore this warning and choose the option to keept the file.

The downloaded file is b2brouter-setup.exe and is usually saved in the downloads folder.

Download area

Installation

When you execute the B2B Win installation, Windows may raise a security warning. B2B Win is secure and you can proceed with the installation. You may also be requested to provide the administration password.

When the installation process finalizes, the B2B Win configuration window appears.

In the first screen you have to enter your username and password. These credentials are the same as those used to access www.b2brouter.net.

Credentials

Once the user and password has been validated, you get an API Key, which will be used to identify you automatically in a unique and secure way during the daily use of the application, saving you to enter the user and password each time.

In the next screen you can choose a working directory and a time interval. The working folder (path) is where the subfolders will be created and the interval (interval) is the frequency with which the application will check for files.

Settings

Because B2B Win internally installs a Windows 'Scheduled Task', you only have to open the configuration program in case you need to change the folder, interval or access credentials.

Operation

In the working directory, B2B Win creates a subfolder for each sending channel.

In order to send invoices, the files must be placed in the corresponding directory and the application will import them automatically according to the chosen interval.

  • Import CSV to import the B2B CSV that generates an invoice

  • Import Excel to generate multiple invoices from the B2B Microsoft Excel file

  • Import Facturae to import XML files in Facturae format. These may already be signed or not (in the latter case the invoice will be signed by B2B Router on behalf of the sender)

  • Import UBL to import XML files in UBL format.

  • Import Navision to import XML files in Navision format.

  • Import EDI to import EDI INVOIC files.

  • Import SII to import the CSV files with VAT information

The B2B CSV and B2B Excel format and contents of the files ar described in another document.

Directory

All imported documents disappear from the corresponding working directory and appear in B2B Router.

If the format of the document does not correspond to the channel, or if the file is damaged, you will receive an e-mail notifying that it has not been imported. In these cases you have to check the file and copy the file back in the corresponding folder to retry the import.