OBAPI OBAPI

Getting Started

Get your first OBAPI response in 5 minutes.

Prerequisites

  • An OBAPI-compatible provider (e.g. a Dolibarr instance with the OBAPI module)
  • An API token (Bearer token) provided by your provider
  • A tool to make HTTP requests: curl, Postman, or any HTTP client

Step 1 -- Check server capabilities

The Discovery endpoint requires no authentication and tells you what the server supports:

GET https://provider.example.com/obapi/v1/discovery
{
    "discovery": {
        "provider": "Acme Corp",
        "obapi_version": "1.0",
        "endpoints": [
            "thirdparty", "contacts", "products",
            "proposals", "orders", "invoices",
            "creditnotes", "shipments", "download"
        ],
        "tier": 1,
        "authentication": ["bearer"],
        "documentation": "https://obapi.org"
    }
}

This tells you the server implements Tier 1 and accepts Bearer token authentication.

Step 2 -- Authenticate

All other endpoints require a Bearer token in the Authorization header:

Authorization: Bearer your-api-token-here

How you obtain the token depends on the provider (pre-shared key, OAuth2, login/password, etc.). Check with your provider.

Step 3 -- Retrieve invoices

Let's fetch the latest invoices:

GET https://provider.example.com/obapi/v1/invoices
Authorization: Bearer your-api-token-here

Response:

{
    "items": [
        {
            "id": "1042",
            "ref": "FA2405-0001",
            "customer_ref": "PO-2024-789",
            "date_invoice": "2024-05-15",
            "date_due": "2024-06-15",
            "status": "validated",
            "total_excl_tax": "1500.00",
            "total_vat": "300.00",
            "total_incl_tax": "1800.00"
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 50,
        "total_items": 1,
        "total_pages": 1
    }
}

Step 4 -- Get invoice details

Fetch a single invoice with its line items:

GET https://provider.example.com/obapi/v1/invoices/1042
Authorization: Bearer your-api-token-here

The response includes all fields plus the lines array with each line item.

Step 5 -- Download the PDF

GET https://provider.example.com/obapi/v1/download/1042?type=invoice
Authorization: Bearer your-api-token-here

The server returns the binary PDF with Content-Type: application/pdf.

Using pagination

List endpoints accept page and per_page parameters:

GET /obapi/v1/invoices?page=2&per_page=20

The response always includes a pagination object so you know how many pages remain.

Filtering by date

Most list endpoints accept date_start and date_end:

GET /obapi/v1/invoices?date_start=2024-01-01&date_end=2024-12-31

Error handling

If something goes wrong, OBAPI returns a structured error:

{
    "error": {
        "type": "authentication_error",
        "code": "INVALID_TOKEN",
        "message": "The provided Bearer token is invalid or expired"
    }
}

Always check the HTTP status code first (401, 403, 404, 422, 500), then read the error object for details. See the full error reference.

Next steps