Documentación API — Taskmania.cl | Integración SII Chile

Flujo de integración

Taskmania.cl opera de forma asíncrona. Tu software registra la solicitud y luego consulta el resultado cuando el procesamiento interno ha finalizado.

1

Tu software registra la solicitud

Envía las credenciales SII de la empresa, el período y el tipo de información requerida. Recibes un id_sync de confirmación.

POST /api/sync/ → 202 pending

Guarda el id_sync que recibes — lo vas a necesitar en el paso 3.

2

Taskmania procesa con el SII

El proceso interno consulta el SII, obtiene la información y la almacena. Este paso es completamente transparente para tu software.

Proceso interno automático

Aquí soy yo. Me encargo del SII sin que tengas que hacer nada.

3

Tu software recupera el resultado

Consulta el estado. Si retorna "status": "ready", el campo data contiene el JSON del SII listo para usar.

POST /api/retrieve/ → 200 ready

Si ves "pending", espera unos segundos y vuelve a consultar. El dato ya viene en camino.

🔔

Notificación por Webhook (recomendado): En lugar de consultar /api/retrieve/ periódicamente, puedes registrar una Callback URL en tu cuenta. Cuando la sincronización finalice, Taskmania.cl enviará un POST automático a esa URL con el resultado listo — eliminando la necesidad de polling. Ver sección Callback URL →

Autenticación

Todos los requests requieren el campo api_key en el cuerpo del request. La clave es provista por Taskmania.cl al contratar el servicio.

JSON

{
  "api_key": "XXXX-XXX-XXXXX",
  // ... resto de los campos del endpoint
}

Tasky recomienda

Tu api_key es la llave de acceso a toda la API. Guárdala en una variable de entorno, nunca en el código fuente. Si la expones, contáctanos y la rotamos de inmediato.

Código	Significado
EXITO = 1	Key válida y activa — acceso permitido
EXITO = 0	Key no encontrada → HTTP 401
EXITO = -1	Key deshabilitada → HTTP 403
EXITO = -2	Key vencida → HTTP 401

Consideraciones generales

ℹ️

Content-Type: Todos los requests deben enviarse como application/json. Las respuestas siempre son JSON con Content-Type: application/json; charset=utf-8.

🔄

Re-sincronización: Si se solicita el mismo tipo y período más de una vez, el resultado anterior es sobreescrito y el campo data vuelve al estado pendiente hasta que el nuevo procesamiento finalice.

POST /api/sync/

Registra una solicitud de sincronización con el SII para una empresa y período determinado. La solicitud queda en estado pendiente hasta que el proceso interno la complete.

POST https://taskmania.cl/api/sync/ Content-Type: application/json

Parámetros del request

Campo	Tipo	Requerido	Descripción
api_key	string	Sí	API Key de autenticación provista por Taskmania.cl.
RutEmpresa	string	Sí	RUT de la empresa en el SII. Ejemplo: `77577479-7`
PasswordSII	string	Sí	Contraseña de acceso al SII de la empresa.
Ambiente	integer	Sí	`1` = Producción · `2` = Certificación
TipoSincro	string	Sí	Tipo de información a consultar. Ver Tipos de sincronización.
mes	string	Sí	Mes del período tributario. Formato numérico, 1 a 12. Ejemplo: `"6"`
anno	string	Sí	Año del período tributario. 4 dígitos. Ejemplo: `"2026"`

Ejemplo de request

JSON

POST https://taskmania.cl/api/sync/
Content-Type: application/json

{
  "api_key":     "XXXX-XXX-XXXXX",
  "RutEmpresa":  "77577479-7",
  "PasswordSII": "mi_clave_sii",
  "Ambiente":    1,
  "TipoSincro": "RCV_C",
  "mes":         "6",
  "anno":        "2026"
}

Respuestas

202 pending

Solicitud registrada correctamente. El campo id_sync identifica esta sincronización.

400 error

Campo requerido faltante, TipoSincro inválido, mes o año fuera de rango.

401 / 403 error

API Key no válida, deshabilitada o vencida.

Ejemplo de respuesta exitosa (202)

JSON

{
  "status":  "pending",
  "id_sync": 10,
  "mensaje": "Solicitud registrada, procesamiento en curso.",
  "detalle": {
    "tipo_sincro": "RCV_C",
    "periodo":    "06/2026"
  }
}

POST /api/retrieve/

Consulta el resultado de una sincronización previamente solicitada. Puede retornar tres estados según el avance del procesamiento interno.

POST https://taskmania.cl/api/retrieve/ Content-Type: application/json

Parámetros del request

Campo	Tipo	Requerido	Descripción
api_key	string	Sí	API Key de autenticación.
TipoSincro	string	Sí	Mismo valor usado al crear la solicitud. Ver Tipos de sincronización.
mes	string	Sí	Mes del período. Ejemplo: `"6"`
anno	string	Sí	Año del período. Ejemplo: `"2026"`

Ejemplo de request

JSON

POST https://taskmania.cl/api/retrieve/
Content-Type: application/json

{
  "api_key":    "XXXX-XXX-XXXXX",
  "TipoSincro": "RCV_C",
  "mes":         "6",
  "anno":        "2026"
}

Estados de respuesta

200 ready

Resultado disponible. El campo data contiene el JSON del SII codificado en base64.

202 pending

La sincronización existe pero aún está siendo procesada. Reintentar en unos minutos.

404 not_found

No existe solicitud de sincronización para ese período y tipo. Primero llamar a /api/sync/.

Tasky recomienda

Implementa un polling con espera progresiva: 3 s → 6 s → 12 s. Si tras 5 intentos el estado sigue en pending, muéstrale al usuario que el SII está tardando más de lo normal.

Respuesta cuando hay datos disponibles (200)

JSON

{
  "status":  "ready",
  "id_sync": 10,
  "periodo": "06/2026",
  "tipo":    "RCV_C",
  "cantidad_sincronizaciones": 1,
  "fecha_sincronizacion": "2026-06-23 20:47:23",
  "data": "eyJwYXRoIjoiey4uLn0iLCJjcmVkZW5jaWFsZXMiOlsiLi4uIl19"
}

📦

El campo data es un string codificado en base64 que contiene el JSON completo del SII. Para obtener los datos, aplicar base64_decode(data) y luego parsear como JSON.

Decodificar el campo data

PHP

// Respuesta de /api/retrieve/ ya parseada como array
$response = json_decode($body, true);

if ($response['status'] === 'ready') {
    $json = json_decode(base64_decode($response['data']), true);
    $datos_sii = $json['path']; // JSON string con el contenido del SII
}

Respuesta mientras está en proceso (202)

JSON

{
  "status":  "pending",
  "mensaje": "La sincronización está en proceso. Intente nuevamente en unos minutos.",
  "periodo": "06/2026",
  "tipo":    "RCV_C"
}

Tipos de sincronización

El campo TipoSincro determina qué información se consulta al SII para el período indicado.

Valor	Descripción	Datos obtenidos
RCV_C	Registro de Compras y Ventas — Compras	Facturas de compra, crédito fiscal IVA, resúmenes por tipo de documento
RCV_V	Registro de Compras y Ventas — Ventas	Facturas de venta emitidas, débito fiscal IVA, resúmenes por tipo de documento
BHE	Boletas de Honorarios Electrónicas	Boletas emitidas, monto bruto, retenciones, monto líquido
F29	Formulario 29 — Declaración mensual de IVA	Declaración mensual, historial de envíos, certificado solemne, períodos sin declaración

Códigos de error

Cuando ocurre un error, la respuesta siempre incluye "status": "error" y un codigo identificador.

JSON

{
  "status":  "error",
  "codigo":  "CAMPO_REQUERIDO",
  "mensaje": "El campo 'mes' es obligatorio."
}

Tasky te ayuda

Ante un error 4xx revisa primero el campo codigo — es más específico que el HTTP status. Un AUTH_FAILED con 403 significa que la key existe pero fue deshabilitada, no que sea incorrecta.

Código	HTTP	Causa
CAMPO_REQUERIDO	400	Falta un campo obligatorio en el request.
TIPO_SINCRO_INVALIDO	400	El valor de `TipoSincro` no es válido. Valores aceptados: `RCV_C`, `RCV_V`, `BHE`, `F29`.
MES_INVALIDO	400	El campo `mes` debe ser un valor entre 01 y 12.
ANNO_INVALIDO	400	El campo `anno` debe tener 4 dígitos.
AUTH_FAILED	401 / 403	API Key no válida, deshabilitada o vencida.
METHOD_NOT_ALLOWED	405	El request no fue enviado con método POST.
ERROR_SYNC	500	Error al registrar la solicitud de sincronización. Reintentar.
DB_ERROR	500	Error interno de base de datos.

Callback URL (próximamente)

En lugar de consultar /api/retrieve/ en forma repetida, puedes registrar una Callback URL en tu cuenta. Cuando el procesamiento finalice, Taskmania.cl enviará un POST automático a esa URL con el resultado — sin necesidad de polling.

ℹ️

Esta funcionalidad está en hoja de ruta. Si tu integración la requiere, contáctanos para coordinar su habilitación anticipada en tu cuenta.

Cómo funcionará

1

Registras tu Callback URL

Configuras en tu cuenta la URL de tu software que recibirá las notificaciones. Ejemplo: https://tusoftware.cl/webhooks/taskmania

Tu URL debe responder con 200 OK para confirmar que recibiste el aviso.

2

Solicitas la sincronización normalmente

Llamas a POST /api/sync/ como siempre. No necesitas hacer nada más.

POST /api/sync/ → 202 pending

Con callback activo ya no necesitas hacer polling a /api/retrieve/.

3

Taskmania notifica a tu URL cuando termina

Al finalizar el procesamiento, Taskmania.cl hace un POST a tu Callback URL con el mismo payload que retorna /api/retrieve/ en estado ready.

POST → tu Callback URL

Yo te aviso cuando el dato esté listo. Tú solo tienes que escuchar.

Payload que recibirá tu URL

JSON

POST https://tusoftware.cl/webhooks/taskmania
Content-Type: application/json

{
  "status":   "ready",
  "id_sync":  10,
  "periodo":  "06/2026",
  "tipo":     "RCV_C",
  "cantidad_sincronizaciones": 1,
  "fecha_sincronizacion":      "2026-06-23 20:47:23",
  "data":     "eyJwYXRoIjoiey4uLn0iLCJjcmVkZW5jaWFsZXMiOlsiLi4uIl19"
}

⚠️

Tu endpoint debe responder con HTTP 200 en menos de 10 segundos. Si no responde o retorna un código de error, Taskmania.cl reintentará la notificación hasta 3 veces con intervalos crecientes.

Ventajas frente al polling

Característica	Polling (/api/retrieve/)	Callback URL
Complejidad de integración	Requiere lógica de reintento en tu software	Solo un endpoint receptor en tu lado
Consumo de cuota	Cada consulta puede contar según plan	Sin consultas adicionales
Latencia	Hasta el intervalo de polling	Inmediata al finalizar
Disponibilidad	Disponible ahora	Próximamente

Documentación de la API

/api/sync/

/api/retrieve/

Flujo de integración

Autenticación

Consideraciones generales

POST /api/sync/

Parámetros del request

Ejemplo de request

Respuestas

Ejemplo de respuesta exitosa (202)

POST /api/retrieve/

Parámetros del request

Ejemplo de request

Estados de respuesta

Respuesta cuando hay datos disponibles (200)

Decodificar el campo data

Respuesta mientras está en proceso (202)

Tipos de sincronización

Códigos de error

Callback URL (próximamente)

Cómo funcionará

Payload que recibirá tu URL

Ventajas frente al polling