Sign in
SII Key

Create an SII key

Stores a new SII credential for the caller. Cardda encrypts password and certificate_password at rest; this is the only entry point that accepts them in clear text. On creation Cardda runs a synchronous company sync against the SII — on success the key flips to approved and its managed companies are resolved; if the SII rejects the credentials the key ends up declined.

Company users must set user_id to their own Firebase uid, otherwise the request is rejected with 401.

post/v1/sii/keys

Parameters

#/paths/~1v1~1sii~1keys/get/parameters/0 — unresolved $ref

Request body

rutstring required

Tax id (RUT) the SII certificate belongs to. Digits plus verifier digit, no dots (e.g. 761234567 or 12345678K). Must be unique across all SII keys; a duplicate is rejected with 422.

passwordstring required

SII portal password for the RUT. Stored encrypted at rest and never returned by any read endpoint.

certificate_passwordstring

Password of the digital certificate (.pfx/.p12) used to sign electronic documents. Optional at creation, but required before the key can issue (can_issue?). Stored encrypted; never returned by read endpoints.

user_idstring required

Firebase user id that owns the credential. Required. Create authorization runs before the record is saved and only passes when user_id matches the caller (or the caller is Cardda staff). A company user who omits user_id (or sets it to another user) is therefore rejected with 401 before any validation runs. For a Cardda staff caller, authorization passes and a missing user_id then fails the mandatory user association with { "message": "Validation failed: User must exist" } (422).

Example request

{
  "rut": "761234567",
  "password": "s3cr3t-clave-sii",
  "certificate_password": "cert-pass",
  "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2"
}

Response

The created SII key. status is approved if the synchronous company sync succeeded, otherwise pending/declined.

idstring uuid required

UUID of the SII key.

rutstring required

Tax id (RUT) the certificate belongs to, stored as bare digits plus the verifier digit (e.g. 761234567 or 12345678K). Unique across all SII keys.

user_idstring nullable

Firebase user id of the person who provided the credential.

status'approved' | 'pending' | 'canceled' | 'declined' required

Lifecycle status of the credential.

ValueMeaning
pendingJust created; Cardda has not yet validated it against the SII.
approvedValidated; the key can sync companies and invoices.
declinedThe SII rejected the credentials (auth/wrong-credentials).
canceledThe credential was disabled.
issuer_phoneinteger nullable

Phone number registered for the issuer, when captured.

last_synced_atstring date-time nullable

Timestamp of the last successful invoice/company sync.

can_issueboolean

Whether the key can issue electronic documents — true when status is approved and a certificate password is present. Note: this field is serialized with a trailing question mark in the JSON response (can_issue?).

company_idsstring[]

UUIDs of the companies this key manages (resolved through the SII managers join). Present on the list and detail responses; omitted from the update response.

created_atstring date-time

When the key was created in Cardda.

updated_atstring date-time

When the key was last updated.

Changes