Sending documents

Use the send operation for the document type you need, with its send scope and declared idempotency header. Sending, marking as sent, downloading a PDF and submitting to FACe are different operations. A request accepted by the API does not prove that the recipient received the email; inspect the email delivery log.

curl -X POST "https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices/$INVOICE_ID/send" \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-fac-2026-00042" \
  --data '{
  "to": "facturacion@acme.example"
}'

All the routes in this guide hang off /v1/companies/{company}/…: {company} is the id (UUID v7) of the tax ID you operate on, and in the curl examples it is $COMPANY_ID. Reach a tax ID explains how to resolve it.

When an invoice counts as sent

For invoices, sending is not issuing. POST /v1/companies/{company}/invoices/{invoice}/send issues a draft first if needed and then emails it; the invoice is marked as sent only when the mail server accepts the delivery email. A queued or failed email, a payment reminder and an email of a draft that was never issued leave the mark unset. The mark keeps the first delivery: a resend does not move it.

If you deliver an issued invoice through your own channel (WhatsApp, paper, a portal), record it with POST /v1/companies/{company}/invoices/{invoice}/mark-sent and Factuarea-Version: 2026-10-01; on earlier versions that operation issues a draft instead. Clear a wrong mark with POST /v1/companies/{company}/invoices/{invoice}/unsend, which never changes the status or the number. Subscribe to invoice.marked_sent and invoice.unsent to follow the mark, and filter pending deliveries with is_sent=false. See Working with invoices.

Sender identity

When the sender-identity gate applies, either an active Factuarea subscription or an accepted census identification proves the sender’s identity. Merely entering card details is not the condition read by the service. An absent or unavailable census response does not prove identity; an active subscription remains an alternative.

A rejection uses 422 sender_identity_not_verified. Complete census verification or activate the subscription, then retry the intended send. This guide describes the enforced behavior when the gate is active; availability is determined by the service configuration.

Identity inherited from another company

The identity that is checked is not always the one of the tax ID that sends. A tax ID takes its sender identity, and its probation state, from the company it inherits its trust from, with the signals and the rules of that company. There are three rules and a single hop, the same ones as identity for document sending in the tax ID portfolio:

• A tax ID of an account that is not managed, other than its titular company, because the account bought it, received it by transfer or registered it, inherits from the titular company of its own account. The titular company inherits from nobody, and neither does a company without an account.
• A tax ID of a managed account inherits from the titular company of the provider's account for as long as the management lasts. When the management ends, it goes back to the rule above, with its own titular company, and it never keeps inheriting from the provider.
• A tax ID you reach through granted access inherits nothing from the account that receives the access. Its trust stays the one of the titular company of its own account.

Inheriting is not being exempt: if the company a tax ID inherits from is in probation, the tax ID gets the same state. The hop is of one level, and an identity that cannot be read never proves anything.

A 422 sender_identity_not_verified refers to that company. In error.details.resolved_against, own_company means that the identity was checked against the tax ID itself, and managing_company that it was checked against the company the tax ID inherits from. In the second case the other company has to act: its active subscription or its accepted census identification is what proves the identity, so its titular registers a payment method or verifies its NIF in the census. Do not ask the tax ID, or the client of a managed account, to buy a subscription of its own: a tax ID of an account has none to buy, and the account pays.

Test mode

A sandbox company, the one a fact_test_ key operates on, is not evaluated by the identity check, so it never gets sender_identity_not_verified. It remains subject to test-mode suppression: document email is not delivered to real recipients.

Handle delivery failures

Identity verification does not remove email quotas or other account budgets. A 429 requires the action and retry timing reported by the rate-limit response; repeated immediate retries will not fix it. A validation error requires correcting its field. Preserve request_id when investigating an accepted request with an unexpected delivery outcome. Store autosend_enabled uses the same sending safeguards.

The PDF when you send

Sending only queues the email. The PDF is prepared and rendered after your request commits, from the original captured with the document, and the response is the updated document. Its pdf_output_state can still be pending, so do not wait on it: confirm delivery in the email delivery log and, if you need the file, follow the retry loop of PDF previews and artifacts.

When revisioned output is active for your company (render_activation is revisioned in GET /v1/companies/{company}/pdf-templates/defaults), the operations that issue, send or accept a document need the presentation precondition: the reviewed context you approved. It has exactly seven fields, all or none:

Get the values by previewing the draft with source.kind: persisted_draft in PDF previews and artifacts. Where they go:

Without it the operation answers 428 pdf_presentation_precondition_required. A context that changed since your preview answers 409 (pdf_presentation_conflict or pdf_presentation_context_changed); an invoice whose legal data changed answers 409 pdf_legal_source_changed and its delivery is blocked until you revise it; and a malformed field answers 422 pdf_presentation_invalid. While revisioned output is not active for your company the precondition is ignored and the operation behaves as before. Preview again, review, and send with the new values.

Attach the FacturaE XML

POST /v1/companies/{company}/invoices/{invoice}/send can attach the invoice's FacturaE XML. It needs the FacturaE module.

curl -X POST "https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices/$INVOICE_ID/send" \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-fac-2026-00042-xml" \
  --data '{
  "to": "facturacion@acme.example",
  "attach_facturae": true,
  "submission_id": "0199f410-6a2b-7d31-8c5f-9e1a3b7d4c28"
}'

Publish a version on the public link

PATCH /v1/companies/{company}/invoices/{invoice}/public-link (and the same operation of quotes, proformas and delivery notes) accepts action revoke, activate, extend (with extend_days), reset and publish. publish binds the exact captured PDF to the public link and requires publication_context; the other actions reject it:

{
  "action": "publish",
  "publication_context": {
    "presentation_id": "0199f401-33de-7a8c-9e15-b7c4d2a60f38",
    "expected_binding_version": 3
  }
}

presentation_id is the id and expected_binding_version the binding_version of the presentation block of the document. If the version is stale the request answers 409 and keeps the previous publication: read the document again. The PATCH does not return a usable URL; read the link with GET /v1/companies/{company}/invoices/{invoice}/public-link and use publication.public_url only when publication.state is ready. It is null while the link is revoked or expired, or after a privacy erasure. See the operations of invoices, quotes and delivery notes.