Sincronizaciones recurrentes

Configura y administra programaciones automáticas de sincronización para un RUC.

Qué es una sincronización recurrente

Una sincronización recurrente le indica a Zettana que cree solicitudes de sincronización automáticamente según una programación definida por ti.

La programación no descarga documentos por sí sola. Su función es crear solicitudes normales de sincronización en segundo plano, para que después el flujo de recuperación opere como siempre.

Con estos endpoints puedes:

listar programaciones recurrentes de un RUC
crear una programación recurrente
actualizar una programación recurrente
eliminar una programación recurrente

Endpoints

GET /v1/rucs/:rucId/recurring-sync-schedules
POST /v1/rucs/:rucId/recurring-sync-schedules
PATCH /v1/rucs/:rucId/recurring-sync-schedules/:scheduleId
DELETE /v1/rucs/:rucId/recurring-sync-schedules/:scheduleId

Objeto de programación recurrente

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

id: identificador de la programación
rucId: identificador del RUC asociado
documentType: tipo de documento. Consulta Tipos de documento
frequency: frecuencia de ejecución. Puede ser DAILY (una vez al dia) o WEEKLY (una vez a la semana)
timezone: zona horaria usada para interpretar la programación
isActive: indica si la programación está activa
nextRunAt: próxima ejecución programada en formato ISO 8601
lastRunAt: última ejecución registrada, si existe
lastRunMessage: mensaje descriptivo del último intento de ejecución
createdAt: fecha de creación de la programación
updatedAt: fecha de última actualización

Listar programaciones recurrentes

`GET /v1/rucs/:rucId/recurring-sync-schedules`

Devuelve la lista paginada de programaciones recurrentes 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

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}/recurring-sync-schedules",
    params={
        "page": 1,
        "pageSize": 10,
    },
    headers={"x-api-key": API_KEY},
    timeout=30,
)

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

Campos de salida

recurringSyncSchedules: arreglo de objetos de programación recurrente
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 programaciones registradas
totalPages: cantidad total de páginas disponibles

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

Ejemplo de salida

{
  "recurringSyncSchedules": [
    {
      "id": "cf4c27fe-df30-449a-b247-ec3fc8ff7a45",
      "rucId": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
      "documentType": "FACTURA",
      "frequency": "DAILY",
      "timezone": "America/Guayaquil",
      "isActive": true,
      "nextRunAt": "2030-04-13T06:00:00.000Z",
      "lastRunAt": "2030-04-12T06:00:10.000Z",
      "lastRunMessage": "Solicitudes creadas: 2",
      "createdAt": "2030-04-12T05:30:00.000Z",
      "updatedAt": "2030-04-12T06:00:10.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "totalPages": 1
  }
}

Crear una programación recurrente

`POST /v1/rucs/:rucId/recurring-sync-schedules`

Crea una nueva programación automática para ruc y tipo de documento.

Parámetros de ruta

rucId: identificador del RUC

Body

documentType: tipo de documento que cubrirá la programación
frequency: frecuencia. DAILY o WEEKLY
timezone: zona horaria de referencia, por ejemplo UTC
nextRunAt: próxima ejecución deseada en formato ISO 8601

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 = {
    "documentType": "FACTURA",
    "frequency": "DAILY",
    "timezone": "America/Guayaquil",
    "nextRunAt": "2030-04-13T06:00:00.000Z",
}

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

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

Campos de salida

Este endpoint responde con un objeto de programación recurrente. Sus campos están descritos en la sección Objeto de programación recurrente.

Ejemplo de salida

{
  "id": "cf4c27fe-df30-449a-b247-ec3fc8ff7a45",
  "rucId": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
  "documentType": "FACTURA",
  "frequency": "DAILY",
  "timezone": "America/Guayaquil",
  "isActive": true,
  "nextRunAt": "2030-04-13T06:00:00.000Z",
  "lastRunAt": null,
  "lastRunMessage": null,
  "createdAt": "2030-04-12T05:30:00.000Z",
  "updatedAt": "2030-04-12T05:30:00.000Z"
}

Actualizar una programación recurrente

`PATCH /v1/rucs/:rucId/recurring-sync-schedules/:scheduleId`

Actualiza una programación ya existente.

Parámetros de ruta

rucId: identificador del RUC
scheduleId: identificador de la programación

Body

Actualmente puedes enviar uno o varios de estos campos:

documentType
frequency
timezone
nextRunAt
isActive

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"
SCHEDULE_ID = "REEMPLAZA_CON_EL_ID_DE_LA_PROGRAMACION"

payload = {
    "frequency": "WEEKLY",
    "nextRunAt": "2030-04-19T06:00:00.000Z",
    "isActive": True,
}

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

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

Campos de salida

Este endpoint responde con el objeto de programación actualizado.

Ejemplo de salida

{
  "id": "cf4c27fe-df30-449a-b247-ec3fc8ff7a45",
  "rucId": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
  "documentType": "FACTURA",
  "frequency": "WEEKLY",
  "timezone": "America/Guayaquil",
  "isActive": true,
  "nextRunAt": "2030-04-19T06:00:00.000Z",
  "lastRunAt": "2030-04-12T06:00:10.000Z",
  "lastRunMessage": "Solicitudes creadas: 2",
  "createdAt": "2030-04-12T05:30:00.000Z",
  "updatedAt": "2030-04-12T06:10:00.000Z"
}

Eliminar una programación recurrente

`DELETE /v1/rucs/:rucId/recurring-sync-schedules/:scheduleId`

Elimina una programación recurrente.

Parámetros de ruta

rucId: identificador del RUC
scheduleId: identificador de la programación

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"
SCHEDULE_ID = "REEMPLAZA_CON_EL_ID_DE_LA_PROGRAMACION"

response = requests.delete(
    f"{BASE_URL}/rucs/{RUC_ID}/recurring-sync-schedules/{SCHEDULE_ID}",
    headers={"x-api-key": API_KEY},
    timeout=30,
)

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

Campos de salida

Este endpoint responde con el objeto eliminado.

Ejemplo de salida

{
  "id": "cf4c27fe-df30-449a-b247-ec3fc8ff7a45",
  "rucId": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
  "documentType": "FACTURA",
  "frequency": "DAILY",
  "timezone": "America/Guayaquil",
  "isActive": true,
  "nextRunAt": "2030-04-13T06:00:00.000Z",
  "lastRunAt": null,
  "lastRunMessage": null,
  "createdAt": "2030-04-12T05:30:00.000Z",
  "updatedAt": "2030-04-12T05:30:00.000Z"
}

En esta página