Saltar al contenido
P4 Software P4 Software / activoHQ - Español

Agrega esta documentación a Claude

Hazle preguntas a Claude sobre esta documentación. Claude lee las páginas publicadas y te enlaza a ellas. Copia esta dirección:

https://p4-software.opendocs.page/mcp

En claude.ai o Claude Desktop: abre Configuración, luego Conectores, elige Agregar conector personalizado y pega la dirección.

En Claude Code, ejecuta:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

Auditoría y ciclo de vida

API: Auditoria y ciclo de vida

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.


Auditoría y ciclo de vida (consulta)

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.

GET /api/v1/count-sessions

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.

GET /api/v1/count-sessions/

Sesión de conteo individual -- los mismos campos que los anteriores (sin sobre de paginación).


GET /api/v1/count-results

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.


GET /api/v1/transfers

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.


GET /api/v1/checkouts

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.


GET /api/v1/reservations

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.


Acciones del ciclo de vida

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.

POST /api/v1/assets/

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" }

POST /api/v1/assets/

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.

POST /api/v1/assets/

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"}.


POST /api/v1/reservations/

Cancelar una reservación existente. No se requiere cuerpo en la solicitud.


POST /api/v1/assets/

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"}.


POST /api/v1/assets/

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.

Sesiones de conteo (escritura)

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.

POST /api/v1/count-sessions

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.).

POST /api/rfid/sessions/

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).

POST /api/v1/count-sessions/

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.

POST /api/v1/count-sessions/

Cierra la sesión. Devuelve 200 {"status":"ok"}.

¿Te resultó útil esta página?