Manual de Integración API

Copia este texto y pégalo en ChatGPT, Claude o el asistente que uses para que programe la integración por ti. Reemplaza TU_API_TOKEN por el token de tu empresa.

# API de Facturador Web

URL base: https://sistema.facturadorweb.cl

Necesito integrar mi sistema con esta API. Estos son los endpoints, los campos y las reglas.

## 02 · Autenticación

Todas las rutas requieren el API token de la empresa. El token se genera desde el
sistema en Mi perfil (https://sistema.facturadorweb.cl/miperfil), botón
"Generar API token". Es por usuario y empresa: al generarlo de nuevo, el anterior
deja de servir.

Se envía de cualquiera de estas formas:

    Authorization: Bearer TU_API_TOKEN
    ?api_token=TU_API_TOKEN            (en la URL)
    "api_token": "TU_API_TOKEN"        (en el cuerpo del POST)

La empresa, la sucursal y el usuario se deducen del token: nunca se mandan en el
cuerpo. Sin token o con un token inválido la respuesta es HTTP 401.
Límite de uso: 60 peticiones por minuto.

## 03 · Registrar una venta

POST /api/save-sale

Crea el borrador de la venta con sus ítems, y opcionalmente firma el DTE en el
mismo llamado enviando "firmar": "Si".

Campos del cuerpo (JSON):

- identificador (requerido, string): id de la venta en mi sistema. Se guarda como
  venta_externa_id y sirve para firmarla después. Debe ser único por venta.
- doc_tributario (requerido, int): tipo de documento (ver tabla más abajo).
- rut (requerido, string): rut del cliente, formato 11111111-1.
- nombre (requerido, string): nombre o razón social.
- email, telefono, direccion, ciudad, giro (opcionales, string).
- comunas_id (opcional, int) o comuna (opcional, string, nombre): comuna del
  cliente. Si no envías ninguna, queda la comuna de tu empresa.
- formapago_id (opcional, int): forma de pago (ver tabla). Por defecto 1.
- valor_neto, valor_iva, valor_exento, valor_bruto, valor_total (opcionales, number).
- detail (requerido, array): ítems de la venta. Sin este campo la venta no se crea.
- firmar (opcional, string): "Si" para firmar el DTE de inmediato.

Cada elemento de detail:

- nombre (requerido, string): nombre del producto o servicio.
- descripcion (opcional, string), codigo (opcional, string), productos_id (opcional, int).
- cantidad (requerido, number).
- neto e iva (requeridos salvo documentos exentos, number): POR UNIDAD.
- valor (requerido, number): total POR UNIDAD (neto + iva si es afecto).

Ejemplo:

    curl -X POST "https://sistema.facturadorweb.cl/api/save-sale" \
      -H "Authorization: Bearer TU_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "identificador": "PEDIDO-1001",
        "doc_tributario": 39,
        "rut": "11111111-1",
        "nombre": "Cliente de prueba",
        "email": "cliente@correo.cl",
        "comunas_id": 295,
        "formapago_id": 9,
        "detail": [
          { "nombre": "Producto A", "cantidad": 2, "neto": 1000, "iva": 190, "valor": 1190 }
        ],
        "firmar": "Si"
      }'

La respuesta trae status y el id de la venta en el sistema, por ejemplo
{ "status": "success", "id": 1372600, ... }. El id viene también cuando la firma
falla (status "warning"): el borrador queda guardado con ese id. Si no se guardó
nada, es un error sin id.

## 04 · Firmar el DTE

GET /api/firmar/{identificador}

Firma y emite ante el SII una venta ya registrada. El identificador es el mismo
que se envió al crearla. Cada firma consume un folio del SII: no firmar dos veces
el mismo identificador.

    curl "https://sistema.facturadorweb.cl/api/firmar/PEDIDO-1001" \
      -H "Authorization: Bearer TU_API_TOKEN"

## 05 · Crear una cotización

POST /api/crear/cotizacion

Crea una cotización, que queda listada en el sistema en Ventas > Cotizaciones
(https://sistema.facturadorweb.cl/ventas/cotizaciones), igual que las que se hacen
a mano. Una cotización NO se firma ni consume folios del SII.

Campos del cuerpo (JSON):

- rut (requerido, string): rut del cliente. Acepta con o sin puntos.
- nombre (requerido, string): nombre o razón social.
- detalles (requerido, array): ítems de la cotización, al menos uno.
- venta_externa_id (opcional, string): id de la cotización en mi sistema. Si se
  envía y se repite el llamado, se actualiza la misma cotización en vez de
  duplicarla (útil para reintentos).
- documentotributario_id (opcional, int): 33 factura (por defecto), 39 boleta,
  34 factura exenta, 41 boleta exenta. Con 34 o 41 todo el detalle va exento.
- fecha (opcional, YYYY-MM-DD): por defecto hoy.
- comuna (opcional, string) o comunas_id (opcional, int): si no se envía ninguno
  queda la comuna de la empresa.
- email, telefono, celular, direccion, ciudad, giro (opcionales, string).
- condicionesdepago, atencion, titulo, comentario, pie_cotizacion (opcionales, string).
- formapago_id (opcional, int), centro_costos_id (opcional, int).

Cada elemento de detalles:

- descripcion (requerido, string): nombre del producto o servicio.
- cantidad (requerido, number).
- total (requerido, number): precio unitario BRUTO, con IVA incluido. También se
  acepta con el nombre precio o valor_unitario. El neto y el IVA los calcula el
  sistema.
- codigo, detalle, unidad_medida (opcionales, string; unidad_medida por defecto "UN").
- afecto_iva (opcional, 0 o 1): 0 deja esa línea exenta. Por defecto 1.
- descuento (opcional, number): descuento unitario.

Ejemplo:

    curl -X POST "https://sistema.facturadorweb.cl/api/crear/cotizacion" \
      -H "Authorization: Bearer TU_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "venta_externa_id": "COT-2001",
        "rut": "11111111-1",
        "nombre": "Cliente de prueba",
        "email": "cliente@correo.cl",
        "telefono": "912345678",
        "direccion": "Calle Falsa 123",
        "comuna": "Santiago",
        "giro": "Servicios",
        "documentotributario_id": 33,
        "condicionesdepago": "30 dias",
        "detalles": [
          { "codigo": "P1", "descripcion": "Producto uno", "cantidad": 2, "total": 11900 },
          { "codigo": "P2", "descripcion": "Producto dos", "cantidad": 1, "total": 5950, "afecto_iva": 0 }
        ]
      }'

Respuesta (HTTP 201 al crear, 200 si actualizó una existente):

    {
      "status": "success",
      "mensaje": "Cotizacion creada",
      "id": 1371090,
      "correlativo": 2,
      "valor_neto": 20000,
      "valor_exento": 5950,
      "valor_iva": 3800,
      "valor_total": 29750,
      "url_cotizacion": "https://sistema.facturadorweb.cl/ver-cotizacion/MTM3MTA5MA=="
    }

url_cotizacion es un link público: se le puede mandar al cliente para que vea la
cotización y descargue su PDF, sin necesidad de que tenga usuario.

Si faltan campos obligatorios responde HTTP 422:

    {
      "status": "error",
      "errores": { "detalles": ["La cotizacion debe tener al menos un producto"] }
    }

## 06 · Crear un pedido web (tienda online)

POST /api/crear/pedido

Registra un pedido de la tienda con sus productos y, si ya lo pagaron, el
comprobante de pago. Llega a Sitio WEB > Pedidos, en la pestaña que indique estado
(por defecto "Nuevos pedidos", Por Pagar). Desde ahí el administrador revisa el
comprobante y presiona "Confirmar Pago", que crea la venta en el sistema.
No uses /api/save-sale para esto.

Campos del cuerpo (JSON):

- rut, nombre, correo (o email), telefono (requeridos, string).
- detalles (requerido, array): productos del pedido, al menos uno.
- codigo (opcional, string): id del pedido en mi tienda. Repetir el mismo codigo
  no duplica el pedido: responde el existente y, si viene un estado más avanzado,
  lo mueve de pestaña (sirve para reintentos y para avanzar el pedido).
- estado (opcional): "nuevo" (por defecto, pestaña Nuevos pedidos), "atendido"
  (Pedidos Atendidos) o "entregado" (Pedidos Entregados).
- documento (requerido, int): 39 boleta electronica, 33 factura electronica, 41
  boleta exenta electronica o 34 factura exenta electronica. Con 34 o 41 el
  detalle va exento, sin IVA. También se aceptan las palabras "Boleta" y
  "Factura". Enviar giro si es factura.
- direccion, ciudad (opcionales, string). comuna (nombre) o comunas_id (opcional).
- retiro (opcional): "Domicilio", "Sucursal" o "Tienda".
- forma_pago (opcional): transferencia (por defecto), webpay, flow, mercadopago.
- costo_envio, descuento (opcionales, int, en pesos).
- pago (opcional, objeto): comprobante del pago.

Cada elemento de detalles:

- nombre (requerido, string), cantidad (requerido, int, mínimo 1).
- valor (requerido, number): precio UNITARIO con IVA incluido. El total del pedido
  se calcula solo: suma de valor x cantidad + costo_envio - descuento.
- descripcion (opcional), productos_id (opcional, int: producto del sistema).

Objeto pago:

- comprobante (opcional, string): archivo en base64 (se acepta data URI). Imagen
  JPG, PNG o WEBP de hasta 15 MB, o PDF de hasta 5 MB. Las imágenes se optimizan al recibirlas
  (JPG de hasta 1.600 px por lado, orientación corregida); los PDF quedan igual.
- comprobante_nombre (opcional, string), monto (opcional, number, no mayor al
  total), fecha (opcional, YYYY-MM-DD, por defecto hoy), operacion (opcional).

También se puede enviar como multipart/form-data con el archivo en
pago[comprobante]. Si algún dato viene malo el pedido NO se crea: HTTP 422 con el
detalle en errores. Responde 201 al crear y 200 si el codigo ya existía.

Estados (campo estado):

- nuevo -> Nuevos pedidos (Por Pagar). Es el único que después se confirma con
  "Confirmar Pago" y genera la venta.
- atendido -> Pedidos Atendidos (Pagado).
- entregado -> Pedidos Entregados (Pagado y Entregado).

Con atendido o entregado el pedido SOLO queda en esa pestaña: no crea la venta, no
descuenta stock y no envía correos. Para avanzar un pedido ya enviado, repite el
llamado con el mismo codigo y el nuevo estado (nuevo -> atendido -> entregado).
Nunca retrocede y no toca pedidos cancelados.

Respuestas: siempre JSON, con un id o con un error.

- 201: pedido creado, trae status "success" e id.
- 200: ya existía un pedido con ese codigo, trae el id del existente.
- 401: token ausente o inválido. 403: el token no tiene empresa válida.
- 405: método no permitido (usar POST).
- 422: datos inválidos, trae el detalle por campo en errores. No se guardó nada.
- 429: límite de peticiones por minuto. 500: error interno al guardar.

Todo error trae "status": "error" y el motivo en "message", sin id. Ante 429 o 500
reintenta con el mismo codigo: nunca se duplica.

Ejemplo:

    curl -X POST "https://sistema.facturadorweb.cl/api/crear/pedido" \
      -H "Authorization: Bearer TU_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "codigo": "TIENDA-3001",
        "estado": "nuevo",
        "rut": "11111111-1",
        "nombre": "Cliente de prueba",
        "correo": "cliente@correo.cl",
        "telefono": "912345678",
        "direccion": "Calle Falsa 123",
        "comuna": "Santiago",
        "documento": 39,
        "costo_envio": 3500,
        "detalles": [
          { "nombre": "Producto A", "cantidad": 2, "valor": 11900 },
          { "nombre": "Producto B", "cantidad": 1, "valor": 5950 }
        ],
        "pago": {
          "monto": 33250,
          "operacion": "TRX-558812",
          "comprobante_nombre": "transferencia.pdf",
          "comprobante": "JVBERi0xLjQK... (archivo en base64)"
        }
      }'

Respuesta:

    { "status": "success", "message": "Pedido creado", "id": 145,
      "codigo": "TIENDA-3001", "estado": "Por Pagar", "total": 33250,
      "comprobante_id": 12 }

### Mover un pedido ya creado

    POST /api/pedido/{id}/estado

    estado      obligatorio   atendido | entregado
    notificar   opcional      true envia el correo al cliente por el cambio de estado
                              (por defecto false, no envia nada)

Solo mueve el pedido de pestana: no registra la venta, no firma DTE y no descuenta stock.
El estado nunca retrocede. Acepta el id del pedido o tu propio codigo.

    curl -X POST "https://sistema.facturadorweb.cl/api/pedido/145/estado" \
      -H "Authorization: Bearer TU_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "estado": "entregado", "notificar": true }'

Respuesta:

    { "status": "success", "message": "El pedido se movio a Pagado y Entregado",
      "id": 145, "codigo": "TIENDA-3001", "estado": "Pagado y Entregado",
      "estado_anterior": "Pagado", "movido": true, "correo_enviado": true,
      "venta_id": 1372576, "venta_folio": 4, "venta_firmada": true }

venta_id es el id en operacionestributarias de la venta que el ERP registro con
Confirmar Pago, con su folio en venta_folio. Si el pedido todavia no tiene venta
vienen en null: este endpoint no la crea. Si la venta quedo como borrador sin
firmar, venta_firmada viene en false y venta_folio en null.

## 07 · Tipos de documento (doc_tributario / documentotributario_id)

    33  Factura Electrónica
    34  Factura Exenta Electrónica
    39  Boleta Electrónica
    41  Boleta Exenta Electrónica
    52  Guía de Despacho Electrónica
    56  Nota de Débito Electrónica
    61  Nota de Crédito Electrónica

## 08 · Formas de pago (formapago_id)

    1   Por pagar          2   Efectivo
    3   Tarjeta de Débito  4   Tarjeta de Crédito
    5   Cheque al día      6   Cheque a fecha
    7   Crédito empresa    8   Transferencia
    9   Contado            10  Pago Digital
    30  Sin pago registrado
    31  Pago Electrónico

## 09 · Errores frecuentes al firmar

- {"error": "El certificado digital ha caducado"}: hay que renovar el certificado.
- {"error": "No hay folios disponibles"}: pedir folios al SII.
- {"error": "Los folios disponibles están vencidos"}: superaron los 6 meses.
- {"error": "El identificador de venta no es válido"}: ese identificador no existe.
- {"status": "warning", "message": "El borrador fue generado, pero no se pudo emitir el DTE"}:
  la venta se guardó pero la firma falló; se puede reintentar con /api/firmar/{identificador}.

## 10 · Reglas a respetar

1. Los valores por ítem son SIEMPRE unitarios, nunca el total de la línea: el
   sistema multiplica por la cantidad.
2. En /api/save-sale el ítem lleva neto e iva por separado; en /api/crear/cotizacion
   basta el precio bruto en total.
3. Guardar el identificador / venta_externa_id de cada documento: es la única forma
   de volver a referenciarlo.
4. Nunca exponer el API token en código de front-end: los llamados se hacen desde
   el servidor.