mini-erp/mini-backend/docs/api-reference.md

API Reference

Base URL: http://<host>:8000 API Version: 1.1.0 Content-Type: application/json

---

Headers Globales

Header	Requerido	Descripción
Content-Type	Sí	application/json
X-Session-Token	Sí (excepto /api/Login)	Token obtenido en el login
X-Request-ID	Opcional	UUID para trazabilidad; si no se envía, el servidor lo genera

---

Formato de Errores

Todas las respuestas de error siguen el mismo formato:

{
  "detail": "Mensaje de error de SAP o del servidor"
}

Código	Significado
400	Error de negocio SAP (ej: código duplicado, validación fallida)
401	Token inválido/expirado, o credenciales incorrectas
404	Recurso no encontrado en SAP
500	Error de conexión con SAP o error interno

---

Autenticación

POST /api/Login

Inicia sesión de empleado. Valida contra SAP EmployeesInfo usando el apellido como contraseña.

Request body:

{
  "Username": "123",
  "Password": "Garcia"
}

Response 200:

{
  "message": "Login exitoso",
  "token": "aB3x...token_urlsafe_32_chars...",
  "username": "Juan"
}

Response 401:

{
  "detail": "Usuario o contraseña incorrectos"
}

---

POST /api/Logout

Cierra la sesión del empleado.

Headers: X-Session-Token: <token>

Response 200:

{
  "message": "Logout exitoso"
}

---

Socios de Negocio

GET /api/BusinessPartners

Lista paginada de socios de negocio.

Query parameters:

Parámetro	Tipo	Default	Descripción
skip	int	0	Registros a saltar ($skip)
top	int	50	Registros por página ($top)
fields	string	—	Campos a retornar, separados por coma ($select)
filter	string	—	Filtro OData ($filter). Activa B1S-CaseInsensitive

Response 200:

{
  "odata.metadata": "https://.../$metadata#BusinessPartners",
  "value": [
    {
      "CardCode": "C001",
      "CardName": "Cliente Demo",
      "CardType": "C"
    }
  ],
  "odata.count": 150
}

---

GET /api/BusinessPartners/{bp_code}

Obtiene un socio de negocio por CardCode.

Response 200:

{
  "CardCode": "C001",
  "CardName": "Cliente Demo",
  "CardType": "C",
  "Phone1": "123456789",
  "EmailAddress": "cliente@demo.com"
}

---

POST /api/BusinessPartners

Crea un nuevo socio de negocio.

Request body:

{
  "CardCode": "C001",
  "CardName": "Cliente Demo",
  "CardType": "C"
}

Response 201:

{
  "CardCode": "C001"
}

---

PATCH /api/BusinessPartners/{bp_code}

Actualiza un socio de negocio existente.

Request body:

{
  "CardName": "Nuevo Nombre",
  "Phone1": "987654321"
}

Response 204: Sin contenido.

---

Artículos

GET /api/Items

Lista paginada de artículos.

Query parameters:

Parámetro	Tipo	Default	Descripción
skip	int	0	Registros a saltar
top	int	50	Registros por página
fields	string	—	Campos a retornar ($select)
filter	string	—	Filtro OData ($filter)

Response 200:

{
  "odata.metadata": "https://.../$metadata#Items",
  "value": [
    {
      "ItemCode": "A001",
      "ItemName": "Artículo Demo",
      "InventoryUOM": "UN"
    }
  ],
  "odata.count": 250
}

---

GET /api/Items/{item_code}

Obtiene un artículo por ItemCode.

Response 200:

{
  "ItemCode": "A001",
  "ItemName": "Artículo Demo",
  "InventoryUOM": "UN",
  "SalesPrice": 100.50
}

---

POST /api/Items

Crea un nuevo artículo.

Request body:

{
  "ItemCode": "A001",
  "ItemName": "Artículo Demo",
  "InventoryUOM": "UN"
}

Response 201:

{
  "ItemCode": "A001"
}

---

PATCH /api/Items/{item_code}

Actualiza un artículo existente.

Request body:

{
  "ItemName": "Nuevo Nombre",
  "SalesPrice": 120.00
}

Response 204: Sin contenido.

---

Ventas

Facturas (A/R Invoices)

GET /api/Invoices

Lista paginada de facturas de venta.

Query parameters:

Parámetro	Tipo	Default	Descripción
skip	int	0	Registros a saltar
top	int	50	Registros por página
fields	string	—	Campos a retornar
filter	string	—	Filtro OData
orderby	string	—	Ordenamiento ($orderby)

Response 200:

{
  "odata.metadata": "https://.../$metadata#Invoices",
  "value": [
    {
      "DocEntry": 1001,
      "CardCode": "C001",
      "DocTotal": 1500.00,
      "DocDate": "2026-07-06"
    }
  ],
  "odata.count": 45
}

---

POST /api/Invoices

Crea una factura de venta.

Response 201:

{
  "DocEntry": 1001
}

---

GET /api/Invoices/{invoice_key}

Obtiene una factura por DocEntry.

---

PATCH /api/Invoices/{invoice_key}

Actualiza una factura. Usa header B1S-ReplaceCollectionsOnPatch: true.

Response 204: Sin contenido.

---

Pedidos (Sales Orders)

GET /api/Orders

Lista paginada de pedidos de venta. Mismos parámetros que Invoices.

POST /api/Orders

Crea un pedido de venta.

Response 201:

{
  "DocEntry": 2001
}

GET /api/Orders/{order_key}

Obtiene un pedido por DocEntry.

PATCH /api/Orders/{order_key}

Actualiza un pedido. Usa header B1S-ReplaceCollectionsOnPatch: true.

Response 204: Sin contenido.

---

Compras

Órdenes de Compra

GET /api/PurchaseOrders

Lista paginada. Mismos parámetros que Invoices/Orders.

GET /api/PurchaseOrders/{key}

Obtiene una orden de compra por DocEntry.

PATCH /api/PurchaseOrders/{key}

Actualiza una orden de compra. Usa header B1S-ReplaceCollectionsOnPatch: true.

Response 204: Sin contenido.

---

Facturas de Compra (A/P Invoices)

GET /api/PurchaseInvoices

Lista paginada. Mismos parámetros que Invoices/Orders.

GET /api/PurchaseInvoices/{key}

Obtiene una factura de compra por DocEntry.

PATCH /api/PurchaseInvoices/{key}

Actualiza una factura de compra. Usa header B1S-ReplaceCollectionsOnPatch: true.

Response 204: Sin contenido.

---

Catálogos

GET /api/Currencies

Lista de monedas.

Response 200:

{
  "value": [
    { "Code": "USD", "Name": "US Dollar" },
    { "Code": "EUR", "Name": "Euro" }
  ]
}

---

GET /api/BusinessPartnerGroups

Lista de grupos de socios de negocio.

Response 200:

{
  "value": [
    { "Number": 1, "GroupName": "Clientes Nacionales" }
  ]
}

---

GET /api/Warehouses

Lista paginada de almacenes. Acepta skip, top, fields, filter.

---

GET /api/ItemGroups

Lista de grupos de artículos.

Response 200:

{
  "value": [
    { "Number": 1, "GroupName": "Materia Prima" }
  ]
}

---

GET /api/SalesTaxCodes

Lista paginada de códigos de IVA. Acepta skip, top, fields, filter.

---

Lotes

GET /api/BatchNumberDetails

Lista paginada de lotes/números de serie. Acepta skip, top, fields, filter, orderby.

---

GET /api/BatchNumberDetails/{batch_id}

Obtiene un lote por ID.

---

PATCH /api/BatchNumberDetails/{batch_id}

Actualiza un lote.

Response 204: Sin contenido.

---

Permisos

GET /api/user/menu

Retorna las rutas de menú permitidas para el empleado autenticado.

Headers: X-Session-Token: <token>

Response 200:

{
  "allowedPaths": [
    "/inventario/*",
    "/ventas/*",
    "/compras/*"
  ]
}

Response 401:

{
  "detail": "Usuario no autenticado"
}

---

Resumen de Códigos de Respuesta

Método	Éxito	Cuerpo en éxito	Error SAP	Error de conexión
GET	200	JSON del recurso	4xx con detail	500
POST	201	{"CardCode"/"ItemCode"/"DocEntry": valor}	4xx con detail	500
PATCH	204	Sin cuerpo	4xx con detail	500