Artefactos y enlaces públicos
PDF, XML, la copia cedible, y cómo entregarle un documento a alguien que no tiene una llave.
Los artefactos autenticados
# PDF, carta (por defecto)
curl -L https://api.facturia.cl/v1/documents/doc_01K2R7.../pdf \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA" -o factura.pdf
# Térmico 80 mm, para un POS
curl -L "https://api.facturia.cl/v1/documents/doc_01K2R7.../pdf?format=80mm" \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA" -o boleta.pdf
# Copia cedible (facturas: tipo 33 y 34)
curl -L "https://api.facturia.cl/v1/documents/doc_01K2R7.../pdf?copy=cedible" \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA" -o factura-cedible.pdf
# XML firmado, exactamente como se envió al SII (ISO-8859-1)
curl -L https://api.facturia.cl/v1/documents/doc_01K2R7.../xml \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA" -o dte.xmlformat: carta (letter — las reglas de muestras del SII están basadas en carta, no en A4) o
80mm. copy: original (por defecto), cedible o both.
Los PDF se generan en la primera solicitud y quedan cacheados; el XML existe desde el momento en que
el documento se firma. Un documento en queued todavía no tiene XML → 409 artifact_not_ready.
La copia cedible es de las facturas: tipo 33 y tipo 34. Pedir copy=cedible en cualquier otro
tipo devuelve 422 cedible_not_available.
Eso es un hecho legal antes que una decisión de producto. La Ley 19.983 art. 1 exige la copia en
toda operación "en que el vendedor o prestador del servicio esté sujeto a la obligación de emitir
factura": el gatillo es la factura, sin mencionar IVA ni afecta. La Res. Ex. SII N°14/2005 la
nombra explícitamente para "facturas de ventas y servicios exentos o no afectos", con la leyenda
FACTURA EXENTA CUADRUPLICADO COBRO EJECUTIVO. Y el Manual de Muestras Impresas §1.4 del propio
SII la exige para la Factura No Afecta o Exenta Electrónica.
Trampa
Dos límites honestos sobre la copia cedible
Somos más angostos que la ley. Los tipos 46 y 52 también son cedibles y todavía no rendereamos su layout cedible. Preferimos una restricción de producto dicha en voz alta antes que una afirmación sobre un archivo que no producimos.
La cedibilidad también depende de la forma de pago. Una factura al contado no es cedible. Este
parámetro mira solo el tipo de documento, así que te va a entregar una copia cedible para una factura
al contado cuya copia no tiene uso legal. Afinarlo exige un mapeo de FmaPago que no hemos
verificado, y adivinarlo sería peor que decir esto.
Enlaces públicos
Las URL de arriba necesitan tu llave. Para entregarle un artefacto a alguien que no tiene una — el receptor, su contador, un hilo de WhatsApp — pide un enlace público al emitir. Los dos artefactos lo soportan, en los mismos términos:
"pdf": { "format": "carta", "public": true },
"xml": { "public": true }que pueblan dos campos independientes en el documento:
"pdf_public_url": "https://ver.facturia.cl/d/8f2c1a9e4b",
"xml_public_url": "https://ver.facturia.cl/d/8f2c1a9e4b.xml"El enlace del XML no es un gemelo de conveniencia del PDF: es el artefacto que le importa a quien tiene que hacer algo con el documento. El PDF es para que una persona lea; el XML es lo que ingiere el sistema contable del receptor y lo que su contador va a pedir cuando el PDF no cuadre.
# Sin header Authorization — ese es el punto
curl -L https://ver.facturia.cl/d/8f2c1a9e4b.xml -o dte.xml
# Encender un enlace después de emitir, o rotarlo (invalida la URL anterior)
curl -X POST https://api.facturia.cl/v1/documents/doc_01K2R7.../public_links \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA" \
-H "Content-Type: application/json" \
-d '{"artifacts":["pdf","xml"],"expires_in_days":30}'
# Revocar todo lo compartido de este documento
curl -X DELETE https://api.facturia.cl/v1/documents/doc_01K2R7.../public_links \
-H "Authorization: Bearer $FACTURIA_KEY" -H "Facturia-Empresa: $EMPRESA"Vencimiento
Los enlaces son firmados, inadivinables, con vencimiento (90 días por defecto), con alcance de un artefacto de un documento, y revocables en cualquier momento.
| Unidad | Dónde | Rango |
|---|---|---|
link_expires_in_days | en el objeto pdf / xml de la emisión | 1–365, o null para no vencer |
expires_in_days | en POST /v1/documents/{document_id}/public_links | 1–365 |
link_expires_in_seconds | en el objeto pdf / xml de la emisión | 30 s – 365 días |
expires_in_seconds | en POST /v1/documents/{document_id}/public_links | 30 s – 365 días |
Los segundos ganan cuando mandas ambas unidades. Los días son la unidad correcta para un enlace que le entregas a un receptor y la incorrecta para uno que le entregas a una máquina. Usa segundos para cualquier cosa que deba estar muerta en minutos — una subida a un formulario del SII, una descarga de una sola vez en un chat.
La respuesta del minteo devuelve ambas unidades, así que un enlace de diez minutos nunca se reporta como «0 días»:
{ "expires_in_seconds": 600, "expires_in_days": 0.00694 }Qué expone y qué no
Un enlace público expone exactamente un artefacto de un documento. Nunca expone los demás documentos de la empresa, ni su metadata, ni nada de tu cuenta, y no puede escalarse a una credencial de API.
xml_public_url sirve los bytes firmados exactamente como se enviaron al SII, con
Content-Type: application/xml; charset=ISO-8859-1 — idénticos byte a byte al endpoint autenticado
/xml, porque un documento cuyos bytes cambian según la ruta es un documento cuya firma alguien va a
terminar fallando en verificar.