Invoice connections

A company is wired to an external AP/invoice provider via a connection — a record pairing a provider key with encrypted API credentials and an optional webhook secret. A company "uses Yooz" if and only if it has an active connection for that provider. All endpoints are scoped to the authenticated company (cookie/JWT auth, accounting permissions required). Secrets are write-only: the API key and webhook secret are stored encrypted and are never returned by any endpoint. Supplier→contractor matching is performed automatically using the SIREN number (the 9-digit prefix of the contractor's SIRET) — there is no per-connection matching configuration. See the authentication page for cookie/JWT auth details.

Properties

Name
id
Type
string
Description
Unique identifier for the connection.
Name
client
Type
string
Description
Company (tenant) id that owns this connection.
Name
provider
Type
string
Description
External provider key, e.g. "yooz".
Name
active
Type
boolean
Description
Whether this connection is currently active. Only one active connection per provider is allowed per company.
Name
hasCredentials
Type
boolean
Description
true when an API key is stored for this connection. The key itself is never returned.
Name
hasWebhookSecret
Type
boolean
Description
true when a webhook secret is stored. The secret itself is never returned.
Name
lastPolledAt
Type
string => ISODate | null
Description
Timestamp of the last successful poll from the provider. null if the connection has never been polled.
Name
createdAt
Type
string => ISODate
Description
Date the connection was created.
Name
updatedAt
Type
string => ISODate
Description
Date the connection was last modified.

GET/invoice-connections

List connections

Returns all connections belonging to the authenticated company. The array may contain both active and inactive connections. Requires accounting permissions. See the authentication page for cookie/JWT auth details.

Request

GET

/invoice-connections

curl -G https://jarvis.bob-desk.com/invoice-connections \
  -H "Cookie: session={cookie}"

Response

[
  {
    "id": "64b2e4d19ab7e72a4fb4ac20",
    "client": "5d9b5b5b9ab7e72a4fb4ae69",
    "provider": "yooz",
    "active": true,
    "hasCredentials": true,
    "hasWebhookSecret": true,
    "lastPolledAt": "2024-06-20T06:00:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-06-20T06:00:00.000Z"
  }
]

POST/invoice-connections

Create connection

Creates a new provider connection for the authenticated company. apiKey and webhookSecret are stored encrypted and are never echoed back — hasCredentials and hasWebhookSecret indicate their presence. Requires accounting permissions. See the authentication page for cookie/JWT auth details.

Returns 201 Created with the connection view on success.

Required body parameters

Name
provider
Type
string
Description
Provider key, e.g. "yooz". Returns 400 if the provider is unknown.
Name
apiKey
Type
string
Description
API credentials for the provider. Write-only — stored encrypted, never returned.

Optional body parameters

Name
webhookSecret
Type
string
Description
HMAC secret used to verify inbound webhook payloads. Write-only — stored encrypted, never returned.
Name
active
Type
boolean
Description
Whether to activate the connection immediately. Defaults to true. Returns 409 Conflict if an active connection for the same provider already exists.

Error responses

Name
400
Type
error
Description
Unknown provider key.
Name
409
Type
error
Description
An active connection for this provider already exists for this company.

Request

POST

/invoice-connections

curl -X POST https://jarvis.bob-desk.com/invoice-connections \
  -H "Content-Type: application/json" \
  -H "Cookie: session={cookie}" \
  -d '{
    "provider": "yooz",
    "apiKey": "yz_live_sk_••••••••••••••••",
    "webhookSecret": "whsec_••••••••••••••••",
    "active": true
  }'

Response

{
  "id": "64b2e4d19ab7e72a4fb4ac20",
  "client": "5d9b5b5b9ab7e72a4fb4ae69",
  "provider": "yooz",
  "active": true,
  "hasCredentials": true,
  "hasWebhookSecret": true,
  "lastPolledAt": null,
  "createdAt": "2024-06-22T09:00:00.000Z",
  "updatedAt": "2024-06-22T09:00:00.000Z"
}

PATCH/invoice-connections/:id

Update connection

Partially updates an existing connection. At least one body field must be provided. Use this endpoint to rotate the API key, update the webhook secret, or enable/disable the connection. Requires accounting permissions. See the authentication page for cookie/JWT auth details.

Route parameters

Name
id
Type
string
Description
The connection id to update.

Optional body parameters (at least one required)

Name
apiKey
Type
string
Description
Replacement API key. Write-only — overwrites the stored key, never returned.
Name
webhookSecret
Type
string
Description
Replacement webhook secret. Write-only — overwrites the stored secret, never returned.
Name
active
Type
boolean
Description
Enable or disable the connection. Returns 409 Conflict if enabling would result in two active connections for the same provider.

Error responses

Name
404
Type
error
Description
No connection found with the given id.
Name
409
Type
error
Description
Setting active: true would create a second active connection for the same provider.

Request

PATCH

/invoice-connections/:id

curl -X PATCH https://jarvis.bob-desk.com/invoice-connections/64b2e4d19ab7e72a4fb4ac20 \
  -H "Content-Type: application/json" \
  -H "Cookie: session={cookie}" \
  -d '{
    "apiKey": "yz_live_sk_new••••••••••••"
  }'

Response

{
  "id": "64b2e4d19ab7e72a4fb4ac20",
  "client": "5d9b5b5b9ab7e72a4fb4ae69",
  "provider": "yooz",
  "active": true,
  "hasCredentials": true,
  "hasWebhookSecret": true,
  "lastPolledAt": "2024-06-20T06:00:00.000Z",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-06-22T11:45:00.000Z"
}

DELETE/invoice-connections/:id

Delete connection

Disconnects the provider by soft-deleting the connection. Active polling and webhook processing for this connection stop immediately. Returns 204 No Content on success. Requires accounting permissions. See the authentication page for cookie/JWT auth details.

Route parameters

Name
id
Type
string
Description
The connection id to delete.

Error responses

Name
404
Type
error
Description
No connection found with the given id.

Request

DELETE

/invoice-connections/:id

curl -X DELETE https://jarvis.bob-desk.com/invoice-connections/64b2e4d19ab7e72a4fb4ac20 \
  -H "Cookie: session={cookie}"

Response

{}