Invoices

Push supplier invoices from your accounting provider (Yooz, etc.) and read them back. Unlike the invoices embedded in a ticket payload, this resource also exposes invoices not yet associated to a ticket.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the invoice.

  • Name
    provider
    Type
    string
    Description

    Accounting provider the invoice comes from (e.g. yooz).

  • Name
    invoice_platform_id
    Type
    string
    Description

    Id of the document in the provider (PA id). Used as the idempotency key.

  • Name
    number
    Type
    string
    Description

    Invoice reference.

  • Name
    issue_date
    Type
    string => ISODate
    Description

    Issue date of the invoice.

  • Name
    due_date
    Type
    string => ISODate
    Description

    Due date of the invoice.

  • Name
    currency
    Type
    string
    Description

    ISO currency code.

  • Name
    amounts
    Type
    object
    Description

    { ht, tva, ttc } — excluding tax / VAT / including tax.

  • Name
    supplier
    Type
    object
    Description

    Provider-side supplier record: { name, siret }.

  • Name
    state
    Type
    string
    Description

    Canonical state of the invoice (ticket_unmatched, linked, ...).

  • Name
    ticket_id
    Type
    string
    Description

    Linked ticket id, or null.

  • Name
    supplier_id
    Type
    string
    Description

    Resolved Bob! Desk contractor id, or null.

  • Name
    created_at
    Type
    string => ISODate
    Description

    Date when the invoice was created.

  • Name
    updated_at
    Type
    string => ISODate
    Description

    Date when the invoice was last updated.

GET/api/v3.0/invoices

Invoices list

This endpoint allows you to retrieve a list of invoices. To paginate, pass the id of the last item of the current page as the cursor parameter of the next request. When the response returns an empty invoices array and cursor is null, you have reached the end of the list.

Optional parameters

All filters are combined with a logical AND: an invoice is returned only if it matches every provided parameter (e.g. created_after + updated_after both apply).

  • Name
    association
    Type
    string
    Description

    unmatched | linked | all (default all). Use unmatched to list invoices awaiting ticket association (state = ticket_unmatched).

  • Name
    issued_after
    Type
    timestamp
    Description

    Filter on issue_date, timestamp in ms.

  • Name
    issued_before
    Type
    timestamp
    Description

    Filter on issue_date, timestamp in ms.

  • Name
    created_after
    Type
    timestamp
    Description

    Filter on created_at, timestamp in ms.

  • Name
    created_before
    Type
    timestamp
    Description

    Filter on created_at, timestamp in ms.

  • Name
    updated_after
    Type
    timestamp
    Description

    Filter on updated_at, timestamp in ms.

  • Name
    updated_before
    Type
    timestamp
    Description

    Filter on updated_at, timestamp in ms.

  • Name
    provider
    Type
    string
    Description

    Exact match on the provider key (e.g. yooz).

  • Name
    supplier_siret
    Type
    string
    Description

    Exact match on the supplier SIRET.

  • Name
    number
    Type
    string
    Description

    Exact match on the invoice reference.

  • Name
    invoice_platform_id
    Type
    string
    Description

    Exact match on the provider-side invoice id.

  • Name
    cursor
    Type
    string
    Description

    Cursor to paginate the results (id of the last item of the previous page).

  • Name
    limit
    Type
    number
    Description

    Page size, 1..200 (default 50).

Request

GET
/api/v3.0/invoices
curl -G https://api.bob-desk.com/api/v3.0/invoices \
  -H "Authorization: Bearer {token}" \
  -d association="unmatched" \
  -d limit="50"

Response

{
  "cursor": "64a1f3c89ab7e72a4fb4ae03",
  "invoices": [
    {
      "id": "64a1f3c89ab7e72a4fb4ae01",
      "provider": "yooz",
      "invoice_platform_id": "YZ-2024-00871",
      "number": "FA-2024-00871",
      "issue_date": "2024-03-12T00:00:00.000Z",
      "due_date": "2024-04-12T00:00:00.000Z",
      "currency": "EUR",
      "amounts": { "ht": 1000.0, "tva": 200.0, "ttc": 1200.0 },
      "supplier": { "name": "ACME", "siret": "12345678900011" },
      "state": "ticket_unmatched",
      "ticket_id": null,
      "supplier_id": null,
      "created_at": "2024-03-12T08:00:00.000Z",
      "updated_at": "2024-03-12T08:00:00.000Z"
    }
  ]
}
GET/api/v3.0/invoices/:id

Retrieve an invoice

This endpoint allows you to retrieve a single invoice. Returns 404 if the invoice does not exist or belongs to another account.

Route parameters

  • Name
    id
    Type
    string
    Description

    The Bob! Desk invoice id.

Request

GET
/api/v3.0/invoices/:id
curl https://api.bob-desk.com/api/v3.0/invoices/64a1f3c89ab7e72a4fb4ae01 \
  -H "Authorization: Bearer {token}"

Response

{
  "invoice": {
    "id": "64a1f3c89ab7e72a4fb4ae01",
    "provider": "yooz",
    "invoice_platform_id": "YZ-2024-00871",
    "number": "FA-2024-00871",
    "issue_date": "2024-03-12T00:00:00.000Z",
    "due_date": "2024-04-12T00:00:00.000Z",
    "currency": "EUR",
    "amounts": { "ht": 1000.0, "tva": 200.0, "ttc": 1200.0 },
    "supplier": { "name": "ACME", "siret": "12345678900011" },
    "state": "ticket_unmatched",
    "ticket_id": null,
    "supplier_id": null,
    "created_at": "2024-03-12T08:00:00.000Z",
    "updated_at": "2024-03-12T08:00:00.000Z"
  }
}
POST/api/v3.0/invoices

Push an invoice

This endpoint lets an accounting provider (or your own integration) push a supplier invoice into Bob! Desk. Configure your provider's export with your Bob! Desk API key as the Authorization: Bearer header — the invoice is automatically attributed to your account.

Required parameters

  • Name
    invoice_platform_id
    Type
    string
    Description

    Id of the invoice in the provider (max 64 chars). Used as the idempotency key.

Optional parameters

  • Name
    provider
    Type
    string
    Description

    Provider key (default yooz, max 64 chars).

  • Name
    number
    Type
    string
    Description

    Invoice reference (max 256 chars).

  • Name
    issue_date
    Type
    string => ISODate
    Description

    Issue date (ISO 8601).

  • Name
    due_date
    Type
    string => ISODate
    Description

    Due date (ISO 8601).

  • Name
    currency
    Type
    string
    Description

    Currency code (max 8 chars).

  • Name
    amounts
    Type
    object
    Description

    { ht, tva, ttc } (numbers).

  • Name
    supplier
    Type
    object
    Description

    { name (max 256), siret, iban }. siret must be a 9-digit SIREN or a 14-digit SIRET. iban is stored but never returned by the API.

  • Name
    document
    Type
    object
    Description

    { filename (max 255), mime, base64 }. mime must be application/pdf; the decoded file must not exceed 25 MB.

  • Name
    match_hints
    Type
    object
    Description

    { ticket_ref, po_ref, location_ref } (max 256 chars each), optional hints for future ticket reconciliation. location_ref is the reference of the site carried by the invoice (store code, cost-center…), used to resolve the Bob! Desk location during reconciliation.

Behavior

  • Idempotent: pushing the same invoice_platform_id twice for the same provider returns 200 with the existing invoice, unchanged — safe for provider retries.
  • The supplier is automatically matched to one of your contractors by SIRET (exact) or SIREN (establishment prefix). supplier_id is set only when exactly one contractor matches; an ambiguous or unknown SIRET leaves it null.
  • The invoice is created with state = ticket_unmatched; ticket association happens later in Bob! Desk.

Responses

  • 201 — invoice created, returns { "invoice": { ... } }
  • 200 — invoice already known (idempotent replay), returns the existing invoice
  • 400 — validation error, returns { "error": "..." }
  • 401 — missing or invalid API key
  • 413 — document larger than 25 MB
  • 502 — document storage failed (nothing was created; retry later)

Request

POST
/api/v3.0/invoices
curl https://api.bob-desk.com/api/v3.0/invoices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_platform_id": "YZ-2024-00871",
    "number": "FA-2024-00871",
    "issue_date": "2024-03-12T00:00:00.000Z",
    "due_date": "2024-04-12T00:00:00.000Z",
    "currency": "EUR",
    "amounts": { "ht": 1000.0, "tva": 200.0, "ttc": 1200.0 },
    "supplier": { "name": "ACME", "siret": "12345678900011" },
    "document": { "filename": "FA-2024-00871.pdf", "mime": "application/pdf", "base64": "JVBERi0xLjQ..." },
    "match_hints": { "ticket_ref": "T-1024", "location_ref": "MAG-LYON-02" }
  }'

Response (201)

{
  "invoice": {
    "id": "64a1f3c89ab7e72a4fb4ae01",
    "provider": "yooz",
    "invoice_platform_id": "YZ-2024-00871",
    "number": "FA-2024-00871",
    "issue_date": "2024-03-12T00:00:00.000Z",
    "due_date": "2024-04-12T00:00:00.000Z",
    "currency": "EUR",
    "amounts": { "ht": 1000.0, "tva": 200.0, "ttc": 1200.0 },
    "supplier": { "name": "ACME", "siret": "12345678900011" },
    "state": "ticket_unmatched",
    "ticket_id": null,
    "supplier_id": null,
    "created_at": "2024-03-12T08:00:00.000Z",
    "updated_at": "2024-03-12T08:00:00.000Z"
  }
}