{"openapi":"3.0.3","info":{"title":"Facttura Public API","description":"API pública de Facttura para integraciones de organizaciones. Usa tokens de API creados desde el panel de la organización y los scopes correspondientes.\n\nEnvironment selection: the organization API key selects either the production or linked sandbox workspace. Production and sandbox require separate organization keys; routes and /api/v1 URLs do not change. Sandbox documents are simulated, never sent to SII, and have no tax validity. Sandbox responses expose environment=sandbox, livemode=false, and siiSubmissionStatus=not_submitted. Document webhooks include environment/livemode in the payload and X-Facttura-Environment and X-Facttura-Livemode headers.","version":"1.0.0","contact":{"name":"Facttura Support","email":"support@facttura.com"}},"servers":[{"url":"https://app.facttura.com/api/v1","description":"Producción"}],"tags":[{"name":"Companies","description":"Gestión de empresas. Requiere scopes companies:read o companies:write."},{"name":"Documents","description":"Gestión y emisión de documentos DTE. Requiere scopes documents:read o documents:write."},{"name":"Webhooks","description":"Outbound webhook destinations. Verify `X-Facttura-Signature` as lowercase hex HMAC-SHA256 of `<X-Facttura-Timestamp>.<raw request body>`, prefixed with `sha256=`. The signing secret is returned only once on creation or rotation and is never sent in delivery headers. Events: `document.created` is delivered once a document is issued with a folio. `document.cancelled` is delivered when a document reaches `status: \"cancelled\"` and can no longer be issued; subscribe to it explicitly in `events` (existing webhooks do not receive it). Both events share the delivery contract: headers `X-Webhook-Event`, `X-Webhook-Id` (`<event>:<id>`, use it to deduplicate retries), `X-Facttura-Timestamp`, `X-Facttura-Signature`, `X-Facttura-Environment` and `X-Facttura-Livemode`, and a JSON body with `id`, `type`, `version`, `occurredAt`, `environment`, `livemode`, `siiSubmissionStatus`, `uuid`, `status`, `data`, `pdfUrl` and `cediblePdfUrl`. `document.cancelled` adds `cancellation.reason`: `annulled` (it had a folio and the SII confirmed its annulment note; `siiSubmissionStatus` is `submitted`) or `withdrawn` (it never reached the SII, folio 0; `siiSubmissionStatus` is `not_submitted` and no credit note is needed). Webhook deliveries are identical for every API version. Full contract, payload examples and a signature test vector: https://facttura.com/documentacion (section Webhooks)."},{"name":"Libro de Compra y Venta (SII)","description":"Consultas y acciones del Libro SII. Requiere scope libro:write."},{"name":"BHE REC (Boletas Honorarios Recibidas)","description":"Informes BHE REC y descarga de PDFs. Requiere scope bhe:read."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Token","description":"Token de API de la organización, creado en el panel de Facttura."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"Company":{"type":"object","properties":{"id":{"type":"integer"},"organizationId":{"type":"integer"},"rut":{"type":"string"},"rutNumber":{"type":"string"},"rutDv":{"type":"string"},"razonSocial":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"},"businessType":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"actividadEconomica":{"type":"string","maxLength":10,"nullable":true},"actividadesEconomicas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"codigo":{"type":"string"},"descripcion":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"siiConnectionStatus":{"type":"string","nullable":true},"logoPath":{"type":"string","nullable":true},"logoUrl":{"type":"string","format":"uri","nullable":true},"siiCredential":{"$ref":"#/components/schemas/SiiCredential","nullable":true}}},"Document":{"type":"object","description":"DTE document in SII standard format"},"Webhook":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"name":{"type":"string","nullable":true},"active":{"type":"boolean"},"companyIds":{"type":"array","items":{"type":"integer"},"description":"Array of company IDs associated with this webhook"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"companies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"razonSocial":{"type":"string"}}}},"events":{"type":"array","items":{"type":"string","enum":["document.created","document.cancelled","purchase_document.created"]},"example":["document.created"]}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer"},"perPage":{"type":"integer"},"currentPage":{"type":"integer"},"lastPage":{"type":"integer"}}},"CreateCompanyRequest":{"type":"object","required":["rutNumber","rutDv","razonSocial","email","address","region","city"],"properties":{"rutNumber":{"type":"string","minLength":7,"maxLength":9,"example":"12345678"},"rutDv":{"type":"string","pattern":"^[0-9K]$","example":"9"},"razonSocial":{"type":"string","maxLength":250,"example":"Mi Empresa S.A."},"email":{"type":"string","format":"email","example":"contacto@empresa.cl"},"address":{"type":"string","example":"Av. Principal 123"},"region":{"type":"string","example":"Región Metropolitana"},"city":{"type":"string","example":"Santiago"},"businessType":{"type":"string","maxLength":200,"nullable":true},"phone":{"type":"string","maxLength":20,"nullable":true},"actividadEconomica":{"type":"string","maxLength":10,"nullable":true}}},"UpdateCompanyRequest":{"type":"object","properties":{"rutNumber":{"type":"string","minLength":7,"maxLength":9},"rutDv":{"type":"string","pattern":"^[0-9K]$"},"razonSocial":{"type":"string","maxLength":250},"email":{"type":"string","format":"email"},"address":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"},"businessType":{"type":"string","maxLength":200},"phone":{"type":"string","maxLength":20},"actividadEconomica":{"type":"string","maxLength":10}}},"CreateWebhookRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"example":"https://example.com/webhook"},"name":{"type":"string","maxLength":255,"nullable":true,"example":"My Webhook"},"companyIds":{"type":"array","items":{"type":"integer"},"nullable":true,"example":[1,2,3]},"active":{"type":"boolean","default":true},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["document.created","document.cancelled","purchase_document.created"]},"description":"Events delivered to this webhook. Defaults to [\"document.created\"] on creation."}}},"UpdateWebhookRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2048},"name":{"type":"string","maxLength":255},"companyIds":{"type":"array","items":{"type":"integer"}},"active":{"type":"boolean"},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["document.created","document.cancelled","purchase_document.created"]},"description":"Events delivered to this webhook. Defaults to [\"document.created\"] on creation."}}},"BatchDocumentsRequest":{"type":"object","required":["documents"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"},"minItems":1,"maxItems":1000}}},"BatchDocumentResult":{"type":"object","properties":{"index":{"type":"integer"},"client_reference_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["queued","error"]},"uuid":{"type":"string","format":"uuid","nullable":true},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string","nullable":true}}}}},"LibroResumenRequest":{"type":"object","required":["anho","mes","operacion"],"properties":{"empresaRutDv":{"type":"string","description":"RUT empresa en formato 77644429-4","pattern":"^[\\d.]+-[0-9K]$"},"empresaRut":{"type":"integer","description":"RUT numérico (alternativa a empresaRutDv)"},"empresaDv":{"type":"string","maxLength":1,"description":"Dígito verificador"},"anho":{"type":"integer","minimum":2000,"maximum":2100},"mes":{"type":"integer","minimum":1,"maximum":12},"operacion":{"type":"string","enum":["COMPRA","VENTA","DESCARGAS_DIFERIDAS"]},"estadoContab":{"type":"string","enum":["REGISTRO","PENDIENTE","NO_INCLUIR","RECLAMADO"]}}},"LibroDetalleRequest":{"type":"object","required":["anho","mes","codTipoDoc","operacion"],"properties":{"empresaRutDv":{"type":"string","pattern":"^[\\d.]+-[0-9K]$"},"empresaRut":{"type":"integer"},"empresaDv":{"type":"string","maxLength":1},"anho":{"type":"integer","minimum":2000,"maximum":2100},"mes":{"type":"integer","minimum":1,"maximum":12},"codTipoDoc":{"type":"string"},"operacion":{"type":"string","enum":["COMPRA","VENTA"]},"estadoContab":{"type":"string","enum":["REGISTRO","PENDIENTE","NO_INCLUIR","RECLAMADO"]},"montoTotalDesde":{"type":"number","minimum":0},"montoTotalHasta":{"type":"number","minimum":0},"fechaDesde":{"type":"string","pattern":"^\\d{2}/\\d{2}/\\d{4}$","description":"dd/mm/yyyy"},"fechaHasta":{"type":"string","pattern":"^\\d{2}/\\d{2}/\\d{4}$"},"folio":{"type":"integer","minimum":0},"rutProveedor":{"type":"integer"},"dvProveedor":{"type":"string","maxLength":1}}},"CambiarTipoCompraRequest":{"type":"object","required":["codTipoDoc","folio","tipoCompra","rutProveedor","dvProveedor","operacion"],"properties":{"empresaRutDv":{"type":"string","pattern":"^[\\d.]+-[0-9K]$"},"empresaRut":{"type":"integer"},"empresaDv":{"type":"string","maxLength":1},"anho":{"type":"integer","minimum":2000,"maximum":2100},"mes":{"type":"integer","minimum":1,"maximum":12},"codTipoDoc":{"type":"string"},"folio":{"type":"integer","minimum":0},"tipoCompra":{"type":"integer","minimum":1,"maximum":7,"description":"1=Del Giro, 2=Supermercados, 3=Bienes Raíces, 4=Activo Fijo, 5=IVA Uso Común, 6=IVA no Recuperable, 7=No Corresp. Incluir"},"rutProveedor":{"type":"integer"},"dvProveedor":{"type":"string","maxLength":1},"operacion":{"type":"string","enum":["COMPRA","VENTA"]},"estadoContab":{"type":"string","enum":["REGISTRO","PENDIENTE","NO_INCLUIR","RECLAMADO"]}}},"IngresarEventoRequest":{"type":"object","required":["codTipoDoc","folio","codEvento","rutEmisor","dvEmisor"],"properties":{"codTipoDoc":{"type":"integer"},"folio":{"type":"integer","minimum":0},"codEvento":{"type":"string","enum":["ERM","RCD","RFP","ACD","RFT"],"description":"ERM - Acuse Recibo de Mercaderías o Servicios; RCD - Reclamo al Contenido del Documento; RFP - Reclamo por Falta Parcial de Mercaderías o Servicios; ACD - Acepta Contenido DTE; RFT - Reclamo por Falta Total de Mercaderías o Servicios"},"rutEmisor":{"type":"integer","description":"RUT del emisor del DTE"},"dvEmisor":{"type":"string","minLength":1,"maxLength":1},"empresaRutDv":{"type":"string","pattern":"^[\\d.]+-[0-9K]$"},"empresaRut":{"type":"integer"},"empresaDv":{"type":"string","maxLength":1}}},"SiiCredential":{"type":"object","properties":{"id":{"type":"integer"},"organizationId":{"type":"integer"},"companyId":{"type":"integer"},"username":{"type":"string","nullable":true},"hasPassword":{"type":"boolean"},"hasCertPassword":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookWithSecret":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string","format":"uri"},"name":{"type":"string","nullable":true},"active":{"type":"boolean"},"companyIds":{"type":"array","items":{"type":"integer"},"description":"Array of company IDs associated with this webhook"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"companies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"razonSocial":{"type":"string"}}}},"events":{"type":"array","items":{"type":"string","enum":["document.created","document.cancelled","purchase_document.created"]},"example":["document.created"]},"secret":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Secreto HMAC revelado una sola vez. Guárdalo ahora.","example":"8d7f4d7e2a1c9f86b6d4b3a8ef8a4b75f20c84bfe58171c9f2282ab42c36a951"}}}},"parameters":{"IdempotencyKeyRequired":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[a-zA-Z0-9._-]+$"},"description":"Unique operation key. Required for document creation and batch creation."},"OrganizationUuid":{"name":"organization","in":"query","description":"Organization UUID. If not provided, uses the user's first organization.","schema":{"type":"string","format":"uuid"}},"OrganizationUuidHeader":{"name":"X-Organization-UUID","in":"header","description":"Organization UUID. Alternative to query parameter.","schema":{"type":"string","format":"uuid"}},"Page":{"name":"page","in":"query","description":"Page number for pagination","schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","description":"Items per page","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}}},"paths":{"/companies":{"get":{"tags":["Companies"],"summary":"List companies","description":"Get all companies for the specified organization","operationId":"listCompanies","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"List of companies","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"No access to organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Companies"],"summary":"Create company","description":"Create a new company in the specified organization","operationId":"createCompany","security":[{"BearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompanyRequest"}}}},"responses":{"201":{"description":"Company created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Company"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"No access to organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/companies/{id}":{"get":{"tags":["Companies"],"summary":"Get company","description":"Get a single company by ID","operationId":"getCompany","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Company data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Company"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Companies"],"summary":"Update company","description":"Update an existing company","operationId":"updateCompany","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompanyRequest"}}}},"responses":{"200":{"description":"Company updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Company"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Companies"],"summary":"Delete company","description":"Delete a company","operationId":"deleteCompany","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Company ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Company deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Company deleted successfully"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/documents":{"get":{"tags":["Documents"],"summary":"List documents","description":"Get all documents for the specified organization with optional filtering and sorting\n\nEnvironment selection: the organization API key selects either the production or linked sandbox workspace. Production and sandbox require separate organization keys; routes and /api/v1 URLs do not change. Sandbox documents are simulated, never sent to SII, and have no tax validity. Sandbox responses expose environment=sandbox, livemode=false, and siiSubmissionStatus=not_submitted. Document webhooks include environment/livemode in the payload and X-Facttura-Environment and X-Facttura-Livemode headers.","operationId":"listDocuments","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"},{"name":"type","in":"query","description":"Filter by document type","schema":{"type":"string","enum":["invoice","exempt_invoice","receipt","exempt_receipt","shipping_guide","dispatch_guide","debit_note","credit_note","export_invoice"],"example":"invoice"}},{"name":"text","in":"query","description":"Search in folio, razón social, or RUT","schema":{"type":"string","example":"12345"}},{"name":"company","in":"query","description":"Filter by emitter company (razón social)","schema":{"type":"string","example":"Mi Empresa S.A."}},{"name":"date_from","in":"query","description":"Filter documents from this date (YYYY-MM-DD)","schema":{"type":"string","format":"date","example":"2024-01-01"}},{"name":"date_to","in":"query","description":"Filter documents until this date (YYYY-MM-DD)","schema":{"type":"string","format":"date","example":"2024-12-31"}},{"name":"sort_by","in":"query","description":"Sort field","schema":{"type":"string","enum":["date","amount","folio"],"example":"date"}},{"name":"sort_direction","in":"query","description":"Sort direction","schema":{"type":"string","enum":["asc","desc"],"example":"desc"}}],"responses":{"200":{"description":"List of documents","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"},"uuid":{"type":"string","format":"uuid","description":"Document UUID","example":"550e8400-e29b-41d4-a716-446655440000"},"pdfUrl":{"type":"string","format":"uri","nullable":true,"description":"Public URL to the document PDF","example":"https://s3.amazonaws.com/bucket/path/to/document.pdf"},"cediblePdfUrl":{"type":"string","format":"uri","nullable":true,"description":"Public URL to the standalone cedible PDF copy","example":"https://s3.amazonaws.com/bucket/path/to/document-cedible.pdf"}}}},"meta":{"$ref":"#/components/schemas/PaginationMeta"},"environment":{"type":"string","enum":["production","sandbox"],"description":"Environment selected by the authenticated organization API key."},"livemode":{"type":"boolean","description":"True only for production organizations. Sandbox responses are always false."},"siiSubmissionStatus":{"type":"string","enum":["submitted","not_submitted"],"description":"Sandbox documents are always not_submitted and never contact SII."}},"example":{"success":true,"data":[{"data":{"Encabezado":{"IdDoc":{"TipoDTE":33,"Folio":123,"FchEmis":"2024-01-15"},"Emisor":{"RUTEmisor":"77226199-3","RznSoc":"Mi Empresa S.A.","GiroEmis":"Comercio","Acteco":[620200],"DirOrigen":"Av. Principal 123","CmnaOrigen":"Santiago","CorreoEmisor":"contacto@empresa.cl"},"Receptor":{"RUTRecep":"12345678-9","RznSocRecep":"Cliente S.A.","GiroRecep":"Servicios","DirRecep":"Calle Cliente 456","CmnaRecep":"Providencia"},"Totales":{"MntNeto":100000,"TasaIVA":19,"IVA":19000,"MntTotal":119000}},"Detalle":[{"NroLinDet":1,"NmbItem":"Producto de ejemplo","QtyItem":2,"UnmdItem":"UN","PrcItem":50000,"MontoItem":100000}]},"uuid":"550e8400-e29b-41d4-a716-446655440000","pdfUrl":"https://s3.amazonaws.com/bucket/path/to/document.pdf","cediblePdfUrl":"https://s3.amazonaws.com/bucket/path/to/document-cedible.pdf"}],"meta":{"total":150,"perPage":50,"currentPage":1,"lastPage":3}},"required":["environment","livemode","siiSubmissionStatus"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Documents"],"summary":"Create document","description":"Create a new DTE document and queue it for processing. Returns a job UUID to track status.\n\nFor DTE 56 (Nota de Débito), use `CodRef: 3` with `TpoDocRef: \"33\"` or `\"34\"` to correct amounts, or `CodRef: 1` with `TpoDocRef: \"61\"` to annul a credit note. `CodRef: 2` is not available for debit notes.\n\nFor DTE 33 (Factura Electrónica) and DTE 34 (Factura Exenta), you can create documents without receptor data by setting `allow_missing_receptor: true`. When receptor is missing and this parameter is set, the response will include:\n- `completeReceptorUrl`: API endpoint URL (for custom frontend integration)\n- `completeReceptorFormUrl`: Frontend form URL (for using the prepared form)\n\nBoth URLs are valid for 2 weeks and can be used to complete the receptor data.\n\nEnvironment selection: the organization API key selects either the production or linked sandbox workspace. Production and sandbox require separate organization keys; routes and /api/v1 URLs do not change. Sandbox documents are simulated, never sent to SII, and have no tax validity. Sandbox responses expose environment=sandbox, livemode=false, and siiSubmissionStatus=not_submitted. Document webhooks include environment/livemode in the payload and X-Facttura-Environment and X-Facttura-Livemode headers.","operationId":"createDocument","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["DTE"],"properties":{"DTE":{"type":"object","description":"DTE in SII standard format (version 2.2)"},"send_email_to_emisor":{"type":"boolean","description":"Send email to emisor (optional)"},"send_email_to_receptor":{"type":"boolean","description":"Send email to receptor (optional)"},"allow_missing_receptor":{"type":"boolean","description":"If true, allows creating DTE 33/34 without receptor data. When allow_missing_receptor is true and receptor is missing, a signed URL will be returned to complete the receptor data later.","default":false,"example":false}}}}}},"responses":{"201":{"description":"Document created (missing receptor data - requires completion)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Document UUID"},"status":{"type":"string","enum":["pending_receptor"],"description":"Document status - waiting for receptor data"},"completeReceptorUrl":{"type":"string","format":"uri","description":"API endpoint URL to complete receptor data (for custom frontend integration). Valid for 2 weeks.","example":"https://app.facttura.com/api/public/documents/abc123/complete-receptor"},"completeReceptorFormUrl":{"type":"string","format":"uri","description":"Frontend form URL to complete receptor data (for using the prepared form). Valid for 2 weeks.","example":"https://app.facttura.com/autoservicio/abc123"}}},"message":{"type":"string","example":"Document created. Receptor data required to proceed."},"environment":{"type":"string","enum":["production","sandbox"],"description":"Environment selected by the authenticated organization API key."},"livemode":{"type":"boolean","description":"True only for production organizations. Sandbox responses are always false."},"siiSubmissionStatus":{"type":"string","enum":["submitted","not_submitted"],"description":"Sandbox documents are always not_submitted and never contact SII."}},"required":["environment","livemode","siiSubmissionStatus"]}}}},"202":{"description":"Document creation queued","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Job status (not document status)"}}},"message":{"type":"string","example":"Document creation queued"},"environment":{"type":"string","enum":["production","sandbox"],"description":"Environment selected by the authenticated organization API key."},"livemode":{"type":"boolean","description":"True only for production organizations. Sandbox responses are always false."},"siiSubmissionStatus":{"type":"string","enum":["submitted","not_submitted"],"description":"Sandbox documents are always not_submitted and never contact SII."}},"required":["environment","livemode","siiSubmissionStatus"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Company not found in organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/documents/{rutEmisor}/{tipoDTE}/{folio}":{"get":{"tags":["Documents"],"summary":"Get document","description":"Get a single document by company RUT, document type, and folio\n\nEnvironment selection: the organization API key selects either the production or linked sandbox workspace. Production and sandbox require separate organization keys; routes and /api/v1 URLs do not change. Sandbox documents are simulated, never sent to SII, and have no tax validity. Sandbox responses expose environment=sandbox, livemode=false, and siiSubmissionStatus=not_submitted. Document webhooks include environment/livemode in the payload and X-Facttura-Environment and X-Facttura-Livemode headers.","operationId":"getDocument","security":[{"BearerAuth":[]}],"parameters":[{"name":"rutEmisor","in":"path","required":true,"description":"Company RUT (with or without formatting)","schema":{"type":"string","example":"12345678-9"}},{"name":"tipoDTE","in":"path","required":true,"description":"Document type (33=Factura, 39=Boleta, etc.)","schema":{"type":"integer","example":33}},{"name":"folio","in":"path","required":true,"description":"Document folio number","schema":{"type":"integer","example":123}}],"responses":{"200":{"description":"Document data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Document"},"uuid":{"type":"string","format":"uuid","description":"Document UUID","example":"550e8400-e29b-41d4-a716-446655440000"},"pdfUrl":{"type":"string","format":"uri","nullable":true,"description":"Public URL to the document PDF","example":"https://s3.amazonaws.com/bucket/path/to/document.pdf"},"cediblePdfUrl":{"type":"string","format":"uri","nullable":true,"description":"Public URL to the standalone cedible PDF copy","example":"https://s3.amazonaws.com/bucket/path/to/document-cedible.pdf"},"environment":{"type":"string","enum":["production","sandbox"],"description":"Environment selected by the authenticated organization API key."},"livemode":{"type":"boolean","description":"True only for production organizations. Sandbox responses are always false."},"siiSubmissionStatus":{"type":"string","enum":["submitted","not_submitted"],"description":"Sandbox documents are always not_submitted and never contact SII."}},"example":{"success":true,"data":{"Encabezado":{"IdDoc":{"TipoDTE":33,"Folio":123,"FchEmis":"2024-01-15"},"Emisor":{"RUTEmisor":"77226199-3","RznSoc":"Mi Empresa S.A.","GiroEmis":"Comercio","Acteco":[620200],"DirOrigen":"Av. Principal 123","CmnaOrigen":"Santiago","CorreoEmisor":"contacto@empresa.cl"},"Receptor":{"RUTRecep":"12345678-9","RznSocRecep":"Cliente S.A.","GiroRecep":"Servicios","DirRecep":"Calle Cliente 456","CmnaRecep":"Providencia"},"Totales":{"MntNeto":100000,"TasaIVA":19,"IVA":19000,"MntTotal":119000}},"Detalle":[{"NroLinDet":1,"NmbItem":"Producto de ejemplo","QtyItem":2,"UnmdItem":"UN","PrcItem":50000,"MontoItem":100000}]},"uuid":"550e8400-e29b-41d4-a716-446655440000","pdfUrl":"https://s3.amazonaws.com/bucket/path/to/document.pdf","cediblePdfUrl":"https://s3.amazonaws.com/bucket/path/to/document-cedible.pdf"},"required":["environment","livemode","siiSubmissionStatus"]}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Company not found in organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pending-documents/{uuid}":{"get":{"tags":["Documents"],"summary":"Get pending document status","description":"Get the status of a document creation job\n\nEnvironment selection: the organization API key selects either the production or linked sandbox workspace. Production and sandbox require separate organization keys; routes and /api/v1 URLs do not change. Sandbox documents are simulated, never sent to SII, and have no tax validity. Sandbox responses expose environment=sandbox, livemode=false, and siiSubmissionStatus=not_submitted. Document webhooks include environment/livemode in the payload and X-Facttura-Environment and X-Facttura-Livemode headers.","operationId":"getPendingDocumentStatus","security":[{"BearerAuth":[]}],"parameters":[{"name":"uuid","in":"path","required":true,"description":"Document UUID returned in the uuid field by POST /documents (not jobUuid or a numeric ID). Invalid UUIDs return 422.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Document job status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"},"uuid":{"type":"string","format":"uuid","description":"Document UUID"},"status":{"type":"string","enum":["pending_receptor","pending","completed","cancelled"],"description":"Document status"},"pdfUrl":{"type":"string","format":"uri","nullable":true,"description":"Public URL to the document PDF"},"cediblePdfUrl":{"type":"string","format":"uri","nullable":true,"description":"Public URL to the standalone cedible PDF copy"}}},"environment":{"type":"string","enum":["production","sandbox"],"description":"Environment selected by the authenticated organization API key."},"livemode":{"type":"boolean","description":"True only for production organizations. Sandbox responses are always false."},"siiSubmissionStatus":{"type":"string","enum":["submitted","not_submitted"],"description":"Sandbox documents are always not_submitted and never contact SII."}},"required":["environment","livemode","siiSubmissionStatus"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Pending document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/documents:batchCreate":{"post":{"operationId":"batchCreateDocuments","tags":["Documents"],"summary":"Create documents in batch","description":"Create multiple DTE documents in batch atomically.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchDocumentsRequest"}}}},"responses":{"200":{"description":"Éxito","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchDocumentResult"}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"queued":{"type":"integer"},"failed":{"type":"integer"}}}}}}}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyRequired"}]}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","description":"Get all webhooks for the specified organization","operationId":"listWebhooks","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Webhooks"],"summary":"Create webhook","description":"Create a new webhook or update an existing one if the URL matches. A `201` response reveals `data.secret` once; a `200` response never reveals it.","operationId":"createWebhook","security":[{"BearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}}},"responses":{"200":{"description":"Webhook updated (existing URL)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"201":{"description":"Webhook created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/WebhookWithSecret"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error or webhook limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/webhooks/{id}":{"put":{"tags":["Webhooks"],"summary":"Update webhook","description":"Update an existing webhook","operationId":"updateWebhook","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Webhook updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete webhook","description":"Delete a webhook","operationId":"deleteWebhook","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Webhook deleted successfully"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/libro-compra-venta/empresas-autorizadas":{"get":{"tags":["Libro de Compra y Venta (SII)"],"summary":"Empresas autorizadas SII","description":"Obtiene las empresas autorizadas del SII para la organización. Requiere scope: libro:write","operationId":"libroEmpresasAutorizadas","security":[{"BearerAuth":[]}],"responses":{"200":{"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Prohibido - scope libro:write requerido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Sesión SII no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"description":"Lista de empresas autorizadas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}}}}},"/libro-compra-venta/periodos":{"get":{"tags":["Libro de Compra y Venta (SII)"],"summary":"Periodos disponibles SII","description":"Obtiene los periodos disponibles del libro de compra y venta en el SII para la organización. Usar servidor API v1 (token) con scope libro:write.","operationId":"libroPeriodos","security":[{"BearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Lista de periodos","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}}}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Sesión SII no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/libro-compra-venta/resumen":{"post":{"tags":["Libro de Compra y Venta (SII)"],"summary":"Resumen libro compra y venta","description":"Obtiene el resumen del libro de compra y venta del SII para el periodo y operación indicados.","operationId":"libroResumen","security":[{"BearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibroResumenRequest"}}}},"responses":{"200":{"description":"Resumen del libro","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}}}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Sesión SII no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/libro-compra-venta/detalle-compra":{"post":{"tags":["Libro de Compra y Venta (SII)"],"summary":"Detalle compra libro","description":"Obtiene el detalle de compra del libro de compra y venta del SII con filtros opcionales.","operationId":"libroDetalleCompra","security":[{"BearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibroDetalleRequest"}}}},"responses":{"200":{"description":"Detalle de compra/venta","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}}}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Sesión SII no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/libro-compra-venta/cambiar-tipo-compra":{"post":{"tags":["Libro de Compra y Venta (SII)"],"summary":"Cambiar tipo de compra","description":"Cambia el tipo de compra de un documento en el libro del SII (Del Giro, Supermercados, Bienes Raíces, etc.).","operationId":"libroCambiarTipoCompra","security":[{"BearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CambiarTipoCompraRequest"}}}},"responses":{"200":{"description":"Tipo de compra actualizado","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}}}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Sesión SII no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/libro-compra-venta/ingresar-evento":{"post":{"tags":["Libro de Compra y Venta (SII)"],"summary":"Ingresar evento (aceptar/rechazar)","description":"Ingresa un evento en el SII: aceptar o rechazar documento. Códigos de evento: ERM - Acuse Recibo de Mercaderías o Servicios; RCD - Reclamo al Contenido del Documento; RFP - Reclamo por Falta Parcial de Mercaderías o Servicios; ACD - Acepta Contenido DTE; RFT - Reclamo por Falta Total de Mercaderías o Servicios.","operationId":"libroIngresarEvento","security":[{"BearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngresarEventoRequest"}}}},"responses":{"200":{"description":"Evento ingresado","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}}}}}},"404":{"description":"No encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Sesión SII no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/libro-compra-venta/download-pdf":{"get":{"tags":["Libro de Compra y Venta (SII)"],"summary":"Descargar PDF DTE del libro compra/venta","description":"Descarga desde el SII el PDF de una factura u otro DTE listado en el libro de compra y venta. Requiere scope: libro:write. Para facturas de compra usar operacion=COMPRA con rutDoc/dvDoc del emisor y folio, o enviar dhdrCodigo si ya se conoce.","operationId":"libroDownloadPdf","security":[{"BearerAuth":[]}],"parameters":[{"name":"empresaRutDv","in":"query","required":false,"schema":{"type":"string"},"description":"RUT empresa en formato 77644429-4 (alternativa a empresaRut + empresaDv)."},{"name":"empresaRut","in":"query","required":false,"schema":{"type":"integer"},"description":"RUT numérico de la empresa (alternativa a empresaRutDv)."},{"name":"empresaDv","in":"query","required":false,"schema":{"type":"string","maxLength":1},"description":"Dígito verificador de la empresa."},{"name":"operacion","in":"query","required":false,"schema":{"type":"string","enum":["COMPRA","VENTA"]},"description":"COMPRA para documentos recibidos, VENTA para documentos emitidos. Requerido si no se envía dhdrCodigo."},{"name":"rutDoc","in":"query","required":false,"schema":{"type":"string"},"description":"RUT numérico del emisor (COMPRA) o receptor (VENTA). Requerido si no se envía dhdrCodigo."},{"name":"dvDoc","in":"query","required":false,"schema":{"type":"string","maxLength":1},"description":"Dígito verificador del documento. Requerido si no se envía dhdrCodigo."},{"name":"codTipoDoc","in":"query","required":false,"schema":{"type":"string"},"description":"Código SII del tipo de documento, por ejemplo 33, 34 o 46."},{"name":"folio","in":"query","required":false,"schema":{"type":"integer"},"description":"Folio del documento. Requerido si no se envía dhdrCodigo."},{"name":"dhdrCodigo","in":"query","required":false,"schema":{"type":"integer"},"description":"Código interno DHDR del SII. Si se envía, se usa como fallback directo para descargar el PDF."}],"responses":{"200":{"description":"PDF del documento","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Prohibido - scope libro:write requerido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Documento o empresa no encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Sesión SII no disponible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/informe-anual-bhe-rec":{"post":{"tags":["BHE REC (Boletas Honorarios Recibidas)"],"summary":"Informe anual BHE REC","description":"Obtiene el informe anual de boletas de honorarios electrónicas recibidas del SII para la empresa. Requiere token API v1 con scope bhe:read y que la empresa tenga credenciales del representante legal configuradas.","operationId":"informeAnualBheRec","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["año","empresa"],"properties":{"año":{"type":"string","description":"Año del informe (ej. 2025)","example":"2025"},"empresa":{"type":"string","description":"RUT de la empresa con dígito verificador (ej. 77644429-4)","example":"77644429-4"}}}}}},"responses":{"200":{"description":"Informe anual","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"nombreContribuyente, rut, dv, anio, meses[], totales"}}}}}},"400":{"description":"Año fuera de rango","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"403":{"description":"Faltan credenciales del representante o SII","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"Empresa no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Error del SII o credenciales inválidas","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/informe-mensual-bhe-rec":{"post":{"tags":["BHE REC (Boletas Honorarios Recibidas)"],"summary":"Informe mensual BHE REC","description":"Obtiene el informe mensual de boletas de honorarios electrónicas recibidas del SII (con paginación, 100 boletas por página). Requiere token API v1 con scope bhe:read y credenciales del representante legal.","operationId":"informeMensualBheRec","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["año","mes","empresa"],"properties":{"año":{"type":"string","description":"Año (ej. 2025)","example":"2025"},"mes":{"type":"integer","minimum":1,"maximum":12,"description":"Mes 1-12"},"empresa":{"type":"string","description":"RUT empresa con DV","example":"77644429-4"},"pagina":{"type":"integer","minimum":1,"description":"Página (1-based). Por defecto 1.","default":1}}}}}},"responses":{"200":{"description":"Informe mensual con boletas y totales","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"nombreContribuyente, rut, dv, anio, mes, totalBoletas, paginaActual, paginasTotales, totales, boletas[] (nroBoleta, codigoBarras, codComuna, etc.)"}}}}}},"400":{"description":"Año fuera de rango","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"403":{"description":"Faltan credenciales del representante","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"Empresa no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Error del SII","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/informe-mensual-bhe-rec/boleta-pdf":{"post":{"tags":["BHE REC (Boletas Honorarios Recibidas)"],"summary":"PDF de boleta recibida","description":"Descarga el PDF de una boleta de honorarios recibida. Los valores codigoBarras y codComuna se obtienen de cada ítem del informe mensual. Requiere scope bhe:read y credenciales del representante.","operationId":"boletaPdfBheRec","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["empresa","codigoBarras","codComuna"],"properties":{"empresa":{"type":"string","description":"RUT empresa con DV","example":"77644429-4"},"codigoBarras":{"type":"string","description":"Código de barras de la boleta (del informe mensual)"},"codComuna":{"type":"string","description":"Código comuna (del informe mensual)"}}}}}},"responses":{"200":{"description":"PDF de la boleta","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"403":{"description":"Faltan credenciales del representante","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"Empresa no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"No se pudo obtener el PDF del SII","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/informe-diario-bhe-rec":{"post":{"tags":["BHE REC (Boletas Honorarios Recibidas)"],"summary":"Informe diario BHE REC","description":"Obtiene el informe diario de boletas de honorarios electrónicas recibidas del SII para la fecha indicada. Requiere token API v1 con scope bhe:read y credenciales del representante legal.","operationId":"informeDiarioBheRec","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["año","mes","dia","empresa"],"properties":{"año":{"type":"string","description":"Año (ej. 2026)","example":"2026"},"mes":{"type":"integer","minimum":1,"maximum":12,"description":"Mes 1-12"},"dia":{"type":"integer","minimum":1,"maximum":31,"description":"Día 1-31"},"empresa":{"type":"string","description":"RUT empresa con DV","example":"77644429-4"}}}}}},"responses":{"200":{"description":"Informe diario con boletas y totales","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"nombreContribuyente, rut, dv, fecha, anio, mes, dia, totalBoletas, totales, boletas[]"}}}}}},"400":{"description":"Año fuera de rango","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"403":{"description":"Faltan credenciales del representante","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"Empresa no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Error de validación","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Error del SII","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}},"x-facttura-environments":{"selector":"organization_api_key","routesUnchanged":true,"separateKeysRequired":true,"sandboxTaxValidity":false,"webhookHeaders":["X-Facttura-Environment","X-Facttura-Livemode"]}}