Manejo de errores
Los errores en Siigo API tienen la siguiente estructura:
- Status: Siigo utiliza códigos de respuesta HTTP para indicar el éxito o fracaso de una solicitud de API.
- Code: Para algunos errores que podrían manejarse mediante programación, se muestra una cadena corta que indica el código de error.
- Message: Mensaje con la explicación del error.
- Param: Si el error es específico del parámetro, el parámetro relacionado con el error.
- Detail: Mensaje que proporciona más detalles acerca del error.
Límite de solicitudes
Es importante tener en cuenta en el momento de construir tu integración, que puedes enviar como máximo 100 peticiones por minuto a Siigo API por cada empresa de Siigo Nube.
Tiempos de respuesta
Los tiempos de respuesta de Siigo API en promedio se encuentran por debajo de los 2 segundos, sin embargo, recomendamos establecer tiempos de espera de 120 segundos o más, antes de romper la conexión o cancelar un request, especialmente en creaciones de comprobantes como facturas de venta, notas crédito, recibos de caja y/o comprobantes contables ya que en picos altos de uso algunas transacciones podrían tardar más de lo esperado.
Error already_exists
Este error ocurre cuando se intenta crear un registro ya existente en Siigo Nube.
Usa un valor diferente y único para el id o código e intenta nuevamente.
Error disabled_functionality
Este error ocurre cuando la funcionalidad esta temporalmente inhabilitada.
Error company_settings
Este error ocurre cuando se se envía algún parámetro que no está configurado en tu organización.
Puedes validar en el menú Configuración > Más Configuraciones > Organización > Perfil de la organización la configuración de Moneda extrajera y Datos tributarios.
Error customer_settings
Este error ocurre cuando se quiere crear un documento y el tercero relacionado NO tiene creados contactos en su perfil, se debe garantizar que existan los contactos, bien sea en Siigo Nube o a través de Siigo API en el endpoint de customers.
Error delete_not_allowed
El recurso no se puede eliminar porque tiene movimientos o transacciones relacionadas.
Error blocked_transactions
La fecha de creación del documento es menor o igual al bloqueo de transacciones en Siigo Nube, por favor revisar esta configuración un usuario administrador por la ruta: Configuración > Transacciones > Procesos > Bloqueo por fecha para transacciones
Error disabled_functionality
Se está intentando enviar una petición a una funcionalidad que se encuentra inhabilitada de forma temporal o permanente.
Error documents_service
El servicio de documentos no esta disponible, intente en unos minutos.
Error document_settings
Este error ocurre cuando se envía algún parámetro que no está configurado en el comprobante.
Verifica la configuración de los siguientes parámetros de Factura de Venta en el menú Configuración > Transacciones > Facturas > Elige el tipo de factura
- Vendedor por ítem
- Centro de costos
- Numeración automática
- Descuentos por valor o porcentaje
- Decimales
Más información en: https://siigonube.portaldeclientes.siigo.com/basedeconocimiento/configuracion-factura-de-venta/
Error duplicated_document
El documento ya existe, por favor valide la información, para prevenir la generación de documentos duplicados utilice el header “Idempotency-Key” para identificar los documentos, encuentre más información en: https://siigoapi.docs.apiary.io/#introduction/idempotencia.
Error header_required
No se está enviando una cabecera que es requerida en las peticiones, revisa que se esté enviando la cabecera "Partner-Id" con el nombre de la aplicación que estás integrando en el value, encuentra más información de esta cabecera aquí .
Error invalid_array
Este error ocurre cuando se envía un array con valores inválidos.
- Contacts: Este error ocurre al exceder la cantidad máxima de contactos, puedes crear hasta 10 contactos por cliente.
- Name: Debes verificar los siguientes escenarios:
Si estás creando un cliente tipo 'Person'
Si estás creando un cliente tipo 'Company'
-
Payments: Este error ocurre al envíar formas de pago inválidas, debes consultar las formas de pago válidas y verificar si son de tipo cartera: Si ingresa dinero o proveedor: En caso de compras.
-
Prices: Este error ocurre al exceder la cantidad máxima de Listas de precio, puedes crear hasta 12 Listas de precio por producto.
-
Retentions: De acuerdo a la configuración del comprobante en el menú Configuración
>Transacciones>Facturas, sección Datos tributarios, puedes utilizar los siguientes tipos de retenciones:ReteIVA: Se aplica sobre el valor del IVA facturado.
ReteICA: Se aplica sobre el subtotal de la factura.
Autorretención: Se aplica si el subtotal de la factura es mayor al tope mínimo configurado.
-
Taxes: Este error ocurre:
-Si envías más de la cantidad de impuestos permitidos, puedes enviar hasta 3 impuestos.-Si envías Iva y Ad Valorem en el mismo producto de una factura.-Si envías un mismo tipo de impuesto más de una vez.-Si envías un reteIVA o reteICA en los items de factura. -
Items: Este error ocurre:
-En recibo de caja si envías items en un Anticipo o en un Abono a deuda el mismo vencimiento más de una vez.-En factura de venta y notas crédito si envías más de 500 items
Error invalid_amount
El valor especificado no es válido. El monto debe ser un número positivo en la unidad monetaria correspondiente y no exceder el monto mínimo o máximo (99,999,999,999.99).
Consideraciones
El total de payments debe coincidir con el total de la factura, el valor máximo es máximo (9,999,999,999,999.99).
El valor de advance_payment debe ser mayor al subtotal de la factura.
El campo de price permite hasta 6 decimales.
Los demás campos como advance_payment y discount permiten hasta 2 decimales.
No puede enviar un valor mayor al valor del saldo de la "cuota".
Error invalid_code
El código no puede tener comillas simples (') ni espacios.
Expresión regular: ^[^'\s]+$
Error invalid_cost_center
Por favor verifica el identificador del centro de costos. /cost-centers
Error invalid_currency
No es necesario que envíes este campo si estás manejando la moneda local.
En nota crédito debe coincider la moneda de la factura de venta.
Error invalid_date
Estás enviando una fecha inválida, verifica el limite de días para facturas electronicas que es 10 días inferior o superior a la fecha actual. Tambien verifica los formatos válidos para las fechas:
Date: yyyy-MM-dd
Date and time in UTC: yyyy-MM-ddTHH:mm:ssZ
Para creación o edición de Facturas de venta o Notas crédito de tipo electrónico, NO puedes enviar una fecha anterior a la fecha actual.
Error invalid_description
Estás enviando una descripción inválida.
Expresión regular: @"^$|^[\w\.@-\\%_;()\]#?¡[/:{ } *+,$"\sñáéíóúÁÉÍÓÚüÜ\-"]+$"
Error invalid_document
El id del tipo de comprobante no corresponde al que estás creando. /document-types
En Nota Crédito, debes verificar que invoice sea del mismo electronic_type.
Si se está usando un tipo de comprobante con marcación electronica en su definición, esta debe estar enviada ante la DIAN si se desea aplicar nota crédito.
Error invalid_email
La dirección de correo electrónico no es válida, verifica que la dirección de correo electrónico tenga el formato correcto.
Expresión regular: ^([-+.]*\w)+[-+.]*@([\w-]+\.)+[\w-]{2,}$
Error invalid_identification
Estás enviando una identificación inválida.
Expresión regular: @"^[\d\w]{1}[\d\w\-]+[\d\w]{1}$"
Error invalid_idempotency-key
Estás enviando un idempotency-key inválido, este header es alfanumérico, sin caracteres especiales y de máximo 32 caracteres.
Error invalid_name
Estás enviando un nombre inválido.
Expresión regular: @"^[\w\.@-\\%_;()\]#?¡[/:{ } *+,$"\sñáéíóúÁÉÍÓÚüÜ\-"]+$"
Error invalid_payment
El error sucede si: si envías una forma de pago inválida para el tipo de comprobante (Factura de Venta, Nota Crédito, Recibo de Caja). se envía payment en un recibo de caja avanzado.
Error invalid_partner_id
Estas enviando el header Partner-Id con un formato inválido, en este header no se aceptan caracteres especiales, espacios en blanco y debe contener entre 3 y 100 caracteres.
Error payment_types_service
El servicio no está disponible por el momento. inténtalo en unos minutos.
Error invalid_range
El campo solo permite un valor entre los rangos indicados.
En generación de reportes de balance de prueba general o balance de prueba por tercero: se da cuando se envía un valor que no está entre 1 y 13 en los parámetros "month_start" o "month_end"
Error invalid_reference
Este error ocurre cuando envías un id o código que no existe. Verifica los Catálogos.
En generación de reportes de balance de prueba general o balance de prueba por tercero: se da cuando se envía una cuenta contable inexistente en alguno de los parametros "account_start" o "account_end"
Error invalid_total_payments
El sistema valida que el valor total pagado (suma de payments[i].value) coincida con el total de la factura (suma de los totales de los ítems).
El total por ítem se calcula así:
Ejemplo:
Error invalid_retentions
De acuerdo a la configuración del comprobante en el menú Configuración > Transacciones > Facturas, sección Datos tributarios, puedes utilizar los siguientes tipos de retenciones:
ReteIVA: Se aplica sobre el valor del IVA facturado.
ReteICA: Se aplica sobre el subtotal de la factura.
Autorretención: Se aplica si el subtotal de la factura es mayor al tope mínimo configurado.
Error invalid_type
El tipo de dato enviado es inválido.
Error invalid_url
La URL proporcionada no es válida. Verifica que la URL esté formateada correctamente.
Error update_not_allowed
No se puede actualizar el grupo de inventarios del producto, debido a que ya tiene movimientos.
Error invalid_value
El valor especificado no es válido. (Cantidades, Consecutivos y Cuotas)
Error length_max
Verifica que no superas la longitud máxima del campo indicada en el mensaje del error.
Error length_min
Verifica la longitud mínima del campo indicada en el mensaje del error.
Error not_found
Recurso no encontrado.
Error parameter_empty
Se utiliza para los campos unit y fiscal responsabilities, debes verificar que envías un valor válido. Si no se envía se asigna el valor por defecto.
Error parameter_inactive
El parámetro que estás utilizando está inactivo. Usa un parámetro diferente o activa el parámetro actual nuevamente.
Usuarios: Puedes validar en en Siigo Nube en el menú lateral: Reportes > Más reportes > Usuarios > Administración de usuarios
Formas de Pago: Puedes validar en en Siigo Nube en el menú lateral: Configuración > Transacciones > Catálogos > Formas de Pago
Impuestos: Puedes validar en Siigo Nube en el menú lateral: Configuración > Transacciones > Catálogos > Impuestos
Listas de Precios: Puedes validar en en Siigo Nube en el menú Configuración > Más Configuraciones > Inventarios > Listas de precios ahi puedes habilitar hasta 12 de listas de precios.
Error parameter_required
No se proporcionaron uno o más valores obligatorios. Asegúrate de que las solicitudes incluyan todos los parámetros necesarios.
Formas de Pago: Debes enviar el query parameter document_type=FV (FV, NC y RC)
Error parameters_exclusive
Se proporcionó un valor no permitido, consulta la documentación de nuestra API o el mensaje de error devuelto para verificar los valores que están permitidos al crear o modificar el recurso especificado.
Error invalid_plan_type
Se proporcionó un valor no permitido, su plan no tiene límite de documentos.
Error invalid_account
En generación de comprobantes contables: se proporcionó un número de cuenta contable inexistente.
En generación de reportes de balance de prueba general o balance de prueba por tercero: se da cuando "account_start" corresponde a una cuenta contable mayor que "account_end"
Error product_settings
Este error sucede si envías una bodega en la creación de factura y el producto no maneja control de inventarios.
Error requests_limit
Están llegando solicitudes demasiado rápido a la API. Recomendamos una retirada exponencial de sus solicitudes.
Importante: > Para la empresa de pruebas las solicitudes son de 10 request por minuto
> Empresas en producción son 100 request por minuto.
Error unauthorized
No estás autorizado, verifica el token de acceso. El token de acceso puede estar vencido o ser inválido. O el usuario asociado puede estar bloqueado.
Error unhandled_error
Error no controlado, escríbenos a [email protected] para ayudarte y dar claridad a este error.
Error request_timeout
Siigo API no logró completar la solicitud dentro del tiempo que estaba preparado para esperar. Puede intentar de nuevo en unos segundos.
Error service_unavailable
Siigo API actualmente no está disponible debido a una sobrecarga temporal o mantenimiento programado. Puede intentar de nuevo en unos segundos.
Error warehouse_settings
Este error sucede si envías una bodega en la creación de factura o nota crédito y NO está activo el manejo de bodegas.
Puedes validar en el menú Configuración > Más Configuraciones > Inventarios > Configuración de bodegas la habilitación de uso de bodegas.
Error invalid_balance
Este error aparece cuando la suma de los debitos y créditos nos son iguales.
Error values_limit
Este error aparece cuando se ha excedido él limite de los valores permitidos.
Error invalid_date_range
Este error aparece cuando las fechas que se proporcionan no están en un rango válido.
Error date_settings
Este error aparece cuando la fecha que se proporcionan en la elaboración del comprobante no es permitida.
Error parameter_not_allowed
Este error aparece cuando se envía el campo de vat_excluded: true, y no se está en la fecha correcta para los dias de la exención de IVA. Puede presentarse al enviar un "id" invalido para el tipo de impuesto que se desea manejar, ejemplo: Enviar un valor de imp.consumo y un "id" de un impuesto de retención.
Error non_editable
Este error ocurre cuando se cambian datos que NO son editables
Error entry_service
No es posible completar su solicitud con las condiciones actuales.
Error general_service
El servicio no está disponible por el momento. Inténtalo en unos minutos.