Documentación de Integración B2B - DiffSii API

Esta API REST permite a sistemas externos (ERPs, CRMs o software a medida) inyectar movimientos comerciales (Compras y Ventas) directamente a la base de datos de DiffSii. El sistema aplicará deduplicación inteligente, validación de periodos y asentar los movimientos contablemente de manera automática.

1. Autenticación (Login)

Todos los endpoints están protegidos y requieren un token JWT. Para obtener el token, debes autenticarte en el endpoint general de DiffSii.

Request: Obtener Token

Body (JSON):

{
  "email": "usuario@tuempresa.cl",
  "password": "tu_password_segura"
}

Respuesta Exitosa (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR...",
  "user": {
    "id": 1,
    "name": "Juan Perez",
    "companies": [
      {
        "id": 10,
        "name": "Empresa de Prueba SpA"
      }
    ]
  }
}

2. Inyección de Movimientos Masivos

Este endpoint permite enviar un lote de facturas o boletas para un periodo contable específico.

Endpoint

(Reemplaza {companyId} por el ID de la empresa obtenido en el Login)

Headers Requeridos

• Authorization: Bearer {tu_token_aqui}
• Content-Type: application/json

Estructura del Payload (JSON)

{
  "tipo": "ventas", 
  "periodo": "2024-04",
  "movimientos": [
    {
      "tipoDocumento": "33",
      "folio": 14502,
      "rutContraparte": "76123456-7",
      "montoNeto": 100000,
      "montoExento": 0,
      "montoIva": 19000,
      "montoTotal": 119000,
      "fechaEmision": "2024-04-15"
    }
  ]
}

Diccionario de Datos

• tipo: Obligatorio. Solo acepta "compras" o "ventas".
• periodo: Obligatorio. Formato YYYY-MM.
• tipoDocumento: Código tributario del SII (ej: "33", "39") o nombre descriptivo.
• folio: Número del documento (entero).
• rutContraparte: RUT del cliente o proveedor (con guion y dígito verificador).
• montoNeto, montoExento, montoIva, montoTotal: Valores numéricos enteros.
• fechaEmision: Fecha en formato YYYY-MM-DD.

Respuestas y Códigos de Error - Servicio POST Movimientos

Ocurre cuando la petición fue procesada y se inyectaron los registros exitosamente.

{
  "message": "Registros insertados (Total: 1). Ignorados: 0.",
  "records": 1,
  "duplicates": 0
}

Ocurre si todos los registros que enviaste ya existen en la base de datos (mismo Folio, Tipo, RUT y Periodo). El sistema protege la integridad contable y los ignora automáticamente.

Error de formato en el JSON (ej. array vacío o tipo incorrecto).

Ocurre si el usuario del token no tiene permisos comerciales, o si intentas enviar más documentos del límite del plan.

El periodo ha sido cerrado de forma contable por el administrador. No se aceptan inyecciones.

3. Descarga de Movimientos (Exportación)

Este endpoint permite a sistemas externos recuperar los movimientos (compras o ventas) previamente inyectados y procesados, incluyendo su estado de cuadratura actual.

Endpoint

(Reemplaza {companyId} por el ID de la empresa obtenido en el Login)

Headers Requeridos

• Authorization: Bearer {tu_token_aqui}

Parámetros de Consulta (Query Params)

• periodo: (Opcional) Filtra los documentos de un mes específico (ej: "2024-05").
• tipo: (Opcional) Selecciona el libro contable ("compras" o "ventas").
• estado: (Opcional) Filtra por subestado del documento (ej: "Aceptado", "Pendiente", "Reclamado", "Excluido").

Respuestas y Códigos de Error - Servicio GET Movimientos

Ocurre cuando la petición es procesada correctamente. Devuelve la lista de movimientos registrados en la base de datos de DiffSii según los filtros aplicados.

{
  "success": true,
  "count": 2,
  "data": [
    {
      "id": 105,
      "tipo": "ventas",
      "tipoDocumento": "33 - Factura electrónica",
      "folio": 14502,
      "rutContraparte": "76123456-7",
      "montoNeto": 100000,
      "montoIva": 19000,
      "montoTotal": 119000,
      "periodo": "2024-04"
    },
    "... otros documentos ..."
  ]
}

Ocurre cuando no se envía el header Authorization con un token JWT válido, o si el token ha expirado.

{
  "error": "Token de autenticación inválido o no proporcionado."
}

Ocurre cuando el token es válido, pero el usuario no tiene los permisos suficientes asignados en la plataforma (RBAC) para el módulo solicitado (Compras o Ventas).

{
  "error": "Tu usuario no tiene acceso concedido para solicitar información del módulo de Ventas."
}

Ocurre si hay un problema de conexión con la base de datos o un error inesperado al procesar la solicitud en el servidor.