webFactura

Documentación de integración

Consultar documentos — getDocumentsFiltered

Endpoint de consulta para sistemas externos (POS, ERP, e-commerce, etc) que necesiten leer documentos tributarios electrónicos emitidos o recibidos, con filtros dinámicos y paginación.

GET {host} /api/v3/pos/getDocumentsFiltered/data
Sandbox api-qa.webfactura.cl Producción api.webfactura.cl
← Documentación general de la API Solicitar credenciales →

01 Descripción general

Por cada documento que cumpla los filtros solicitados, la respuesta entrega:

  • Datos generales — folio, fecha, tipo de documento, estado ante el SII
  • Datos del emisor y del receptor
  • Totales — neto, exento, IVA, total
  • Detalle de ítems (líneas del documento)
  • Referencias a otros documentos (notas de crédito/débito, guías, órdenes de compra, etc.)
  • Enlace de descarga del PDF, o el XML del documento según el formato solicitado

02 Autenticación

OAuth 2.0, grant type client_credentials. Toda solicitud va por HTTPS. Cada llamada debe incluir un token vigente en el header: 

Authorization: Bearer {access_token}

Obtención del token

POST {host} /oauth/v2/token

Usar el host del ambiente correspondiente — ver sección 03.

Parámetro Valor
grant_type client_credentials
client_id Entregado por webFactura al habilitar la integración
client_secret Entregado por webFactura al habilitar la integración

Respuesta

{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": null,
  "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Nota: client_id/client_secret identifican unívocamente a la empresa — no se indica ningún identificador de empresa en la consulta; se resuelve automáticamente a partir del token.

03 Endpoint

No recibe body — todos los parámetros se envían como query string.

Ambiente Host
Sandbox / pruebas https://api-qa.webfactura.cl
Producción https://api.webfactura.cl

04 Parámetros de consulta

Parámetro Tipo Requerido Default Descripción
operation string No VENTA VENTA o COMPRA (no distingue mayúsculas). Documentos emitidos o recibidos por la empresa.
limit entero positivo No 50 Documentos por página.
page entero positivo No 1 Número de página.
searchCriteria objeto anidado No — Filtros dinámicos. Ver sección siguiente.
resource string No DATA
  • DATA — detalle completo del documento
  • XML — XML sin firma en base64
  • XMLFIRMADO — XML firmado en base64
  • 80MM — solo link a PDF formato ticket

limit y page deben ser enteros positivos válidos; de lo contrario la API retorna 400.

05 Filtros dinámicos

Arreglo de condiciones bajo searchCriteria[filter], usando notación estándar de query params anidados: 

searchCriteria[filter][0][field]=RUTRecep
searchCriteria[filter][0][value]=76123456-7
searchCriteria[filter][0][conditionType]=igual
searchCriteria[filter][1][field]=FchEmis
searchCriteria[filter][1][value]=2026-07-01
searchCriteria[filter][1][conditionType]=mayorIgual
Propiedad Descripción
field Campo a filtrar — ver tabla de campos disponibles.
value Valor a comparar.
conditionType igual · mayor · menor · mayorIgual · menorIgual

Campos disponibles (field)

Alias Descripción
TipoDTE Tipo de documento tributario (código SII, ej. 33, 34, 39, 61)
FchEmis Fecha de emisión
RUTEmisor RUT del emisor
RUTRecep RUT del receptor
Default: Si no se especifica TipoDTE, se aplica un conjunto de tipos por defecto según operation: VENTA → 33, 34, 39, 41, 43, 56, 61, 110, 111, 112 · COMPRA → 33, 34, 46, 56, 61 (exige además período contable asignado).

Los resultados se ordenan siempre por fecha de emisión ascendente; el orden no es configurable.

06 Ejemplo de solicitud

Consulta de documentos de compra (operation=COMPRA), página 1 con 20 resultados por página, filtrando solo los documentos cuya fecha de emisión sea mayor o igual a 2026-07-01. 

GET /api/v3/pos/getDocumentsFiltered/data?operation=COMPRA&page=1&limit=20&searchCriteria[filter][0][field]=FchEmis&searchCriteria[filter][0][value]=2026-07-01&searchCriteria[filter][0][conditionType]=mayorIgual
Authorization: Bearer {access_token}

Desglose de los parámetros usados

Parámetro Valor Significado
operation COMPRA Documentos recibidos por la empresa
page 1 Primera página de resultados
limit 20 20 documentos por página
searchCriteria[filter][0][field] FchEmis Filtrar por fecha de emisión
searchCriteria[filter][0][value] 2026-07-01 Fecha a comparar
searchCriteria[filter][0][conditionType] mayorIgual Condición mayor o igual (>=)

Para agregar más de un filtro, se repite el mismo patrón incrementando el índice (searchCriteria[filter][1][field]=...) — todos los filtros se combinan con AND.

07 Estructura de la respuesta

Resultado exitoso — resource=DATA (default)

Nota: UrlPdf/docUrl vienen resueltas por la propia API — usar el valor tal como llega en la respuesta, sin asumir el dominio. 
{
  "status": "OK",
  "docs": [
    {
      "UrlPdf": "https://{host_pdf}/pdf/{token}",
      "TipoDTE": 33,
      "TipoDTENombre": "Factura Electrónica",
      "id": 123456,
      "Folio": 987,
      "FchEmis": "2026-07-20",
      "FmaPago": "1",
      "TermPagoGlosa": "Contado",
      "FchVenc": "2026-08-19",
      "EstadoSII": "ACEPTADO",
      "Emisor": {
        "RUTEmisor": "76000000-1",
        "RznSoc": "Empresa Emisora SPA",
        "GiroEmis": "Servicios informáticos",
        "Acteco": "620200",
        "DirOrigen": "Av. Siempre Viva 123",
        "CmnaOrigen": "Providencia",
        "CiudadOrigen": "Santiago"
      },
      "Receptor": {
        "RUTRecep": "76123456-7",
        "RznSocRecep": "Empresa Receptora Ltda.",
        "GiroRecep": "Comercio",
        "Contacto": "Juan Pérez",
        "CorreoRecep": "juan.perez@ejemplo.cl",
        "DirRecep": "Calle Falsa 456",
        "CmnaRecep": "Ñuñoa",
        "CiudadRecep": "Santiago"
      },
      "Totales": {
        "SubTotal": 100000,
        "MntNeto": 100000,
        "MntExe": 0,
        "TasaIVA": 19,
        "IVA": 19000,
        "MntTotal": 119000
      },
      "Observacion": "",
      "SucursalCodigo": "001",
      "Detalles": [
        {
          "NroLinea": 1,
          "CdgItem": [ { "TpoCodigo": "INT", "VlrCodigo": "SKU-001" } ],
          "SKUItem": "SKU-001",
          "NmbItem": "Producto de ejemplo",
          "DscItem": "Descripción del producto",
          "QtyItem": 2,
          "UnmdItem": "UN",
          "PrcItem": 50000,
          "DescuentoPct": 0,
          "DescuentoMonto": 0,
          "MontoItem": 100000
        }
      ],
      "Referencias": [
        {
          "NroLinRef": 1,
          "TpoDocRef": "801",
          "FolioRef": "12345",
          "FchRef": "2026-07-15",
          "RazonRef": "Referencia a orden de compra"
        }
      ]
    }
  ],
  "pagination": {
    "currentPage": 1,
    "itemsPerPage": 20,
    "totalRecords": 1,
    "totalPages": 1
  }
}
  • CdgItem solo aparece si el ítem tiene código.
  • Referencias solo aparece si el documento tiene documentos referenciados asociados.
  • DscRcgGlobal solo aparece si el documento tiene un descuento global aplicado.
  • OtraMoneda solo aparece en documentos de exportación (tipos 110, 111, 112) con tipo de cambio informado.

Sin resultados

{ "status": "OK", "message": "No se encuentran documentos" }

resource=XML (XML sin firma)

Cada elemento de docs se reemplaza por un objeto reducido con solo id, Folio y xml (XML sin firma, pierde el resto de campos). Si la consulta retorna varios documentos, docs trae un elemento por cada uno: 

{
  "status": "OK",
  "docs": [
    { "id": 123456, "Folio": 987, "xml": "PD94bWwgdmVyc2lvbj0iMS4wIi..." },
    { "id": 123457, "Folio": 988, "xml": "PD94bWwgdmVyc2lvbj0iMS4wIi..." },
    { "id": 123458, "Folio": 989, "xml": "Sin XML Disponible" }
  ],
  "pagination": {
    "currentPage": 1,
    "itemsPerPage": 20,
    "totalRecords": 3,
    "totalPages": 1
  }
}
Atención: xml viene en base64. Si el documento no tiene XML disponible, el valor es el string "Sin XML Disponible" — no es null. El integrador debe verificar este caso antes de intentar decodificar el valor.

resource=XMLFIRMADO

Igual que resource=XML, pero retorna el XML firmado del documento (el mismo que se envía al SII), en vez del XML sin firma. Cada elemento de docs se reemplaza por un objeto con id, Folio y xmlFirmado: 

{
  "status": "OK",
  "docs": [
    { "id": 123456, "Folio": 987, "xmlFirmado": "PD94bWwgdmVyc2lvbj0iMS4wIi..." },
    { "id": 123457, "Folio": 988, "xmlFirmado": null, "message": "XML Firmado no disponible, vuelva a consultar a partir de las 2026-08-05 15:00 hrs." }
  ],
  "pagination": {
    "currentPage": 1,
    "itemsPerPage": 20,
    "totalRecords": 2,
    "totalPages": 1
  }
}
Atención: el XML firmado solo existe una vez que el documento fue enviado al SII. Mientras no esté disponible, xmlFirmado viene en null (a diferencia de resource=XML, que usa el string "Sin XML Disponible") y se agrega un campo message indicando cuándo reintentar: si el documento tiene un envío al SII programado, indica la hora estimada (envío programado + 30 minutos); si no, sugiere reintentar en unos minutos.

resource=80MM (formato ticket)

Si la consulta retorna un único documento:

{ "docUrl": "https://{host_pdf}/pdf/{token}/3", "status": "OK" }

Si retorna más de un documento, cada elemento de docs se reemplaza por {"docUrl": "..."}, manteniendo el wrapper status/docs/pagination.

08 Manejo de errores

Importante: esta API solo retorna un código HTTP distinto de 200 para errores de parámetros inválidos o de autenticación. Los errores de negocio se retornan con HTTP 200 y "status": "ERR" en el body. El integrador siempre debe revisar el campo status de la respuesta, no solo el código HTTP.
HTTP Situación Respuesta
401 Token ausente, inválido o expirado Respuesta estándar OAuth2 (invalid_token / access_denied)
403 Petición no realizada por HTTPS Rechazo por el firewall
400 limit inválido (no numérico o ≤ 0) {"error": "El valor del límite no es válido..."}
400 page inválido (no numérico o ≤ 0) {"error": "El valor de la página no es válido..."}
400 operation distinto de VENTA/COMPRA {"error": "El valor de la operation no es válido..."}
200 Token válido pero sin empresa asociada {"status": "ERR", "message": "No se encuentra la empresa."}
200 Otro error interno (ej. field de filtro inexistente) {"status": "ERR", "message": "ERR: {detalle} En la Linea: {n}"}
200 Sin documentos que cumplan los filtros {"status": "OK", "message": "No se encuentran documentos"}

09 Recomendaciones para la integración

  • Cachear el access_token y renovarlo antes de que expire (expires_in), en vez de solicitar uno nuevo en cada llamada.
  • Validar siempre status en el body de la respuesta antes de asumir éxito.
  • Usar page/limit para recorrer resultados grandes — se recomienda un valor moderado (50–100) por página.
  • Si se requiere el XML del DTE, usar resource=XML en una llamada separada — no viene incluido en la respuesta estándar.
Solicitar credenciales de integración
Soporte Agendar demo Hablar con Ventas