Skip to content

Tenant Onboarding

Bringing a new tenant onto PAC is a 5-step process. There's a CLI script, onboard_tenant.py, that walks you through it. This page describes what each step does so you can debug failures.

Prerequisites

You'll need from the customer:

  • Digital certificate — A .p12 (PKCS#12) file issued by an authorized provider, plus its password. This is the cryptographic identity Alanube uses to sign documents on behalf of the tenant.
  • RUC + RUC type (NATURAL or JURIDICO) + DV.
  • Trade name (legal business name, will appear on invoices).
  • Logo URL — public URL to a logo PNG/JPG.
  • At least one office: physical address, coordinates, phone, location code.

Step 1 — Create the company in Alanube

POST /pan/v1/companies

Body includes the certificate (base64-encoded), the password, the RUC, the trade name, and the logo URL.

Response gives you the company_id. Save this; it becomes tenant.pac_company_id.

CLI prompts: cert file path, cert password, RUC type, RUC, DV, trade name, logo URL.

Step 2 — Create the tenant in Cifras

The CLI then calls the admin API to create the tenant row, with pac_company_id set from step 1.

If anything later in the flow fails, you may end up with a tenant in Cifras but an incomplete state in Alanube — fix this manually before retrying, or delete the tenant.

Step 3 — Affiliation type 3 (QR)

GET /pan/v1/company-affiliate?idCompany={company_id}&affiliationType=3

Returns a QR code URL. The customer must:

  1. Scan the QR with the DGI mobile app.
  2. Authorize Cifras-via-Alanube to act on their behalf.

This is the only step that requires customer action outside the CLI. The script will pause until you confirm the customer has done it.

Step 4 — Affiliation type 1 (Final)

GET /pan/v1/company-affiliate?idCompany={company_id}&affiliationType=1

Once the QR has been scanned, this call finalizes the affiliation. Until this returns successfully, the tenant cannot issue documents.

Step 5 — Create the first office

POST /pan/v1/companies/{company_id}/offices

CLI prompts: coordinates, address, telephone, location code, office code (default 0001), office type (main for the first one).

Response gives pac_office_id. The CLI persists this on the corresponding Office row in Cifras.

Adding more offices later

Use the admin GraphQL mutation create_pac_office. Same flow, just no need to redo the company-level steps.

Common failures

Symptom Cause Fix
Step 1: 400 "invalid certificate" Wrong password or expired cert Re-export and re-encrypt.
Step 3: QR never authorized Customer didn't scan or scanned wrong QR Re-run step 3 to get a fresh QR.
Step 4: 400 "affiliation pending" Customer hasn't finished step 3 Wait.
Step 5: 400 on location Wrong DGI region code format See Glossary → location code.

After onboarding

Verify the tenant by issuing a single proforma invoice (no PAC call), then a small DGI invoice. You should see:

  1. POST /invoices returns 200.
  2. legal_status becomes PAC_AUTHORIZED.
  3. Within a minute, webhook arrives and legal_status becomes DGI_AUTHORIZED.
  4. PDF is attached to the invoice.

If any of those don't happen, see Troubleshooting.