3. Using the API

Authentication

All routes require an Authorization: Bearer {access_token} header (OAuth 2.0 access token for your partner application).

Header	Value	Origin
`x-oneconnect-api-key`	`{integrationSecret}`	Except exceptions, the header `x-one-connect-api-key` is mandatory. It’s the integration secret key, retrieved by the end-user from OneConnect by Shine user-interface, upon invitation of their accountant, and configured into your application. This is an organization-level configuration.

All routes are structured as follows: integrations/{integrationId}. The integrationId is retrieved at the same time as integrationSecret.

Key identifiers

Document ID (`documentId`)

Generated by OneConnect by Shine on each successful import (UUID).
Immutable: never changes for a given import.
Returned in the HTTP response and in status webhooks.
Keep it for support and traceability.

External reference (`externalReference`)

Optional: you define it freely (your invoice number, internal identifier, etc.).
Constraints: [a-zA-Z0-9_-:], max 64 characters.
Must be unique per integrationId and document type (purchase invoices, sales invoices, accounting entry, etc.). The same reference may be used for different import types. On duplicate for the same type, OneConnect by Shine returns 409 with the documentId and depositDate of the existing import.
Returned in status webhooks — useful for correlating events with your own records without storing our documentId.

Invoice import format: multipart/form-data

The invoice import endpoints (purchase-invoices, sales-invoices) expect multipart/form-data.

Required fields

Field	Type	Description
`file`	binary	The invoice file. Formats: PDF, JPEG, PNG, BMP. Max size: 5 MB.
`filename`	string	Declared name; must end with `.pdf`, `.jpg`, `.jpeg`, `.png`, or `.bmp` (case-insensitive).

Optional fields

Field	Type	Description
`userEmail`	string	Email of the user performing the import. We recommend always sending it; if omitted, OneConnect may use the email of the user who received the invitation.
`comment`	string	Free-form note for the accounting firm.
`externalReference`	string	Your reference (see above).
`entries`	JSON (string)	Accounting entries (see dedicated section below). In multipart/form-data, serialize this field as a JSON string (not a nested multipart object).
`organization`	JSON (string)	Optional structured metadata about the counterparty or organization (`name`, `siren`, `legalForm`, `naf`, `address`, `phoneNumber`, `contactEmail`). See the public OpenAPI schema for `organization` and nested types. In multipart/form-data, serialize this field as a JSON string (not a nested multipart object).

Accounting entries (`entries` multipart field)

When you already have accounting lines, send them in the entries multipart part as UTF-8 JSON (string or object, depending on your client). The JSON must have a root object with a data object that contains data.lines: the array of lines to import.

Maximum size: the entries payload is limited to 5 MB (UTF-8).

Full example (`data.lines` with optional fields)

The example uses two lines: the same amount is on the debit side of the first account and on the credit side of a second account

{
  "data": {
    "lines": [
      {
        "date": "2026-03-09T00:00:00.000Z",
        "debit": {
          "amount": 100.0,
          "currency": "EUR",
          "currencyAmount": 100.0,
          "currencyRate": 1
        },
        "credit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "journal": "ACH",
        "account": "40100000",
        "thirdParty": "FRN001",
        "thirdPartySiren": "123456789",
        "thirdPartyLabel": "Fournisseur Exemple",
        "label": "Facture achat mars",
        "reference": "FA-2026-042"
      },
      {
        "date": "2026-03-09T00:00:00.000Z",
        "debit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "credit": {
          "amount": 100.0,
          "currency": "EUR",
          "currencyAmount": 100.0,
          "currencyRate": 1
        },
        "journal": "ACH",
        "account": "60100000",
        "thirdParty": "FRN001",
        "thirdPartySiren": "123456789",
        "thirdPartyLabel": "Fournisseur Exemple",
        "label": "Facture achat mars",
        "reference": "FA-2026-042"
      }
    ]
  }
}

Required fields (each object in `data.lines`)

Field	Type	Description
`date`	string	Entry date (ISO 8601).
`debit`	object	Debit side; must include the four amount fields below.
`credit`	object	Credit side; must include the four amount fields below.
`journal`	string	Journal code.
`account`	string	General ledger account code.
`reference`	string	Line reference.

Each of debit and credit must contain amount, currency, currencyAmount, and currencyRate.

Optional fields (each line)

Field	Type	Notes
`dueDate`	string	Due date (ISO 8601).
`journalLabel`	string	Journal label.
`thirdParty`	string	Third-party identifier. If omitted, treated as an empty string when the line is processed.
`thirdPartySiren`	string	SIREN or equivalent. If omitted, treated as an empty string.
`thirdPartyLabel`	string	Third-party display name. If omitted, treated as an empty string.
`label`	string	Line description.
`documentReference`	string	Invoice / document reference for the line.

For exact OpenAPI types and descriptions, use the public API reference bundled with this documentation.

Minimal line (required fields only)

{
  "data": {
    "lines": [
      {
        "date": "2026-03-09T00:00:00.000Z",
        "debit": {
          "amount": 100.0,
          "currency": "EUR",
          "currencyAmount": 100.0,
          "currencyRate": 1
        },
        "credit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "journal": "ACH",
        "account": "40100000",
        "reference": "FA-2026-042"
      }
    ]
  }
}

Importing accounting entries directly into the accountant's software (e.g., payroll entries) (`POST /entries`)

Use this endpoint when you want to push accounting lines without attaching an invoice file. The request body is application/json (not multipart).

Request fields

Field	Required	Type	Description
`entries`	yes	object (`PreEntriesDto`)	Accounting lines — same structure as the `entries` field in invoice imports.
`userEmail`	no	string (email)	Email of the user performing the import.
`externalReference`	no	string (max 64 chars)	Your reference (e.g., the accounting entry batch reference) — uniqueness is scoped per document type .

The entries object must have the same structure as described in Accounting entries: a root data object containing a lines array.

Response

A successful submission returns 201 Created:

{
  "documentId": "550e8400-e29b-41d4-a716-446655440000"
}

Example

curl -X POST "https://api.oneconnect.shine.co/v1/integrations/{integrationId}/entries" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-oneconnect-api-key: {integrationSecret}" \
  -H "Content-Type: application/json" \
  -d '{
    "userEmail": "user@someCompany.com",
    "externalReference": "BATCH-2026-042",
    "entries": {
      "data": {
        "lines": [
          {
            "date": "2026-03-09T00:00:00.000Z",
            "debit": { "amount": 100, "currency": "EUR", "currencyAmount": 100, "currencyRate": 1 },
            "credit": { "amount": 0, "currency": "EUR", "currencyAmount": 0, "currencyRate": 1 },
            "journal": "OD",
            "account": "41100000",
            "reference": "OD-2026-042"
          },
          {
            "date": "2026-03-09T00:00:00.000Z",
            "debit": { "amount": 0, "currency": "EUR", "currencyAmount": 0, "currencyRate": 1 },
            "credit": { "amount": 100, "currency": "EUR", "currencyAmount": 100, "currencyRate": 1 },
            "journal": "OD",
            "account": "70100000",
            "reference": "OD-2026-042"
          }
        ]
      }
    }
  }'

Replace {integrationId}, {access_token}, and {integrationSecret} with your actual values.

Complete examples

Import a purchase invoice (simple)

curl -X POST "https://api.oneconnect.shine.co/v1/integrations/{integrationId}/purchase-invoices" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-oneconnect-api-key: {integrationSecret}" \
  -F "file=@/path/to/invoice.pdf;type=application/pdf" \
  -F "filename=invoice.pdf" \
  -F "userEmail=user@someCompany.com"

Import a sales invoice with external reference

curl -X POST "https://api.oneconnect.shine.co/v1/integrations/{integrationId}/sales-invoices" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-oneconnect-api-key: {integrationSecret}" \
  -F "file=@/path/to/invoice.pdf;type=application/pdf" \
  -F "filename=invoice.pdf" \
  -F "userEmail=user@someCompany.com" \
  -F "externalReference=INV-2026-042" \
  -F "comment=Monthly billing"

Import a purchase invoice with accounting entries

Example with only required fields on each line (entries is one compact JSON string):

curl -X POST "https://api.oneconnect.shine.co/v1/integrations/{integrationId}/purchase-invoices" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-oneconnect-api-key: {integrationSecret}" \
  -F "file=@/path/to/invoice.pdf;type=application/pdf" \
  -F "filename=invoice.pdf" \
  -F "userEmail=user@someCompany.com" \
  -F "externalReference=FA-2026-042" \
  -F 'entries={"data":{"lines":[{"date":"2026-03-09T00:00:00.000Z","debit":{"amount":100,"currency":"EUR","currencyAmount":100,"currencyRate":1},"credit":{"amount":0,"currency":"EUR","currencyAmount":0,"currencyRate":1},"journal":"ACH","account":"40100000","reference":"FA-2026-042"},{"date":"2026-03-09T00:00:00.000Z","debit":{"amount":0,"currency":"EUR","currencyAmount":0,"currencyRate":1},"credit":{"amount":100,"currency":"EUR","currencyAmount":100,"currencyRate":1},"journal":"ACH","account":"60100000","reference":"FA-2026-042"}]}}'

Add optional properties (thirdParty, thirdPartySiren, thirdPartyLabel, label, dueDate, journalLabel, documentReference, etc.) on each line object as needed; see the JSON examples in Accounting entries.

Replace {integrationId}, {access_token}, and {integrationSecret} with your actual values.

Import response

A successful invoice import (purchase-invoices, sales-invoices) or accounting entries submission (entries) returns 200 OK.

{
  "documentId": "550e8400-e29b-41d4-a716-446655440000"
}

Keep this documentId: it appears in webhooks and serves as reference for support.

Business error codes

All errors follow the RFC 9457 format. Business errors include an errorCode field:

HTTP Code	`errorCode`	Meaning
400	`VALIDATION_ERROR`	Invalid data (file, format, missing fields).
400	`SMB_CLOSED`	The company has been closed on the accounting tool side. The integration is then automatically revoked(*).
400	`SMB_NOTFOUND`	Your company could not be found. The integration is then automatically revoked(*).
400	`CPA_CLOSED`	The accounting firm has been closed on the accounting tool side. The integration is then automatically revoked(*).
409	`DUPLICATE_EXTERNAL_REFERENCE`	`externalReference` already used for this `integrationId` and document type. The response includes the `documentId` and `depositDate` of the existing import.

*: the subsequent calls will fail and return a 401, with SMB Closed, SMB not Found or CPA Closed as revokation reason.

Limits

Limits are applied to ensure platform stability.

Parameter	Value
Max file size	5 MB
Max `entries` JSON size	5 MB

Production URLs

Item	URL
OAuth 2.0 token endpoint	`https://auth.shine.co/oauth2/token`
OneConnect by Shine API base URL	`https://api.oneconnect.shine.co/v1`
JWKS endpoint (webhook verification)	`https://api.oneconnect.shine.co/.well-known/jwks.json`

Authentication​

Key identifiers​

Document ID (documentId)​

External reference (externalReference)​

Invoice import format: multipart/form-data​

Required fields​

Optional fields​

Accounting entries (entries multipart field)​

Full example (data.lines with optional fields)​

Required fields (each object in data.lines)​

Optional fields (each line)​

Minimal line (required fields only)​

Importing accounting entries directly into the accountant's software (e.g., payroll entries) (POST /entries)​

Request fields​

Response​

Example​

Complete examples​

Import a purchase invoice (simple)​

Import a sales invoice with external reference​

Import a purchase invoice with accounting entries​

Import response​

Business error codes​

Limits​

Production URLs​