P4 Software
/
activoHQ - Español
Esta página requiere el encabezado X-Api-Key y el parámetro ?companyId= descritos en la descripción general de la API REST para desarrolladores.
Estos endpoints exponen los datos generados por conteos físicos de inventario, Transferencias de Activos,
operaciones de préstamo / devolución y reservaciones. Los de esta sección son únicamente GET, requieren X-Api-Key
y ?companyId=, y devuelven el sobre de paginación estándar ({items, total, skip, take}) --
excepto GET /api/v1/count-sessions/{id}, que devuelve el objeto directamente.
Lista paginada de Sesiones de conteo físico de inventario.
curl -s "https://acme.activohq.cloud/api/v1/count-sessions?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "X-Api-Key: $ACTIVOHQ_API_KEY"
Campos de los elementos en la respuesta:
{
"id": "...",
"code": "CNT-2025-001",
"name": "Mid-year physical count",
"openedDate": "2025-06-01",
"status": "Reconciled",
"expectedCount": 312,
"reconciledDate": "2025-06-05",
"notes": "Annual mid-year audit."
}
status es Open, Reading, Reconciled o Closed. Una sesión nueva se crea directamente en Reading; Open no se asigna nunca. expectedCount cuenta los Activos con estado Active de la empresa al abrir la sesión.
Sesión de conteo individual -- los mismos campos que los anteriores (sin sobre de paginación).
Lista paginada de líneas de resultado de conteo. Use ?sessionId= para obtener los resultados de una sesión específica.
Campos de los elementos en la respuesta:
{
"id": "...",
"countSessionId": "...",
"assetId": "...",
"epc": "E28011700000020F4B1C0D5A",
"status": "Found",
"expectedLocationId": "...",
"readLocationId": "...",
"transferApplied": false
}
Valores posibles de status: Found, Missing, Unexpected, Moved.
Lista paginada de Transferencias de ubicación de Activos (incluyendo las generadas automáticamente desde un conteo). Filtre con ?assetId=.
Campos de los elementos en la respuesta:
{
"id": "...",
"assetId": "...",
"fromLocationId": "...",
"toLocationId": "...",
"transferDate": "2025-06-05",
"reason": "RFID reconciliation",
"sourceCountResultId": "..."
}
sourceCountResultId es null en las Transferencias creadas manualmente (con la acción Transferir del activo); en ellas reason es el texto que escribió el usuario. En las que se generan al aplicar un conteo, reason es RFID reconciliation.
Lista paginada de registros de préstamo / devolución de Activos. Filtre con ?assetId=.
Campos de los elementos en la respuesta:
{
"id": "...",
"assetId": "...",
"employeeId": "...",
"checkoutDate": "2025-06-10",
"expectedReturnDate": "2025-06-17",
"actualReturnDate": "2025-06-16",
"notes": "Required for field visit.",
"returnCondition": "Good",
"damageNotes": null
}
actualReturnDate es null mientras el activo sigue prestado.
Valores de returnCondition: Good, MinorWear, Damaged, Lost.
Lista paginada de reservaciones de Activos. Filtre con ?assetId=.
Campos de los elementos en la respuesta:
{
"id": "...",
"assetId": "...",
"employeeId": "...",
"startDate": "2025-07-01",
"endDate": "2025-07-05",
"status": "Reserved",
"notes": "Reserved for training session."
}
Valores de status: Reserved, Fulfilled, Cancelled.
Los siguientes endpoints POST ejecutan transiciones del ciclo de vida de Activos y registran los mismos
asientos contables que la aplicación web. Todos requieren X-Api-Key y ?companyId=. En caso de éxito
devuelven 200 {"status":"ok"}. Las violaciones de reglas de negocio devuelven 400 con {"error":"...message..."};
"no encontrado" devuelve 404.
Prestar un activo a un empleado.
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
employeeId |
guid | Sí | Empleado que recibe el activo. Use GET /api/v1/employees para listar los ids. |
expectedReturnDate |
date (ISO) | No | Ej. "2025-07-15". |
notes |
string | No | Notas de texto libre para el préstamo. |
photoBase64 |
string | No | Foto de la condición del activo codificada en base64 (PNG, GIF, JPG o WebP, máximo 5 MB). |
photoContentType |
string | No | Tipo de contenido de la foto, p. ej. image/png. |
eulaAcceptedText |
string | Según el modelo | Texto del acuerdo aceptado. Es obligatorio cuando el modelo del activo exige un acuerdo; si falta, la API responde 400 con This asset requires acceptance of the agreement before checkout. Para consultar el acuerdo use GET /api/v1/assets/{id}/eula, que devuelve {"required": true/false, "text": "..."}. |
Ejemplo de error 400 por regla de negocio: {"error":"Asset is already checked out"}.
curl -s -X POST "https://acme.activohq.cloud/api/v1/assets/f47edba8-67fe-42ce-8209-0e20e1abc17e/checkout?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "X-Api-Key: $ACTIVOHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employeeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"expectedReturnDate": "2025-07-15",
"notes": "Required for field visit."
}'
Respuesta (200 OK):
{ "status": "ok" }
Devolver un activo prestado.
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
notes |
string | No | Notas de devolución. |
condition |
string | No | Condición de devolución por nombre de enumeración: Good, MinorWear, Damaged o Lost. El valor predeterminado es Good. |
damageNotes |
string | No | Descripción del daño (relevante cuando condition es Damaged o Lost). |
photoBase64 |
string | No | Foto de la condición del activo en base64 (PNG, GIF, JPG o WebP, máximo 5 MB). |
photoContentType |
string | No | Tipo de contenido de la foto, p. ej. image/jpeg. |
Reservar un activo para un empleado en un rango de fechas.
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
employeeId |
guid | Sí | Empleado para quien se realiza la reservación. |
startDate |
date (ISO) | Sí | Primer día de la reservación. |
endDate |
date (ISO) | Sí | Último día de la reservación. |
notes |
string | No | Notas de texto libre. |
Ejemplo de error 400 por regla de negocio: {"error":"Reservation conflicts with an existing reservation"}.
Cancelar una reservación existente. No se requiere cuerpo en la solicitud.
Dar de baja (retirar o vender) un activo. Registra el asiento contable de la baja.
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
date |
date (ISO) | Sí | Fecha de la baja. |
proceeds |
decimal | Sí | Ingresos por la venta (use 0 para una cancelación / retiro). |
retirement |
boolean | Sí | true para retiro / cancelación; false para venta. |
notes |
string | No | Notas de texto libre. |
Ejemplo de error 400 por regla de negocio: {"error":"Only active assets can be disposed"}.
Registrar una revaluación o deterioro de un activo.
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
date |
date (ISO) | Sí | Fecha efectiva. |
type |
string | Sí | Revaluation (ajuste al alza) o Impairment (reducción de valor). |
amount |
decimal | Sí | Monto del ajuste (siempre positivo; type establece la dirección). |
notes |
string | No | Notas de texto libre. |
Estas llamadas abren, concilian y cierran una sesión de conteo RFID (las usa la aplicación móvil). Requieren X-Api-Key y ?companyId=, salvo el envío de lecturas, que no lleva companyId. Los mensajes de error están en inglés.
Abre una sesión. Cuerpo: code (obligatorio, único en la empresa), name (obligatorio) y notes (opcional). Devuelve 201 Created con la sesión (mismos campos que GET /api/v1/count-sessions/{id}). Si el código ya existe o falta code o name, responde 400 (Session code already exists o code and name are required.).
Envía lecturas a una sesión. Esta ruta no está bajo /api/v1 ni lleva companyId: la empresa se toma de la sesión. El cuerpo es un arreglo JSON de lecturas:
[
{ "epc": "E28011700000020F4B1C0D5A", "readTimestamp": "2025-06-01T14:05:00Z", "readerId": "DOCK-01", "locationCode": "HQ-01" }
]
locationCode es opcional y se compara sin distinguir mayúsculas; un código desconocido deja la lectura sin ubicación. Para un activo sin EPC, envíe su código de activo en epc. Respuesta: 200 {"ingested": n}. Un arreglo vacío devuelve 400 (No reads supplied.), una sesión desconocida 404 y una sesión que ya no está en estado Reading 400 (Session is not accepting reads).
Concilia la sesión. Devuelve 200 con los totales {"found": n, "missing": n, "unexpected": n, "moved": n}. Después de conciliar, la sesión ya no acepta lecturas.
Cierra la sesión. Devuelve 200 {"status":"ok"}.
¿Te resultó útil esta página?