MCP Alegra

Servidor MCP (Model Context Protocol) para integración con Alegra.
Permite acceso a herramientas de gestión empresarial como inventarios, contactos,
facturas, bancos, pagos, retenciones, entre otros, a través de una interfaz MCP estandarizada.

Paquete MCP Expenses (@alegradev/mcp-expenses): facturas de compra (bills), notas de débito de
gastos, órdenes de compra y pagos salientes; las herramientas públicas documentadas enlazan con
references/tools/ y se invocan igual vía JSON-RPC sobre POST /mcp (véase #/paths/~1mcp).

Base URL: https://mcp.alegra.com
Versión: 1.0.0
Soporte: Comunidad Alegra

Inicio Rápido

El token se construye codificando email:token-alegra en Base64:

Base64(email:token-alegra)

Obtén tu token en Alegra → Configuración → API.

Cursor IDE

{
  "mcpServers": {
    "alegra-mcp": {
      "type": "streamable-http",
      "streamable": true,
      "url": "https://mcp.alegra.com/mcp",
      "headers": {
        "Authorization": "Basic TU_TOKEN_AQUI",
        "mcp-groups": "maestros,gastos,ingresos,items,config,contacts,invoices,banks,income-payments,resolutions,currencies,sellers,taxes,retentions,reports,ledger,accounting,support-center"
      }
    }
  }
}

Otros clientes MCP

• URL: https://mcp.alegra.com/mcp
• Transporte: streamable-http
• Header auth: Authorization: Basic <token-base64>
• Header grupos: mcp-groups: <grupos-separados-por-coma>

Grupos disponibles

147 herramientas en 19 grupos.

Herramientas

🧾 Gastos

Facturas de compra, notas de débito, órdenes de compra y pagos salientes.

🧾 Bills

• bills__list_bills — bills__list_bills
• bills__get_bill — bills__get_bill
• bills__create_bill — bills__create_bill
• bills__update_bill — bills__update_bill
• bills__delete_bill — bills__delete_bill
• bills__close_bill — bills__close_bill
• bills__apply_bill_advances — bills__apply_bill_advances
• bills__update_bill_retentions — bills__update_bill_retentions
• bills__update_bill_perceptions — bills__update_bill_perceptions
• bills__add_bill_comments — bills__add_bill_comments
• bills__update_bill_comment — bills__update_bill_comment
• bills__delete_bill_comment — bills__delete_bill_comment
• bills__upload_bill_attachment — bills__upload_bill_attachment
• bills__delete_bill_attachment — bills__delete_bill_attachment
• bills__import_bill_by_cufe — bills__import_bill_by_cufe

bills__list_bills

MCP

Herramienta lógica list_bills. Nombre típico: bills__list_bills (p. ej. expenses__list_bills según el servidor).

HTTP

GET /v1/bills — Query: todos los parámetros opcionales van en arguments como claves planas (equivalente a query string).

Respuesta exitosa

HTTP 200: arreglo de bills, o { metadata: { total }, data: [...] } si metadata=true.

Errores frecuentes

Filtros proveedor

client_id exacto: si no existe ese proveedor, cero resultados (no es error). No combinar lógica de intersección con client_name/provider_name; usar id o nombre (ver guía list_filter_semantics en la fuente).

Campos expandidos

Usar fields como lista separada por comas; ver fields_query_param y fields_guidance en la guía pública (stamp, xml, retentions, journal, etc.).

Respuesta:

{
  "data": []
}

bills__get_bill

MCP

get_bill → bills__get_bill.

HTTP

GET /v1/bills/{id}

Argumentos

• id (path): id local del bill.
• Query opcional: fields, decimalMode, simple, includeVoidPayments, dataByDate.

Respuesta exitosa

HTTP 200: objeto bill (forma según fields).

Errores

Respuesta:

{
  "id": "1"
}

bills__create_bill

MCP

create_bill → bills__create_bill.

HTTP

POST /v1/bills — Cuerpo JSON = objeto bill de alta.

Requisitos

• date, dueDate, provider.id obligatorios.
• Líneas bajo purchases.items y/o purchases.categories (al menos una línea), salvo fusión válida con órdenes de compra (ver guía).
• No enviar en alta: id, status, total, totalPaid, balance, calculationScale, payments (solo lectura / calculados).
• No usar idCostCenter en raíz (rechazado); usar costCenter: { id } o atajo numérico costCenter.

Impuestos en líneas

tax debe ser arreglo de { id }. Códigos: 11048, 11058, 11081 (multiples impuestos), 11067/11059 ids inválidos.

Respuesta exitosa

HTTP 201: bill creado.

Errores (selección)

Ver error_3051_stamp_failure y error_code_reference en la guía pública.

Respuesta:

{
  "id": "1"
}

bills__update_bill

MCP

update_bill → bills__update_bill.

HTTP

PUT /v1/bills/{id} — Actualización parcial.

Restricciones

No enviar id, status, total, totalPaid, balance, calculationScale, payments, advances en el sentido de forzar estado.

Errores

Respuesta:

{
  "id": "1"
}

bills__delete_bill

MCP

delete_bill → bills__delete_bill.

HTTP

DELETE /v1/bills/{id}

Respuesta exitosa

HTTP 204 (cuerpo vacío).

Errores

Respuesta:

{}

bills__close_bill

MCP

close_bill → bills__close_bill.

HTTP

POST /v1/bills/{id}/close

Body obligatorio

• date (yyyy-MM-dd): fecha de cierre.
• category: id de categoría de ingreso (string, number u objeto { id }).

Body opcional

• observations (máx. 500 caracteres).
• journal.numberTemplate.id si la empresa usa tipos y numeraciones para el asiento de cierre.

Errores

Respuesta:

{
  "code": 200,
  "message": "OK"
}

bills__apply_bill_advances

MCP

apply_bill_advances → bills__apply_bill_advances.

HTTP

POST /v1/bills/{id}/advances-applied

Body

advances: arreglo de { id, amount }.

Respuesta

HTTP 200: { code: 200, message: [ ... anticipos ... ] }

Errores

Respuesta:

{
  "code": 200,
  "message": []
}

bills__update_bill_retentions

MCP

update_bill_retentions → bills__update_bill_retentions.

HTTP

PUT /v1/bills/{id}/retentions — Reemplazo total del arreglo retentions.

Errores

Respuesta:

[]

bills__update_bill_perceptions

MCP

update_bill_perceptions → bills__update_bill_perceptions.

HTTP

PUT /v1/bills/{id}/perceptions

Solo empresas Argentina con percepciones habilitadas. Otros países: 405. Cuenta sin feature: 923.

Body

perceptions: arreglo de { id, amount }.

Errores

Respuesta:

[]

bills__add_bill_comments

MCP

add_bill_comments → bills__add_bill_comments.

HTTP

POST /v1/bills/{id}/comments

Body

Debe incluir comments: arreglo de objetos (p. ej. { text } según integración).

Errores

Respuesta:

{
  "success": true
}

bills__update_bill_comment

MCP

update_bill_comment → bills__update_bill_comment.

HTTP

PUT /v1/bills/{id}/comments/{commentId}

Body

comment: string (texto del comentario).

Errores

Respuesta:

{
  "success": true
}

bills__delete_bill_comment

MCP

delete_bill_comment → bills__delete_bill_comment.

HTTP

DELETE /v1/bills/{id}/comments/{commentId}

Respuesta:

{
  "success": true
}

bills__upload_bill_attachment

MCP

upload_bill_attachment → bills__upload_bill_attachment.

HTTP

POST /v1/bills/{id}/attachment — multipart/form-data con un solo campo de archivo llamado file. El id del bill va solo
en la URL ({id}), no como campo extra del formulario.

Argumentos (MCP)

• id: mismo valor que {id} del path (no se duplica como campo multipart).
• file: contenido del único campo de formulario file (en JSON-RPC suele enviarse como base64).

Errores

Respuesta:

{
  "id": "1"
}

bills__delete_bill_attachment

MCP

delete_bill_attachment → bills__delete_bill_attachment.

HTTP

DELETE /v1/bills/attachment/{fileId} — fileId va solo en la URL (no es el id del bill).

Respuesta:

{
  "success": true
}

bills__import_bill_by_cufe

MCP

import_bill_by_cufe → bills__import_bill_by_cufe.

HTTP

POST /v1/bills/import-by-cufe — Body JSON: { "cufe": "..." }.

Solo Colombia.

Respuesta:

{
  "id": "1"
}

📑 Debit Notes

• debit-notes__list_debit_notes — debit-notes__list_debit_notes
• debit-notes__get_debit_note — debit-notes__get_debit_note
• debit-notes__create_debit_note — debit-notes__create_debit_note
• debit-notes__update_debit_note — debit-notes__update_debit_note
• debit-notes__delete_debit_note — debit-notes__delete_debit_note
• debit-notes__add_debit_note_comments — debit-notes__add_debit_note_comments

debit-notes__list_debit_notes

MCP

list_debit_notes → debit-notes__list_debit_notes.

HTTP

GET /v1/debit-notes

Query (arguments)

Paginación: start (default 0), limit (default 30). type: normal | adjustmentNote | all (default normal).
Filtros: fields, metadata, order_field, order_direction, number, date, item_id, provider_name,
emissionStatus, idGlobal, client_id, id (lista de ids locales, máx. 30 en un request), rangos de fecha, etc.

Respuesta

HTTP 200: arreglo o { metadata, data } si metadata está definido.

Errores frecuentes

Respuesta:

{
  "data": []
}

debit-notes__get_debit_note

MCP

get_debit_note → debit-notes__get_debit_note.

HTTP

GET /v1/debit-notes/{id} — Query opcional: fields.

Errores

Respuesta:

{
  "id": "1"
}

debit-notes__create_debit_note

MCP

create_debit_note → debit-notes__create_debit_note.

HTTP

POST /v1/debit-notes

Obligatorio

• client: { id } (proveedor), date
• Al menos una línea: items, categories, purchases.items o purchases.categories

Opcional

bills: [{ id, amount }], refunds, retentions, stamp, warehouse, currency, costCenter,
resolution, metadatos (adjustmentNoteType, annotation, reason, typeCreditNote CR), etc.

No enviar

id, status, total, balance, calculationScale, emissionStatus, payments.

Errores (selección)

Códigos de líneas: 13043–13054, 13104, etc. Ver line_models.validation_codes_common en la fuente.

Actualización tras 3051

Persistir debitNote.id y usar update_debit_note (ver error_3051_stamp_failure en la guía).

Respuesta:

{
  "id": "1"
}

debit-notes__update_debit_note

MCP

update_debit_note → debit-notes__update_debit_note.

HTTP

PUT /v1/debit-notes/{id}

Errores

No reintentar el mismo payload fallido a ciegas en rutas de timbre.

Respuesta:

{
  "id": "1"
}

debit-notes__delete_debit_note

MCP

delete_debit_note → debit-notes__delete_debit_note.

HTTP

DELETE /v1/debit-notes/{id}

Respuesta

HTTP 204; algunos despliegues devuelven JSON legacy { code, message }.

Errores

Respuesta:

{
  "code": 200
}

debit-notes__add_debit_note_comments

MCP

add_debit_note_comments → debit-notes__add_debit_note_comments.

HTTP

POST /v1/debit-notes/{id}/comments

Body

Debe existir la clave comments (arreglo u objeto según servicio de comentarios).

Errores

Respuesta:

{
  "success": true
}

📋 Purchase Orders

• purchase-orders__list-purchase-orders — purchase-orders__list-purchase-orders
• purchase-orders__get-purchase-order — purchase-orders__get-purchase-order
• purchase-orders__create-purchase-order — purchase-orders__create-purchase-order
• purchase-orders__update-purchase-order — purchase-orders__update-purchase-order
• purchase-orders__delete-purchase-order — purchase-orders__delete-purchase-order
• purchase-orders__void-purchase-order — purchase-orders__void-purchase-order
• purchase-orders__add-purchase-order-comments — purchase-orders__add-purchase-order-comments
• purchase-orders__email-purchase-order — purchase-orders__email-purchase-order

purchase-orders__list-purchase-orders

MCP

list-purchase-orders → purchase-orders__list-purchase-orders.

HTTP

GET /v1/purchase-orders

Query (arguments)

Defaults API/MCP: start=0, limit=30. Opcional: metadata (boolean), order_field (name, date, id, deliveryDate, status),
order_direction (ASC|DESC), fields, client_id, provider_name, costCenter_id (usar null/none/0 para sin CC),
warehouse_id, fullNumber, number, item_id, status, date, deliveryDate, delivery_date, id, currency.

Respuesta

Arreglo de órdenes o { metadata: { total }, data } con metadata=true.

Errores frecuentes

Respuesta:

{
  "data": []
}

purchase-orders__get-purchase-order

MCP

get-purchase-order → purchase-orders__get-purchase-order.

HTTP

GET /v1/purchase-orders/{id}

Query

fields, fromMicro (boolean o string según cliente).

Errores

Respuesta:

{
  "id": "1"
}

purchase-orders__create-purchase-order

MCP

create-purchase-order → purchase-orders__create-purchase-order.

HTTP

POST /v1/purchase-orders

Body obligatorio

• date, deliveryDate
• provider (o provider.id)
• purchases con al menos una línea en purchases.items y/o purchases.categories

No enviar

id, status, total, subTotal, bills (en respuesta). Evitar idCostCenter en raíz; usar costCenter objeto.

Líneas

Items/categories: id, price, quantity; impuestos como { id } o arreglo de objetos { id }.

Errores

México puede exigir taxCondition en líneas.

Respuesta:

{
  "id": "1"
}

purchase-orders__update-purchase-order

MCP

update-purchase-order → purchase-orders__update-purchase-order.

HTTP

PUT /v1/purchase-orders/{id}

Errores

Respuesta:

{
  "id": "1"
}

purchase-orders__delete-purchase-order

MCP

delete-purchase-order → purchase-orders__delete-purchase-order.

HTTP

DELETE /v1/purchase-orders/{id} — Solo si es eliminable (sin bills ligadas que bloqueen).

Errores

Respuesta:

{
  "code": 200
}

purchase-orders__void-purchase-order

MCP

void-purchase-order → purchase-orders__void-purchase-order.

HTTP

POST al endpoint de anulación (void) — no es DELETE.

Errores

Respuesta:

{
  "id": "1",
  "status": "void"
}

purchase-orders__add-purchase-order-comments

MCP

add-purchase-order-comments → purchase-orders__add-purchase-order-comments.

HTTP

POST /v1/purchase-orders/{purchaseOrderId}/comments (nombre de path en guía: purchaseOrderId).

Body

comments: string o arreglo (no vacío).

Errores

Respuesta:

{
  "code": 201
}

purchase-orders__email-purchase-order

MCP

email-purchase-order → purchase-orders__email-purchase-order.

HTTP

POST con path purchaseOrderId según API de correo de OC.

Body

• emails: arreglo o string (obligatorio)
• Opcional: sendCopyToUser, emailTemplate: { subject, message }

Errores

Respuesta:

{
  "success": true
}

💸 Transaction Out

• transaction-out__list-outgoing-payments — transaction-out__list-outgoing-payments
• transaction-out__get-outgoing-payment — transaction-out__get-outgoing-payment
• transaction-out__create-outgoing-payment — transaction-out__create-outgoing-payment
• transaction-out__update-outgoing-payment — transaction-out__update-outgoing-payment
• transaction-out__delete-outgoing-payment — transaction-out__delete-outgoing-payment
• transaction-out__void-outgoing-payment — transaction-out__void-outgoing-payment

transaction-out__list-outgoing-payments

MCP

list-outgoing-payments → transaction-out__list-outgoing-payments.

HTTP

GET /api/v1/payments (según gateway; el listado de solo salientes usa type=out).

Query (arguments)

Incluir type: "out" para restringir a pagos salientes. Paginación: start, limit (típico tope 30).
Filtros adicionales: order_field, order_direction, from, to (fechas), fields, client_id, account_id, status.

Respuesta

Lista paginada o arreglo según API; expandir con fields.

Errores frecuentes

Respuesta:

{
  "data": []
}

transaction-out__get-outgoing-payment

MCP

get-outgoing-payment → transaction-out__get-outgoing-payment.

HTTP

GET /api/v1/payments/{id}

Query

fields (lista separada por comas) para expandir numberTemplate, bills, pdf, etc.

Errores

Respuesta:

{
  "id": "1",
  "type": "out"
}

transaction-out__create-outgoing-payment

MCP

create-outgoing-payment → transaction-out__create-outgoing-payment.

HTTP

POST /api/v1/payments

Body obligatorio

• type: "out"
• date: YYYY-MM-DD
• bankAccount: { id } o id escalar

Asociaciones (al menos una)

• bills: [{ id, amount, retentions? }]
• categories: líneas de gasto (ver line_models.categories en fuente)
• documentLines: pagos a líneas de mayor (idJournal, documentLineId, amount)

Opcional

numberTemplate, currency, costCenter (objeto { id }, no idCostCenter en raíz),
client, paymentMethod, observations, metadata (string JSON), paymentType (Rep. Dominicana → mayúsculas en metadata).

Errores

Timbre async

Otros códigos de timbre pueden ir en error anidado según país (ver guía pública).

Respuesta:

{
  "id": "1"
}

transaction-out__update-outgoing-payment

MCP

update-outgoing-payment → transaction-out__update-outgoing-payment.

HTTP

PUT /api/v1/payments/{id}

Restricción

No cambiar el tipo fuera de out.

Errores

Respuesta:

{
  "id": "1"
}

transaction-out__delete-outgoing-payment

MCP

delete-outgoing-payment → transaction-out__delete-outgoing-payment.

HTTP

DELETE /api/v1/payments/{id} cuando las reglas lo permitan.

Errores

Respuesta:

{
  "success": true
}

transaction-out__void-outgoing-payment

MCP

void-outgoing-payment → transaction-out__void-outgoing-payment.

HTTP

Endpoint de void del recurso de pagos (no confundir con delete).

Body opcional

voidCause, voidDate (nombres según contrato API / guía).

Errores

Respuesta:

{
  "id": "1",
  "status": "void"
}

📈 Ingresos

Gestión de facturación, emisión de comprobantes, numeraciones y pagos recibidos.

💰 Invoices

• invoices__getInvoices — invoices__getInvoices
• invoices__getInvoiceById — invoices__getInvoiceById
• invoices__getInvoiceByNumber — invoices__getInvoiceByNumber
• invoices__createInvoice — invoices__createInvoice
• invoices__updateInvoice — invoices__updateInvoice
• invoices__deleteInvoice — invoices__deleteInvoice
• invoices__getPaymentTypes — invoices__getPaymentTypes

invoices__getInvoices

Lista todas las facturas con filtros opcionales

Respuesta:

{
  "data": [
    {
      "id": 1,
      "number": "FAC-001",
      "status": "open"
    }
  ]
}

invoices__getInvoiceById

Obtiene una factura específica por su ID

Respuesta:

{
  "id": 1,
  "number": "FAC-001"
}

invoices__getInvoiceByNumber

Obtiene una factura por su número (NCF o número completo)

Respuesta:

{
  "id": 1
}

invoices__createInvoice

Crea una nueva factura

Respuesta:

{
  "id": 1
}

invoices__updateInvoice

Actualiza una factura existente

Respuesta:

{
  "id": 1
}

invoices__deleteInvoice

Elimina una factura por ID

Respuesta:

{
  "success": true
}

invoices__getPaymentTypes

Obtiene tipos de pago disponibles (específico para República Dominicana)

Respuesta:

{
  "data": [
    {
      "id": 1,
      "name": "Efectivo"
    },
    {
      "id": 2,
      "name": "Tarjeta"
    }
  ]
}

💵 Income Payments

• incomePayments__getIncomePayments — incomePayments__getIncomePayments
• incomePayments__createIncomePayment — incomePayments__createIncomePayment
• incomePayments__updateIncomePayment — incomePayments__updateIncomePayment
• incomePayments__deleteIncomePayment — incomePayments__deleteIncomePayment

incomePayments__getIncomePayments

Obtiene lista de pagos asociados a ingresos

Respuesta:

{
  "data": [
    {
      "id": 1,
      "amount": 100,
      "date": "2024-01-15"
    }
  ]
}

incomePayments__createIncomePayment

Crea un nuevo pago recibido

Respuesta:

{
  "id": 1
}

incomePayments__updateIncomePayment

Actualiza un pago existente

Respuesta:

{
  "id": 1
}

incomePayments__deleteIncomePayment

Elimina un pago por ID

Respuesta:

{
  "success": true
}

📄 Resolutions

• resolutions__getResolutionss — resolutions__getResolutionss
• resolutions__getResolutionById — resolutions__getResolutionById
• resolutions__getDefaultResolutions — resolutions__getDefaultResolutions
• resolutions__createResolutions — resolutions__createResolutions
• resolutions__updateResolutions — resolutions__updateResolutions
• resolutions__deleteResolutions — resolutions__deleteResolutions

resolutions__getResolutionss

Obtiene lista de resoluciones (plantillas de numeración)

Respuesta:

{
  "data": [
    {
      "id": 1,
      "name": "Factura Electrónica"
    }
  ]
}

resolutions__getResolutionById

Obtiene una resolución específica por ID

Respuesta:

{
  "id": 1
}

resolutions__getDefaultResolutions

Obtiene las resoluciones por defecto para un tipo de documento

Respuesta:

{
  "data": []
}

resolutions__createResolutions

Crea una nueva resolución

Respuesta:

{
  "id": 1
}

resolutions__updateResolutions

Actualiza una resolución existente

Respuesta:

{
  "id": 1
}

resolutions__deleteResolutions

Elimina una resolución por ID

Respuesta:

{
  "success": true
}

📦 Items

Gestión de inventario y productos

• items__getItems — items__getItems
• items__getItem — items__getItem
• items__createItem — items__createItem
• items__updateItem — items__updateItem
• items__deleteItem — items__deleteItem
• customFields__getCustomFields — customFields__getCustomFields
• customFields__getCustomField — customFields__getCustomField
• customFields__createCustomField — customFields__createCustomField
• customFields__updateCustomField — customFields__updateCustomField
• customFields__deleteCustomField — customFields__deleteCustomField
• itemCategories__getItemCategories — itemCategories__getItemCategories
• itemCategories__getItemCategory — itemCategories__getItemCategory
• itemCategories__createItemCategory — itemCategories__createItemCategory
• itemCategories__updateItemCategory — itemCategories__updateItemCategory
• itemCategories__deleteItemCategory — itemCategories__deleteItemCategory
• priceList__getPriceLists — priceList__getPriceLists
• priceList__getPriceList — priceList__getPriceList
• priceList__createPriceList — priceList__createPriceList
• priceList__updatePriceList — priceList__updatePriceList
• priceList__deletePriceList — priceList__deletePriceList
• warehouses__getWarehouses — warehouses__getWarehouses
• warehouses__getWarehouse — warehouses__getWarehouse
• warehouses__createWarehouse — warehouses__createWarehouse
• warehouses__updateWarehouse — warehouses__updateWarehouse
• warehouses__deleteWarehouse — warehouses__deleteWarehouse
• itemStock__get_item_stock — itemStock__get_item_stock
• itemStock__get_item_stock_summary — itemStock__get_item_stock_summary
• variantAttributes__getVariantAttributes — variantAttributes__getVariantAttributes
• variantAttributes__getVariantAttribute — variantAttributes__getVariantAttribute
• variantAttributes__createVariantAttribute — variantAttributes__createVariantAttribute
• variantAttributes__updateVariantAttribute — variantAttributes__updateVariantAttribute
• variantAttributes__deleteVariantAttribute — variantAttributes__deleteVariantAttribute
• warehouseTransfers__getWarehouseTransfers — warehouseTransfers__getWarehouseTransfers
• warehouseTransfers__getWarehouseTransfer — warehouseTransfers__getWarehouseTransfer
• warehouseTransfers__createWarehouseTransfer — warehouseTransfers__createWarehouseTransfer
• warehouseTransfers__updateWarehouseTransfer — warehouseTransfers__updateWarehouseTransfer
• warehouseTransfers__deleteWarehouseTransfer — warehouseTransfers__deleteWarehouseTransfer

items__getItems

Obtiene la lista de ítems registrados en la aplicación con filtros opcionales. Usar el parámetro "fields" para incluir datos adicionales cuando el contexto de la conversación lo requiera (e.g. inventory para consultas de stock, images para catálogos, editable/deletable para tareas de gestión).

Respuesta:

[
  {
    "id": "1",
    "name": "Camiseta azul",
    "description": "Algodón 100%",
    "price": [
      {
        "price": 25
      }
    ],
    "type": "product",
    "status": "active"
  },
  {
    "id": "2",
    "name": "Consultoría básica",
    "price": [
      {
        "price": 150
      }
    ],
    "type": "service",
    "status": "active"
  }
]

items__getItem

Obtiene un ítem específico por su ID. Preferir sobre getItems cuando el ID es conocido — es más rápido y devuelve datos más completos. Usar el parámetro fields para solicitar información adicional solo cuando el contexto lo requiera.

Respuesta:

{
  "id": "10",
  "name": "Camiseta azul",
  "type": "product",
  "status": "active",
  "price": [
    {
      "price": 25
    }
  ],
  "description": "Algodón 100%"
}

items__createItem

Crea un nuevo ítem en la aplicación. El campo type determina qué campos son requeridos:

⚠️

Límite de variantes: Para type=variantParent, el producto cartesiano de las opciones de variantAttributes no puede superar 100 combinaciones. Si se proveen itemVariants explícitos, no pueden superar 100 entradas. El servidor rechazará el request si se supera este límite.

Respuesta:

{
  "id": "10",
  "name": "Camiseta azul",
  "type": "product",
  "status": "active"
}

items__updateItem

Actualiza los datos de un ítem existente. Solo enviar los campos que cambiarán.

⚠️

Advertencia para type=variantParent:

• Enviar variantAttributes reemplaza TODOS los atributos existentes del ítem padre.
• Enviar itemVariants reemplaza TODAS las variantes existentes (operación destructiva).
• Límite: El producto cartesiano de opciones en variantAttributes no puede superar 100 combinaciones. El servidor rechazará el request si se supera este límite.

Respuesta:

{
  "id": "10",
  "name": "Camiseta azul actualizada",
  "type": "product",
  "status": "active"
}

items__deleteItem

Elimina un ítem por su ID de la aplicación.

Respuesta:

{
  "id": "10",
  "name": "Camiseta azul",
  "status": "inactive"
}

customFields__getCustomFields

Obtiene los campos adicionales registrados en la aplicación con filtros opcionales.

Respuesta:

[
  {
    "id": "1",
    "name": "Código de barras",
    "resourceType": "item",
    "status": "active",
    "key": "barcode",
    "type": "text",
    "settings": {
      "isRequired": false,
      "showInItemVariants": true,
      "printOnInvoices": null
    }
  }
]

customFields__getCustomField

Obtiene un campo adicional específico por su ID. Preferir sobre getCustomFields cuando el ID es conocido.

Respuesta:

{
  "id": "1",
  "name": "Código de barras",
  "type": "text",
  "resourceType": "item",
  "status": "active",
  "key": "barcode",
  "settings": {
    "isRequired": false,
    "printOnInvoices": null
  },
  "editable": true,
  "deletable": true
}

customFields__createCustomField

Crea un nuevo campo adicional para ítems.

Respuesta:

{
  "id": "3",
  "name": "Fecha de vencimiento",
  "resourceType": "item",
  "status": "active",
  "type": "date"
}

customFields__updateCustomField

Actualiza los datos de un campo adicional existente.

Respuesta:

{
  "id": "3",
  "name": "Fecha de vencimiento actualizada",
  "status": "active",
  "type": "date"
}

customFields__deleteCustomField

Elimina un campo adicional por su ID.

Respuesta:

{
  "id": "3",
  "name": "Fecha de vencimiento",
  "status": "inactive"
}

itemCategories__getItemCategories

Obtiene las categorías de ítems registradas en la aplicación con filtros opcionales.

Respuesta:

[
  {
    "id": "1",
    "name": "Telas",
    "status": "active"
  },
  {
    "id": "2",
    "name": "Ropa para hombre",
    "status": "inactive"
  }
]

itemCategories__getItemCategory

Obtiene una categoría de ítems específica por su ID. Preferir sobre getItemCategories cuando el ID es conocido.

Respuesta:

{
  "id": "1",
  "name": "Telas",
  "description": "Telas y materiales textiles",
  "status": "active",
  "editable": true,
  "deletable": false
}

itemCategories__createItemCategory

Crea una nueva categoría de ítems en la aplicación.

Respuesta:

{
  "id": "3",
  "name": "Ropa de mujer",
  "status": "active"
}

itemCategories__updateItemCategory

Actualiza los datos de una categoría de ítems existente.

Respuesta:

{
  "id": "3",
  "name": "Ropa de mujer actualizada",
  "status": "active"
}

itemCategories__deleteItemCategory

Elimina una categoría de ítems por su ID.

Respuesta:

{
  "id": "3",
  "name": "Ropa de mujer",
  "status": "inactive"
}

priceList__getPriceLists

Obtiene las listas de precios registradas en la aplicación.

Respuesta:

[
  {
    "id": "1",
    "name": "General",
    "status": "active",
    "type": "amount"
  },
  {
    "id": "2",
    "name": "Precios mayorista",
    "status": "active",
    "type": "percentage",
    "percentage": "10.00"
  }
]

priceList__getPriceList

Obtiene una lista de precios específica por su ID. Preferir sobre getPriceLists cuando el ID es conocido.

Respuesta:

{
  "id": "53",
  "name": "Lista mayorista",
  "type": "percentage",
  "percentage": 10,
  "status": "active",
  "editable": true,
  "deletable": true,
  "main": false
}

priceList__createPriceList

Crea una nueva lista de precios.

Respuesta:

{
  "id": "53",
  "name": "Lista mayorista",
  "status": "active",
  "type": "percentage",
  "percentage": 10
}

priceList__updatePriceList

Actualiza los datos de una lista de precios existente.

Respuesta:

{
  "id": "53",
  "name": "Lista mayorista actualizada",
  "status": "active",
  "type": "percentage",
  "percentage": 15
}

priceList__deletePriceList

Elimina una lista de precios por su ID.

Respuesta:

{
  "id": "53",
  "name": "Lista mayorista",
  "status": "inactive"
}

warehouses__getWarehouses

Obtiene la lista de bodegas registradas en la aplicación con filtros opcionales.

Respuesta:

[
  {
    "id": "1",
    "name": "Bodega Norte",
    "isDefault": true,
    "address": "Calle principal",
    "status": "active"
  },
  {
    "id": "3",
    "name": "Bodega Sur",
    "isDefault": false,
    "status": "active"
  }
]

warehouses__getWarehouse

Obtiene una bodega específica por su ID. Preferir sobre getWarehouses cuando el ID es conocido.

Respuesta:

{
  "id": "1",
  "name": "Principal",
  "isDefault": true,
  "address": "Calle principal",
  "status": "active",
  "editable": true,
  "deletable": false
}

warehouses__createWarehouse

Crea una nueva bodega en la aplicación.

Respuesta:

{
  "id": "22",
  "name": "Bodega de alimentos",
  "isDefault": false,
  "status": "active"
}

warehouses__updateWarehouse

Actualiza los datos de una bodega existente.

Respuesta:

{
  "id": "22",
  "name": "Bodega de alimentos actualizada",
  "status": "active"
}

warehouses__deleteWarehouse

Elimina una bodega existente por su ID.

Respuesta:

{
  "code": 200,
  "message": "Se eliminó la bodega correctamente"
}

itemStock__get_item_stock

Obtiene el stock disponible de un ítem específico desglosado por bodega. Usar el campo idGlobal del ítem como valor de itemId. Soporta consulta histórica enviando documentDate para obtener el stock a una fecha específica. SIEMPRE mostrar el nombre de la bodega al presentar resultados — NUNCA mostrar el ID de la bodega directamente al usuario.

Respuesta:

{
  "company": {
    "id": "518587"
  },
  "item": {
    "id": "1046720"
  },
  "quantity": 5,
  "warehouses": [
    {
      "id": "019c24b0-744e-723e-8fb1-1b76a4f1704e",
      "quantity": -7
    },
    {
      "id": "019c441e-48ab-7396-8319-362c4341fbbf",
      "quantity": 12
    }
  ]
}

itemStock__get_item_stock_summary

Obtiene un resumen del stock de múltiples ítems filtrado por condición de stock. Requiere stockCondition para determinar qué ítems incluir en el resultado. Condiciones disponibles: NEGATIVE_STOCK (stock negativo), ZERO_STOCK (stock en cero), LOW_STOCK (stock por debajo de un umbral — usar con stockThreshold), CURRENT_STOCK (ítems con stock disponible). SIEMPRE usar otras herramientas para resolver nombres de ítems a partir de sus IDs. SIEMPRE mostrar el nombre de la bodega — NUNCA mostrar el ID de la bodega al usuario.

Respuesta:

[
  {
    "item": {
      "id": "1046720"
    },
    "quantity": 0
  },
  {
    "item": {
      "id": "1046721"
    },
    "quantity": 0
  }
]

variantAttributes__getVariantAttributes

Obtiene la lista de atributos de variante registrados en la aplicación con filtros opcionales. Los atributos de variante son dimensiones de producto (Color, Talla, Material) y sus opciones los valores posibles (Rojo, Azul, S, M, L). Usar para obtener IDs reales antes de crear o actualizar ítems de tipo variantParent.

Respuesta:

[
  {
    "id": "1",
    "name": "Color",
    "status": "active",
    "options": [
      {
        "id": "1",
        "value": "Rojo"
      },
      {
        "id": "2",
        "value": "Verde"
      }
    ]
  },
  {
    "id": "2",
    "name": "Talla",
    "status": "active",
    "options": [
      {
        "id": "3",
        "value": "S"
      },
      {
        "id": "4",
        "value": "M"
      }
    ]
  }
]

variantAttributes__getVariantAttribute

Obtiene un atributo de variante específico por su ID, incluyendo su lista completa de opciones.