Payroll cycles

Read the current revision and evidence-backed state

GET

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}

Returns collecting, preview_ready, approved, finalized, filed, accepted or correction_required. A managed candidate includes the exact job/result-set identity and a result projection with native gross, employee/employer contributions, net before tax, PAS, net payable, employer cost, person wage-type details, warnings and blockers. Missing native amounts stay null; native DSN results are not exposed. Calculation/finalization and documents have separate statuses. filed/accepted are projected from Ops/Filing evidence, never partner declarations.

Read the current revision and evidence-backed state › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · pattern: ^[0-9]{4}-(0[1-9]|1[… · required

Current payroll month or M-1.

Read the current revision and evidence-backed state › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Read the current revision and evidence-backed state › Responses

Current cycle revision

GET/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}

curl https://versohq-main-2cc89fe.zuplo.app/partners/:partnerId/tenants/:tenantId/payroll-cycles/:period \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "result": {
    "candidateId": "candidateId",
    "payrunJobId": 0,
    "resultSetId": 0,
    "outcome": "green",
    "persons": [
      {
        "employeeId": 0,
        "resultSetId": 0,
        "gross": 0,
        "employeeContributions": 0,
        "employerContributions": 0,
        "netDeductions": 0,
        "netBeforeTax": 0,
        "netSocial": 0,
        "pas": 0,
        "netPayable": 0,
        "employerCost": 0,
        "details": [
          {
            "number": 0,
            "name": "name",
            "value": 0
          }
        ]
      }
    ],
    "warnings": [
      {
        "id": "id",
        "label": "label",
        "status": "status",
        "observed": "observed",
        "expected": "expected",
        "detail": "detail"
      }
    ],
    "blockers": [
      {
        "id": "id",
        "label": "label",
        "status": "status",
        "observed": "observed",
        "expected": "expected",
        "detail": "detail"
      }
    ]
  }
}

json

application/json

Create or replay a monthly payroll cycle

PUT

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}

Creates revision 1 of the tenant/period logical resource. Replays are idempotent. Legal filing is not exposed to partners.

Create or replay a monthly payroll cycle › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · pattern: ^[0-9]{4}-(0[1-9]|1[… · required

Current payroll month or M-1.

Create or replay a monthly payroll cycle › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Create or replay a monthly payroll cycle › Responses

Existing cycle returned

No data returned

Get the exact legacy cycle payslip preview read URL

GET

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/payslip

Returns a bounded private URL for the PDF frozen by /preview, with its period, revision, beneficiary, job, result set and checksum. documentStatus is preview before partner approval or approved_preview after approval; this legacy PDF is not a managed final document. When unavailable, 409 includes the cycle state, last preview blockers and nextAction. Read the cycle and prepare /preview after resolving blockers.

Get the exact legacy cycle payslip preview read URL › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · pattern: ^[0-9]{4}-(0[1-9]|1[… · required

Get the exact legacy cycle payslip preview read URL › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get the exact legacy cycle payslip preview read URL › Responses

Exact legacy PDF preview URL and identity; download and verify the checksum

url

string · uri · required

Temporary signed private PDF URL. Fetch without the partner API key; request this endpoint again after expiration.

documentStatus

string · enum · required

preview is unapproved; approved_preview is the same legacy preview after approval. Neither is a managed final document.

Enum values:

preview

approved_preview

period

string · pattern: ^[0-9]{4}-(0[1-9]|1[… · required

revision

integer · min: 1 · required

employeeId

integer · int64 · required

payrunJobId

integer · int64 · required

payslipChecksum

string · pattern: ^[0-9a-f]{64}$ · required

SHA-256 of the exact PDF bytes.

resultSetId

integer · int64 · required

Set monthly payroll variables

PUT

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/variables

Persists an exact write intent before writing the mandate remuneration and planned payment date atomically to PayrollEngine. Ops accepts an exact yyyy-MM-dd calendar value and transports it unchanged; it does not apply a fiscal or social admissibility window. A first legacy write may omit it, but preview then reports date_de_versement_missing; once set it cannot be silently removed. A change after cutoff, approval or filing opens a new revision. An ambiguous downstream outcome blocks blind replay and is exposed for reconciliation. A PayrollEngine refusal is relayed explicitly.

Set monthly payroll variables › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · pattern: ^[0-9]{4}-(0[1-9]|1[… · required

Set monthly payroll variables › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

If-Match

string · required

Set monthly payroll variables › Request Body

remuneration

number · min: 0 · required

Monthly mandate remuneration in euros; 0 is a legitimate payroll month.

dateDeVersement

string · date · pattern: ^[0-9]{4}-(0[1-9]|1[…

Planned calendar payment date, explicitly confirmed for this payroll cycle and transported unchanged to PayrollEngine. Ops does not interpret its fiscal or social admissibility.

Set monthly payroll variables › Responses

Variables persisted or replayed

No data returned

Evaluate preview readiness

POST

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/preview

Legacy readiness check. A cycle with a managed operation must use calculate and poll the exact operation; this route cannot select the latest unrelated native job.

Evaluate preview readiness › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · required

Evaluate preview readiness › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

If-Match

string · required

Evaluate preview readiness › Responses

Readiness evaluated; inspect state and preview.blockers

No data returned

Approve and freeze the preview revision

POST

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/approval

Approve the exact persisted candidate under If-Match, then finalize its native job durably. Returns 202 and Location while finalization proceeds. Legacy approval remains available only for cycles with no managed operation.

Approve and freeze the preview revision › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · required

Approve and freeze the preview revision › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

If-Match

string · required

Approve and freeze the preview revision › Request Body

approvalKey

string · minLength: 1 · maxLength: 128 · required

candidateId

string · minLength: 1

Exact persisted calculation candidate to approve

Approve and freeze the preview revision › Responses

Revision approved or identical replay returned

No data returned

Calculate payroll cycle

POST

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/calculate

Creates a durable calculation operation; 202 does not prove the result exists. Idempotency-Key and If-Match are required.

Calculate payroll cycle › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · required

Calculate payroll cycle › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

If-Match

string · required

Idempotency-Key

string · minLength: 1 · maxLength: 128 · required

Calculate payroll cycle › Responses

Durable operation accepted; poll Location for outcome

No data returned

Get payroll operation

GET

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/operations/{operationId}

Returns the exact persisted status, phase, candidate and reconciliation blocker. GET never sends a payroll command.

Get payroll operation › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · required

operationId

integer · int64 · required

Get payroll operation › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get payroll operation › Responses

Successful response

No data returned

Abandon an exact unapproved legacy Draft

POST

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/drafts/{jobId}/abort

Queues an audited, idempotent Abort of one exact native Draft without an Ops candidate. Poll the returned operation; no recalculation is admitted before confirmation. The adapter is disabled until Ops prerequisites are verified.

Abandon an exact unapproved legacy Draft › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · required

jobId

integer · int64 · required

Abandon an exact unapproved legacy Draft › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

If-Match

string · required

Abandon an exact unapproved legacy Draft › Request Body

requestKey

string · uuid · required

reasonCode

string · enum · required

Enum values:

simulation_discarded

draft_replaced

operator_recovery

Abandon an exact unapproved legacy Draft › Responses

Durable Abort operation accepted; poll Location

No data returned

Abandon payroll candidate

POST

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/abandon

Abandons the exact draft candidate using a durable native transition.

Abandon payroll candidate › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · required

Abandon payroll candidate › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

If-Match

string · required

Abandon payroll candidate › Request Body

candidateId

string · minLength: 1 · required

idempotencyKey

string · minLength: 1 · maxLength: 128 · required

Abandon payroll candidate › Responses

Durable operation accepted; poll Location for outcome

No data returned

Read an exact candidate document

GET

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/revisions/{revision}/candidates/{candidateId}/documents/{variant}

Document identity includes revision, candidate and variant. Final requires a finalized candidate; PDF generation never recalculates payroll. Sandbox documents carry TEST — SANS VALEUR; draft documents also carry BROUILLON — À VALIDER.

Read an exact candidate document › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · required

revision

integer · int32 · min: 1 · required

candidateId

string · uuid · required

variant

string · enum · required

Enum values:

draft

final

Read an exact candidate document › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Read an exact candidate document › Responses

Document state and bounded read URL when ready

No data returned

Generate or retry an exact candidate document

POST

https://versohq-main-2cc89fe.zuplo.app

/partners/{partnerId}/tenants/{tenantId}/payroll-cycles/{period}/revisions/{revision}/candidates/{candidateId}/documents/{variant}

Generate or retry an exact candidate document › path Parameters

partnerId

integer · int32 · required

tenantId

integer · int32 · required

period

string · required

revision

integer · int32 · min: 1 · required

candidateId

string · uuid · required

variant

string · enum · required

Enum values:

draft

final

Generate or retry an exact candidate document › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Generate or retry an exact candidate document › Responses

Document state and bounded read URL when ready

No data returned

DSN filing