Sincronizar Usuarios Autorizados

Sincronizar usuarios autorizados con el SII

curl --request POST \
  --url https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/ \
  --header 'Authorization: <api-key>'

import requests

url = "https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/"

headers = {"Authorization": "<api-key>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

fetch('https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "job_id": 123,
  "status": "queued",
  "channel_key": "honorary-authorized-users-sync-456"
}

{
  "error": "Usuario sin permisos para acceder a la entidad"
}

{
  "error": "No encontrado"
}

POST

honorary

master-entities

{master_entity_id}

authorized-users

sync

Sincronizar usuarios autorizados con el SII

curl --request POST \
  --url https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/ \
  --header 'Authorization: <api-key>'

import requests

url = "https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/"

headers = {"Authorization": "<api-key>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

fetch('https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tupana.ai/v1/honorary/master-entities/{master_entity_id}/authorized-users/sync/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "job_id": 123,
  "status": "queued",
  "channel_key": "honorary-authorized-users-sync-456"
}

{
  "error": "Usuario sin permisos para acceder a la entidad"
}

{
  "error": "No encontrado"
}

Qué hace

GET /honorary/authorized-users/ no consulta el SII en cada request — lee de un caché local que solo se actualiza cuando se dispara una sincronización explícita. Este endpoint encola esa sincronización de forma asíncrona: la consulta al SII corre en background y el POST responde de inmediato, sin esperar a que termine.

POST /honorary/master-entities/{master_entity_id}/authorized-users/sync/

Respuesta (202 Accepted):

{
    "job_id": 123,
    "status": "queued",
    "channel_key": "honorary-authorized-users-sync-456"
}

Cómo saber cuándo terminó

El channel_key referencia un canal WebSocket interno usado por el frontend de Tu Pana (autenticación de sesión JWT) para mostrar el progreso en tiempo real. Ese WebSocket no acepta API key — si estás integrando desde afuera, la forma soportada es hacer polling de Listar Usuarios Autorizados hasta que last_sync_status sea "done" o "error":

GET /honorary/master-entities/{master_entity_id}/authorized-users/

{
    "authorized_users": [...],
    "last_sync_status": "done",
    "last_sync_error": "",
    "last_synced_at": "2026-07-22T15:40:12.123456+00:00"
}

Como el GET solo lee del caché (nunca vuelve a tocar el SII), el polling es barato. Un intervalo de 2-3 segundos mientras el estado sea "queued" o "syncing" es razonable. last_synced_at refleja cuándo terminó el último intento (exitoso o fallido) — si hay una sincronización en curso, sigue mostrando la fecha del último intento que ya concluyó, no se adelanta hasta que el nuevo intento también termine.

Reglas de negocio

Nunca se scrapea el SII en el GET

Antes, GET /honorary/authorized-users/ consultaba el SII en cada llamada. Ahora esa lectura es siempre local; el único punto que toca el SII es este endpoint de sync.

Un sync fallido nunca borra ni corrompe el caché

Si el SII no responde, la credencial está inválida, o cualquier otro error ocurre durante el scraping, el caché no se modifica en absoluto — sigue reflejando la última sincronización exitosa. Solo se registra el error en last_sync_status/last_sync_error.

Un sync exitoso puede desactivar usuarios, nunca borrarlos

Si un usuario que estaba autorizado deja de aparecer en la respuesta del SII durante un sync exitoso, se marca como inactivo (no vuelve a aparecer en GET .../authorized-users/) pero la fila no se elimina — se conserva el historial de cuándo se vio por última vez.

Enrolar requiere sincronizar primero

Enrolar Usuario Autorizado valida el RUT contra este mismo caché. Si la entidad nunca fue sincronizada, el enroll responde 400 pidiendo sincronizar primero.

Ejemplos de uso

Antes de mostrar el listado de autorizados en tu integración por primera vez para una entidad nueva (el caché empieza vacío).
Cuando el usuario final pide explícitamente “actualizar” el listado (botón de refrescar).
Después de que el cliente autorice a un nuevo usuario directamente en el portal del SII, para que el cambio se refleje en Tu Pana.

Consideraciones importantes

Requiere una credencial SII (sii_company o sii) válida asociada a la entidad — si no existe, el sync termina en last_sync_status: "error".
No hay límite de frecuencia explícito, pero cada llamada dispara un scrape real al SII: evita sincronizar en un loop ajustado a los reintentos de polling.
Es idempotente en efecto (no en side-effects): podés disparar varios syncs seguidos sin riesgo de corromper el caché, aunque cada uno consume un scrape real.

Authorizations

Authorization

string

header

required

API Key para autenticación. Debe proporcionarse en el header Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo 'Api-Key ' seguido de tu API key)

Path Parameters

master_entity_id

integer

required

ID de la entidad emisora

Response

Sincronización encolada exitosamente

job_id

integer

required

ID del job de sincronización, útil para trazabilidad interna

Example:

123

status

enum<string>

required

Available options:

queued

Example:

"queued"

channel_key

string

required

Canal WebSocket interno (solo JWT) donde se publica el avance

Example:

"honorary-authorized-users-sync-456"

​Qué hace

​Cómo saber cuándo terminó

​Reglas de negocio

​Nunca se scrapea el SII en el GET

​Un sync fallido nunca borra ni corrompe el caché

​Un sync exitoso puede desactivar usuarios, nunca borrarlos

​Enrolar requiere sincronizar primero

​Ejemplos de uso

​Consideraciones importantes

Authorizations

Path Parameters

Response

Qué hace

Cómo saber cuándo terminó

Reglas de negocio

Nunca se scrapea el SII en el GET

Un sync fallido nunca borra ni corrompe el caché

Un sync exitoso puede desactivar usuarios, nunca borrarlos

Enrolar requiere sincronizar primero

Ejemplos de uso

Consideraciones importantes