Endpoints

Document endpoints require Authorization: Bearer <api-key> and X-Issuer-Id: <issuer-id>. Tenant settings, issuer management, and key management require only Authorization: Bearer <api-key>. Registration and email verification are public.

Registration (public)

Method	Path	Description
POST	/v1/register	Self-service: create tenant + issuer + sandbox API key. New accounts only — if the email already exists, rejects with 409 CONFLICT (use /v1/recover instead).
POST	/v1/recover	Recover access to an existing account with the same P12 certificate — revokes and reissues the current environment's key only if the certificate matches the one on file
GET	/v1/verify-email/check	Check whether a verification token is valid, without consuming it — safe for email link-scanners to prefetch
POST	/v1/verify-email	Confirm verification with the token — activates the tenant; call only on explicit user action
GET	/v1/verify-email	Legacy combined check-and-consume endpoint, kept for backward compatibility
POST	/v1/resend-verification	Resend verification email (regenerates token)

Agreements (public)

Method	Path	Description
GET	/v1/agreements	List current published version of each document type (TERMS, PRIVACY, DPA) — read version from here and pass it as termsVersion when accepting via POST /v1/tenants/agreements
GET	/v1/agreements/:type	Fetch the current document rendered as HTML — embed in a modal or page in your registration UI

Tiers (public)

Method	Path	Description
GET	/v1/tiers	Full subscription tier catalog — quota, monthly/yearly price, overage rate, document types, limits

Payments (authenticated)

Method	Path	Description
PATCH	/v1/payments/:id/proof	Upload proof of an SPI bank transfer for a pending subscription payment — up to 5 files per request, nothing already uploaded is ever overwritten. A REJECTED payment can be re-submitted; only VERIFIED blocks further uploads.
GET	/v1/payments/:id/proofs	List every active proof file uploaded for a payment
GET	/v1/payments/:id/proofs/:proofId	Download one specific proof file
DELETE	/v1/payments/:id/proofs/:proofId	Soft-delete a proof file from your own view (your provider can still see it)

Subscriptions (authenticated)

Method	Path	Description
POST	/v1/subscriptions	Start a paid subscription for the authenticated tenant — works while still in sandbox or after promotion, requires a verified email
GET	/v1/subscriptions/me	Full subscription/payment history, newest first, with rejection_reason_code when applicable — payment reviews and renewals fire notifications too, but activation itself doesn't, so this is still how a tenant checks status
POST	/v1/subscriptions/change-tier	Upgrade (immediate, prorated payment) or downgrade (scheduled, no payment) an existing ACTIVE subscription's tier — use DELETE below to cancel entirely
DELETE	/v1/subscriptions	Schedule a cancellation at period end — drops the tenant to FREE with no refund when current_period_end passes

Tenants (authenticated)

Method	Path	Description
GET	/v1/tenants/me	Resolve the tenant (id, email, tier, status, quota, environment, agreement acceptance) for the authenticated API key
PATCH	/v1/tenants/language	Update the preferred language for outgoing emails
POST	/v1/tenants/promote	Promote the tenant to production — revokes all sandbox keys and creates matching production keys
GET	/v1/tenants/agreements	Check whether any agreements need acceptance — returns which types are outdated. Lazily generates PENDING instances for any new template versions; third-party integrators should poll this periodically
POST	/v1/tenants/agreements	Accept all PENDING agreements — required before promoting to production
GET	/v1/tenants/agreements/history	List all personalized agreement instances for the tenant, with status and acceptance timestamps
GET	/v1/tenants/agreements/:type	Render the tenant's personalized document as HTML — includes their business name/RUC and the dates as of when the account was created
GET	/v1/tenants/events	Full tenant-level audit trail (verification, subscription, payment, tier/billing-interval change history), chronological
POST	/v1/tenants/retry-failed-documents	Recovers every stuck document for the tenant (failed send/authorize after exhausting automatic retries) — covers all issuers, no X-Issuer-Id needed (Retry All Failed Documents)

Issuers (authenticated)

Method	Path	Description
GET	/v1/issuers	List all active issuers (branches / issue points) for the tenant
POST	/v1/issuers	Create a new branch or issue point — inherits cert from an existing issuer of the tenant. Does NOT mint a new API key.
GET	/v1/issuers/:id	Get a single issuer's profile (name, RUC, cert expiry)
PATCH	/v1/issuers/:id	Edit tradeName and/or branchAddress
DELETE	/v1/issuers/:id	Soft-delete an issuer (blocked if it's the last one or has issued documents)
PATCH	/v1/issuers/:id/activate	Reactivate a soft-deleted issuer (re-checks plan branch/issue-point limits)
PATCH	/v1/issuers/:id/logo	Upload or replace the issuer logo shown in RIDE PDFs (PNG/JPEG/GIF, max 500 KB)
PATCH	/v1/issuers/:id/certificate	Renew the issuer's P12 certificate (private key + cert) — e.g. when it has expired
GET	/v1/issuers/:id/document-types	List active document types for the issuer
POST	/v1/issuers/:id/document-types	Enable a document type for the issuer
DELETE	/v1/issuers/:id/document-types/:code	Disable a document type for the issuer
GET	/v1/issuers/:id/sequentials	View current and next sequential numbers per document type, by environment
PATCH	/v1/issuers/:id/sequentials/:documentType	Manually set the next sequential number for one document type/environment

API keys (authenticated)

Method	Path	Description
GET	/v1/keys	List all active keys for the tenant (label, environment, created_at)
POST	/v1/keys	Mint a new named key (label, optional environment)
DELETE	/v1/keys/:id	Revoke an API key. Cannot revoke the key used for the current request.

Documents

Every document endpoint requires both Authorization: Bearer <key> and X-Issuer-Id: <issuer-id>.

Method	Path	Description
GET	/v1/documents	List documents with filtering and pagination
GET	/v1/documents/stats	Per-type document stats for the current month + needs-attention count
POST	/v1/documents	Create and sign a document — invoice (Create Invoice) or credit note (Create Credit Note), selected by documentType
GET	/v1/documents/:accessKey	Get a document by access key
POST	/v1/documents/:accessKey/send	Queue submission to SRI (Send to SRI — returns 202, async)
POST	/v1/documents/:accessKey/send/retry	Recovers a stuck document after its automatic send/authorize retries are exhausted (Retry Send/Authorize — returns 202, async)
GET	/v1/documents/:accessKey/authorize	Queue an SRI authorization check (Check Authorization — returns 202, async)
POST	/v1/documents/:accessKey/rebuild	Rebuild and re-sign a rejected document
GET	/v1/documents/:accessKey/ride	Download RIDE PDF
GET	/v1/documents/:accessKey/xml	Download signed XML
GET	/v1/documents/:accessKey/events	Get audit event history
GET	/v1/documents/:accessKey/sri-responses	Raw SRI reception/authorization call outcomes (status + messages) for this document
GET	/v1/documents/:accessKey/credit-notes	Sum of AUTHORIZED credit notes issued against this document + remaining balance
POST	/v1/documents/email-retry	Retry all failed/pending emails (batch)
POST	/v1/documents/:accessKey/email-retry	Retry email for a single document

Notifications (authenticated)

Tenant-level alerts for document events and certificate status. Supply X-Issuer-Id to filter to a specific issuer; omit to receive notifications across all your issuers. Use ?sinceId=<id> to efficiently poll only new notifications since your last request.

Method	Path	Description
GET	/v1/notifications	List active notifications (read and unread). Optional ?sinceId=<id> for catch-up polling.
POST	/v1/notifications/:id/read	Mark a notification as read
GET	/v1/notifications/preferences	Get notification type preferences for the tenant
PATCH	/v1/notifications/preferences	Enable or disable notification types

Webhooks (authenticated)

Register HTTPS callback URLs to receive event notifications in near-real time.

Method	Path	Description
POST	/v1/webhooks	Register a new webhook endpoint (secret shown once)
GET	/v1/webhooks	List active webhook endpoints (secrets excluded)
PATCH	/v1/webhooks/:id	Update URL, event subscriptions, or active flag
DELETE	/v1/webhooks/:id	Deregister an endpoint (soft-delete)

Monitoring

Method	Path	Auth	Description
GET	/health	None	DB connectivity check for liveness probes