RUCs

Qué es un RUC en Zettana

En Zettana, un RUC representa una credencial operativa con la que la plataforma puede consultar y recuperar documentos desde el SRI.

Con estos endpoints puedes:

crear un RUC
listar los RUCs disponibles
obtener el rucId a partir del número de RUC
consultar el detalle de un RUC
actualizar un RUC existente

Para entender cómo pasa de creado a listo para usarse, consulta Ciclo de vida del RUC.

Endpoints

GET /v1/rucs
POST /v1/rucs
GET /v1/rucs/by-number/:rucNumber
GET /v1/rucs/:rucId
PATCH /v1/rucs/:rucId

Objeto RUC

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

id: identificador interno del RUC en Zettana
name: nombre visible del RUC dentro de tu cuenta
userId: identificador del usuario asociado
ruc: número de RUC
rucVerificationStatus: estado actual de verificación. Explicado en Ciclo de vida del RUC.
rucVerificationStatusMessage: mensaje descriptivo del estado
downloadCount: contador asociado al RUC

Listar RUCs

`GET /v1/rucs`

Devuelve la lista paginada de RUCs disponibles.

Parámetros de consulta

page: número de página. Por defecto 1
pageSize: cantidad de elementos por página. Por defecto 10
name: filtro opcional por nombre
ruc: filtro opcional por número de RUC

Ejemplo

import requests

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

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

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

Campos de salida

rucs: arreglo de objetos RUC
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 RUCs que cumplen el filtro
totalPages: cantidad total de páginas disponibles

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

Ejemplo de salida

{
  "rucs": [
    {
      "id": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
      "name": "Empresa principal",
      "userId": "d4aa2a65-b13a-4ccf-9787-8a3a399a1d9d",
      "ruc": "XXXXXXXXXXXXX",
      "rucVerificationStatus": "SUCCEEDED",
      "rucVerificationStatusMessage": "Verificado correctamente.",
      "downloadCount": 0
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "totalPages": 1
  }
}

Crear un RUC

`POST /v1/rucs`

Crea un nuevo RUC e inicia su proceso de verificación.

Body

name: nombre visible para identificar el RUC en tu cuenta
ruc: número de RUC
password: clave con la que Zettana operará contra el SRI

Ejemplo

import requests

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

payload = {
    "name": "Empresa principal",
    "ruc": "XXXXXXXXXXXXX",
    "password": "REEMPLAZA_CON_LA_CLAVE",
}

response = requests.post(
    f"{BASE_URL}/rucs",
    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 RUC. Sus campos están descritos en la sección Objeto RUC.

Ejemplo de salida

{
  "id": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
  "name": "Empresa principal",
  "userId": "d4aa2a65-b13a-4ccf-9787-8a3a399a1d9d",
  "ruc": "XXXXXXXXXXXXX",
  "rucVerificationStatus": "ENQUEUED",
  "rucVerificationStatusMessage": "Por favor espere",
  "downloadCount": 0
}

Obtener `rucId` desde el número de RUC

`GET /v1/rucs/by-number/:rucNumber`

Devuelve el rucId asociado a un número de RUC.

Parámetros de ruta

rucNumber: número de RUC

Ejemplo

import requests

BASE_URL = "https://backend.zettana.com/v1"
API_KEY = "REEMPLAZA_CON_TU_API_KEY"
RUC_NUMBER = "XXXXXXXXXXXXX"

response = requests.get(
    f"{BASE_URL}/rucs/by-number/{RUC_NUMBER}",
    headers={"x-api-key": API_KEY},
    timeout=30,
)

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

Campos de salida

rucId: identificador interno del RUC en Zettana

Ejemplo de salida

{
  "rucId": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6"
}

Obtener un RUC

`GET /v1/rucs/:rucId`

Devuelve el detalle de un RUC específico.

Parámetros de ruta

rucId: identificador interno del RUC

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}",
    headers={"x-api-key": API_KEY},
    timeout=30,
)

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

Campos de salida

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

Ejemplo de salida

{
  "id": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
  "name": "Empresa principal",
  "userId": "d4aa2a65-b13a-4ccf-9787-8a3a399a1d9d",
  "ruc": "XXXXXXXXXXXXX",
  "rucVerificationStatus": "SUCCEEDED",
  "rucVerificationStatusMessage": "Verificado correctamente.",
  "downloadCount": 0
}

Actualizar un RUC

`PATCH /v1/rucs/:rucId`

Actualiza los datos del RUC. Si el password cambia, Zettana reinicia la verificación del RUC.

Body

Actualmente este endpoint acepta:

name: nombre del RUC
password: clave del RUC

Comportamiento importante

Al actualizar un RUC, se vuelve a encolar su verificación y el estado regresa a ENQUEUED

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 = {
    "name": "Empresa principal actualizada",
    "password": "REEMPLAZA_CON_LA_CLAVE",
}

response = requests.patch(
    f"{BASE_URL}/rucs/{RUC_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 un objeto RUC actualizado. Sus campos están descritos en la sección Objeto RUC.

Ejemplo de salida

{
  "id": "3b2781b9-8d95-4b02-a6b7-4d5d66e0b8b6",
  "name": "Empresa principal actualizada",
  "userId": "d4aa2a65-b13a-4ccf-9787-8a3a399a1d9d",
  "ruc": "XXXXXXXXXXXXX",
  "rucVerificationStatus": "ENQUEUED",
  "rucVerificationStatusMessage": "El ruc necesita ser verificado nuevamente.",
  "downloadCount": 0
}

En esta página