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/loginen el dominio de tu empresa, con el correo y la contraseña del usuario. No uses el/api/logindel 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_moreesfalse(ynext_cursoresnull) 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.