{"openapi":"3.0.0","info":{"title":"Notta API","version":"1.0.0","description":"Facturación electrónica chilena (SII) API-first: DTE 33/34/52/56/61, boletas 39/41, BHE, CAF y certificados."},"servers":[{"url":"https://app.notta.cl/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key Bearer token (`Authorization: Bearer ntt_prod_…`). Creala en https://app.notta.cl/app/api-keys#crear."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string"},"hint":{"type":"string"},"next_action":{"type":"string","example":"fix_body_and_retry"},"request_id":{"type":"string"},"detail":{"type":"object","additionalProperties":{"nullable":true}},"docs_url":{"type":"string"},"issues":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"Zod issues[] — solo presente en code=validation_failed"}},"required":["code","message"],"description":"Error envelope común de la API ({ code, message, hint?, next_action?, request_id? })"},"DteEmitInput":{"type":"object","properties":{"tipo_dte":{"anyOf":[{"type":"number","enum":[33]},{"type":"number","enum":[34]},{"type":"number","enum":[39]},{"type":"number","enum":[41]},{"type":"number","enum":[46]},{"type":"number","enum":[52]},{"type":"number","enum":[56]},{"type":"number","enum":[61]}]},"correo_receptor":{"type":"array","nullable":true,"items":{"type":"string","maxLength":200,"format":"email"},"minItems":1,"maxItems":5},"rut_emisor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"receptor":{"type":"object","properties":{"rut":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"razon_social":{"type":"string"},"giro":{"type":"string"},"direccion":{"type":"string"},"comuna":{"type":"string"}},"required":["rut","razon_social"]},"fecha_emision":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"items":{"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":80},"cantidad":{"type":"integer","minimum":0,"exclusiveMinimum":true},"precio_unitario":{"type":"integer"},"exento":{"type":"boolean"},"monto_item":{"type":"integer"},"descuento_pct":{"type":"number","minimum":0,"maximum":100}},"required":["nombre","cantidad","precio_unitario","exento","monto_item"]},"minItems":1,"maxItems":60},"monto_neto":{"type":"integer"},"monto_exento":{"type":"integer","minimum":0},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"descuento_global":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","enum":["descuento","recargo"]},"es_porcentaje":{"type":"boolean"},"valor":{"type":"number","minimum":0,"exclusiveMinimum":true},"glosa":{"type":"string"},"aplica_exento":{"type":"boolean"}},"required":["tipo","es_porcentaje","valor"]}},"certificate_id":{"type":"string","format":"uuid"},"emisor":{"type":"object","properties":{"giro":{"type":"string","minLength":1,"maxLength":80},"direccion":{"type":"string","minLength":1,"maxLength":70},"comuna":{"type":"string","minLength":1,"maxLength":20},"actividadEconomica":{"type":"integer","minimum":0,"exclusiveMinimum":true}}},"sii_env":{"type":"string","enum":["cert","prod"],"default":"cert"},"override_cedida":{"type":"boolean"},"forma_pago":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}]},"references":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"maxItems":40,"description":"Referencias comerciales (33/34: orden_compra/contrato/hes o tipo_doc_ref crudo) o correctivas (56/61: cod_ref ∈ {1,2,3})."}},"required":["tipo_dte","receptor","fecha_emision","items"]},"Dte56EmitInput":{"type":"object","properties":{"tipo_dte":{"type":"number","enum":[56]},"rut_emisor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"receptor":{"type":"object","properties":{"rut":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"razon_social":{"type":"string"},"giro":{"type":"string"},"direccion":{"type":"string"},"comuna":{"type":"string"}},"required":["rut","razon_social"]},"correo_receptor":{"type":"array","nullable":true,"items":{"type":"string","maxLength":200,"format":"email"},"minItems":1,"maxItems":5},"fecha_emision":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"items":{"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":80},"cantidad":{"type":"integer","minimum":0,"exclusiveMinimum":true},"precio_unitario":{"type":"integer"},"exento":{"type":"boolean"},"monto_item":{"type":"integer"},"descuento_pct":{"type":"number","minimum":0,"maximum":100}},"required":["nombre","cantidad","precio_unitario","exento","monto_item"]},"minItems":1,"maxItems":60},"references":{"type":"array","items":{"type":"object","properties":{"line_num":{"type":"integer","minimum":1,"maximum":40},"tipo_doc_ref":{"type":"integer"},"folio_ref":{"type":"integer","minimum":0,"exclusiveMinimum":true},"fecha_ref":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"cod_ref":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}]},"razon_ref":{"type":"string","minLength":1}},"required":["line_num","tipo_doc_ref","folio_ref","fecha_ref","cod_ref","razon_ref"]},"minItems":1,"maxItems":40},"nd_reason":{"type":"string","enum":["correccion_monto","reposicion_nc_anulada","interese_moratorio_contractual"]},"monto_neto":{"type":"integer"},"monto_exento":{"type":"integer","minimum":0},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"emisor":{"type":"object","properties":{"giro":{"type":"string","minLength":1,"maxLength":80},"direccion":{"type":"string","minLength":1,"maxLength":70},"comuna":{"type":"string","minLength":1,"maxLength":20},"actividadEconomica":{"type":"integer","minimum":0,"exclusiveMinimum":true}}},"certificate_id":{"type":"string","format":"uuid"},"sii_env":{"type":"string","enum":["cert","prod"],"default":"cert"}},"required":["tipo_dte","receptor","fecha_emision","items","references","nd_reason"]},"Dte61EmitInput":{"type":"object","properties":{"tipo_dte":{"type":"number","enum":[61]},"rut_emisor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"receptor":{"type":"object","properties":{"rut":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"razon_social":{"type":"string"},"giro":{"type":"string"},"direccion":{"type":"string"},"comuna":{"type":"string"}},"required":["rut","razon_social"]},"correo_receptor":{"type":"array","nullable":true,"items":{"type":"string","maxLength":200,"format":"email"},"minItems":1,"maxItems":5},"fecha_emision":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"items":{"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":80},"cantidad":{"type":"integer","minimum":0,"exclusiveMinimum":true},"precio_unitario":{"type":"integer"},"exento":{"type":"boolean"},"monto_item":{"type":"integer"},"descuento_pct":{"type":"number","minimum":0,"maximum":100}},"required":["nombre","cantidad","precio_unitario","exento","monto_item"]},"minItems":1,"maxItems":60},"references":{"type":"array","items":{"type":"object","properties":{"line_num":{"type":"integer","minimum":1,"maximum":40},"tipo_doc_ref":{"type":"integer"},"folio_ref":{"type":"integer","minimum":0,"exclusiveMinimum":true},"fecha_ref":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"cod_ref":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}]},"razon_ref":{"type":"string","minLength":1}},"required":["line_num","tipo_doc_ref","folio_ref","fecha_ref","cod_ref","razon_ref"]},"minItems":1,"maxItems":40},"monto_neto":{"type":"integer"},"monto_exento":{"type":"integer","minimum":0},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"override_cedida":{"type":"boolean"},"emisor":{"type":"object","properties":{"giro":{"type":"string","minLength":1,"maxLength":80},"direccion":{"type":"string","minLength":1,"maxLength":70},"comuna":{"type":"string","minLength":1,"maxLength":20},"actividadEconomica":{"type":"integer","minimum":0,"exclusiveMinimum":true}}},"certificate_id":{"type":"string","format":"uuid"},"sii_env":{"type":"string","enum":["cert","prod"],"default":"cert"}},"required":["tipo_dte","receptor","fecha_emision","items","references"]},"DteEmitAccepted":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"],"description":"Estado SII inicial (típicamente `queued`)"},"folio":{"type":"integer"},"tipo_dte":{"anyOf":[{"type":"number","enum":[33]},{"type":"number","enum":[34]},{"type":"number","enum":[39]},{"type":"number","enum":[41]},{"type":"number","enum":[46]},{"type":"number","enum":[52]},{"type":"number","enum":[56]},{"type":"number","enum":[61]}]},"rut_emisor":{"type":"string"},"rut_receptor":{"type":"string"},"monto_neto":{"type":"integer"},"monto_exento":{"type":"integer"},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"sii_env":{"type":"string","enum":["cert","prod"]},"sii_status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"]},"fecha_emision":{"type":"string"},"links":{"type":"object","properties":{"self":{"type":"string"},"pdf":{"type":"string"},"xml":{"type":"string"},"events":{"type":"string"}},"required":["self","pdf","xml","events"]}},"required":["id","status","folio","tipo_dte","rut_emisor","rut_receptor","monto_neto","monto_exento","iva","monto_total","sii_env","sii_status","fecha_emision","links"],"description":"DTE aceptado y encolado — el folio ya está asignado; el estado avanza async."},"DteSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"folio":{"type":"integer"},"tipo_dte":{"anyOf":[{"type":"number","enum":[33]},{"type":"number","enum":[34]},{"type":"number","enum":[39]},{"type":"number","enum":[41]},{"type":"number","enum":[46]},{"type":"number","enum":[52]},{"type":"number","enum":[56]},{"type":"number","enum":[61]}]},"rut_emisor":{"type":"string"},"rut_receptor":{"type":"string"},"monto_total":{"type":"integer"},"sii_status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"]},"fecha_emision":{"type":"string"},"created_at":{"type":"string"},"links":{"type":"object","properties":{"self":{"type":"string"}},"required":["self"]}},"required":["id","folio","tipo_dte","rut_emisor","rut_receptor","monto_total","sii_status","fecha_emision","created_at","links"]},"DteListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DteSummary"}},"next_cursor":{"type":"string","nullable":true}},"required":["data","next_cursor"]},"DteDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"folio":{"type":"integer"},"tipo_dte":{"anyOf":[{"type":"number","enum":[33]},{"type":"number","enum":[34]},{"type":"number","enum":[39]},{"type":"number","enum":[41]},{"type":"number","enum":[46]},{"type":"number","enum":[52]},{"type":"number","enum":[56]},{"type":"number","enum":[61]}]},"rut_emisor":{"type":"string"},"rut_receptor":{"type":"string"},"razon_social_receptor":{"type":"string","nullable":true},"monto_neto":{"type":"integer"},"monto_exento":{"type":"integer"},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"sii_env":{"type":"string","enum":["cert","prod"]},"sii_status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"]},"sii_glosa":{"type":"string","nullable":true},"track_id":{"type":"integer","nullable":true},"fecha_emision":{"type":"string"},"created_at":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"nombre":{"type":"string"},"descripcion":{"type":"string","nullable":true},"cantidad":{"type":"number"},"precio_unitario":{"type":"number"},"monto_item":{"type":"integer"},"exento":{"type":"boolean"}},"required":["position","nombre","descripcion","cantidad","precio_unitario","monto_item","exento"]}},"links":{"type":"object","properties":{"self":{"type":"string"},"pdf":{"type":"string"},"xml":{"type":"string"},"events":{"type":"string"}},"required":["self","pdf","xml","events"]}},"required":["id","folio","tipo_dte","rut_emisor","rut_receptor","razon_social_receptor","monto_neto","monto_exento","iva","monto_total","sii_env","sii_status","sii_glosa","track_id","fecha_emision","created_at","items","links"]},"DteRefreshAccepted":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["refresh_enqueued"]}},"required":["id","status"]},"DteEventsFeed":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"],"description":"Estado en esta transición (queued/sending/EPR/RPR/RFR/RCT/RSC…)"},"at":{"type":"string","description":"ISO-8601 del momento observado"},"source":{"type":"string","enum":["local","sii"],"description":"Origen: transición local o estado reportado por el SII"},"glosa":{"type":"string","nullable":true,"description":"Motivo que reporta el SII (rechazo/reparo); null si no aplica"}},"required":["status","at","source","glosa"]}},"links":{"type":"object","properties":{"self":{"type":"string"},"dte":{"type":"string"}},"required":["self","dte"]}},"required":["data","links"]},"DteMuestrasSendResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"sent":{"type":"integer","description":"Cantidad de PDFs de muestra adjuntados en el correo al SII"},"sentAt":{"type":"string","description":"ISO timestamp persistido en metadata.muestras.sentAt"}},"required":["sent","sentAt"]}},"required":["data"]},"BoletaEmitInput":{"anyOf":[{"type":"object","properties":{"tipo_dte":{"type":"number","enum":[39]},"rut_emisor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"rut_receptor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"razon_social_receptor":{"type":"string","minLength":1},"fecha_emision":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"items":{"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":80},"cantidad":{"type":"integer","minimum":0,"exclusiveMinimum":true},"precio_unitario":{"type":"integer"},"exento":{"type":"boolean"},"monto_item":{"type":"integer"},"descuento_pct":{"type":"number","minimum":0,"maximum":100}},"required":["nombre","cantidad","precio_unitario","exento","monto_item"]},"minItems":1,"maxItems":60},"monto_neto":{"type":"integer"},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"certificate_id":{"type":"string","format":"uuid"},"sii_env":{"type":"string","enum":["cert","prod"],"default":"cert"}},"required":["tipo_dte","rut_emisor","fecha_emision","items"]},{"type":"object","properties":{"tipo_dte":{"type":"number","enum":[41]},"rut_emisor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"rut_receptor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"razon_social_receptor":{"type":"string","minLength":1},"fecha_emision":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"items":{"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":80},"cantidad":{"type":"integer","minimum":0,"exclusiveMinimum":true},"precio_unitario":{"type":"integer"},"exento":{"type":"boolean"},"monto_item":{"type":"integer"},"descuento_pct":{"type":"number","minimum":0,"maximum":100}},"required":["nombre","cantidad","precio_unitario","exento","monto_item"]},"minItems":1,"maxItems":60},"monto_exento":{"type":"integer","minimum":0,"exclusiveMinimum":true},"monto_total":{"type":"integer","minimum":0,"exclusiveMinimum":true},"certificate_id":{"type":"string","format":"uuid"},"sii_env":{"type":"string","enum":["cert","prod"],"default":"cert"}},"required":["tipo_dte","rut_emisor","fecha_emision","items"]}]},"BoletaBatchEmitInput":{"type":"object","properties":{"batch_idempotency_key":{"type":"string","minLength":1,"maxLength":128},"boletas":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"tipo_dte":{"type":"number","enum":[39]},"rut_emisor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"rut_receptor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"razon_social_receptor":{"type":"string","minLength":1},"fecha_emision":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"items":{"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":80},"cantidad":{"type":"integer","minimum":0,"exclusiveMinimum":true},"precio_unitario":{"type":"integer"},"exento":{"type":"boolean"},"monto_item":{"type":"integer"},"descuento_pct":{"type":"number","minimum":0,"maximum":100}},"required":["nombre","cantidad","precio_unitario","exento","monto_item"]},"minItems":1,"maxItems":60},"monto_neto":{"type":"integer"},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"certificate_id":{"type":"string","format":"uuid"},"sii_env":{"type":"string","enum":["cert","prod"],"default":"cert"}},"required":["tipo_dte","rut_emisor","fecha_emision","items"]},{"type":"object","properties":{"tipo_dte":{"type":"number","enum":[41]},"rut_emisor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"rut_receptor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"razon_social_receptor":{"type":"string","minLength":1},"fecha_emision":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"items":{"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":80},"cantidad":{"type":"integer","minimum":0,"exclusiveMinimum":true},"precio_unitario":{"type":"integer"},"exento":{"type":"boolean"},"monto_item":{"type":"integer"},"descuento_pct":{"type":"number","minimum":0,"maximum":100}},"required":["nombre","cantidad","precio_unitario","exento","monto_item"]},"minItems":1,"maxItems":60},"monto_exento":{"type":"integer","minimum":0,"exclusiveMinimum":true},"monto_total":{"type":"integer","minimum":0,"exclusiveMinimum":true},"certificate_id":{"type":"string","format":"uuid"},"sii_env":{"type":"string","enum":["cert","prod"],"default":"cert"}},"required":["tipo_dte","rut_emisor","fecha_emision","items"]}]},"minItems":1,"maxItems":1000}},"required":["batch_idempotency_key","boletas"]},"BoletaEmitAccepted":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_dte":{"anyOf":[{"type":"number","enum":[39]},{"type":"number","enum":[41]}]},"folio":{"type":"integer"},"status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"]},"sii_status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"]},"rut_emisor":{"type":"string"},"rut_receptor":{"type":"string","nullable":true},"monto_neto":{"type":"integer"},"monto_exento":{"type":"integer"},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"fecha_emision":{"type":"string"},"sii_env":{"type":"string","enum":["cert","prod"]},"links":{"type":"object","properties":{"self":{"type":"string"},"xml":{"type":"string"}},"required":["self","xml"]}},"required":["id","tipo_dte","folio","status","sii_status","rut_emisor","rut_receptor","monto_neto","monto_exento","iva","monto_total","fecha_emision","sii_env","links"]},"BoletaSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_dte":{"anyOf":[{"type":"number","enum":[39]},{"type":"number","enum":[41]}]},"folio":{"type":"integer"},"rut_emisor":{"type":"string"},"rut_receptor":{"type":"string","nullable":true},"monto_total":{"type":"integer"},"sii_status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"]},"fecha_emision":{"type":"string"},"created_at":{"type":"string"},"links":{"type":"object","properties":{"self":{"type":"string"}},"required":["self"]}},"required":["id","tipo_dte","folio","rut_emisor","rut_receptor","monto_total","sii_status","fecha_emision","created_at","links"]},"BoletaListResponse":{"type":"object","properties":{"boletas":{"type":"array","items":{"$ref":"#/components/schemas/BoletaSummary"}},"next_cursor":{"type":"string","nullable":true}},"required":["boletas","next_cursor"]},"BoletaDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_dte":{"anyOf":[{"type":"number","enum":[39]},{"type":"number","enum":[41]}]},"folio":{"type":"integer"},"rut_emisor":{"type":"string"},"rut_receptor":{"type":"string","nullable":true},"monto_neto":{"type":"integer"},"monto_exento":{"type":"integer"},"iva":{"type":"integer"},"monto_total":{"type":"integer"},"sii_status":{"type":"string","enum":["queued","sending","awaiting_sii","SOK","CRT","EPR","RPR","aceptado_con_reparos","RFR","RCT","RSC","stuck"]},"sii_glosa":{"type":"string","nullable":true},"track_id":{"type":"integer","nullable":true},"fecha_emision":{"type":"string"},"sii_env":{"type":"string","enum":["cert","prod"]},"created_at":{"type":"string"},"links":{"type":"object","properties":{"self":{"type":"string"},"xml":{"type":"string"}},"required":["self","xml"]}},"required":["id","tipo_dte","folio","rut_emisor","rut_receptor","monto_neto","monto_exento","iva","monto_total","sii_status","sii_glosa","track_id","fecha_emision","sii_env","created_at","links"]},"BoletaBatchAccepted":{"type":"object","properties":{"batchId":{"type":"string","format":"uuid"},"queued":{"type":"integer","description":"Cantidad de boletas encoladas en el batch"}},"required":["batchId","queued"]},"BoletaBatchStatus":{"type":"object","properties":{"batchId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","completed","partial","failed"]},"total":{"type":"integer"},"queued":{"type":"integer"},"sending":{"type":"integer"},"done":{"type":"integer"},"failed":{"type":"integer"},"createdAt":{"type":"string"},"completedAt":{"type":"string","nullable":true}},"required":["batchId","status","total","queued","sending","done","failed","createdAt","completedAt"]},"BheEmitInput":{"type":"object","properties":{"rut_emisor":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"receptor":{"type":"object","properties":{"rut":{"type":"string","pattern":"^\\d{1,8}-[\\dKk]$"},"razon_social":{"type":"string"},"persona_natural_sin_giro":{"type":"boolean"}},"required":["rut","razon_social","persona_natural_sin_giro"]},"fecha_emision":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"monto_bruto":{"type":"integer","minimum":0,"exclusiveMinimum":true},"descripcion":{"type":"string","minLength":1,"maxLength":1000},"sii_env":{"type":"string","enum":["cert","prod"],"default":"cert"}},"required":["rut_emisor","receptor","fecha_emision","monto_bruto","descripcion"]},"BheAnularInput":{"type":"object","properties":{"folio":{"type":"integer","minimum":0,"exclusiveMinimum":true},"razon":{"type":"string","minLength":1,"maxLength":250}},"required":["folio","razon"]},"BheEmitAccepted":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"Estado SII inicial (típicamente `queued`)"},"sii_status":{"type":"string"},"tasa_retencion":{"type":"number","description":"Tasa retención 2ª categoría vigente (Ley 21.420), p.ej. 14.5"},"monto_retencion":{"type":"integer"},"monto_liquido":{"type":"integer"},"period_year":{"type":"integer"},"period_month":{"type":"integer"},"links":{"type":"object","properties":{"self":{"type":"string"}},"required":["self"]}},"required":["id","status","sii_status","tasa_retencion","monto_retencion","monto_liquido","period_year","period_month","links"]},"BheDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"folio":{"type":"integer","nullable":true},"period_year":{"type":"integer"},"period_month":{"type":"integer"},"rut_emisor":{"type":"string"},"rut_receptor":{"type":"string"},"razon_social_receptor":{"type":"string"},"receptor_persona_natural_sin_giro":{"type":"boolean"},"descripcion":{"type":"string"},"monto_bruto":{"type":"integer"},"tasa_retencion":{"type":"string","description":"Numeric crudo de la DB serializado como string, p.ej. \"14.5000\" (a diferencia del POST, que devuelve number)"},"monto_retencion":{"type":"integer"},"monto_liquido":{"type":"integer"},"sii_status":{"type":"string"},"sii_env":{"type":"string","enum":["cert","prod"]},"anulada":{"type":"boolean"},"anulada_at":{"type":"string","nullable":true},"anulada_reason":{"type":"string","nullable":true},"track_id":{"type":"integer","nullable":true},"fecha_emision":{"type":"string"},"created_at":{"type":"string"},"links":{"type":"object","properties":{"self":{"type":"string"}},"required":["self"]}},"required":["id","folio","period_year","period_month","rut_emisor","rut_receptor","razon_social_receptor","receptor_persona_natural_sin_giro","descripcion","monto_bruto","tasa_retencion","monto_retencion","monto_liquido","sii_status","sii_env","anulada","anulada_at","anulada_reason","track_id","fecha_emision","created_at","links"]},"BheListResponse":{"type":"object","properties":{"bhes":{"type":"array","items":{"$ref":"#/components/schemas/BheDetail"}},"next_cursor":{"type":"string","nullable":true}},"required":["bhes","next_cursor"]},"BheAnularResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"anulada":{"type":"boolean"},"folio":{"type":"integer","nullable":true}},"required":["id","anulada","folio"]},"CafUploadInput":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"XML CAF descargado del SII (rango de folios)"},"tipo_esperado":{"type":"integer","nullable":true,"description":"Si se envía, rechaza el upload cuando el tipo del CAF no coincide (caf.wrong_tipo)"},"certificate_id":{"type":"string","format":"uuid","description":"Default: el primer certificado activo del org"}},"required":["file"]},"CafUploadResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tipo_dte":{"type":"integer"},"folio_desde":{"type":"integer"},"folio_hasta":{"type":"integer"},"remaining":{"type":"integer"},"low_folios":{"type":"boolean"}},"required":["id","tipo_dte","folio_desde","folio_hasta","remaining","low_folios"]}},"required":["data"]},"CafListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rut_emisor":{"type":"string"},"tipo_dte":{"type":"integer"},"folio_desde":{"type":"integer"},"folio_hasta":{"type":"integer"},"next_folio":{"type":"integer"},"remaining":{"type":"integer"},"low_folios":{"type":"boolean"},"not_after":{"type":"string"},"exhausted":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","rut_emisor","tipo_dte","folio_desde","folio_hasta","next_folio","remaining","low_folios","not_after","exhausted","created_at"]}}},"required":["data"]},"CafDeleteResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"dtes_deleted":{"type":"integer"}},"required":["id","deleted","dtes_deleted"]}},"required":["data"]},"CafRequestInput":{"type":"object","properties":{"tipo":{"type":"integer","description":"Tipo DTE a timbrar. Uno de: 33, 34, 46, 52, 56, 61 (NO boletas 39/41 — pipeline REST propio).","example":33},"cantidad":{"type":"integer","minimum":1,"maximum":1000,"description":"Override opcional de la cantidad de folios a solicitar (default por-tipo). 1–1000."}},"required":["tipo"]},"CafRequestResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"requested":{"type":"boolean","description":"true si se solicitó un rango nuevo al SII"},"reason":{"type":"string","description":"p.ej. no_cafs_missing cuando ya hay folios suficientes y no se pidió nada"},"cafs":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"integer"},"estado":{"type":"string","description":"requested | cooldown | prod_not_certified | rejected | …"}},"required":["tipo","estado"]}}},"required":["requested","cafs"]}},"required":["data"]},"CertificateUploadInput":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Certificado digital .p12/.pfx"},"password":{"type":"string","description":"Contraseña del .p12 — se cifra junto al blob (KMS per-org)"},"label":{"type":"string"},"rut_owner":{"type":"string","description":"RUT del titular del certificado (BODY-DV)"},"subject_cn":{"type":"string"},"issuer_cn":{"type":"string"}},"required":["file","password","label"]},"CertificateUploadResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Usalo como header X-Cert-Id en /dtes y /boletas"},"label":{"type":"string"},"not_after":{"type":"string"}},"required":["id","label","not_after"]}},"required":["data"]},"CertificateListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"rut_owner":{"type":"string"},"subject_cn":{"type":"string"},"not_before":{"type":"string"},"not_after":{"type":"string"},"created_at":{"type":"string"}},"required":["id","label","rut_owner","subject_cn","not_before","not_after","created_at"]}}},"required":["data"]},"CertificateDeleteResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"}},"required":["id","deleted"]}},"required":["data"]},"ProfileResponse":{"type":"object","properties":{"giro":{"type":"string","minLength":1,"maxLength":80},"direccion":{"type":"string","minLength":1,"maxLength":70},"comuna":{"type":"string","minLength":1,"maxLength":20},"actividadEconomica":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"description":"Perfil del emisor tal como se persiste — todos los campos son opcionales."},"SiiCertStateResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"journey":{"type":"object","additionalProperties":{"nullable":true},"description":"Journey de certificación derivado del snapshot scrapeado."},"scrapedAt":{"type":"string","nullable":true,"description":"ISO del último scrape, o null si nunca se scrapeó."}},"required":["journey","scrapedAt"]}},"required":["data"]},"SiiReadinessResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean","description":"true si la certificación SII está completa."},"postulationStep":{"type":"string"},"currentPhase":{"type":"string"},"certSubStates":{"type":"object","additionalProperties":{"nullable":true}}},"required":["ok","postulationStep","currentPhase","certSubStates"]}},"required":["data"]},"SiiRecentDocumentsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"Últimas ventas 33/34 de la org (máx 50), env-scopeadas por `api_keys.sii_env` (Bearer) o la cookie de env (browser)."}},"required":["data"]},"SiiDocumentTemplateResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"tipo_dte":{"type":"number","example":33},"receptor":{"type":"object","properties":{"rut":{"type":"string"},"razon":{"type":"string"}},"required":["rut","razon"]},"items":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["tipo_dte","receptor","items"]}},"required":["data"]},"SetPruebasEnvelope":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"nullable":true}}},"required":["data"],"description":"Envelope { data } del pipeline Set de Pruebas — shape interno rico, ver route handlers."},"RcofSendInput":{"type":"object","properties":{"fecha":{"type":"string","description":"YYYY-MM-DD, requerido (rcof.fecha_required si falta/vacío)"}},"required":["fecha"]},"RcofSendAccepted":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"fecha":{"type":"string"},"sec_envio":{"type":"integer","description":"Incrementa por cada reenvío/corrección del mismo día"},"status":{"type":"string","enum":["queued"]}},"required":["ok","fecha","sec_envio","status"]},"RcofEnvioSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fecha":{"type":"string"},"sec_envio":{"type":"integer"},"estado":{"type":"string","enum":["queued","EPR","DOK","RPR","aceptado_con_reparos","RFR","RCT","RSC","error"],"description":"Lifecycle real: queued → EPR → terminal (DOK|RPR|aceptado_con_reparos|RFR|RCT|RSC|error)"},"track_id":{"type":"string","nullable":true},"sii_glosa":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","fecha","sec_envio","estado","track_id","sii_glosa","created_at"]},"RcofListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RcofEnvioSummary"}}},"required":["data"]},"RcofDetailResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fecha":{"type":"string"},"sec_envio":{"type":"integer"},"estado":{"type":"string","enum":["queued","EPR","DOK","RPR","aceptado_con_reparos","RFR","RCT","RSC","error"],"description":"Lifecycle real: queued → EPR → terminal (DOK|RPR|aceptado_con_reparos|RFR|RCT|RSC|error)"},"track_id":{"type":"string","nullable":true},"sii_glosa":{"type":"string","nullable":true},"summary":{"type":"object","nullable":true,"properties":{"orgId":{"type":"string","format":"uuid"},"fecha":{"type":"string"},"resumenes":{"type":"array","items":{"type":"object","properties":{"tipoDocumento":{"anyOf":[{"type":"number","enum":[39]},{"type":"number","enum":[41]}]},"mntNeto":{"type":"integer"},"mntIva":{"type":"integer"},"mntExento":{"type":"integer"},"mntTotal":{"type":"integer"},"foliosEmitidos":{"type":"integer"},"foliosAnulados":{"type":"integer"},"foliosUtilizados":{"type":"integer"},"rangoUtilizados":{"type":"array","items":{"type":"object","properties":{"inicial":{"type":"integer"},"final":{"type":"integer"}},"required":["inicial","final"]}},"rangoAnulados":{"type":"array","items":{"type":"object","properties":{"inicial":{"type":"integer"},"final":{"type":"integer"}},"required":["inicial","final"]}}},"required":["tipoDocumento","mntNeto","mntIva","mntExento","mntTotal","foliosEmitidos","foliosAnulados","foliosUtilizados","rangoUtilizados","rangoAnulados"]}}},"required":["orgId","fecha","resumenes"],"description":"JSONB persistido tal cual al crear el envío (camelCase, sin re-serializar)"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","fecha","sec_envio","estado","track_id","sii_glosa","summary","created_at","updated_at"]}},"required":["data"]},"ReadinessResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"phase":{"type":"string"},"siiStep":{"type":"string"},"targetTypes":{"type":"array","items":{"type":"integer"}},"assignedUnsupported":{"type":"array","items":{"type":"integer"}},"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["ready","missing","blocked","pending"]},"detail":{"type":"string"},"cta":{"type":"object","properties":{"label":{"type":"string"},"href":{"type":"string"}},"required":["label","href"]}},"required":["key","label","status"]}},"complete":{"type":"boolean"}},"required":["phase","siiStep","targetTypes","assignedUnsupported","items","complete"]}},"required":["data"]},"RcvSyncInput":{"type":"object","properties":{"periodo":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"type":{"type":"string","enum":["received","issued","both"],"default":"both"},"rut":{"type":"string","minLength":1},"force":{"type":"boolean"}},"required":["periodo","rut"]},"RcvSyncAccepted":{"type":"object","properties":{"snapshot_id":{"type":"string","format":"uuid"},"from_cache":{"type":"boolean"}},"required":["snapshot_id","from_cache"]},"RcvSnapshot":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rut":{"type":"string"},"period":{"type":"string"},"period_year":{"type":"integer"},"period_month":{"type":"integer"},"type":{"type":"string","enum":["received","issued","both"]},"record_count":{"type":"integer"},"source":{"type":"string"},"sii_env":{"type":"string","enum":["cert","prod"]},"parsed_json":{"nullable":true,"description":"Payload RCV parseado, forma varía por type"},"synced_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","rut","period","period_year","period_month","type","record_count","source","sii_env","synced_at","created_at"]},"RcvListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RcvSnapshot"}}},"required":["data"]},"SuggestedTypesResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"catalog":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"integer"},"label":{"type":"string"},"preselected":{"type":"boolean"}},"required":["tipo","label","preselected"]}},"assignedUnsupported":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"integer"},"label":{"type":"string"}},"required":["tipo","label"]}},"hasPostulation":{"type":"boolean"}},"required":["catalog","assignedUnsupported","hasPostulation"]}},"required":["data"]},"TargetTypesResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"tipos":{"type":"array","items":{"type":"integer"}}},"required":["tipos"]}},"required":["data"]},"BillingPlanStatus":{"type":"object","properties":{"planId":{"type":"string","enum":["free","starter","growth","pro","enterprise"]},"usedThisMonth":{"type":"integer","description":"Documentos (DTE+BHE) usados este mes en prod."},"limit":{"type":"integer","description":"Cupo mensual del plan activo (o free si no hay suscripción)."}},"required":["planId","usedThisMonth","limit"]},"BillingSubscribeInput":{"type":"object","properties":{"planId":{"type":"string","enum":["free","starter","growth","pro","enterprise"]},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128},"paymentMethod":{"type":"object","properties":{"type":{"type":"string","enum":["mercadopago"]},"mp_payer_email":{"type":"string","minLength":1,"maxLength":200,"format":"email"},"card_token":{"type":"string","minLength":1,"maxLength":200},"payment_method_id":{"type":"string","minLength":1,"maxLength":50}},"required":["type","mp_payer_email"]}},"required":["planId","paymentMethod"]},"BillingSubscribeResult":{"type":"object","properties":{"subscriptionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","trial"]}},"required":["subscriptionId","status"]}},"parameters":{}},"paths":{"/dtes":{"post":{"tags":["dtes"],"summary":"Emitir DTE (33/34/52/56/61)","description":"Encola la emisión (firma + upload SII) y responde 202 con el folio asignado. Requiere headers `Idempotency-Key` y `X-Cert-Id` (UUID devuelto por POST /certificates). tipo_dte 56 y 61 usan sus schemas dedicados (references obligatorias). Para factura 33/34, receptor.giro / receptor.direccion / receptor.comuna y forma_pago (1=Contado, 2=Crédito, 3=Sin costo) son obligatorios (validación condicional por tipo; no expresada en el schema JSON required).","parameters":[{"schema":{"type":"string","description":"Obligatorio. UUIDv7 generado client-side; replays devuelven el mismo documento."},"required":true,"name":"Idempotency-Key","in":"header"},{"schema":{"type":"string","format":"uuid","description":"Certificado digital con el que se firma. Obligatorio en verbos mutantes."},"required":true,"name":"X-Cert-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DteEmitInput"},{"$ref":"#/components/schemas/Dte56EmitInput"},{"$ref":"#/components/schemas/Dte61EmitInput"}]}}}},"responses":{"202":{"description":"DTE encolado — folio asignado, estado avanza async (poll links.self)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DteEmitAccepted"}}}},"400":{"description":"Idempotency-Key faltante, JSON inválido, X-Cert-Id faltante o validation_failed (con issues[])","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Cuota del plan free agotada (billing.free_tier_exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene scope dte:write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflicto de negocio (p.ej. NC sobre factura cedida sin override_cedida)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Regla SII violada (CAF agotado, plazo NC 6 meses, interés moratorio en ND, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listDtes","tags":["dtes"],"summary":"Listar DTEs","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Default 20, máx 100"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["folio","monto_total","fecha_emision","sii_status","created_at"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"dir","in":"query"}],"responses":{"200":{"description":"Lista de DTEs del org (orden default: created_at desc)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DteListResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dtes/{id}":{"get":{"operationId":"getDte","tags":["dtes"],"summary":"Detalle de un DTE","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"DTE con items por línea","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DteDetail"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"DTE inexistente (o de otra org)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dtes/{id}/pdf":{"get":{"tags":["dtes"],"summary":"Representación impresa (PDF con timbre PDF417)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"PDF de la representación impresa (NF SII)","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"DTE inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"dte.pdf.not_signed — aún sin TED; poll links.xml y reintentá","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dtes/{id}/xml":{"get":{"tags":["dtes"],"summary":"XML firmado del DTE","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"XML del DTE (firmado cuando está disponible; verificá la XML-DSig embebida)","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"not_found, o dte.xml.not_yet_available si el workflow aún no firmó","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dtes/{id}/events":{"get":{"operationId":"getDteEvents","tags":["dtes"],"summary":"Feed de cambios de estado del DTE (para polling)","description":"Historia cronológica de transiciones de estado (queued → sending → EPR/RPR/RFR/RCT/RSC) con la glosa del SII. Endpoint canónico para los consumidores que hacen polling del estado. NO es un webhook: no hay push.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Feed de transiciones de estado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DteEventsFeed"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"DTE inexistente (o de otra org)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dtes/{id}/refresh-status":{"post":{"tags":["dtes"],"summary":"Forzar re-consulta del estado en el SII","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"Poll de estado encolado — el estado se persiste async en el DTE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DteRefreshAccepted"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"DTE inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"dte.refresh_status.no_track_id (aún sin upload) o dte.refresh_status.no_cert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dtes/muestras":{"get":{"tags":["dtes"],"summary":"ZIP de Muestras Impresas (certificación SII)","description":"Arma un ZIP con un PDF por cada DTE firmado (33/34/56/61) del org para el lote de Muestras Impresas del SII. `?source=set_pruebas` lo acota al set de pruebas.","parameters":[{"schema":{"type":"string","enum":["set_pruebas"],"description":"Acota el lote a los DTE emitidos vía set de pruebas"},"required":false,"name":"source","in":"query"}],"responses":{"200":{"description":"ZIP con un PDF por DTE firmado","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"dte.muestras.empty — no hay DTE firmados (33/34/56/61) para el lote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dtes/muestras/send":{"post":{"tags":["dtes"],"summary":"Enviar Muestras Impresas al SII por correo","description":"Notta arma y envía el correo de Muestras Impresas a `sii_dte_impresos@sii.cl` con un PDF por DTE firmado adjunto y el RUT del emisor en el asunto. Acción de salida: solo ocurre al confirmar.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Requerido por el middleware en verbos mutantes de /dtes."},"required":true,"name":"X-Cert-Id","in":"header"}],"responses":{"200":{"description":"Correo enviado — sentAt persistido en el avance de certificación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DteMuestrasSendResponse"}}}},"400":{"description":"cert_id_missing — falta el header X-Cert-Id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"dte.muestras.no_samples, dte.muestras.too_large (>3MB) o dte.muestras.send_not_configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"501":{"description":"dte.muestras.send_not_wired — envío no configurado en este entorno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/boletas":{"post":{"tags":["boletas"],"summary":"Emitir boleta electrónica (39/41)","description":"Pipeline REST del SII (distinto del SOAP de facturas). Requiere `Idempotency-Key` y `X-Cert-Id`.","parameters":[{"schema":{"type":"string","description":"Obligatorio. UUIDv7 generado client-side; replays devuelven el mismo documento."},"required":true,"name":"Idempotency-Key","in":"header"},{"schema":{"type":"string","format":"uuid","description":"Certificado digital con el que se firma."},"required":true,"name":"X-Cert-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletaEmitInput"}}}},"responses":{"202":{"description":"Boleta encolada — folio asignado, upload REST corre async","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletaEmitAccepted"}}}},"400":{"description":"Idempotency-Key faltante o JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Cuota del plan free agotada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Regla violada (p.ej. boleta 41 con items afectos, CAF agotado)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listBoletas","tags":["boletas"],"summary":"Listar boletas","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Default 20, máx 100"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Boletas del org (tipo_dte ∈ {39, 41})","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletaListResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/boletas/batch":{"post":{"tags":["boletas"],"summary":"Emitir batch de boletas (máx 1000)","description":"Idempotencia por `batch_idempotency_key` (body) — reenviar el mismo batch devuelve el mismo batchId. El progreso se consulta con GET /boletas/batch/{id}.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Certificado digital con el que se firma."},"required":true,"name":"X-Cert-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletaBatchEmitInput"}}}},"responses":{"202":{"description":"Batch aceptado y encolado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletaBatchAccepted"}}}},"400":{"description":"JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Cuota del plan free agotada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"validation_error o boleta.batch.exceeds_max (> 1000 boletas)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/boletas/batch/{id}":{"get":{"tags":["boletas"],"summary":"Estado de un batch de boletas","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Conteos de progreso por estado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletaBatchStatus"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Batch inexistente (o de otra org)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/boletas/{id}":{"get":{"operationId":"getBoleta","tags":["boletas"],"summary":"Detalle de una boleta","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Boleta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoletaDetail"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Boleta inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/boletas/{id}/xml":{"get":{"tags":["boletas"],"summary":"XML firmado de la boleta","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"XML de la boleta","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"not_found, o boleta.xml.not_yet_available si aún no firmó","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bhe":{"post":{"tags":["bhe"],"summary":"Emitir Boleta de Honorarios Electrónica","description":"Pipeline REST loa.sii.cl con clave tributaria custodiada — NO requiere certificado digital ni X-Cert-Id. La retención 2ª categoría se calcula server-side según el año (Ley 21.420).","parameters":[{"schema":{"type":"string","description":"Obligatorio. UUIDv7 generado client-side; replays devuelven el mismo documento."},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BheEmitInput"}}}},"responses":{"202":{"description":"BHE encolada — retención calculada, upload corre async","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BheEmitAccepted"}}}},"400":{"description":"Idempotency-Key faltante o JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Cuota del plan free agotada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validación fallida (RUT inválido, monto_bruto ≤ 0, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listBhe","tags":["bhe"],"summary":"Listar BHEs","parameters":[{"schema":{"type":"integer","nullable":true},"required":false,"name":"period_year","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":12},"required":false,"name":"period_month","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"anulada","in":"query"},{"schema":{"type":"string"},"required":false,"name":"sii_status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Default 50, máx 100"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["folio","period","monto_bruto","monto_liquido","sii_status","created_at"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"dir","in":"query"}],"responses":{"200":{"description":"BHEs del org, filtrables por período / anulada / estado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BheListResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bhe/{id}":{"get":{"operationId":"getBhe","tags":["bhe"],"summary":"Detalle de una BHE","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"BHE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BheDetail"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"BHE inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bhe/{id}/anular":{"post":{"tags":["bhe"],"summary":"Anular una BHE","description":"Plazo legal: 3 meses calendario desde fecha_emision (gate server-side).","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BheAnularInput"}}}},"responses":{"200":{"description":"BHE anulada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BheAnularResponse"}}}},"400":{"description":"JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"BHE inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Fuera del plazo de anulación (3 meses) o ya anulada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/caf":{"post":{"tags":["caf"],"summary":"Subir archivo CAF (rango de folios del SII)","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CafUploadInput"}}}},"responses":{"201":{"description":"CAF registrado y cifrado; folios disponibles para emitir","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CafUploadResponse"}}}},"400":{"description":"caf.invalid_request — falta el archivo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked, o la API key no tiene scope de escritura (rol viewer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"caf.duplicate — el rango ya está registrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required — completá el onboarding primero","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"caf.parse_error, caf.wrong_tipo o caf.no_certificate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable o caf.kms_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["caf"],"summary":"Listar CAFs del org","responses":{"200":{"description":"CAFs con folios restantes y flag low_folios (≤10)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CafListResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/caf/{id}":{"delete":{"tags":["caf"],"summary":"Eliminar un CAF","description":"Hard delete (permite re-subir el mismo rango). Bloqueado si algún DTE del CAF fue aceptado por el SII (folios comprometidos + retención legal de 6 años) o fue cedido vía RPETC.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"CAF eliminado (cascade de DTEs no aceptados)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CafDeleteResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked, o la API key no tiene scope de escritura (rol owner/admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"caf.not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"caf.has_accepted_dtes o caf.has_ceded_dtes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/caf/request":{"post":{"tags":["caf"],"summary":"Solicitar folios (timbraje on-demand)","description":"Solicita al SII un rango nuevo de folios (CAF) para un tipo. ⚠️ IRREVERSIBLE — el SII otorga folios reales que no se devuelven. Dual-auth: Bearer API key o sesión del dashboard; con Bearer el ambiente SII (cert/prod) sale de la API key. Requiere scope de escritura (un rol viewer recibe 403). Hay cooldown anti doble-grant.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CafRequestInput"}}}},"responses":{"200":{"description":"Ya hay folios suficientes — no se pidió rango nuevo (reason=no_cafs_missing)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CafRequestResponse"}}}},"201":{"description":"Rango de folios solicitado al SII (requested=true)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CafRequestResponse"}}}},"400":{"description":"caf.invalid_request — tipo faltante/no soportado o cantidad fuera de rango","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked, o la API key no tiene scope de escritura (rol viewer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"caf.request_in_flight (cooldown, incluye retry_in_seconds) o caf.type_not_prod_certified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required (sesión sin org) o cert.missing (sin certificado activo)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"caf.request_failed o rechazo del SII","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable o caf.kms_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/certificates":{"post":{"tags":["certificates"],"summary":"Subir certificado digital (.p12)","description":"El .p12 se cifra con DEK per-org (envelope encryption). El id devuelto es el X-Cert-Id para emitir.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CertificateUploadInput"}}}},"responses":{"200":{"description":"Certificado actualizado en su lugar (mismo .p12 re-subido → re-deriva metadata / revive)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateUploadResponse"}}}},"201":{"description":"Certificado almacenado cifrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateUploadResponse"}}}},"400":{"description":"cert.invalid_request — file, password y label son obligatorios","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked, o la API key no tiene scope de escritura (rol owner/admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"cert.duplicate — mismo fingerprint ya subido para este org (race de upload concurrente)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"cert.invalid — el .p12 o la clave no son válidos (no se pudo parsear el certificado)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable o cert.kms_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["certificates"],"summary":"Listar certificados del org","description":"Certificados vigentes (no eliminados) de la organización.","responses":{"200":{"description":"Certificados con vigencia (not_before / not_after)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateListResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/certificates/{id}":{"delete":{"tags":["certificates"],"summary":"Eliminar un certificado","description":"Soft delete: deja de aparecer en el listado y de servir para firmar.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Certificado eliminado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateDeleteResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked, o la API key no tiene scope de escritura (rol owner/admin)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"cert.not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/profile":{"get":{"tags":["profile"],"summary":"Leer el perfil del emisor","description":"Giro / dirección / comuna / actividad económica que aparecen en el <Emisor> del DTE. `{}` si el org todavía no configuró ningún campo.","responses":{"200":{"description":"Perfil actual (campos ausentes si nunca se configuraron)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["profile"],"summary":"Actualizar el perfil del emisor","description":"Update parcial: solo los campos presentes en el body se mergean, el resto se preserva. `POST /dtes` con perfil incompleto devuelve `422 emisor.profile_incompleto` con el hint de completarlo acá.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"giro":{"type":"string","minLength":1,"maxLength":80},"direccion":{"type":"string","minLength":1,"maxLength":70},"comuna":{"type":"string","minLength":1,"maxLength":20},"actividadEconomica":{"type":"integer","minimum":0,"exclusiveMinimum":true}}}}}},"responses":{"200":{"description":"Perfil actualizado (forma completa post-merge)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"}}}},"400":{"description":"profile.invalid — campo vacío, fuera de ISO-8859-1, o actividadEconomica no entera","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sii/cert-state":{"get":{"tags":["sii"],"summary":"Estado del journey de certificación SII","description":"Journey derivado del último snapshot scrapeado del portal SII. `scrapedAt` es null si nunca se scrapeó.","responses":{"200":{"description":"Journey de certificación + timestamp del último scrape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiiCertStateResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked — request cross-origin bloqueado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sii/readiness":{"get":{"tags":["sii"],"summary":"Readiness de certificación SII del emisor","description":"Resumen de aplicabilidad/estado de certificación (ok, paso de postulación, fase, sub-estados por tipo).","responses":{"200":{"description":"Readiness de certificación de la org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiiReadinessResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked — request cross-origin bloqueado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sii/documents/recent":{"get":{"tags":["sii"],"summary":"Documentos de venta recientes (33/34)","description":"Últimas ventas 33/34 (máx 50) para pre-llenar el form desde el historial. Env-scopeado por el `sii_env` de la API key.","responses":{"200":{"description":"Lista de documentos recientes de la org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiiRecentDocumentsResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked — request cross-origin bloqueado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sii/documents/{id}/template":{"get":{"tags":["sii"],"summary":"Template de un documento previo (para reusar en un nuevo DTE)","description":"Tipo + receptor + items de un documento previo. `?source=notta` (default) usa el DTE de Notta (env-scopeado); `?source=rcv` usa una venta del RCV del SII (pre-fill degradado, sin líneas).","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["notta","rcv"],"description":"Fuente del documento (default: notta)."},"required":false,"name":"source","in":"query"}],"responses":{"200":{"description":"Template para hidratar el form de un nuevo DTE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiiDocumentTemplateResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked — request cross-origin bloqueado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"document.not_found — inexistente, de otra org, o de otro env","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"document.not_templatable — solo 33/34 se pueden reusar como template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"db.unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/set-pruebas/status":{"get":{"tags":["set-pruebas"],"summary":"Estado de un run de Set de Pruebas","description":"Estado (aggregate + casos) del run identificado por `run_id`. El query param es obligatorio.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"run_id","in":"query"}],"responses":{"200":{"description":"Estado del run (aggregate_state + casos)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPruebasEnvelope"}}}},"400":{"description":"set_pruebas.run_id_required — falta el query param run_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked — request cross-origin bloqueado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/set-pruebas/latest":{"get":{"tags":["set-pruebas"],"summary":"Último run de Set de Pruebas de la org","responses":{"200":{"description":"Último run (o null si nunca corrió)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPruebasEnvelope"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked — request cross-origin bloqueado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/set-pruebas/{runId}/report":{"get":{"tags":["set-pruebas"],"summary":"Reporte XML de un run de Set de Pruebas","description":"Descarga el XML del reporte final (attachment, charset ISO-8859-1) del run — solo disponible cuando el run llegó a state='passed'. Se renderiza + cachea en el primer request.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"XML del reporte final del run (attachment, charset ISO-8859-1)","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked — request cross-origin bloqueado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"set_pruebas.run_not_found — run inexistente (o de otra org)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"set_pruebas.run_not_passed — el run no está en estado 'passed'","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/set-pruebas/result/{caseId}":{"get":{"tags":["set-pruebas"],"summary":"Resultado de un caso de Set de Pruebas","parameters":[{"schema":{"type":"string"},"required":true,"name":"caseId","in":"path"}],"responses":{"200":{"description":"Resultado del caso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPruebasEnvelope"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked — request cross-origin bloqueado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"caso inexistente (o de otra org)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/rcof":{"post":{"tags":["rcof"],"summary":"Enviar ConsumoFolio manual de un día","description":"Envío manual de un día (mismo path que el cron `rcof-daily-send`). Requiere scope `rcof:write` (un scope `dte:write` sin `rcof:write` no alcanza). Reenvíos del mismo día incrementan `sec_envio`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcofSendInput"}}}},"responses":{"202":{"description":"RCOF encolado — estado avanza async (poll GET /rcof/{id})","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcofSendAccepted"}}}},"400":{"description":"invalid_json o rcof.fecha_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene scope rcof:write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"rcof.no_active_cert — no hay certificado activo para el org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["rcof"],"summary":"Listar envíos RCOF del org","parameters":[{"schema":{"type":"string","description":"YYYY-MM-DD"},"required":false,"name":"desde","in":"query"},{"schema":{"type":"string","description":"YYYY-MM-DD"},"required":false,"name":"hasta","in":"query"}],"responses":{"200":{"description":"Envíos RCOF, acotados al ambiente SII de la API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcofListResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene scope dte:read (default de lectura del mount RCOF)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/rcof/resend":{"post":{"tags":["rcof"],"summary":"Reenviar el ConsumoFolio de un día (corrección)","description":"Mismo handler que POST /rcof — re-encola con un `sec_envio` nuevo (corrección del mismo día).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcofSendInput"}}}},"responses":{"202":{"description":"RCOF re-encolado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcofSendAccepted"}}}},"400":{"description":"invalid_json o rcof.fecha_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene scope rcof:write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"rcof.no_active_cert — no hay certificado activo para el org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/rcof/{id}":{"get":{"tags":["rcof"],"summary":"Detalle de un envío RCOF","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Envío RCOF con el resumen agregado por tipo de documento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcofDetailResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene scope dte:read (default de lectura del mount RCOF)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"rcof.not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/rcof/{id}/xml":{"get":{"tags":["rcof"],"summary":"XML firmado del ConsumoFolio","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"XML firmado del ConsumoFolio_v10","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene scope dte:read (default de lectura del mount RCOF)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"rcof.not_found o rcof.xml_not_available (aún sin firmar)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/rcv":{"post":{"tags":["rcv"],"summary":"Sincronizar snapshot mensual de RCV","description":"Sincroniza (o devuelve cacheado, salvo `force`) el Registro de Compras y Ventas de un período. Requiere scope `rcv:read` (cubre POST y GET — RCV no emite ni consume folios).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcvSyncInput"}}}},"responses":{"200":{"description":"Snapshot sincronizado o servido desde cache (from_cache)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RcvSyncAccepted"}}}},"401":{"description":"Bearer API key faltante o inválida, o rcv.unauthorized (clave tributaria rechazada por el SII)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene scope rcv:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"rcv.input.invalid (body no matchea {rut, periodo, type?, force?}) o rcv.period.invalid (periodo en el futuro)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"rcv.sync.failed — el SII no respondió o falló el fetch; reintentar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["rcv"],"summary":"Listar o consultar snapshots RCV","description":"Con `rut` devuelve el detalle de un snapshot; sin `rut` devuelve la lista del período.","parameters":[{"schema":{"type":"string","description":"YYYY-MM, requerido"},"required":true,"name":"periodo","in":"query"},{"schema":{"type":"string","description":"Si se pasa, devuelve el detalle (no la lista)"},"required":false,"name":"rut","in":"query"},{"schema":{"type":"string","enum":["received","issued","both"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["rut","period","type","record_count","synced_at"]},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"dir","in":"query"}],"responses":{"200":{"description":"Detalle (con rut) o { data: [...] } (sin rut)","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/RcvSnapshot"},{"$ref":"#/components/schemas/RcvListResponse"}]}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene scope rcv:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"rcv.not_found — con rut, ningún snapshot para ese período","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"rcv.query.invalid — falta ?periodo=YYYY-MM","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/onboarding/readiness":{"get":{"tags":["onboarding"],"summary":"Checklist de qué le falta a la org para emitir","description":"Cert vigencia, CAF por tipo-objetivo, set de pruebas y producción. `complete=true` cuando todo pasa.","responses":{"200":{"description":"Readiness actual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/onboarding/suggested-types":{"get":{"tags":["onboarding"],"summary":"Tipos DTE sugeridos según la postulación SII del certificado","description":"Catálogo completo con `preselected` marcado por lo que el scrape de postulación detectó. Factura afecta (33) siempre presente aunque el SII no la haya devuelto (el scrape es frágil).","responses":{"200":{"description":"Catálogo + tipos sugeridos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestedTypesResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/onboarding/target-types":{"post":{"tags":["onboarding"],"summary":"Confirmar los tipos DTE que la org va a emitir","description":"Persiste los tipos-objetivo. Si la org estaba en fase cert_uploaded, la avanza a sandbox_ready (habilita el orquestador de certificación).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tipos":{"type":"array","items":{"type":"integer","minimum":0,"exclusiveMinimum":true},"minItems":1,"maxItems":10}},"required":["tipos"]}}}},"responses":{"200":{"description":"Tipos-objetivo persistidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetTypesResponse"}}}},"400":{"description":"bad_request — tipos requerido, array de números","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked, o la API key no tiene scope de escritura (dte:write)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"org.required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/plan":{"get":{"operationId":"getBillingPlan","tags":["billing"],"summary":"Estado de cuota del plan actual","description":"Plan activo (`free` si no hay suscripción) + documentos usados / límite del mes en curso (prod). Chequealo antes de emitir para evitar el 402 `billing.free_tier_exceeded` de POST /dtes.","responses":{"200":{"description":"Estado de cuota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPlanStatus"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"La API key no tiene el scope 'billing:read'","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/subscribe":{"post":{"operationId":"subscribeBilling","tags":["billing"],"summary":"Suscribirse a un plan","description":"Activa (o reemplaza) la suscripción de la org al `planId` indicado. Planes pagos requieren `card_token` + `payment_method_id` (tokenizados client-side vía MercadoPago Card Payment Brick).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSubscribeInput"}}}},"responses":{"200":{"description":"Suscripción activa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSubscribeResult"}}}},"401":{"description":"Bearer API key faltante o inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"billing.payment_rejected — MercadoPago rechazó el primer cobro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"csrf_blocked (carril sesión), o la API key no tiene el scope 'billing:write'","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"billing.already_subscribed — cancela el plan actual antes de cambiarte","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"billing.plan_not_found | billing.card_required | validación de body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"billing.mercadopago_auth — token de MercadoPago inválido (no reintentable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"billing.mercadopago_unavailable | billing.config_missing | billing.upgrade_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}