Using the Alegra connector

Alegra is a cloud invoicing + accounting platform used across Latin America (Mexico, Colombia, Peru, Spain, Dominican Republic, Argentina, Chile, …). It is electronic-invoicing (CFDI/e-invoice) native, which shapes a lot of how invoicing works here.

Authentication

Alegra uses HTTP Basic auth with an email + API token: the consumer generates the token in their own Alegra account under Settings → Manual integration (API) → Usuario / Token. There is no OAuth and no application to register with Alegra, so there are no shared Apideck credentials: every consumer brings their own token. Setup is covered in the connection guide. Once connected, all calls use the standard Apideck headers:

Authorization: Bearer {APIDECK_API_KEY}
x-apideck-app-id: {APP_ID}
x-apideck-consumer-id: {CONSUMER_ID}
x-apideck-service-id: alegra

The credential model, from your side

There is no OAuth flow, no Apideck OAuth app to create, and no client ID or secret to paste into the Apideck configuration. Alegra authenticates each call with the consumer's own email plus a token they generate inside their own Alegra account, so every connection carries its own credential and there is nothing for you to register or provision centrally.

The API token is long-lived and does not expire on its own. It changes only when the account owner clicks Renovar token (regenerate) in Alegra, and doing so immediately invalidates the previous token and disconnects every integration that was using it, not just this connection. Ask consumers to regenerate the token only when they intend to rotate all of their Alegra integrations at once, and to re-supply the new value in Vault straight afterwards: the connection keeps failing until they do. Alegra documents this in its help centre.

What you can do

Seventeen accounting resources are mapped. The per-resource read/write coverage is on the connector's Supported Resources tab. Check it there rather than here, so you are reading the generated list rather than a copy of it. The sections below cover the behaviour that is specific to Alegra.

1. CFDI stamping (timbrado): the most important topic

Stamping certifies a document with the Mexican tax authority (SAT), issuing a folio fiscal (UUID) and consuming a real fiscal folio. It applies to the sales documents you issue: invoices and credit notes. Bills and purchase orders are not stamped: they record a document the supplier issues, and stay editable while open.

Creating an invoice produces a draft

A create returns an unstamped draft; no fiscal folio is consumed:


curl -X POST 'https://unify.apideck.com/accounting/invoices' -H '…headers…' -d '{
  "customer":     { "id": "7" },
  "invoice_date": "2026-05-31",
  "due_date":     "2026-06-30",
  "line_items": [{ "item": { "id": "11" }, "unit_price": 0.01, "quantity": 1 }]
}'
# → 201, and a GET shows: { "id": "6", "status": "draft", "total": 0.01, "currency": "MXN" }

Each line item's Alegra product must have a SAT product key (productKey) configured, or the create is rejected:


{ "status_code": 400, "error": { "message": "La clave del producto es requerida.", "code": 1035 } }

productKey is a Mexico-specific SAT code with no unified field (the unified code maps to Alegra's reference/SKU, a different thing). Set it when creating the item through Unify via pass_through; it must be a valid SAT clave de producto/servicio string:


{
  "name": "Servicio de consultoría",
  "type": "service",
  "pass_through": [{ "service_id": "alegra", "extend_object": { "productKey": "80141600" } }]
}

To read productKey back, fetch the item through the Proxy (GET /items/{id}). Native mapping is tracked in #11099. (Unset payment_method/paymentType on an invoice default to cash/PUE.)

Issuing (stamping) an invoice

To stamp, send a pass_through that turns on stamping and supplies the required SAT fields:


{
  "customer": { "id": "7" },
  "invoice_date": "2026-05-31", "due_date": "2026-06-30",
  "payment_method": "cash",
  "line_items": [{ "item": { "id": "11" }, "unit_price": 100, "quantity": 1 }],
  "pass_through": [{ "service_id": "alegra", "extend_object": {
    "stamp":        { "generateStamp": true, "version": "4.0" },
    "paymentType":  "PUE",
    "cfdiUse":      "G03",
    "regimeClient": "SIMPLIFIED_REGIME"
  }}]
}

Field	Meaning	Notes
`stamp.generateStamp`	stamp now vs. leave as draft	`true` to issue
`payment_method`	forma de pago	Alegra string (`cash`/`transfer`/`deposit`/`check`/`credit-card`/`debit-card`/…): a numeric SAT code is rejected
`paymentType`	método de pago	`PUE` (single payment) or `PPD` (installments/deferred). PPD requires `payment_method: "other"`
`cfdiUse`	uso del CFDI	SAT catalog (`G01`, `G03`, `D01`, `S01`, …)
`regimeClient`	client's fiscal regime	required for CFDI 4.0

⚠️ Stamping consumes a real CFDI folio: there is no test/dry-run stamp. The client must have a valid RFC (XAXX010101000 works for unstamped/draft testing).
If stamping fails, Alegra still saves the invoice as a draft and returns HTTP 400 with the error (e.g. code 3051) plus the created invoice: fix the data and re-stamp; nothing is lost.

Reading the CFDI back (folio fiscal, seals)

A stamped invoice read through Unify returns the commercial data (status, totals, lines) but not the CFDI fields. To get them, add ?raw=true to the normal GET; the full downstream record, including stamp, comes back under data._raw:


curl 'https://unify.apideck.com/accounting/invoices/5?raw=true' -H '…headers…'


"stamp": {
  "uuid":          "2B95841F-9AAA-5AFB-980F-F266F8D23D67",   // folio fiscal, the field most often needed
  "emissionStatus":"STAMPED_AND_ACCEPTED",
  "version":       "4.0",
  "satSeal":       "pOl8yNEC3Q2Nm/2rjpAgOQP7…",              // sello del SAT
  "cfdSeal":       "QpyNuG04R7cProDVN5VbM8Sv…",              // sello del CFD
  "satCertificateNumber": "00001000000707310321",
  "stampDate":     "2026-05-30 13:02:18",
  "barCodeContent":"https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=2B95…",
  "originalString":"||1.1|2B95841F-…||CVD110412TF6|…"        // cadena original
}

For the CFDI PDF or XML, call the Proxy with Alegra's ?fields=pdf,xml (base /proxy, target in the x-apideck-downstream-url header).

Stamping an existing draft, and cancelling

A stamped invoice is immutable: update and delete only work while it is a draft. Using the Proxy against Alegra's own endpoints you can:

stamp drafts in bulk: POST /invoices/stamp with { "ids": [6] }
stamp one draft: POST /invoices/{id}/open with { "stamp": { "generateStamp": true } }
cancel a stamped invoice at the SAT: POST /invoices/{id}/void with a reason cause (01 to 04; 01 also needs relatedFolio)

The invoice id does not change when a draft becomes stamped, so it is safe to round-trip.

2. Document `status` is derived from the balance

Alegra's underlying states are draft / open / closed / void. The unified status is computed using the balance, so an Alegra open invoice can surface as:

Situation	Unified `status`
draft	`draft`
void	`voided`
nothing paid	`authorised`
partly paid	`partially_paid`
fully paid / closed	`paid`

This applies to invoices, bills and credit notes. Note that partially_paid cannot be used as a filter (Alegra has no equivalent state): for status filtering, paid and authorised/unpaid and voided work.

3. Payments and bank accounts

payments are customer receipts; bill-payments are supplier payments.
A payment must be applied to at least one invoice/bill: Alegra rejects an unapplied payment. The documents it was applied to come back in allocations (with the applied amount).
payment_method is one of cash/transfer/check/deposit/credit-card/debit-card.
bank-accounts represent the money accounts that receive/issue payments (types cash/checking/credit_card). Alegra exposes no IBAN, BIC, routing number, or balance, so those fields come back empty; bank-type accounts do carry an account number.

4. Bill & purchase-order line items: catalog item or ledger account

A bill or purchase-order line can be costed against a catalog item or directly against an expense ledger account, and one document can mix both. line_items[].type tells you which:

expense_item → the line carries line_items[].item (a reference to invoice-items)
expense_account → the line carries line_items[].ledger_account (a reference to ledger-accounts)

(Sales documents such as invoices, credit notes and quotes always bill against catalog items.)

5. Ledger accounts (chart of accounts)

The chart is hierarchical. Each account exposes its parent_account and sub_accounts.
Only postable (leaf) accounts can be used on transactions. Accounts with header: true are grouping/summary nodes; posting against them is rejected.
Two codes are exposed: code (the company's own account code, e.g. 101-01-001) and nominal_code (the SAT código agrupador, e.g. 101.01). The SAT code is shared across related accounts: it is not unique per account.
Creating an account requires a parent (parent_account.id); Alegra rejects a create without one (there is no API-created root account). Accounts can be created and updated but not deleted: Alegra has no delete-account endpoint; block/deactivate the account in Alegra instead.


curl -X POST 'https://unify.apideck.com/accounting/ledger-accounts' -H '…headers…' -d '{
  "name": "Comisiones bancarias",
  "parent_account": { "id": "5315" },   # required, the account this hangs under
  "code": "604-02-001",                 # your own account code (optional)
  "nominal_code": "604.02"              # SAT código agrupador (optional)
}'
# → 200 { "data": { "id": "5486" } }

The account's classification/type and nature (debit/credit) are inherited from the parent: you do not send them. An update (PATCH) changes only the fields you send (name, code, description, …).

6. Tax rates

Two things to know:

Creating a tax requires a type (IVA, IEPS, EXENTO, …): Alegra rejects a tax without one. total_tax_rate (or effective_tax_rate) carries the percentage.
An update preserves the tax's ledger accounts automatically, so you can PATCH just the name or rate; you do not need to re-send tax_payable_account_id/tax_remitted_account_id (Alegra would otherwise reject the update for a missing purchase account).


curl -X POST 'https://unify.apideck.com/accounting/tax-rates' -H '…headers…' -d '{
  "name": "IVA 16",
  "type": "IVA",                 # required
  "total_tax_rate": 16,
  "tax_payable_account_id":  "5166",   # optional, IVA trasladado ledger account
  "tax_remitted_account_id": "5063"    # optional, IVA a favor ledger account
}'
# → 201 { "data": { "id": "21" } }

7. Journal entries

Total debits must equal total credits, or Alegra rejects the entry. Each unified line_items[] entry is one debit or one credit (type + total_amount) posting to a ledger_account.
number is always empty (Alegra assigns none) and journal entries have no created/updated timestamps.

8. A contact can be both a customer and a supplier

In Alegra one contact can be a customer and a supplier at the same time. The consequence: the same record (same id) can appear in both the customers and suppliers lists, and updating it through either resource changes the same underlying contact.

9. Filtering, sorting, pagination

Pagination is offset-based and capped at 30 per page; walk meta.cursors.next until null. ledger-accounts is unpaginated (the whole tree returns at once).
Sorting by created_at/updated_at works on most list resources. ledger-accounts, journal-entries and departments cannot be sorted (no timestamps).
Filtering is uneven: status and customer_id/supplier_id work on payments, bill-payments and journal-entries; invoices, credit-notes and quotes expose no unified-compatible filters; invoice-items filters only by name. Filter client-side when a filter isn't available.
Rate limiting shapes backfills. Alegra throttles requests per user and answers HTTP 429 once the limit is hit. With pages capped at 30 records, a full historical sync is pagination-heavy, so pace it and avoid pulling pages in parallel. See the Rate limits row on the connector's Overview tab for the current ceiling and the response headers it exposes.

10. Mexican fiscal (CFDI/SAT) fields

Beyond stamping, Alegra carries many Mexico-specific fields that have no place in the unified accounting schema: cfdiUse, paymentType, fiscal regime, line productKey/unit, taxCondition, the full CFDI stamp, the IVA ledger accounts, and more. Send them on write with pass_through; read them with ?raw=true (or the Proxy). Native support for these is tracked in #11099; the single most-requested field is the CFDI uuid (folio fiscal).

11. Webhooks

Alegra delivers native webhooks, but they cover only part of the connector's resource set. Events exist for invoices, bills, invoice-items and contacts (created, updated and deleted for each), and a contact change is delivered for both customers and suppliers, since one Alegra contact can be both. That is 5 of the 17 mapped resources. The other 12 (credit notes, bill credit notes, payments, bill payments, journal entries, quotes, purchase orders, tax rates, ledger accounts, departments, bank accounts and company info) emit nothing and have to be polled, so plan a polling path for anything outside the five.

How delivery works, and the one trap in it:

Subscriptions are managed through Alegra's API, not its UI. Apideck registers them when a connection becomes callable and removes them when the connection is disabled or deleted, so there is nothing for you or the consumer to configure inside Alegra.
Each notification is an HTTPS POST that must be acknowledged with a 2XX response. Creating a subscription also fires an immediate verification POST with an empty body, which has to be acknowledged the same way before the subscription exists at all. Alegra enforces an acknowledgement window on each delivery; size any slow handler against the current window documented in Alegra's developer documentation.
Repeated failed deliveries eventually remove the subscription while the connection itself stays healthy (re-enabling the connection re-registers the subscription); the exact failure threshold is in Alegra's developer documentation. Treat webhooks as best-effort and keep a polling fallback on the five webhook-covered resources too, not just the twelve without: when a subscription is silently dropped, events simply stop arriving with nothing to see.

12. Testing, and what your consumers need on their side

There is no Alegra sandbox or developer environment: every call, including the ones made from the API explorer in Alegra's own developer documentation, runs against a real account's live data. The practical test environment is an ordinary Alegra trial account created through the normal sign-up; there is no separate developer tier to apply for. Check Alegra's sign-up page for the trial terms (length and whether it includes API access) that apply in your country. Because stamping consumes a real fiscal folio with no dry run (section 1), do your CFDI experiments on a trial or throwaway account rather than one whose books matter.

On the consumer's side, API access is gated to a qualifying plan, and the plan that includes it differs by country edition: Alegra's international help centre names the Plus plan, the Costa Rica help centre states only that the subscription must include API access, and Peru's help centre lists API 2.0 among what the trial account includes. Some plans also cap the number of active integrations. Check the requirement for the countries you sell into instead of quoting one tier name everywhere, and when a consumer reports a 403, treat their plan as the first thing to look at.

One practical note for your team: Alegra's developer documentation is Spanish-only.

13. Before you commercialise or distribute

Building and testing need no permission from Alegra. The consumer's own email + token is the only credential, so you can go from zero to a working integration without talking to anyone.

Distribution is the step that carries a contract. Alegra's API Terms and Conditions require Alegra's prior written authorisation before a product or service built on its API is distributed or commercialised, and Alegra reserves the right to decline an implementation it considers a competing product or a replication of its own user experience. Treat it as a contract step to clear before a public launch rather than a blocker on development: build and validate first, then raise authorisation with Alegra (the API Terms page is the starting point) and ask your Alegra contact for an expected timeline so you can schedule your launch around it.

The same terms also let Alegra monitor API usage, change the maximum request rate (with advance notice), and suspend or block access for an account or developer it judges to be in violation. That is worth knowing when you size a sync or plan a bulk migration.

Questions about the connector itself go to Apideck Support.