Guía pública de integración API

Sistemas que pueden integrarse

La API puede ser consumida desde sistemas desarrollados en Java, .NET, PHP, Python, Node.js u otras tecnologías que permitan realizar solicitudes HTTP con formato JSON.

También puede integrarse con sistemas ERP, sistemas de ventas, puntos de venta, plataformas administrativas, tiendas en línea o aplicaciones internas que necesiten emitir facturas en línea desde Bolivia.

Credenciales y acceso

Las credenciales API no se crean libremente desde una aplicación externa. Se generan desde la plataforma por un usuario autorizado de la empresa, con la sesión iniciada y los permisos adecuados. El token resultante queda asociado al usuario y a la empresa activa.

Si una empresa necesita integrar su aplicación externa, primero debe activar el servicio y completar la configuración inicial. Recién después el usuario autorizado puede emitir el token y compartirlo de forma segura con el backend de esa aplicación. Si debe operar desde otra sucursal o punto de venta, debe generar o configurar el token correspondiente para ese contexto.

Capacidades principales

Sincronización de productos

Si la aplicación externa administra muchos productos, puede crear, actualizar y eliminar productos usando /api/v1/productos. Para crear un producto debe enviar codigo_producto y descripcion_producto. Si el producto pertenece a una categoría, puede enviar id_categoria o codigo_categoria para heredar los códigos fiscales.

Si el cliente externo trabaja productos sin categoría, puede enviar directamente codigo_actividad_fisco y codigo_producto_fisco. La API valida esos códigos contra las tablas actividad y productobo.

{
  "codigo_producto": "EXT-001",
  "descripcion_producto": "Producto sincronizado",
  "id_categoria": 4,
  "id_unidad": 1,
  "precio_consumidor": 100
}

{
  "codigo_producto": "EXT-002",
  "descripcion_producto": "Producto sin categoria",
  "codigo_actividad_fisco": 620100,
  "codigo_producto_fisco": 99100,
  "id_unidad": 1,
  "precio_consumidor": 100
}

La eliminación solo se ejecuta si el producto no tiene movimientos en facturas. Si ya fue usado, la API responde con error 409.

Sincronización de unidades

La aplicación externa puede consultar /api/v1/catalogos/unidades-fisco para obtener las unidades de medida del fisco. Luego puede crear unidades propias en /api/v1/unidades relacionándolas con id_unidad_bo.

{
  "unidad": "Unidad",
  "abrev": "UN",
  "id_unidad_bo": 58
}

DELETE /api/v1/unidades elimina la unidad solo si no tiene productos asociados. En productos puede enviarse id_unidad o id_unidad_bo.

Sincronización de categorías

La aplicación externa puede consultar /api/v1/catalogos/actividades y /api/v1/catalogos/productos-fisco?codigo_actividad_fisco=620100 para mostrar al usuario las opciones del fisco.

Luego puede crear o editar categorías en /api/v1/categorias. Cuando cambia la actividad o producto fiscal de una categoría, la API hereda esos valores a los productos que tengan esa categoría asignada. Los productos sin categoría no se modifican.

{
  "codigo_categoria": "SERV",
  "descripcion_categoria": "Servicios",
  "codigo_actividad_fisco": 620100,
  "codigo_producto_fisco": 99100
}

DELETE /api/v1/categorias elimina la categoría solo si no tiene productos hijos. Si existen productos relacionados, responde 409.

Códigos HTTP y errores

La API usa estos códigos como referencia general:

Formato de error recomendado:

{
  "ok": false,
  "message": "codigo_metodo_pago invalido",
  "errors": {
    "codigo_metodo_pago": [
      "El metodo de pago no existe o no esta habilitado para esta empresa."
    ]
  }
}

Ejemplo rápido con cURL

Puedes probar la API desde cualquier backend o consola. Solo cambia el token y el payload.

curl -X POST "https://factura.moyata.net/api/v1/facturas" \
  -H "Authorization: Bearer <api_token>" \
  -H "Content-Type: application/json" \
  -d '{...}'

Errores frecuentes

Integración sugerida desde otro sistema

El orden recomendable para una aplicación integradora es este:

1. Solicitar la habilitación API para la empresa que se va a integrar.
2. Guardar el token en el backend de la aplicación integradora y usarlo en cada llamada.
3. Leer catálogos al iniciar sesión o al abrir la pantalla de facturación.
4. Validar NIT antes de emitir cuando corresponda.
5. Crear la factura y persistir el numero_factura, cuf, url_pdf y url_xml.
6. Si tu sistema puede reenviar solicitudes por cortes de red, usa una referencia externa única para evitar duplicados.