Cómo recuperar facturas en Zoho

Recuperar facturas en Zoho CRM es sencillo una vez que tu conexión OAuth está establecida — puedes obtener una lista completa de facturas o una sola factura por su ID utilizando dos operaciones de API dedicadas.

Por qué esto es importante

Si estás creando una integración, automatizando flujos de trabajo de facturación o simplemente auditando tus registros de ventas de forma programática, necesitarás acceso fiable a los datos de facturas almacenados en Zoho CRM. Saber qué endpoints llamar — y cómo se gestiona la autenticación en segundo plano — ahorra un tiempo considerable de depuración. Esta guía es proporcionada por Beam Help, tu soporte experto independiente para Zoho (no es soporte oficial de Zoho).

Paso a paso

Paso 1. Asegúrate de que tu conexión con Zoho CRM está activa y de que tu token de acceso es válido. El sistema comprueba la fecha de expiración del token almacenado y lo renueva automáticamente aproximadamente dos minutos antes de que expire, utilizando el refresh_token guardado en tu registro de conexión. Si la renovación falla o no existe ninguna conexión para tu usuario, la llamada a la API no podrá continuar. ^[2]

Paso 2. Confirma que tus scopes de OAuth incluyen los permisos necesarios de Zoho CRM. Los scopes ZohoCRM.org.ALL y los ZohoCRM relacionados deben estar presentes en tu lista de scopes autorizados para que los datos de CRM — incluidas las facturas — sean accesibles. ^[8]

Paso 3. Para recuperar todas las facturas, realiza una solicitud GET al endpoint /Invoices. En el código, esto se expone como la operación get_invoices, que acepta un diccionario de parámetros opcional (p) para filtrado o paginación. Una llamada mínima pasa un diccionario vacío si no se necesitan filtros. ^[4]

# Retrieve all invoices (no filters)
result = api.get_invoices(p={})

# Retrieve invoices with optional query parameters
result = api.get_invoices(p={"page": 1, "per_page": 50})

Paso 4. Para recuperar una sola factura por su identificador único, realiza una solicitud GET a /Invoices/{invid}, sustituyendo el ID real de la factura. Esta es la operación getinvoice y solo requiere la cadena inv_id como argumento. ^[7]

# Retrieve one specific invoice
result = api.get_invoice(inv_id="4876000000123456")

Paso 5. El cliente de API subyacente (getzohoapi) gestiona la renovación del token de forma transparente mediante un callback tokenrefresher. Si se produce una expiración del token durante una solicitud, el renovador obtiene el refreshtoken más reciente de tu base de datos, llama a ZohoOAuth.refreshtokens y almacena los nuevos valores de accesstoken y tokenexpiresat antes de reintentar. No necesitas gestionar esto manualmente. ^[1]

Paso 6. Analiza la respuesta de cualquiera de las dos llamadas. Tanto getinvoices como getinvoice devuelven la respuesta sin procesar de la capa REST de Zoho CRM. Para una llamada de lista, espera una estructura paginada; para una llamada de registro único, espera un objeto de registro indexado por los campos de la factura. ^[4][7]

Errores comunes

• Conexión inexistente o expirada: Si getzohoconnection devuelve None — lo que significa que no existe ninguna fila en zohoconnections para el userid indicado — no se puede crear la instancia de la API y todas las llamadas de facturas fallarán silenciosamente. Verifica siempre que el registro de conexión existe antes de realizar solicitudes. ^[2]

• La renovación del token no devuelve ningún token de acceso: Durante el flujo de renovación, si la respuesta de ZohoOAuth.refreshtokens no contiene una clave accesstoken, el renovador devuelve None y la solicitud será bloqueada. Esto generalmente indica un refresh_token expirado o revocado que requiere que el usuario vuelva a autenticarse. ^[1][6]

• Scopes de OAuth insuficientes: Si los scopes concedidos durante la autorización OAuth no incluyen los permisos ZohoCRM requeridos, la API de Zoho devolverá un error de permisos en lugar de los datos de facturas. Comprueba que los scopes de CRM correctos se solicitaron en el momento de la conexión. ^[8]

• Parámetro apptype incorrecto: El helper getzohoapi acepta un argumento apptype — pasar "desk" en lugar de "crm" enrutará tu solicitud a Zoho Desk en lugar de a Zoho CRM, donde el endpoint /Invoices no existe. Pasa siempre app_type="crm" cuando trabajes con facturas. ^[1]

Qué verificar

• El registro de conexión existe: Confirma que hay una fila válida en tu tabla zohoconnections para el userid de destino, con un refresh_token no expirado. ^[2]
• Los scopes incluyen acceso a CRM: Verifica que la autorización OAuth incluyó el conjunto de scopes ZohoCRM necesarios, no solo los scopes de Zoho Desk. ^[8]
• Endpoint correcto y formato de ID: Para la recuperación de una sola factura, asegúrate de que el valor de inv_id es el ID de registro completo de Zoho CRM (normalmente una cadena numérica larga), no un número de visualización ni el valor de un campo personalizado. ^[7]