Saltar al contenido
Facturador

API Facturador

Documentación de la API de cada empresa (tenant). Emite comprobantes electrónicos, gestiona clientes, productos, inventario y guías.

No confundir con la API Administrador: aquella corre en el host central y usa el token del reseller. Esta API corre en el subdominio de la empresa.

Prueba cada endpoint desde su página

Cada página de esta sección termina con un bloque Pruébalo: elige la URL de tu empresa en Servers, pega tu token en Authorize y envía el request con Try it out. Si necesitas la especificación completa, descarga el OpenAPI (JSON).

Servidor

La base URL es el FQDN del tenant:

Entorno URL
Empresa https://{subdominio}.{tu-dominio}

Ejemplo: si el facturador abre en https://miempresa.pro.uio.la, las rutas son https://miempresa.pro.uio.la/api/documents, etc.

Autenticación

HTTP Bearer con el api_token del usuario del tenant.

Authorization: Bearer <api_token>

Puedes obtener el token de dos formas:

  • Copiarlo en el facturador: Configuración → Usuarios (campo de solo lectura api_token).
  • Pedirlo con POST /api/login en el dominio de tu empresa, con el correo y la contraseña del usuario. No uses el /api/login del panel administrador: ese token no sirve para esta API.

Guardia

Los endpoints de esta sección requieren auth:api sobre el hostname del tenant. Un token válido de otra empresa o del system devolverá 401.

Comprobantes

La mayoría de CPE (factura, boleta, notas) se emiten con POST /api/documents. Cambia codigo_tipo_documento y el payload: cada página de Facturas, Boletas y Notas es un escenario de ese mismo endpoint.

Respuesta habitual

Tras emitir un CPE el API suele devolver external_id y enlaces de descarga XML / PDF / CDR.

Cabeceras

Además del token, envía siempre Accept: application/json y Content-Type: application/json. Sin Accept, los errores de autenticación o validación pueden llegar como HTML o redirección en lugar de JSON.

Formatos de respuesta

Cada página indica en Formato de respuesta cuál de estos usa el endpoint.

Estándar, registro único:

{ "success": true, "data": { "id": 1 }, "message": "Registro creado con éxito" }

message aparece en altas, ediciones, eliminaciones y acciones.

Estándar, listado con cursor:

{
  "success": true,
  "data": [ { "id": 1 }, { "id": 2 } ],
  "pagination": { "next_cursor": "eyJpZCI6Mn0", "has_more": true }
}
  • limit: registros por página, de 1 a 100 (por defecto 15).
  • Para la siguiente página repite la misma consulta (mismos filtros) con cursor=<next_cursor>.
  • Cuando has_more es false (y next_cursor es null) llegaste al final.

Estándar, error:

{ "success": false, "message": "Registro no encontrado." }

Heredados: la emisión de comprobantes, los listados paginados por página y varios catálogos de venta conservan su formato anterior ({success, message?, ...}, {data: ...} o el objeto sin envoltura). Algunos responden HTTP 200 con success: false ante una regla de negocio, así que revisa siempre success.

Códigos HTTP

Código Significado
200 Correcto (consulta, edición, eliminación, acción).
201 Registro creado.
401 Sin token o token inválido.
403 Sin permiso: recurso solo para administradores, registro de otro vendedor o permiso del usuario faltante.
404 El registro o la URL no existen.
405 Método HTTP no permitido para esa URL.
409 Regla de negocio: registro en uso, anulado, con comprobantes generados, caja cerrada, etc. message explica la causa.
422 Error de validación. message es un objeto con cada campo y sus errores.

Ejemplo de 422:

{
  "success": false,
  "message": {
    "email": ["correo electrónico ya ha sido registrado."],
    "password": ["El campo contraseña es obligatorio."]
  }
}

Algunos endpoints heredados todavía responden 500 cuando el id no existe; se indica en cada página.

Permisos

Recurso Quién puede usarlo
Notas de venta y cotizaciones (ver, editar, anular, pagos) Administrador: todos los registros. Vendedor: solo los que registró (o donde figura como vendedor); otro registro responde 403.
Conductores, vehículos, transportistas y catálogos Cualquier usuario autenticado.

Cada página indica en Quién puede usarlo si el endpoint tiene otra regla. Conviene usar un usuario exclusivo para la integración.

Edición parcial

Las rutas de edición aceptan PUT y PATCH por igual y, salvo que la página diga otra cosa, son parciales: los campos que no envías conservan su valor. Las cotizaciones son la excepción: la edición reemplaza la cabecera y los ítems, así que envía el documento completo.

Clientes generados

Cada sección de esta API está vinculada al método equivalente del cliente. El código vive en sdks/ y se regenera con bash scripts/generate-api-sdks.sh.