Alanube API Reference¶

This is a quick reference for every Alanube endpoint we call. See app/wrappers/pac/pac_service.py and app/admin/services/admin_pac_service.py for the actual call sites.

Base URL is settings.pac_base_url, typically https://api.alanube.co. All requests carry:

Authorization: Bearer {pac_api_key}
Accept: application/json

Most operations also need ?idCompany={pac_company_id} as a query parameter.

Documents¶

Create invoice¶

POST /pan/v1/invoices?idCompany={pac_company_id}
Content-Type: application/json

<PacInvoice JSON>

Returns: { message, document: { id, legalStatus, cufe, ... } }

Called by: PacService.generate_invoice

Create credit note¶

POST /pan/v1/credit-notes?idCompany={pac_company_id}
Content-Type: application/json

<PacCreditNote JSON>

Called by: PacService.generate_credit_note

Get document (with PDF URL)¶

GET /pan/v1/invoices/{document_id}?idCompany={pac_company_id}&documents=pdf
GET /pan/v1/credit-notes/{document_id}?idCompany={pac_company_id}&documents=pdf

Returns: { document: { id, legalStatus, cufe, pdf, xml, qr, authorizationProtocol, ... } }

pdf is a signed URL valid for a short window. Download it immediately.

Called by: PacService.get_invoice, PacService.get_credit_note, PacWebhookService._get_pdf_url_from_pac, PacPdfAttachmentService._get_pdf_url_from_pac, pac_status_poll_task.

Void / cancel document¶

DELETE /pan/v1/invoices/{document_id}?idCompany={pac_company_id}
DELETE /pan/v1/credit-notes/{document_id}?idCompany={pac_company_id}
Content-Type: application/json

{ "reason": "..." }

Reason: 15–1000 characters. See Voiding.

Notify webhook¶

POST /pan/v1/documents/notify-webhook?idCompany={pac_company_id}
Content-Type: application/json

{
  "documentId": "...",
  "webhookUrl": "...",
  "userId": "...",
  "webhookSecret": "..."
}

Asks Alanube to (re-)send a webhook for a specific document. Useful for forcing PDF retrieval out of band.

Notify email¶

POST /pan/v1/documents/notify-email?idCompany={pac_company_id}
Content-Type: application/json

{
  "documentId": "...",
  "mail": "...",
  "message": "...",
  "documentType": "invoice|credit-note"
}

Sends the document PDF to an email address.

Verification¶

Check digit (RUC verification)¶

GET /pan/v1/check-digit?ruc={ruc}&type={NATURAL|JURIDICO}

Returns: { checkDigit, receiver, type }

See RUC Verification.

Catalog¶

Goods and services (CPBS)¶

GET /pan/v1/goods-and-services?idCompany={pac_company_id}

Returns: A list of { code, description, unit }. Used when invoicing government entities. Cached on our side for 24 hours.

Onboarding¶

Create company¶

POST /pan/v1/companies
Content-Type: application/json

{
  "ruc": "...",
  "rucType": "NATURAL|JURIDICO",
  "checkDigit": "...",
  "tradeName": "...",
  "certificate": "<base64-encoded p12>",
  "certificatePassword": "...",
  "logoUrl": "..."
}

Returns: { id } — store this as tenant.pac_company_id.

Affiliation¶

GET /pan/v1/company-affiliate?idCompany={pac_company_id}&affiliationType={1|3}

affiliationType=3 returns a QR code for customer to scan.
affiliationType=1 finalizes affiliation after the QR has been scanned.

Create office¶

POST /pan/v1/companies/{company_id}/offices
Content-Type: application/json

{
  "code": "0001",
  "type": "main|associated",
  "address": "...",
  "telephone": "...",
  "coordinates": "+9.0017832,-79.5275519",
  "location": "8-8-11"
}

Returns: Office details including the pac_office_id.

Reports¶

Documents report¶

GET /pan/v1/reports/documents?idCompany={pac_company_id}&from={date}&to={date}&docType={...}&legalStatus={...}&groupBy={...}

Returns counts and totals of documents in a window. Used for the admin dashboard.

Documents report — all companies¶

GET /pan/v1/reports/documents/all-companies?from={date}&to={date}&legalStatus={...}

Same shape, across all companies the API key has access to. Used for billing reconciliation across tenants.

Retry policy¶

All calls in PacService are wrapped with tenacity:

@retry(
    stop=stop_after_attempt(2),
    wait=wait_exponential(multiplier=1, min=2, max=10),
    retry=retry_if_exception_type(aiohttp.ClientResponseError),
)

That means two total attempts, exponential backoff between them, only retrying on ClientResponseError. Connection errors are also retried via aiohttp.ClientError in RucVerificationService.

A 4xx response is not retried — it's a logical failure, not a transient one.