Sincronizaciones

Qué es una sincronización

Una sincronización le indica a Zettana que recupere documentos para un RUC, para un período específico y para un tipo de documento específico.

Este proceso no devuelve directamente los documentos. Su objetivo es iniciar el trabajo de recuperación y dejarlo disponible para consulta posterior.

Con estos endpoints puedes:

• crear una sincronización
• consultar las sincronizaciones ya registradas
• revisar el estado actual de cada solicitud
• ver si una sincronización fue creada manualmente o por una programación recurrente

Para entender cómo evoluciona una sincronización desde que se crea hasta que termina, consulta Ciclo de vida de una sincronización.

Si quieres configurar ejecuciones automáticas, consulta Sincronizaciones recurrentes.

Endpoints

• POST /v1/rucs/:rucId/sync-requests
• GET /v1/rucs/:rucId/sync-requests

Objeto de sincronización

Las respuestas de este recurso usan un objeto con esta estructura:

• id: identificador de la sincronización
• rucId: identificador del RUC asociado
• source: origen de la sincronización. Puede ser MANUAL o RECURRING
• year: año consultado
• month: mes consultado
• documentType: tipo de documento solicitado. Consulta Tipos de documento
• syncStatus: estado actual de la sincronización. Explicado en Ciclo de vida de una sincronización.
• statusMessage: mensaje descriptivo del estado

Crear una sincronización

POST /v1/rucs/:rucId/sync-requests

Crea una nueva solicitud de sincronización para un RUC.

Parámetros de ruta

• rucId: identificador del RUC

Body

• year: año a consultar
• month: mes a consultar
• documentType: tipo de documento a recuperar

Los valores admitidos para documentType están detallados en Tipos de documento.

Ejemplo

import requests

BASE_URL = "https://backend.zettana.com/v1"
API_KEY = "REEMPLAZA_CON_TU_API_KEY"
RUC_ID = "REEMPLAZA_CON_EL_ID_DEL_RUC"

payload = {
    "year": 2025,
    "month": 10,
    "documentType": "FACTURA",
}

response = requests.post(
    f"{BASE_URL}/rucs/{RUC_ID}/sync-requests",
    headers={"x-api-key": API_KEY},
    json=payload,
    timeout=30,
)

response.raise_for_status()
print(response.json())

Campos de salida

• id: identificador de la sincronización creada
• rucId: identificador del RUC asociado
• source: origen de la sincronización. En este endpoint será MANUAL
• year: año solicitado
• month: mes solicitado
• documentType: tipo de documento solicitado. Consulta Tipos de documento
• syncStatus: estado inicial de la sincronización
• statusMessage: mensaje descriptivo del estado inicial

Ejemplo de salida

{
  "id": "6b2a4b3a-5eb0-4fdc-b1b1-81857ff7e52d",
  "rucId": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
  "source": "MANUAL",
  "year": 2025,
  "month": 10,
  "documentType": "FACTURA",
  "syncStatus": "ENQUEUED",
  "statusMessage": "Por favor espere"
}

Consultar sincronizaciones

GET /v1/rucs/:rucId/sync-requests

Devuelve la lista paginada de sincronizaciones registradas para un RUC.

Parámetros de ruta

• rucId: identificador del RUC

Parámetros de consulta

• page: número de página. Por defecto 1
• pageSize: cantidad de elementos por página. Por defecto 10
• documentType: filtro opcional por tipo de documento

Ejemplo

import requests

BASE_URL = "https://backend.zettana.com/v1"
API_KEY = "REEMPLAZA_CON_TU_API_KEY"
RUC_ID = "REEMPLAZA_CON_EL_ID_DEL_RUC"

response = requests.get(
    f"{BASE_URL}/rucs/{RUC_ID}/sync-requests",
    params={
        "page": 1,
        "pageSize": 10,
    },
    headers={"x-api-key": API_KEY},
    timeout=30,
)

response.raise_for_status()
print(response.json())

Campos de salida

• syncRequests: arreglo de objetos de sincronización
• pagination: metadata de paginación de la respuesta

pagination contiene:

• page: página actual
• pageSize: tamaño de página aplicado
• total: cantidad total de sincronizaciones que cumplen el filtro
• totalPages: cantidad total de páginas disponibles

El detalle de cada elemento está descrito en la sección Objeto de sincronización.

Ejemplo de salida

{
  "syncRequests": [
    {
      "id": "6b2a4b3a-5eb0-4fdc-b1b1-81857ff7e52d",
      "rucId": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
      "source": "MANUAL",
      "year": 2025,
      "month": 10,
      "documentType": "FACTURA",
      "syncStatus": "SUCCEEDED",
      "statusMessage": "Sincronización completada."
    },
    {
      "id": "867fe7bb-f1b9-4cc3-a0ee-c4e87d60dd9f",
      "rucId": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
      "source": "RECURRING",
      "year": 2025,
      "month": 9,
      "documentType": "COMPROBANTE_RETENCION",
      "syncStatus": "PROCESSING",
      "statusMessage": "Procesando solicitud."
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 2,
    "totalPages": 1
  }
}

Relación con documentos

Una sincronización y la consulta de documentos son pasos distintos.

Primero solicitas la sincronización del período y tipo de documento que te interesa. Después puedes consultar los documentos ya disponibles para ese mismo período desde los endpoints de documentos.