PAC Integration

This section explains every part of the PAC (electronic invoicing) integration in the Cifras backend.

What is PAC?

A PAC — Proveedor Autorizado de Certificación — is a tax-authority-certified middleman that signs and submits electronic invoices to Panama's DGI (Dirección General de Ingresos). Cifras integrates with Alanube as its PAC.

When a tenant wants to issue a fiscally valid invoice, Cifras:

1. Builds the document payload.
2. Sends it to Alanube.
3. Alanube validates, signs, and forwards it to the DGI.
4. DGI returns an authorization protocol.
5. Cifras stores the resulting CUFE, QR code, and PDF.

Reading order for a new dev

#	Page	Why
1	Overview	Business context and the cast of characters.
2	Architecture	How requests flow through the codebase.
3	Configuration	What env vars to set.
4	Data Model	Where PAC fields live in the database.
5	Document Lifecycle	The status state machine.
6	Invoice Submission	The happy path for an invoice.
7	Invoicing Scenarios	Every business rule that bends the payload (Gobierno+CPBS, retention, exempt items, ad-hoc clients, etc.).
8	Credit Notes	Where credits differ from invoices.
8	Webhooks	How PAC pushes status updates back to us.
9	Polling Fallback	The taskiq polling task.
10	PDF Attachment	The three paths a PDF can land on a document.
11	Voiding & Cancellation	DELETE flows and time limits.
12	RUC Verification	Validating taxpayer IDs.
13	Tenant Onboarding	The 5-step CLI to set up a new tenant.
14	GraphQL API	Mutations and queries available to clients.
15	Alanube API Reference	Every external endpoint we call.
16	Error Handling	Retries, exceptions, dead-letter behavior.
17	Troubleshooting	"My invoice is stuck" runbook.
18	Glossary	CUFE, RUC, DV, CPBS, etc.