Empresas

Base: https://api.facturia.cl/v1. Every endpoint in this chapter authenticates with Authorization: Bearer unless stated otherwise, and the error envelope is the one in Errors.

This chapter is ordered the way it makes sense to read it, starting with the mandato: it is step 1 of both onboarding tracks, and the certificate (or the portal credential) is step 2. Uploading the certificate first works, but the step stays pending until the machine reaches certificate_pending. The full path is in From sandbox to production.

GET /empresas

List empresas visible to this key

List every empresa this key can reach — its own allowlist resolved to real rows, or the whole account for an unrestricted key.

curl -sS https://api.facturia.cl/v1/empresas \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas

Create an empresa

In test mode the empresa is born emitting: no mandato, no certificate, no certification. In live mode it starts at mandato_pending and progresses through the onboarding state machine.

origen IS REQUIRED IN LIVE MODE and this operation refuses without it — 400 invalid_field with param: "origen" (#495). It is not in required above because the mode is a property of the CREDENTIAL, not of the body, and a schema cannot say «required when the bearer token starts with sk_live_»: declaring it unconditionally would make every sandbox call — where it defaults to ninguno — fail a generated client's own validation before it left the machine. So the rule lives on the 400 below, where a codegen'd client can at least see it, and in the field's own description.

curl -sS -X POST https://api.facturia.cl/v1/empresas \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"rut":"77928532-4","legal_name":"Connect SpA"}'

Parameters

Body

GET /empresas/{empresa_id}

Retrieve an empresa

One empresa: legal identity, ambiente, emission_channel/certification_track, onboarding spine and capabilities.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

PATCH /empresas/{empresa_id}

Update an empresa

Update legal_name, giro, contact_email, acteco, origen, codigo_sucursal, doc_types, emission_channel, certification_track or status. ambiente is derived and rejected if sent (422); origen is the titular's own claim about how the empresa emits today, correctable, never a canal preference.

Two of these move the onboarding machine and say so in their own descriptions: doc_types (adding a tipo re-opens certification for it; 39/41 need the mercado channel) and certification_track (which checklist governs the empresa).

THE PANEL MIRROR IS NARROWER. PATCH /dashboard/empresas/\{empresa_id\} — the same handler behind an account session — accepts only doc_types and certification_track, and refuses every other field with 400 invalid_field naming it. Those two are what the puesta en marcha wizard has to record; the rest are the taxpayer identity each document is printed from, and a browser session is not the credential that rewrites what the SII sees on an invoice. An sk_ key on THIS path is unaffected.

curl -sS -X PATCH https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_name":"Connect SpA","giro":"…"}'

Parameters

Body

DELETE /empresas/{empresa_id}

Delete a SANDBOX empresa

Throw away a scratch empresa. Sandbox only.

A sandbox empresa holds nothing that is a tax record: its documents are mocked, it never reached the SII, and it reserves nothing — not the RUT (uniqueness is per mode) and not the <rut>@dte.facturia.cl reception alias, which live empresas alone carry. So it can be deleted, and the empresa plus everything hanging off it goes in one transaction.

A LIVE empresa is 409 empresa_delete_not_allowed, always. §7.1: emitted documents are tax records. The two real exits are DELETE /v1/empresas/\{empresa_id\}/mandato (ends the authorization, cláusula 7.1.3) and PATCH /v1/empresas/\{empresa_id\} with \{"status": "archived"\} (stops emission and billing); both keep the history.

curl -sS -X DELETE https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

GET /empresas/{empresa_id}/mandato

Whether the representante legal has signed, against which terms, and how

The read half of the hosted mode. Mint a signing_url with an empty POST, send it to the representante legal, then poll this - completion is observable by the agent that asked for it, without subscribing to a webhook or inferring it from steps[].status.

Two fields answer questions the onboarding checklist cannot. terms_current: false on a signed mandato means the text has moved on and the pipeline has already stopped trusting the acceptance - POST again to collect a fresh one. And acceptance_method distinguishes an aprobacion (hosted: a human of the required role completed a page that showed them what they were signing) from an atestacion (api: an integrator's claim that one did). Those are different pieces of evidence.

signing_url is ALWAYS null here: only a SHA-256 of the token is stored, so no read can reproduce it. POST with an empty body re-mints, revoking the previous link.

status: "none" for an empresa nobody has asked yet. It is a state, not a missing resource - the empresa exists and you are authorized for it.

Scope: mandato:write (which empresas:write implies). The scope that mints the link is the scope that reads whether it was used.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/mandato \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/mandato

Record the mandato authorizing Facturia to act before the SII

Post the acceptance you collected yourself, or omit the body to receive a hosted signing_url to send the representante legal.

We record that an acceptance happened, by whom, from where, and against which exact bytes of the mandato text. We do NOT verify a firma electrónica avanzada: whether one is required is an open legal question, and until it is answered this endpoint claims no more than the evidence it holds.

While GET /v1/mandato_terms reports status: "draft", a live-mode acceptance is refused with 422 mandato_terms_draft — the same warning §7.3 prints, enforced.

Two forms, two scopes (ADR-0012 §4). No body — mint the enlace de firma for the representante legal — needs mandato:write, which empresas:write implies. A body — asserting a signature you collected in your own flow — is an atestación and needs mandato:attest itself: empresas:write does NOT imply it (corrected 2026-09-03), so a key that used to post a body under empresas:write alone now gets 403 insufficient_scope naming mandato:attest.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/mandato \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requested_by":"…","representante_legal":{}}'

Parameters

Body

DELETE /empresas/{empresa_id}/mandato

Revoke the mandato

Cláusula 7.1: at any time, without cause, without penalty, and without ending the contract. The empresa moves to suspended immediately, everything already queued is cancelled in the same transaction, and the mandato step returns to action_required.

This is an atestación, not a write (ADR-0012 §4, ticket #465). It is the act with the largest effect in the contract, so empresas:write is NOT enough: send it with mandato:attest, which is granted explicitly, is never implied by empresas:write and is never in the MCP vocabulary. A dashboard session may also call it — a session is the account holder in person. Anything else gets 403 insufficient_scope, whose error.details carries required_scope and the \{method, url\} that mints the hosted revocation page for the representante legal (POST /empresas/\{empresa_id\}/mandato/revocation_link).

It does NOT destroy the certificate — that is DELETE .../certificate, a separate revocation with its own deadline. And it does not undo what preceded it: the empresa's position is remembered, so a fresh acceptance returns it to where it was rather than restarting onboarding.

The empresa stays READABLE while suspended (ticket #515): GET /empresas/\{id\}, GET .../onboarding and GET .../mandato all answer, onboarding.blocked_on names mandato, and onboarding.pending_action is the mandato_revocado handoff whose link.mint re-signs. active is untouched — a right the contract calls reversible is never implemented as a disappearance.

curl -sS -X DELETE https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/mandato \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

GET /empresas/{empresa_id}/certificate

Retrieve certificate metadata

Metadata only. The .pfx and its password are never readable through the API.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/certificate \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/certificate

Upload (or reuse) the empresa's digital certificate

Upload the empresa's .pfx (multipart/form-data with file and password) or reuse another empresa's valid certificate (reuse_from_empresa). An expired certificate is refused at ingest.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/certificate \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -F "file=…" \
  -F "password=…"

Parameters

Body (multipart/form-data)

DELETE /empresas/{empresa_id}/certificate

Purge the certificate from the vault (revokes custody, suspends emission)

Remove the stored certificate metadata. The empresa returns to needing one before it can sign anything the SII will accept.

curl -sS -X DELETE https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/certificate \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

GET /empresas/{empresa_id}/sfg_credential

Retrieve the SFG centralizado clave's custody metadata

Metadata only — whether we hold the clave and when it was stored. The value itself is never readable through the API: there is no code path in this endpoint that decrypts it.

Only an emission_channel: sfg empresa in live mode has one. A mercado empresa signs with the certificate in custody and never asks the SII to sign for it, and a test-mode empresa has no Portal MIPYME at all; both answer 422 naming the fix.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/sfg_credential \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/sfg_credential

Store (or replace) the SFG centralizado clave

The value goes straight to the per-tenant vault and its id to the empresa's credential row; there is no plaintext column. Replacing destroys the outgoing secret first, so the destruction is in the custody record rather than a side effect nobody can point at.

The response is the same metadata GET returns. The clave is not echoed back.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/sfg_credential \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clave_centralizado":"…"}'

Parameters

Body

DELETE /empresas/{empresa_id}/sfg_credential

Destroy the SFG centralizado clave (ends custody)

Destroys the bytes. 204 even when there was nothing to destroy — you asked for a state ("you hold nothing of mine"), and that state is the outcome either way.

Unlike DELETE .../certificate it does NOT walk the empresa's onboarding back: the next SFG emission refuses for want of a signing clave, which the emit path already reports honestly, and a clave can be re-supplied in one call.

curl -sS -X DELETE https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/sfg_credential \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/mandato/revocation_link

Mint the hosted page where the representante legal revokes

Cláusula 7.1 belongs to the person who signed, and this is how you put them in front of it (ticket #465). The acceptance already hands them this address once, and the receipt e-mail carries it; this endpoint is for every later moment — the e-mail was lost, or never went out, or the customer is asking their integrator to help them stop.

Holding the link is not holding the power: the page demands the representante legal's RUT as recorded on the mandato they signed, which this response deliberately does not echo. Minting revokes any previous revocation link, which is what single-use means when a link is reissued.

The URL is returned EXACTLY ONCE — only a SHA-256 of the token is stored. It does not expire: the right it addresses does not either.

409 mandato_not_signed when nothing is in force, because an address for a right that cannot be exercised is worse than a refusal that says so.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/mandato/revocation_link \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/resolucion/verify

Verify a declared resolución with one production timbraje (Facturia operators only)

OPERATOR ONLY — NOT CALLABLE WITH AN API KEY (sii-api#581 D1, founder decision 2026-09-23). Documented so an integrator knows what moves resolucion.verification_status and who moves it.

A resolución stated on POST/PATCH /v1/empresas is a claim. It is verified by asking the PRODUCTION SII for ONE folio range of one declared factura tipo: the SII refuses a timbraje for a RUT it has not authorized for that tipo, so a granted range is the proof. That request is irreversible (a registered range must be used or annulled), so it is made only when a Facturia operator confirms it for this empresa. Nothing is requested implicitly, nothing during POST /v1/empresas, and nothing against the certification environment.

Without confirm: true the call refuses with 400 confirmation_required and names the exact request in the message and in error.details.request. With it, the confirmation (who, when, why) is recorded and ONE folio_request job is queued; the SII's answer then moves resolucion.verification_status from pending_verification to verified or refused. An attempt that gets no answer about the RUT (the SII's edge block, an unusable certificate) stays pending_verification.

409 resolucion_verification_not_allowed names the blocking fact in error.details.reason: sandbox, sfg_channel, no_claim, already_verified, refused, in_flight, range_registered, not_ready (the empresa is not at certificate_verified) or no_factura_tipo.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/resolucion/verify \
  -H "X-Admin-Secret: $FACTURIA_OPERATOR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"confirm":true,"authorized_by":"…"}'

Parameters

Body

GET /empresas/{empresa_id}/counterparties

Counterparties you have invoiced, with the address and contacts on file for each

A DERIVED list, not a stored one: it reads the receivers of the documents this empresa has already emitted (tipos 33, 34, 56 and 61) and joins whatever contacts and address book entries exist, so the screen opens as a checklist rather than a blank form. A counterparty that has an address or a contact but no document yet is included.

The address fields come from the address book only. Where none is on file they are null and so is source, which on this list means "nothing recorded" rather than "nothing known" — the single-counterparty read is the one that falls back to what earlier documents said.

has_more is always false. The window bounds the SCAN, not a page of results, and promising a cursor this shape cannot honour would be worse than saying so.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/counterparties \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

GET /contribuyentes/{rut}

What the SII publishes about a company, by RUT, and a giro that fits a factura

The razón social and economic activities the SII publishes for a persona jurídica, and a suggested giro that fits the receptor of a factura (at most 40 characters, ISO-8859-1). For prefilling a customer before the first invoice to them.

The source is the SII's public nómina of personas jurídicas (https://www.sii.cl/sobre_el_sii/nominapersonasjuridicas.html), which the SII republishes every few months and does not guarantee to be complete or current. source.published_at says which edition answered. Personas naturales are not in it: their RUTs answer 404, like a RUT that does not exist.

A SUGGESTION, not a statement: nothing here is written into a document on its own. Show it to the person, and once confirmed, put it on file with PATCH /v1/empresas/\{id\}/counterparties/\{rut\} — that is what the next emission reads.

suggested_giro.basis is curated when the text comes from Facturia's short wording for a common activity code (the official descriptions are usually longer than 40 characters, and a cut one would change what the factura says), sii_description when the official description fits as it stands. Null when neither applies: ask the person.

Not empresa-scoped: the data is public and about a third party, so no Facturia-Empresa is needed. Limited to 120 requests a minute per account.

curl -sS https://api.facturia.cl/v1/contribuyentes/{rut} \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

GET /empresas/{empresa_id}/counterparties/{counterparty_rut}

What you know about one counterparty, and whether you stated it or we inferred it

Your address book entry for this RUT — the razón social, giro and domicilio we will put on the next document to it.

Two sources, in the order the emission resolver uses them. If you have put an address on file, that is the answer and source is api. If you have not, but you have already emitted a document to this RUT, the answer is read off the newest one and source says so — that is inference, not a statement, and it is the difference worth knowing before you spend a folio. If neither exists, this is a 404.

The counterparty has no id: there is exactly one identity per RUT, so the RUT is the key.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/counterparties/{counterparty_rut} \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

PATCH /empresas/{empresa_id}/counterparties/{counterparty_rut}

Put a counterparty's razón social, giro and address on file

The SII will not file a factura whose receptor has no giro, dirección and comuna: it accepts the ENVELOPE and then refuses the DOCUMENT, and the folio is spent either way. Recording the address here answers that once instead of on every emission — and it is the only source that can answer for a counterparty you have never invoiced, which is exactly when the question bites.

An upsert: the first call creates the entry, later ones edit it. There is no POST and no DELETE, because the entry has no lifecycle of its own.

Partial. A field you do not send keeps its value; a field sent as null is cleared. Every value is held to the same SII schema limit a value sent on a document is held to — giro 40 characters, address.street 70, address.comuna and address.city 20, legal_name 100 — and to the same ISO-8859-1 rule. Over the limit is refused, never truncated: a silently shortened name of trade would change what every document to this counterparty says about who they are.

No earlier document is required. Recording an address for a RUT you have not invoiced yet is the point.

curl -sS -X PATCH https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/counterparties/{counterparty_rut} \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_name":"Connect SpA","giro":"…"}'

Parameters

Body

GET /empresas/{empresa_id}/counterparties/{counterparty_rut}/contacts

The contacts on file for one counterparty

The primary contact comes first — it is the only one that is notified.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/counterparties/{counterparty_rut}/contacts \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/counterparties/{counterparty_rut}/contacts

Put a contacto responsable on file

A contact with no attestation is a legitimate state: it is stored, it is shown, and it is never messaged. Sending opt_in: true without opt_in_method is refused, because consent recorded without recording how it was obtained is not a record.

The first contact for a counterparty becomes the primary unless you say otherwise.

A number that has opted out cannot be re-added under a new id: that is 422 contact_opted_out, and it is what stops delete-and-recreate from undoing a STOP.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/counterparties/{counterparty_rut}/contacts \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"cliente — Comercial Andina","phone":"+56912345678"}'

Parameters

Body

PATCH /empresas/{empresa_id}/counterparties/{counterparty_rut}/contacts/{contact_id}

Edit a contact, promote it, or record an opt-out

primary: true demotes whoever held it, in the same call — exactly one contact per counterparty may be primary and the database is what enforces it.

opted_out: true records that the person asked to stop by some other channel. opted_out: false does not exist: an opted-out contact is frozen and cannot be edited, re-attested or re-enabled. Someone who asked to be left alone is not un-asked by a colleague fixing a typo in their name.

curl -sS -X PATCH https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/counterparties/{counterparty_rut}/contacts/{contact_id} \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"cliente — Comercial Andina","phone":"…"}'

Parameters

Body

DELETE /empresas/{empresa_id}/counterparties/{counterparty_rut}/contacts/{contact_id}

Remove a contact from the address book

204 whether or not it was there. The exception is an opted-out contact, which is kept: its row is precisely what makes re-adding the same number refusable.

curl -sS -X DELETE https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/counterparties/{counterparty_rut}/contacts/{contact_id} \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

GET /empresas/{empresa_id}/onboarding

Onboarding lifecycle, steps and blocking human actions

Everything a wizard needs to render progress and tell the user what to do next.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/onboarding/links

Mint a link to a hosted representante-legal page

The person who has to act is often not the person holding the account: the account belongs to the accountant, the certificate belongs to a socio, and the SII steps that need a person are the socio's. So the hosted pages are reached by a link, not by a login.

step is any step of THIS empresa's checklist that needs a person - actor: customer (the step they perform) OR stall_actor: customer (a step of OURS that cannot finish until they decide). Which ones exist depends on its certification_track: certificate, sii_postulacion, cumplimiento and habilitacion on the mercado catalog; credential, clave_centralizado and usuario_autorizado on the SFG one. A step from the other catalog is refused with a 400 naming the ones this empresa does have. The mandato's link is single-use and comes from POST /empresas/\{empresa_id\}/mandato with an empty body instead.

The url is returned exactly once - only its SHA-256 is stored. The link is reusable and lives thirty days, and re-minting revokes the previous one.

The response also carries the step's pending_action, with action_url set to the URL just minted: the mint is the one moment both halves exist at once, so an agent gets the live address and the instructions to relay with it in a single call.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/links \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step":"…"}'

Parameters

Body

DELETE /empresas/{empresa_id}/onboarding/links/{step}

Revoke a hosted representante-legal link

204 whether or not one existed. A revoked link answers exactly like one that never existed, so a token cannot be used to learn whether we ever asked a given company to sign something.

curl -sS -X DELETE https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/links/{step} \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/onboarding/go_live

Ask the titular to approve the go-live, or state the decision on their behalf

The Declaracion de Cumplimiento is a decision about a month, not a progression. On declaring, the empresa "queda operando automaticamente en el sistema de facturacion electronica" and owes the Informacion Electronica de Compras y Ventas FROM THE MONTH OF THE DECLARACION, whether or not it emits anything. The SII's own page says the step may be postponed.

So the month is the customer's to choose and a custody mandate does not carry it.

TWO FORMS, and the body is which one.

• No body mints an enlace de aprobacion for the titular and answers 201 with approval_url and expires_at. The human opens the page, sees the month and the IECV consequence in their own language, and decides. Single use, seven days, and the URL is returned exactly once - only its SHA-256 is stored. Scope onboarding:write.
• \{"authorized": true|false\} states the decision on the titular's behalf: an atestacion, for an integrator that collected it in its own flow. Answers 200 with the authorization. Scope onboarding:attest.

empresas:write implies onboarding:write — the no-body form — but NOT onboarding:attest (corrected 2026-09-03): an atestación is a human granting that power on purpose, every time, never a side effect of a wider grant a key already held. A key that used to send \{"authorized": true|false\} under empresas:write alone now gets 403 insufficient_scope naming onboarding:attest.

This changed in 2026-09. An empty body used to DEFAULT to authorized: true, so a caller who sent no body silently authorized a tax consequence. An omitted field is not a decision; if you were relying on that, send \{"authorized": true\} explicitly.

\{"authorized": false\} withdraws while nothing has been filed. Once the declaracion is filed there is nothing left to withdraw and the call is refused with 409 cumplimiento_already_filed.

Refusals arrive together. The status and code are the first blocker's own - 422 mandato_revoked, for instance - and error.details.blockers[] lists every one, so you do not learn them one round trip at a time.

THE AUTHORIZATION IS FREE (2026-09-04, #530). It used to be gated on the subscription, and only on this door: the hosted cumplimiento page for the representante legal answered 200 for the same unsubscribed empresa, so the rule lived in one channel and an agent that sent the human to the other one walked around it. It is a DECISION, not an emission — the titular saying «start my obligation this month» — and the gate stands where the value is: every act that spends a folio or leaves the building is still gated, so an authorized empresa that has not paid emits nothing. This operation no longer answers 402.

There has to BE a decision (2026-09, #451). Minting an approval link for an empresa that has not reached the Declaracion de Cumplimiento handed a human a page with nothing on it. Two refusals come first, before the blockers and before the mint:

• 409 go_live_not_ready - the mercado lane has not reached the decision. error.details.blocked_on names the step holding it up and error.details.next is the \{method, url\} that reports when it moves. Retriable: it WILL be ready.
• 409 go_live_not_applicable - this empresa is not certifying for mercado, so it has no Declaracion de Cumplimiento at all. What gates an SFG empresa's emission is puesta_en_vivo, which is ours. Not retriable.

Neither applies to \{"authorized": false\}: a decision that exists can always be withdrawn, whatever the lane has done since.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/go_live \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"authorized":true}'

Parameters

Body

POST /empresas/{empresa_id}/onboarding/steps/{step}/recheck

Tell us a human step was performed, and we go and look

The resume half of the pending_action handoff. A person has performed one of the acts Chilean law reserves to them (see pending_action.performed_by), and this asks us to find out whether the SII agrees.

This endpoint accepts a claim and produces no fact. It takes no request body, writes no step status and moves no empresa. What it does is enqueue the producer that READS the SII, plus the tick that folds whatever that producer finds, and return the step's status as it stood the moment you called — read before the enqueue and returned unchanged. If you post a recheck on a step that is action_required and read action_required back, that is the endpoint working: the step advances when we see the fact, not when you say so. verified is on the response and it is always false.

evidence_source says how (or whether) the step can be confirmed at all. sii_probe means we go and read the SII. own_record means the act lands in our own tables and we will see it. no_producer means this build genuinely cannot observe that step yet — the boleta habilitacion is the one — and contact names the door out: POST .../onboarding/steps/\{step\}/attest (#395), which is a DIFFERENT endpoint that writes a fact rather than merely recording a claim. Do not tell a user this call alone is watching a no_producer step; nothing is.

queued and already_queued split the jobs this call created from the ones that were already scheduled for the same five-minute window. Both mean "we are about to look".

For a sandbox empresa nothing is enqueued and evidence_source is sandbox: a test empresa's onboarding never opens a session against the SII, so there is nothing to re-read. Move its steps with the test helpers instead.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/steps/{step}/recheck \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/onboarding/steps/{step}/attest

Record that a human performed a step this build cannot probe (#395)

The endpoint recheck's own contact field points at when evidence_source: 'no_producer'. Unlike recheck — which accepts a claim and produces no fact — this endpoint writes one: a sii_onboarding_evidence row the next onboarding tick reads as the fact that lets the step complete.

Refused with 422 invalid_field on any step whose evidence_source is not no_producer — attesting a step the SII probe or our own records already confirm would be a second, competing source of truth for a fact we can already verify. habilitacion (boleta habilitación at certBolElectDteInternet, an uncaptured SII SPA) is the only step this map names no_producer today.

Requires onboarding:attest itself: never in the bootstrap default set, never implied by empresas:write alone (ADR-0012 §3-4). attested_by is required — who told you this happened.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/steps/{step}/attest \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"attested_by":"…"}'

Parameters

Body

POST /empresas/{empresa_id}/onboarding/steps/{step}/approve

Record the titular's authorization for a step Facturia then performs (#452, #453)

The sibling of attest, for the opposite situation. attest says «a person did something we cannot see»; this says «a person authorized something WE are about to do».

Two acts in this pipeline are ours to perform once somebody chooses the moment. The postulacion is presented with the representante legal's own custodied certificate under mandato 4.2 a), and it costs an empresa on the Sistema de Facturacion Gratuito its "calidad de usuario activo" the instant the SII authorizes it. The boleta habilitacion opens a 24-hour SII clock. Neither is a decision a custody mandate carries, so each waits for a row in sii_onboarding_step_approvals.

act must be the one the step is currently asking for. Read steps[].pending_action.approval on GET .../onboarding: it names the act, whose decision it is, the consequences to show first, and both button labels. A step asking for nothing answers 409 onboarding_approval_not_offered; a mismatched act answers 400 invalid_field. One step carries different decisions at different points of its life, and an approval recorded against the wrong one is consent that was never given.

A rejection is recorded, not ignored. decision: "reject" writes a row exactly as an approval does, so the product can say "you left it for later" rather than "nobody answered". Executors read the LATEST row for the act and branch on decision.

Requires onboarding:attest itself — never in the bootstrap default set, never implied by empresas:write (ADR-0012 §3-4). The canonical form of an approval is the hosted page (POST /onboarding/steps/\{step\}/approve with the link token); this is the integrator door for a decision collected in their own flow.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/steps/{step}/approve \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"act":"…","decision":"approve"}'

Parameters

Body

GET /empresas/{empresa_id}/onboarding/certification

The set de pruebas - what was uploaded, what is missing, what the SII said

One read, not four. A certification is a bounded thing - one set file, one input document, a handful of envios across at most three rounds - and splitting it would make the obvious screen four round trips whose answers can disagree.

TWO FIELDS THAT LOOK ALIKE AND ARE OPPOSITE. envios[].estado is the ENVIO estado, where SOK means "envio recibido" - arrived, not judged. envios[].verdict is the SET verdict, where SOK means the set was APPROVED. Same three letters, opposite consequences, which is why they are two fields and never merged.

envios[].dry_run: true means the envelope was built and NOT sent. submittable is null until a build has happened at all, which is not the same as false.

problems[].message may be null: the sentences live in the build artifact beside the record, and when it cannot be read the response degrades to codes rather than failing. The code is always there.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/certification \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

POST /empresas/{empresa_id}/onboarding/certification/set_file

Upload the set de pruebas the SII issued for this empresa

The SII issues the set .txt per taxpayer when it accepts the postulacion. Nothing downloads it for you; this is how the bytes get in.

MULTIPART, NOT BASE64 IN JSON. The file is ISO-8859-1 and its accents are part of the document - Cajon and Panuelo are two of the items the SII reported as reparos when theirs were lost. Multipart hands us the bytes; a JSON string would already have been through somebody's idea of a text encoding by the time we saw it. The bytes are stored verbatim and never re-encoded. Limit: 1 MB.

Bytes that are not a set de pruebas are refused with 422 set_file_unrecognized and NOTHING is stored - a portal login page parsed as an empty set would report the empresa as having no casos, which is a different thing from having no set file.

A set that IS recognised is stored even when parts of it were not understood; those appear in problems[].

This endpoint does not run a round, does not open a socket to the SII and does not spend a folio. The round is the engine's, on its own clock.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/certification/set_file \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -F "file=…"

Parameters

Body (multipart/form-data)

POST /empresas/{empresa_id}/onboarding/certification/inputs

Supply the facts the set de pruebas does not carry

The set states several things by implication and never spells them out: who issued each purchase in the libro de compras, what the CodRef-2 correction says, which factura invoiced a guia the set marks "facturada", the factor de proporcionalidad, the SII-issued folio de notificacion, and - for a boleta round - the abbreviated unidades and ten everyday boletas. Each one is a deliberate refusal in the engine: the round reports what it needs rather than inventing a value and spending folios on a document the SII will reject.

THE MERGE IS PER TOP-LEVEL SLOT: absent keeps, null clears, present replaces WHOLE. Restating proveedores restates all of them - which is what a form submits and the only way to REMOVE one. A deep merge would leave the row you deleted in the next libro.

NOTHING IS WRITTEN WHEN ANYTHING IS INVALID, not even the valid half: a partial write leaves the empresa in a state nobody asked for and a round that refuses for a reason you believe you already fixed. 400 certification_input_invalid carries EVERY problem in error.details.problems, not the first. It may also refuse over a value you did not send, when the stored document your patch merges into is itself invalid.

ONE SLOT IS PREFILLED: libro_guias.folio_notificacion defaults to 3, the number continuing the 1 and 2 the libro de ventas and the libro de compras carry. LibroGuia_v10.xsd makes the element mandatory where the IECV's is optional, so it cannot simply be omitted, and a round that goes out on the default says so in a notice. libro_boleta_folio_notificacion has no default and will not get one: it is an SII-issued number answering a specific notificacion and nothing can derive it.

curl -sS -X POST https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/certification/inputs \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"receptor":{"rut":"76543212-K"},"giro_recep_emisor":"…"}'

Parameters

Body

GET /empresas/{empresa_id}/onboarding/evidence

The rendicion de cuentas - what we did on the empresa's behalf

Clausula 4.4 of the mandato obliges us to render account of what we did on the customer's behalf. Every act the onboarding pipeline performs is kept as an artifact, and this reads them back, newest first.

retention_until is on every row and is six years from the act - the Codigo Tributario's prescripcion extraordinaria plus its conservation duty, which is also the retention purpose under Ley 21.719. On revocation or traspaso the record freezes read-only and is offered as an export; it is never purged early.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/evidence \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

GET /empresas/{empresa_id}/onboarding/evidence/export

The rendicion de cuentas as one CSV file

The same rows the list endpoint serves, complete in one response, as a file you can hand to a customer, an accountant or a lawyer. The retention ruling says that on revocation or traspaso we offer the customer a full export as the formal clausula 4.4 rendicion; this is that export, and it is available at any time, not only on the way out.

RFC 4180, comma-separated, UTF-8 with NO byte-order mark, CRLF line endings. The columns are the JSON object's own fields in the same order - id, empresa_id, step, tipo_dte, kind, captured_at, retention_until, sha256, bytes, content_type, detail - so storage_path is absent here exactly as it is absent there. detail travels as its compact JSON, quoted.

Paged internally and capped at 50,000 rows. When the cap is reached the response says so in Facturia-Export-Complete: false rather than serving a truncated file that looks whole; step and kind are how you narrow an export that hit it.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/onboarding/evidence/export \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

GET /empresas/{empresa_id}/automation_settings

Retrieve per-empresa automation settings

The empresa's automatic-emission toggles (auto_characterize_purchases, auto_emit_46, …), each defaulted where unset.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/automation_settings \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

PATCH /empresas/{empresa_id}/automation_settings

Update per-empresa automation settings

Every automation defaults to OFF except auto_request_folios. auto_emit_46 and auto_file_f29 are opt-in per empresa and capped.

curl -sS -X PATCH https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/automation_settings \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"object":"…","empresa_id":"…"}'

Parameters

Body

GET /empresas/{empresa_id}/branding

Read logo, default print format and footer text

Every field is filled in from the platform defaults where the empresa has set nothing, so the object always describes what a PDF will actually look like rather than only what was overridden.

curl -sS https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/branding \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parameters

Responses

PATCH /empresas/{empresa_id}/branding

Update logo, default print format and footer text

Update the panel and hosted-page branding fields (logo, colors, display name). An unknown field name is refused (422 unknown_setting), never silently ignored.

curl -sS -X PATCH https://api.facturia.cl/v1/empresas/emp_01K2R6ZC4P8QW1VN7T3MHDY9EK/branding \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"object":"…","logo_url":"…"}'

Parameters

Body