Qué recurso usar
Raúl separa la factura comercial del documento tributario electrónico (DTE). La factura conserva el cobro, las líneas, el cliente y sus eventos. El DTE conserva el folio, el XML, el TrackID y el veredicto del SII. Ambos estados se consultan por separado. Consulta el mapa de endpoints de facturas para elegir el identificador y la ruta correctos, incluidos los alias de compatibilidad.
La emisión sigue directo al SII. Raúl no envía documentos por Wasabil. En estas rutas de backoffice se requiere una sesión Better Auth con token Bearer, rol
admin y acceso al módulo Finanzas.
1. Crear un borrador comercial
POST /api/v1/billing/invoices recibe los datos comerciales y devuelve 201 con la factura en DRAFT. type, receiver_name, issue_date y due_date son obligatorios. Puedes completar line_items antes de publicar; para publicar se exige al menos una línea y un total mayor que cero.
client_id real de tu organización. unit_price está expresado en pesos chilenos enteros; discount_pct es el porcentaje de descuento de la línea. La respuesta incluye id, status, montos y líneas. Guarda el id para consultar el borrador. Si el cliente exige OC o HES, agrega la referencia antes de publicar.
La API comercial no acepta una
idempotency_key del cliente como la API de Wasabil. Un segundo POST de creación puede crear otra factura. Si pierdes la respuesta, busca primero la factura en GET /api/v1/billing/invoices antes de crear otra.2. Publicar y emitir
Cuando el borrador esté completo, llama aPOST /api/v1/billing/invoices/{id}/publish. Raúl valida receptor, líneas, total y referencias OC/HES requeridas; guarda PUBLISHED e intenta emitir el DTE automáticamente. No llames a emit-dte después de cada publish exitoso.
200 puede contener PUBLISHED si falló la emisión automática. La respuesta no significa que el SII aceptó el documento. Consulta GET /api/v1/billing/invoices/{id} y revisa status, dte_document_id y dte_documents[].local_status. Si necesitas el detalle tributario, usa GET /api/v1/dte/documents/{dteId}: allí localStatus, folio y siiTrackId aparecen en camelCase. En la factura comercial los campos usan snake_case.
3. Interpretar los estados
Puedes encontrar documentos inciertos con
GET /api/v1/dte/documents?status=SII_UPLOAD_UNCERTAIN o filtrar POST /api/v1/dte/documents/query con {"status":"SII_UPLOAD_UNCERTAIN"}. El listado responde en camelCase. El estado incierto exige revisión operativa: todavía no existe una operación pública que concilie automáticamente un upload sin TrackID.
El resumen GET /api/v1/dte/documents/by-invoice/{invoiceId}/status devuelve sii.status: "uncertain", sii.errorCode: "upload_uncertain", sii.folio y el ID del DTE. También puedes buscar los registros locales por tipo y folio con GET /api/v1/dte/documents/by-folio/{tipo}/{folio}; la existencia local por sí sola no confirma recepción por el SII.
Para un DTE SII_PENDING con TrackID, usa POST /api/v1/dte/documents/{dteId}/sync y vuelve a consultar el documento. El seguimiento puede requerir más de una consulta; TrackID no equivale a aceptación.
Errores y reintentos
La ruta
emit-dte se conserva para recuperación y está marcada como deprecada en la referencia API; propaga el error de emisión. El reintento interno utiliza una clave estable asociada a la factura y el tipo de DTE, pero la creación de facturas no ofrece idempotencia HTTP controlada por el consumidor. Nunca asumas que repetir un POST sin consultar el estado es seguro.
Alcance del contrato actual
La factura comercial permiteFACTURA o BOLETA en dte_type. El DTE directo soporta FACTURA_33, BOLETA_39 y GUIA_DESPACHO_52. Los precios de las líneas de factura se reciben en CLP enteros; unit_price_uf existe como dato opcional de línea. Esta API no expone en estas rutas los campos payment_method, currency, issue ni una idempotency_key enviados por el cliente como en Wasabil. El envío de correo, el pago y el PDF tienen sus propias rutas y estados.
Consulta la referencia OpenAPI para los campos y respuestas completos y Errores y reintentos para las demás operaciones con efectos externos.