Purchase Order API

Introduction

The API lets you view your customers purchacorders for you and register transport booking, delivery notice on this orders. This is a step-by-step guide on how to use the API.

Purchase Order has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality.

A typical usage pattern is to check whether a customer is a purchaseorder customer. Then follow up with creating a purchase order. And lastly create a packaging list for the given order.

Please note that this API currently doesn’t support json on all of its methods yet. Look in the example section to see which are supported.

SOAP

Versioning

Purchase Order makes an effort to always be backwards compatible regarding data format for requests and responses of the Web Service. To achieve this, a SchemaVersion element is used in the request, indicating which version the client is on and what data-format the client expects in the result.

We make an effort not to return new elements in the response when an old schema version is specified. When changes in the schema are made, the SchemaVersion is incremented by one. The new schema is used at the same endpoint URL as before and uses the same namespace for its XML elements. A TraceMessage element (info message) in the response is added to inform the client that its schema should be updated. Old schema versions might in the future be unsupported.

Regarding the XML API (not Web Services), an XML Schema is not used at all. Therefore, clients of the XML API are expected to handle new elements that appear. Nevertheless, the response will be backwards compatible in the sense that elements are not renamed or deleted.

WSDL

https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl

Error handling

When using the Purchase Order, errors or service unavailability can occur, although we do our utmost to prevent any downtime. Thus it is important to use timeouts and other error handling techniques when making requests to the service.

How you handle errors depends on the nature of your application, but one strategy for handling such situations is by providing a failover if the shipping guide responds with an error or does not respond at all (timeout).

See the list of error codes for hints on how to implement error handling.

Overview of endpoints

Base URL

https://api.bring.com/po/api/v1
Method Endpoint Usage
GET /purchaseorderCustomer/{customerId} Check if customer is valid for purchase orders
GET /order/{customerId}/{purchaseorderId} List purhcase order information
POST /order Send a purchase order
GET /items/{customerId}/{purchaseorderId} List purchase order items
GET /transport/{customerId}/{purchaseorderId} List transport orders for purchase order
POST /transport Add packaging list
GET /senderStatus/{customerId}/{purchaseorderId} Get status for purchase order
POST /event Create TMSEvents
GET /errorCodes List error codes

Check if customer is valid for purchase orders

URL

https://api.bring.com/po/api/v1/purchaseorderCustomer/{customerId}

Request params

URI parameter Type Description
customerId string

Required.

Possible values

Response

Success (200)

Returns true if given customer is a valid for purchase orders.

<IsPurchaseorderCustomerResponse xmlns="http://api.bring.com/po">
    <ResponseProperties>
        <SchemaVersion>
            1
        </SchemaVersion>
        <Locale>
            en
        </Locale>
        <DateAndTimes subClass="ResponseDate">
            2015-12-01T08:10:01.163+01:00
        </DateAndTimes>
    </ResponseProperties>
    <IsPurchaseOrderCustomer>
        false
    </IsPurchaseOrderCustomer>
</IsPurchaseorderCustomerResponse>

List purhcase order information

URL

https://api.bring.com/po/api/v1/order/{customerId}/{purchaseorderId}

Request params

URI parameter Type Description
customerId string

Required.

Possible values
purchaseorderId string

Required.

Possible values

Response

Success (200)

Complete purchase order information including order items.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetPurchaseOrderResponse xmlns="http://api.bring.com/po">
    <ResponseProperties>
        <SchemaVersion>1</SchemaVersion>
        <Locale>en</Locale>
        <DateAndTimes subClass="ResponseDate">2015-12-01T08:10:01.161+01:00</DateAndTimes>
        <Error>
            <Code>PO_STATE_002</Code>
            <Description>You must log in to use this endpoint. See developer.bring.com for details about login with HTTP-headers.</Description>
        </Error>
    </ResponseProperties>
</GetPurchaseOrderResponse>

Send a purchase order

URL

https://api.bring.com/po/api/v1/order

Response

Success (200)

Successfully created a purhcase order.

List purchase order items

URL

https://api.bring.com/po/api/v1/items/{customerId}/{purchaseorderId}

Request params

URI parameter Type Description
customerId string

Required.

Possible values
purchaseorderId string

Required.

Possible values

Response

Success (200)

List of purchase order items.

<GetPurchaseOrderItemResponse xmlns="http://api.bring.com/po">
    <ResponseProperties>
        <SchemaVersion>
            1
        </SchemaVersion>
        <Locale>
            en
        </Locale>
        <DateAndTimes subClass="ResponseDate">
            2015-12-01T08:10:01.161+01:00
        </DateAndTimes>
        <Error>
            <Code>
                PO_STATE_002
            </Code>
            <Description>
                You must log in to use this endpoint. See developer.bring.com for details about login with HTTP-headers.
            </Description>
        </Error>
    </ResponseProperties>
</GetPurchaseOrderItemResponse>

List transport orders for purchase order

URL

https://api.bring.com/po/api/v1/transport/{customerId}/{purchaseorderId}

Request params

URI parameter Type Description
customerId string

Required.

Possible values
purchaseorderId string

Required.

Possible values

Response

Success (200)

List of transport orders for given purchase order, if any.

<GetPurchaseOrderItemResponse xmlns="http://api.bring.com/po">
    <ResponseProperties>
        <SchemaVersion>
            1
        </SchemaVersion>
        <Locale>
            en
        </Locale>
        <DateAndTimes subClass="ResponseDate">
            2015-12-01T08:10:01.161+01:00
        </DateAndTimes>
        <Error>
            <Code>
                PO_STATE_002
            </Code>
            <Description>
                You must log in to use this endpoint. See developer.bring.com for details about login with HTTP-headers.
            </Description>
        </Error>
    </ResponseProperties>
</GetPurchaseOrderItemResponse>

Add packaging list

URL

https://api.bring.com/po/api/v1/transport

Request body

<CreateTransportOrderRequest xmlns="http://api.bring.com/po">
    <RequestProperties>
        <SchemaVersion>1</SchemaVersion>
        <Locale>en</Locale>
        <DateAndTimes subClass="RequestDate">2014-07-01T10:00:26.686+02:00</DateAndTimes>
    </RequestProperties>
    <CustomerNo>12345</CustomerNo>
    <PurchaseOrderNo>1234</PurchaseOrderNo>
    <TransportOrder>
        <ConsignmentId>1353</ConsignmentId>
        <PackingListSet orderLineId="1"></PackingListSet>
    </TransportOrder>
</CreateTransportOrderRequest>

Response

Success (200)

Successfully added packaging list.

Get status for purchase order

URL

https://api.bring.com/po/api/v1/senderStatus/{customerId}/{purchaseorderId}

Request params

URI parameter Type Description
customerId string

Required.

Possible values
purchaseorderId string

Required.

Possible values

Response

Success (200)

Open or Locked.

<GetSenderStatusResponse xmlns="http://api.bring.com/po">
    <ResponseProperties>
        <SchemaVersion>
            1
        </SchemaVersion>
        <Locale>
            en
        </Locale>
        <DateAndTimes subClass="ResponseDate">
            2015-12-01T08:10:01.232+01:00
        </DateAndTimes>
        <Error>
            <Code>
                PO_STATE_002
            </Code>
            <Description>
                You must log in to use this endpoint. See developer.bring.com for details about login with HTTP-headers.
            </Description>
        </Error>
    </ResponseProperties>
    <SenderStatus>
        NOT_FOUND
    </SenderStatus>
</GetSenderStatusResponse>

Create TMSEvents

URL

https://api.bring.com/po/api/v1/event

Request body

<CreateEventRequest xmlns="http://api.bring.com/po">
    <RequestProperties>
        <SchemaVersion>1</SchemaVersion>
        <Locale>no</Locale>
        <DateAndTimes subClass="RequestDate">2014-07-03T08:03:56.040+02:00</DateAndTimes>
    </RequestProperties>
    <Event>
        <ConsignmentId>12345</ConsignmentId>
        <EventType>{event type}</EventType>
        <PerformedBy>{some value}</PerformedBy>
        <Timestamp>2014-07-04T00:00:00+02:00</Timestamp>
    </Event>
</CreateEventRequest>

Response

Success (200)

Successfully created a new resource

List error codes

URL

https://api.bring.com/po/api/v1/errorCodes

Response

Success (200)

Dynamic list of error codes used in the solution.

<ErrorList xmlns="http://api.bring.com/po">
    <errorTypes>
        <Code>
            PO_INPUT_001
        </Code>
        <Description>
            Must provide valid customer ID
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_002
        </Code>
        <Description>
            Must provide valid purchase order
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_003
        </Code>
        <Description>
            Must provide valid schema version. See developer.bring.com for latest schema version
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_004
        </Code>
        <Description>
            Request properties must contain valid datetime
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_005
        </Code>
        <Description>
            Request properties must contain valid locale
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_006
        </Code>
        <Description>
            Request properties must be present
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_007
        </Code>
        <Description>
            Consignment ID is required
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_008
        </Code>
        <Description>
            Must provide valid EventType. See xsd for list of valid types.
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_009
        </Code>
        <Description>
            Must provide valid ISO timestamp for event
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_010
        </Code>
        <Description>
            Purchase order not found. You can not have orderlines to a non-existing purchase order.
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_011
        </Code>
        <Description>
            Negative quantity not allowed.
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_012
        </Code>
        <Description>
            Item on transport order does not exist on purchase order. OrderLineId and ArticleLineId must match purchase order.
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_013
        </Code>
        <Description>
            Shipping container ID is required
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_014
        </Code>
        <Description>
            A valid container type required for the shipping container and the content
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_015
        </Code>
        <Description>
            Content for shipping container is required
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INOUT_016
        </Code>
        <Description>
            Content in shipping container requires either consignment ID or shipping container ID
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_017
        </Code>
        <Description>
            The request contained invalid content.
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_018
        </Code>
        <Description>
            The request contains input that is not supported.
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_019
        </Code>
        <Description>
            Some required parameters are missing.
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_INPUT_020
        </Code>
        <Description>
            Must provide valid transport order
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_STATE_001
        </Code>
        <Description>
            Purchase order not found
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_STATE_002
        </Code>
        <Description>
            You must log in to use this endpoint. See developer.bring.com for details about login with HTTP-headers.
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_STATE_003
        </Code>
        <Description>
            Order items for requested purchase order not found
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_STATE_004
        </Code>
        <Description>
            Access is denied to read this purchaseorder
        </Description>
    </errorTypes>
    <errorTypes>
        <Code>
            PO_STATE_005
        </Code>
        <Description>
            Transport order not found
        </Description>
    </errorTypes>
</ErrorList>