Production onboarding

In the partner portal, in the API keys section, request a live key. Production keys are subject to approval (contract + license); once approved, you generate the key once. A sandbox key (efk_pk_test_…) you create immediately. The base URL is the same for both environments; the key prefix decides.

Via POST /v1/agent/organizations, create a child org for the company (IČO, DIČ (10 digits), VAT ID, full address). Idempotent by IČO: if it already exists, the same one is returned. Requires scope org:provision.

curl -X POST https://api.efaktura.sk/v1/agent/organizations \
  -H "X-API-Key: efk_pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name":"Klient s.r.o.", "ico":"55460399", "dic":"2122027985",
        "ic_dph":"SK2122027985",
        "address":{"street":"Hlavná 1","city":"Trenčín","postalCode":"91101","country":"SK"} }'

On the Financial Administration Portal (PFS), the entity (the company or its representative) chooses eFaktúra as its e-invoice delivery service provider (Peppol PDS). The FS then sends eFaktúra the mandate, usually via webhook, which automatically registers the company as Peppol participant 0245:<DIČ>.

If the mandate arrived after pairing (or you want to resend the email), call POST /v1/agent/organizations/{id}/peppol-claim (scope invoice:send, empty body). eFaktúra sends "Confirm receipt of e-invoices…" to the company's FS company_email.

curl -X POST https://api.efaktura.sk/v1/agent/organizations/{org_id}/peppol-claim \
  -H "X-API-Key: efk_pk_live_..."

Response (note: this endpoint returns the status directly, not in an envelope):

// 202: email sent
{ "organization_id": "1ecf…", "status": "pending_email_confirmation" }

// 200: nothing to send
{ "organization_id": "1ecf…", "status": "no_mandate" }      // FS mandate hasn't arrived yet
{ "organization_id": "1ecf…", "status": "no_email" }        // mandate has no company email

// 409: ambiguous assignment (see Troubleshooting)
{ "organization_id": "1ecf…", "status": "collision", "reason": "real_org_exists_for_ico" }

The email contains a link to a public page (no login). After confirming, the receipt of e-invoices is bound to your child org. The company is now live on production Peppol under your partner account.

Track status via GET /v1/agent/organizations/{id}. Done = claim_status: "claimed" and peppol_eligible: true with an assigned participant_id.

curl https://api.efaktura.sk/v1/agent/organizations/{org_id} \
  -H "X-API-Key: efk_pk_live_..."

{
  "organization_id": "1ecf…",
  "ico": "55460399",
  "status": "aktivne",
  "participant_id": "0245:2122027985",
  "peppol_status": "active",
  "claim_status": "claimed",
  "peppol_eligible": true,
  "pending_mandate": false
}

From now on the company receives e-invoices via Peppol, and you can send on its behalf (issuing + send). You read incoming documents via GET /v1/agent/peppol/received and get the peppol.document.received webhook.