Alegra – Gotchas

Alegra exposes no IBAN, BIC/SWIFT, routing number, currency or balance, so those fields are empty. On create, Alegra requires an opening balance — the connector sets it from the unified balance (or 0) at today's date.

Bill credit notes are Alegra debit notes ("nota débito de proveedor") — the accounts-payable document that reduces the balance owed to a supplier, the mirror of the AR credit-notes. status is derived from the applied amount: posted while unapplied, partially_paid when partially applied, and paid once fully applied; there is no draft or void state. allocations reference the supplier bills the note is applied to. On update, supplying line_items replaces the note's lines. Line discounts are percentage-based (line_items[].discount_percentage); the absolute discount_amount is not supported. currency is always returned as MXN (the debit note carries no per-record currency).

A bill payment must be applied to at least one bill — Alegra rejects an unapplied payment.

Each bill line is costed against either a catalog item (line_items[].type: expense_item, which sets line.item) or an expense ledger account (expense_account, which sets line.ledger_account); a single bill may mix both. See the Alegra usage guide for details.

allocations is not populated — Alegra exposes only the aggregate applied amount, not which invoices a credit note offset. A stamped credit note is immutable; update and delete work only while it is unstamped (open).

The Mexican SAT product key (productKey) has no unified field — set it on create via pass_through and read it back via the Proxy. On create/update only name, description, code, unit_price and type are written; inventory levels, accounts and taxes are managed in Alegra.

Invoices are created unstamped (as a draft), so no CFDI folio is consumed. To stamp (timbrar), send pass_through with stamp.generateStamp: true plus the SAT fields (paymentType, cfdiUse, regimeClient); each line's Alegra item must have a SAT productKey. Update and delete work only while the invoice is a draft — a stamped invoice is immutable (void it in Alegra). The CFDI itself (UUID, seals) is not mapped to unified fields; read it via ?raw=true or the Proxy (#11099). See the Alegra usage guide for the full stamping flow.

Alegra does not assign a journal entry number (always empty), and journal entries have no created/updated timestamps — so they cannot be sorted by date.

Only postable accounts (header: false) can be used on transactions; posting against a header: true grouping node is rejected. Two codes are exposed — code (the company's own account code) and nominal_code (the SAT código agrupador); the SAT code is shared across related accounts, not unique per account. Creating an account requires a parent_account.id, and accounts cannot be deleted (Alegra has no delete-account endpoint).

A payment must be applied to at least one invoice — Alegra rejects an unapplied payment.

delivery_date is required on create. Each line is costed against either a catalog item (line_items[].type: expense_item, which sets line.item) or an expense ledger account (expense_account, which sets line.ledger_account); a PO may mix both. See the Alegra usage guide for details.

Each line's Alegra item must have a SAT productKey or creation fails (code 1035, "La clave del producto es requerida"). The customer address is returned as a single preformatted string in billing_address.line1, not the structured object invoices return.