Skip to main content

3. Using the API

Authentication​

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

HeaderValueOrigin
x-oneconnect-api-key{integrationSecret}Except exceptions, the header x-oneconnect-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 import type (purchase invoices, sales invoices, and accounting entries each have their own namespace). The same reference can be reused across 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​

Import endpoints use one of two request formats, depending on what you send:

  • Invoice routes (/purchase-invoices, /sales-invoices) expect multipart/form-data and require a file (see Required fields below).
  • Entries route (/entries) expects application/json and takes no file (see Import accounting entries (JSON only) below).

The Required fields (file, filename) below apply to the invoice routes only.

Required fields​

FieldTypeDescription
filebinaryThe invoice file. Formats: PDF, JPEG, PNG, BMP. Max size: 5 MB.
filenamestringDeclared name; must end with .pdf, .jpg, .jpeg, .png, or .bmp (case-insensitive), max 120 characters.

Optional fields​

FieldTypeDescription
userEmailstringEmail 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.
commentstringFree-form note for the accounting firm.
externalReferencestringYour reference (see above).
entriesJSON (string)Accounting entries (see dedicated section below). In multipart/form-data, serialize this field as a JSON string (not a nested multipart object).
organizationJSON (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)​

FieldTypeDescription
datestringEntry date (ISO 8601).
debitobjectDebit side; must include the four amount fields below.
creditobjectCredit side; must include the four amount fields below.
journalstringJournal code.
accountstringGeneral ledger account code.
referencestringLine reference.

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

Optional fields (each line)​

FieldTypeNotes
dueDatestringDue date (ISO 8601).
journalLabelstringJournal label.
thirdPartystringThird-party identifier. If omitted, treated as an empty string when the line is processed.
thirdPartySirenstringSIREN or equivalent. If omitted, treated as an empty string.
thirdPartyLabelstringThird-party display name. If omitted, treated as an empty string.
labelstringLine description.
documentReferencestringInvoice / document reference for the line.
analyticalAxesarrayOptional analytic axes. Each item: axisCode, optional axisLabel, and sections (see below).

When analyticalAxes is present, each axis object must include:

FieldTypeDescription
axisCodestringAnalytic axis code (for example A1). Must be unique on a given line.
axisLabelstringOptional analytic axis label.
sectionsarrayRequired, non-empty. Sections on this axis. Each section includes debit, credit, section, and optional sectionLabel.

Each axis should allocate 100% of the line amount. Axes are independent: they are not a split of the line between axes. On every axis, the section amounts on the same side as the line (debit or credit) should add up to the line's debit.amount or credit.amount. For example, an 8 000 € debit line with SERV and SITE should have SERV sections totalling 8 000 € and SITE sections totalling 8 000 €.

OneConnect by Shine does not reject the file if an axis does not total 100% of the line. A well-formed request can still return success; the accounting software is responsible for checking the allocation.

axisCode must be unique on a given line. If the same code appears more than once, the request is rejected with HTTP 400 (VALIDATION_ERROR). Each axis must include a non-empty sections array.

Worked examples with analytic axes (purchase invoice, sales invoice, and payroll entries) are in Complete examples.

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"
      }
    ]
  }
}

The same data.lines structure is used for the standalone JSON-only entries route (POST /entries) — see the section below.

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​

FieldRequiredTypeDescription
entriesyesobject (PreEntriesDto)Accounting lines — same structure as the entries field in invoice imports.
userEmailnostring (email)Email of the user performing the import.
externalReferencenostring (max 64 chars)Your reference (e.g., the accounting entry batch reference) — uniqueness is scoped per import type.
metadatanoobject, nullableA free-form JSON object of your choice. Stored as-is and returned unchanged in the DocumentStatus webhook for this entry. Must be a JSON object (not an array/string/number/boolean), max 16KB serialized.

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

Response​

200 OK confirms that OneConnect by Shine has received and recorded the batch. Processing into the accounting tool happens asynchronously — the actual integration result is delivered via webhook (using the documentId as the correlation key).

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

Example​

A full payroll payload with analytic axes is in Import accounting entries (JSON only).

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

Complete examples​

The following payloads match the examples in the public OpenAPI / Swagger UI for each import route. When a line includes several analytic axes, each axis allocates 100% of that line amount (the section amounts on one axis must add up to the line total; they are not shared across axes).

Import a purchase invoice (file only)​

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/FA-2026-073.pdf;type=application/pdf" \
  -F "filename=FA-2026-073.pdf" \
  -F "userEmail=marie.dupont@cabinet-exemple.fr"

Import a purchase invoice with accounting entries (POST /purchase-invoices)​

Multipart: attach the PDF in file and send the JSON below as the entries form field (UTF-8 JSON string). Expense 60100000 and deductible VAT 44566000 are debited; supplier 40100000 is credited. Analytic axes sit on the expense line: SERV (4 800 + 3 200) and SITE (5 000 + 3 000) each total the 8 000 € line amount.

filename: FA-2026-073.pdf · externalReference: FA-2026-073 · comment: Merchandise purchase — March 2026

{
  "data": {
    "lines": [
      {
        "date": "2026-03-20T00:00:00.000Z",
        "debit": {
          "amount": 8000,
          "currency": "EUR",
          "currencyAmount": 8000,
          "currencyRate": 1
        },
        "credit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "journal": "ACH",
        "account": "60100000",
        "thirdParty": "",
        "thirdPartyLabel": "",
        "label": "Achats de marchandises mars 2026",
        "reference": "FA-2026-073",
        "analyticalAxes": [
          {
            "axisCode": "SERV",
            "axisLabel": "Service",
            "sections": [
              {
                "debit": {
                  "amount": 4800,
                  "currency": "EUR",
                  "currencyAmount": 4800,
                  "currencyRate": 1
                },
                "credit": {
                  "amount": 0,
                  "currency": "EUR",
                  "currencyAmount": 0,
                  "currencyRate": 1
                },
                "section": "COM",
                "sectionLabel": "Commercial"
              },
              {
                "debit": {
                  "amount": 3200,
                  "currency": "EUR",
                  "currencyAmount": 3200,
                  "currencyRate": 1
                },
                "credit": {
                  "amount": 0,
                  "currency": "EUR",
                  "currencyAmount": 0,
                  "currencyRate": 1
                },
                "section": "PROD",
                "sectionLabel": "Production"
              }
            ]
          },
          {
            "axisCode": "SITE",
            "axisLabel": "Site",
            "sections": [
              {
                "debit": {
                  "amount": 5000,
                  "currency": "EUR",
                  "currencyAmount": 5000,
                  "currencyRate": 1
                },
                "credit": {
                  "amount": 0,
                  "currency": "EUR",
                  "currencyAmount": 0,
                  "currencyRate": 1
                },
                "section": "PARIS",
                "sectionLabel": "Paris"
              },
              {
                "debit": {
                  "amount": 3000,
                  "currency": "EUR",
                  "currencyAmount": 3000,
                  "currencyRate": 1
                },
                "credit": {
                  "amount": 0,
                  "currency": "EUR",
                  "currencyAmount": 0,
                  "currencyRate": 1
                },
                "section": "LYON",
                "sectionLabel": "Lyon"
              }
            ]
          }
        ]
      },
      {
        "date": "2026-03-20T00:00:00.000Z",
        "debit": {
          "amount": 1600,
          "currency": "EUR",
          "currencyAmount": 1600,
          "currencyRate": 1
        },
        "credit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "journal": "ACH",
        "account": "44566000",
        "thirdParty": "",
        "thirdPartyLabel": "",
        "label": "TVA déductible mars 2026",
        "reference": "FA-2026-073",
        "analyticalAxes": []
      },
      {
        "date": "2026-03-20T00:00:00.000Z",
        "debit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "credit": {
          "amount": 9600,
          "currency": "EUR",
          "currencyAmount": 9600,
          "currencyRate": 1
        },
        "journal": "ACH",
        "account": "40100000",
        "thirdParty": "FRN001",
        "thirdPartyLabel": "Fournisseur Exemple",
        "label": "Facture achat mars 2026",
        "reference": "FA-2026-073",
        "analyticalAxes": []
      }
    ]
  }
}
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/FA-2026-073.pdf;type=application/pdf" \
  -F "filename=FA-2026-073.pdf" \
  -F "userEmail=marie.dupont@cabinet-exemple.fr" \
  -F "externalReference=FA-2026-073" \
  -F "comment=Merchandise purchase — March 2026" \
  -F "entries=@entries-purchase.json;type=application/json"

Import a sales invoice with accounting entries (POST /sales-invoices)​

Customer 41100000 is debited; services 70600000 and collected VAT 44571000 are credited. Analytic axes sit on the services line: SERV (6 000 + 4 000) and SITE (7 000 + 3 000) each total the 10 000 € credit.

filename: FV-2026-118.pdf · externalReference: FV-2026-118 · comment: Sales invoice — March 2026

{
  "data": {
    "lines": [
      {
        "date": "2026-03-15T00:00:00.000Z",
        "debit": {
          "amount": 12000,
          "currency": "EUR",
          "currencyAmount": 12000,
          "currencyRate": 1
        },
        "credit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "journal": "VTE",
        "account": "41100000",
        "thirdParty": "CLI045",
        "thirdPartyLabel": "Client Exemple SAS",
        "label": "Facture vente mars 2026",
        "reference": "FV-2026-118",
        "analyticalAxes": []
      },
      {
        "date": "2026-03-15T00:00:00.000Z",
        "debit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "credit": {
          "amount": 10000,
          "currency": "EUR",
          "currencyAmount": 10000,
          "currencyRate": 1
        },
        "journal": "VTE",
        "account": "70600000",
        "thirdParty": "",
        "thirdPartyLabel": "",
        "label": "Prestations de services mars 2026",
        "reference": "FV-2026-118",
        "analyticalAxes": [
          {
            "axisCode": "SERV",
            "axisLabel": "Service",
            "sections": [
              {
                "debit": {
                  "amount": 0,
                  "currency": "EUR",
                  "currencyAmount": 0,
                  "currencyRate": 1
                },
                "credit": {
                  "amount": 6000,
                  "currency": "EUR",
                  "currencyAmount": 6000,
                  "currencyRate": 1
                },
                "section": "COM",
                "sectionLabel": "Commercial"
              },
              {
                "debit": {
                  "amount": 0,
                  "currency": "EUR",
                  "currencyAmount": 0,
                  "currencyRate": 1
                },
                "credit": {
                  "amount": 4000,
                  "currency": "EUR",
                  "currencyAmount": 4000,
                  "currencyRate": 1
                },
                "section": "PROD",
                "sectionLabel": "Production"
              }
            ]
          },
          {
            "axisCode": "SITE",
            "axisLabel": "Site",
            "sections": [
              {
                "debit": {
                  "amount": 0,
                  "currency": "EUR",
                  "currencyAmount": 0,
                  "currencyRate": 1
                },
                "credit": {
                  "amount": 7000,
                  "currency": "EUR",
                  "currencyAmount": 7000,
                  "currencyRate": 1
                },
                "section": "PARIS",
                "sectionLabel": "Paris"
              },
              {
                "debit": {
                  "amount": 0,
                  "currency": "EUR",
                  "currencyAmount": 0,
                  "currencyRate": 1
                },
                "credit": {
                  "amount": 3000,
                  "currency": "EUR",
                  "currencyAmount": 3000,
                  "currencyRate": 1
                },
                "section": "LYON",
                "sectionLabel": "Lyon"
              }
            ]
          }
        ]
      },
      {
        "date": "2026-03-15T00:00:00.000Z",
        "debit": {
          "amount": 0,
          "currency": "EUR",
          "currencyAmount": 0,
          "currencyRate": 1
        },
        "credit": {
          "amount": 2000,
          "currency": "EUR",
          "currencyAmount": 2000,
          "currencyRate": 1
        },
        "journal": "VTE",
        "account": "44571000",
        "thirdParty": "",
        "thirdPartyLabel": "",
        "label": "TVA collectée mars 2026",
        "reference": "FV-2026-118",
        "analyticalAxes": []
      }
    ]
  }
}
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/FV-2026-118.pdf;type=application/pdf" \
  -F "filename=FV-2026-118.pdf" \
  -F "userEmail=marie.dupont@cabinet-exemple.fr" \
  -F "externalReference=FV-2026-118" \
  -F "comment=Sales invoice — March 2026" \
  -F "entries=@entries-sales.json;type=application/json"

Import accounting entries (JSON only)​

POST /v1/integrations/{integrationId}/entries — no invoice file. Payroll batch PAIE-2026-03: gross wages 64110000 and employer charges 64500000 (analytic axes SERV/SITE, each axis totalling 100% of its line), then credits to net pay 42100000, URSSAF 43100000, complementary pension 43720000, mutuelle 43730000, unemployment 43740000, and payroll tax 44420000.

{
  "userEmail": "marie.dupont@cabinet-exemple.fr",
  "externalReference": "PAIE-2026-03",
  "entries": {
    "data": {
      "lines": [
        {
          "date": "2026-03-31T00:00:00.000Z",
          "debit": {
            "amount": 45000,
            "currency": "EUR",
            "currencyAmount": 45000,
            "currencyRate": 1
          },
          "credit": {
            "amount": 0,
            "currency": "EUR",
            "currencyAmount": 0,
            "currencyRate": 1
          },
          "journal": "OD",
          "account": "64110000",
          "thirdParty": "",
          "thirdPartyLabel": "",
          "label": "Salaires bruts mars 2026",
          "reference": "PAIE-2026-03",
          "analyticalAxes": [
            {
              "axisCode": "SERV",
              "axisLabel": "Service",
              "sections": [
                {
                  "debit": {
                    "amount": 20000,
                    "currency": "EUR",
                    "currencyAmount": 20000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "COM",
                  "sectionLabel": "Commercial"
                },
                {
                  "debit": {
                    "amount": 15000,
                    "currency": "EUR",
                    "currencyAmount": 15000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "PROD",
                  "sectionLabel": "Production"
                },
                {
                  "debit": {
                    "amount": 10000,
                    "currency": "EUR",
                    "currencyAmount": 10000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "ADM",
                  "sectionLabel": "Administratif"
                }
              ]
            },
            {
              "axisCode": "SITE",
              "axisLabel": "Site",
              "sections": [
                {
                  "debit": {
                    "amount": 30000,
                    "currency": "EUR",
                    "currencyAmount": 30000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "PARIS",
                  "sectionLabel": "Paris"
                },
                {
                  "debit": {
                    "amount": 15000,
                    "currency": "EUR",
                    "currencyAmount": 15000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "LYON",
                  "sectionLabel": "Lyon"
                }
              ]
            }
          ]
        },
        {
          "date": "2026-03-31T00:00:00.000Z",
          "debit": {
            "amount": 18000,
            "currency": "EUR",
            "currencyAmount": 18000,
            "currencyRate": 1
          },
          "credit": {
            "amount": 0,
            "currency": "EUR",
            "currencyAmount": 0,
            "currencyRate": 1
          },
          "journal": "OD",
          "account": "64500000",
          "thirdParty": "",
          "thirdPartyLabel": "",
          "label": "Charges patronales sur salaires mars 2026",
          "reference": "PAIE-2026-03",
          "analyticalAxes": [
            {
              "axisCode": "SERV",
              "axisLabel": "Service",
              "sections": [
                {
                  "debit": {
                    "amount": 8000,
                    "currency": "EUR",
                    "currencyAmount": 8000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "COM",
                  "sectionLabel": "Commercial"
                },
                {
                  "debit": {
                    "amount": 6000,
                    "currency": "EUR",
                    "currencyAmount": 6000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "PROD",
                  "sectionLabel": "Production"
                },
                {
                  "debit": {
                    "amount": 4000,
                    "currency": "EUR",
                    "currencyAmount": 4000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "ADM",
                  "sectionLabel": "Administratif"
                }
              ]
            },
            {
              "axisCode": "SITE",
              "axisLabel": "Site",
              "sections": [
                {
                  "debit": {
                    "amount": 12000,
                    "currency": "EUR",
                    "currencyAmount": 12000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "PARIS",
                  "sectionLabel": "Paris"
                },
                {
                  "debit": {
                    "amount": 6000,
                    "currency": "EUR",
                    "currencyAmount": 6000,
                    "currencyRate": 1
                  },
                  "credit": {
                    "amount": 0,
                    "currency": "EUR",
                    "currencyAmount": 0,
                    "currencyRate": 1
                  },
                  "section": "LYON",
                  "sectionLabel": "Lyon"
                }
              ]
            }
          ]
        },
        {
          "date": "2026-03-31T00:00:00.000Z",
          "debit": {
            "amount": 0,
            "currency": "EUR",
            "currencyAmount": 0,
            "currencyRate": 1
          },
          "credit": {
            "amount": 32000,
            "currency": "EUR",
            "currencyAmount": 32000,
            "currencyRate": 1
          },
          "journal": "OD",
          "account": "42100000",
          "thirdParty": "PERS001",
          "thirdPartyLabel": "Personnel - Rémunérations dues",
          "label": "Net à payer mars 2026",
          "reference": "PAIE-2026-03",
          "analyticalAxes": []
        },
        {
          "date": "2026-03-31T00:00:00.000Z",
          "debit": {
            "amount": 0,
            "currency": "EUR",
            "currencyAmount": 0,
            "currencyRate": 1
          },
          "credit": {
            "amount": 20000,
            "currency": "EUR",
            "currencyAmount": 20000,
            "currencyRate": 1
          },
          "journal": "OD",
          "account": "43100000",
          "thirdParty": "URSSAF01",
          "thirdPartyLabel": "URSSAF",
          "label": "Cotisations URSSAF (part salariale et patronale) mars 2026",
          "reference": "PAIE-2026-03",
          "analyticalAxes": []
        },
        {
          "date": "2026-03-31T00:00:00.000Z",
          "debit": {
            "amount": 0,
            "currency": "EUR",
            "currencyAmount": 0,
            "currencyRate": 1
          },
          "credit": {
            "amount": 4500,
            "currency": "EUR",
            "currencyAmount": 4500,
            "currencyRate": 1
          },
          "journal": "OD",
          "account": "43720000",
          "thirdParty": "AGIRC01",
          "thirdPartyLabel": "AGIRC-ARRCO - Retraite complémentaire",
          "label": "Cotisations retraite complémentaire mars 2026",
          "reference": "PAIE-2026-03",
          "analyticalAxes": []
        },
        {
          "date": "2026-03-31T00:00:00.000Z",
          "debit": {
            "amount": 0,
            "currency": "EUR",
            "currencyAmount": 0,
            "currencyRate": 1
          },
          "credit": {
            "amount": 1000,
            "currency": "EUR",
            "currencyAmount": 1000,
            "currencyRate": 1
          },
          "journal": "OD",
          "account": "43730000",
          "thirdParty": "MUT001",
          "thirdPartyLabel": "Mutuelle Entreprise",
          "label": "Cotisations mutuelle mars 2026",
          "reference": "PAIE-2026-03",
          "analyticalAxes": []
        },
        {
          "date": "2026-03-31T00:00:00.000Z",
          "debit": {
            "amount": 0,
            "currency": "EUR",
            "currencyAmount": 0,
            "currencyRate": 1
          },
          "credit": {
            "amount": 3000,
            "currency": "EUR",
            "currencyAmount": 3000,
            "currencyRate": 1
          },
          "journal": "OD",
          "account": "43740000",
          "thirdParty": "PEMP01",
          "thirdPartyLabel": "Pôle Emploi - Assurance chômage",
          "label": "Cotisations chômage mars 2026",
          "reference": "PAIE-2026-03",
          "analyticalAxes": []
        },
        {
          "date": "2026-03-31T00:00:00.000Z",
          "debit": {
            "amount": 0,
            "currency": "EUR",
            "currencyAmount": 0,
            "currencyRate": 1
          },
          "credit": {
            "amount": 2500,
            "currency": "EUR",
            "currencyAmount": 2500,
            "currencyRate": 1
          },
          "journal": "OD",
          "account": "44420000",
          "thirdParty": "ETAT01",
          "thirdPartyLabel": "État - Taxe sur les salaires",
          "label": "Taxe sur les salaires mars 2026",
          "reference": "PAIE-2026-03",
          "analyticalAxes": []
        }
      ]
    }
  }
}
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 @entries-payroll.json

Replace {integrationId}, {access_token}, and {integrationSecret} with your actual values. These examples are also available in the API (Swagger) tab for each route.

Import response​

All import routes respond synchronously with a documentId — processing into the accounting tool is asynchronous. The actual integration result (success or failure) is delivered via webhook.

RouteHTTP codeMeaning
purchase-invoices, sales-invoices200 OKBatch received and recorded.
entries200 OKBatch received and recorded.
{
  "documentId": "550e8400-e29b-41d4-a716-446655440000"
}

Store this documentId: it is included in all status webhooks and is the reference for support requests.

Business error codes​

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

HTTP CodeerrorCodeMeaning
400VALIDATION_ERRORInvalid data (file, format, missing fields).
400SMB_CLOSEDThe company has been closed on the accounting tool side. The integration is then automatically revoked(*).
400SMB_NOTFOUNDYour company could not be found. The integration is then automatically revoked(*).
400CPA_CLOSEDThe accounting firm has been closed on the accounting tool side. The integration is then automatically revoked(*).
409DUPLICATE_EXTERNAL_REFERENCEexternalReference already used for this integrationId and import 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.

entries route — validation details: VALIDATION_ERROR (400) is returned when data.lines is empty or when a line is missing a required field. Entries are not required to balance; there is no debit/credit equality check.

Limits​

Limits are applied to ensure platform stability.

ParameterValue
Max file size5 MB
Max entries JSON size5 MB

Production URLs​

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