OP 2.1 — Documentación API para Integradores

📘

Descripción general

Qué es esta API y para qué sirve.

La API de OP 2.1 permite que sistemas ERP externos consulten en tiempo real los presupuestos y pedidos a proveedores generados por el software OP 2.1 de Megevandsoft para cada cliente carpintero.

ℹ️El acceso es de solo lectura. La escritura la realiza exclusivamente el software OP 2.1 de forma automática.

🌐

URL Base

Todas las llamadas deben realizarse a esta URL base.

Base URL

https://mgs-op21-api-afdmg9afa3ajhkbr.eastus-01.azurewebsites.net

⚠️Todos los endpoints requieren HTTPS. Las llamadas HTTP serán rechazadas.

🔑

Autenticación

La API usa un sistema de doble token JWT. Cada cliente tiene su propio par de tokens.

1

Megevandsoft te emite los tokens

Al activar la integración, recibís un access_token (30 días) y un refresh_token (1 año) asociados a tu cliente_id.

2

Usá el access_token en cada llamada

Incluí el access_token en el header X-API-Token de todas las consultas.

3

Renovar el access_token automáticamente

Cuando recibas un 401, llamá a /v1/auth/refresh con el refresh_token para obtener uno nuevo sin intervención de Megevandsoft.

4

Al año, contactar a Megevandsoft

El refresh_token vence al año. Contactá a Megevandsoft para renovarlo.

✅Implementá la renovación automática: ante un 401, llamá a /v1/auth/refresh, guardá el nuevo access_token y reintentá la llamada original.

🎟️

Obtener tokens

Emite el par de tokens para un cliente. Solo lo ejecuta Megevandsoft / OP 2.1 internamente.

⚠️Este endpoint es de uso interno. Requiere la admin_key de Megevandsoft. No compartir con integradores externos.

ℹ️La admin_key corresponde a la variable de entorno WRITE_API_KEY. Podés obtenerla en el portal de Azure → Function App mgs-op21-api → Environment variables.

🗄️Al emitir tokens, la API crea o actualiza automáticamente un registro en el contenedor clientes de Cosmos DB (op21db) con los campos: id, cliente_id, access_token, refresh_token, fecha_alta y ultima_actualizacion. Si el cliente ya existía, actualiza los tokens y la fecha.

POST /v1/auth/token Emitir access_token + refresh_token para un cliente ▶

Request Body

{
  "cliente_id": "CLI-001",        // ID del cliente en OP 2.1
  "admin_key":  "••••••••••••••"    // WRITE_API_KEY de Megevandsoft
}

Response 200

{
  "access_token":           "eyJhbGci...",  // entregar al integrador ERP
  "refresh_token":          "eyJhbGci...",  // entregar al integrador ERP
  "token_type":             "bearer",
  "access_expires_in_hours":  720,           // 30 días
  "refresh_expires_in_hours": 8760          // 1 año
}

🔄

Renovar access token

Obtiene un nuevo access_token usando el refresh_token, sin contactar a Megevandsoft.

POST /v1/auth/refresh Renovar access_token vencido ▶

Request Body

{
  "refresh_token": "eyJhbGci..."  // tu refresh_token vigente
}

Response 200

{
  "access_token":           "eyJhbGci...",  // nuevo access_token
  "refresh_token":          "eyJhbGci...",  // mismo (no cambia)
  "token_type":             "bearer",
  "access_expires_in_hours":  720,
  "refresh_expires_in_hours": 8760
}

⚠️Si el refresh_token también expiró, recibirás un 401. Contactar a Megevandsoft para obtener un par nuevo.

🗄️Al renovar el access_token, la API actualiza automáticamente el campo access_token y ultima_actualizacion en el contenedor clientes de Cosmos DB. El refresh_token no cambia.

Cuando el refresh_token venza (1 año), el ERP debe contactar a Megevandsoft. Megevandsoft llama a POST /v1/auth/token con la admin_key, lo que emite un par nuevo y actualiza el registro completo en Cosmos DB.

🔎

Consultar cliente

Verifica si un cliente está registrado y devuelve sus tokens actuales. Solo lo usa Megevandsoft / OP 2.1.

⚠️Endpoint de uso interno. Requiere el header X-Write-API-Key.

GET /v1/clientes/{cliente_id} Consultar existencia y tokens de un cliente ▶

Header requerido

X-Write-API-Key: WRITE_API_KEY

Parámetro	Tipo	Requerido	Descripción
{cliente_id}	string	requerido	ID del cliente a consultar

Ejemplo

GET /v1/clientes/CLI-001
X-Write-API-Key: tu_write_api_key

Response 200 — cliente encontrado

{
  "cliente_id":           "CLI-001",
  "access_token":         "eyJhbGci...",
  "refresh_token":        "eyJhbGci...",
  "fecha_alta":           "2026-03-13T14:12:18.444624",
  "ultima_actualizacion": "2026-03-13T14:12:18.444624"
}

Response 404 — cliente no encontrado

{
  "detail": "Cliente 'CLI-001' no encontrado."
}

✏️

Registrar presupuesto

Registra un presupuesto con todos sus campos. Lo llama OP 2.1 automáticamente al guardar.

⚠️Este endpoint es de uso interno de OP 2.1. Requiere el header X-Write-API-Key, cuyo valor es la variable de entorno WRITE_API_KEY en Azure.

🔄Si ya existe un presupuesto con el mismo cliente_id + id_presupuesto, lo sobreescribe conservando el mismo UUID. Esto permite re-exportar un presupuesto corregido sin generar duplicados.

POST /v1/presupuestos Registrar o actualizar presupuesto — devuelve 201 ▶

Header requerido

X-Write-API-Key: WRITE_API_KEY

Campos raíz

Campo	Tipo	Requerido	Descripción
cliente_id	string	requerido	ID del cliente en OP 2.1
CustomIDPresupuesto	string	requerido	Número de presupuesto (ej: "447")
Escenario	string	opcional	Ej: "Importado desde OP 2.1"
CustomIDEmpresa	string	opcional	ID de la empresa en sistema externo
Empresa	string	opcional	Nombre de la empresa
RazonSocial	string	opcional	Razón social
NroImpuesto1	string	opcional	Número de impuesto (CUIT, etc.)
Impuesto1Tipo	string	opcional	Tipo de impuesto
ModalidadFiscal	string	opcional	Modalidad fiscal del cliente
CustomIDContacto	string	opcional	ID del contacto
Nombre	string	opcional	Nombre del contacto
Apellido	string	opcional	Apellido del contacto
Correo	string	opcional	Email del contacto
NroMoneda	string	opcional	Número de moneda
Notas	string	opcional	Notas del presupuesto
Descripcion	string	opcional	Descripción general
MostrarImpuestos	string	opcional	"0" o "1"
IncluyeImpuestos	string	opcional	"0" o "1"
Introduccion	string	opcional	Texto de introducción
Cierre	string	opcional	Texto de cierre
Descuento	string	opcional	Descuento general del presupuesto
Validez	string	opcional	Validez del presupuesto
Items	array	requerido	Lista de ítems (ver tabla Items)

Objeto Direccion

Campo	Tipo	Descripción
CustomID	string	ID de dirección
Calle / Numero / Dto / Piso	string	Datos de calle
Localidad / Barrio / Ciudad / Provincia / Pais / CP	string	Ubicación
Telefono	string	Teléfono

Objeto Comercial

Campo	Tipo	Descripción
PlazoEntrega	string	Plazo en días
DireccionEntrega	string	Lugar de entrega (LugarEntrega en VB6)
HorarioEntrega / CondicionesPago / FormaPago	string	Condiciones comerciales
PrecioEnvio / EnvioFacturable / Transporte	string	Datos de envío

Objeto Cotizaciones

Campo	Tipo	Descripción
CotMoneda2 … CotMoneda6	string	Cotizaciones de monedas alternativas

Objetos INFO y Adicionales

Campo	Tipo	Descripción
Info1 … Info10	string	Campos de información libre
Adicional1 … Adicional10	string	Campos adicionales libres

Array Items — cada ítem

Campo	Tipo	Requerido	Descripción
Codigo	string	requerido	Código del ítem (ej: VC1)
CodigoFabricante	string	opcional	Código del fabricante
Descripcion	string	requerido	Descripción completa
Descripcion2 / Descripcion3	string	opcional	Descripciones adicionales
Familia	string	opcional	Familia del producto
Cantidad / Precio / Descuento	string	opcional	Valores numéricos como string
Costo / PrecioOculto / Probabilidad / SobrePrecio	string	opcional	Campos de precio extendidos
Notas / PlazoEntrega / FormaPago / Validez	string	opcional	Condiciones por ítem
Unidad / Impuesto / Imagen	string	opcional	Unidad, impuesto e imagen del ítem

Response 201

{
  "id":        "e6703a97-e270-4d5d-a8d9-722672cf1772",  // UUID (mismo si ya existía)
  "mensaje":   "Presupuesto registrado correctamente.",
  "timestamp": "2026-03-13T14:12:18.444624"
}

📋

Listar presupuestos

Devuelve un resumen de presupuestos del cliente, del más reciente al más antiguo.

GET /v1/presupuestos Listar presupuestos por cliente ▶

Header requerido

X-API-Token: tu_access_token

Parámetros de query

Parámetro	Tipo	Requerido	Descripción
cliente_id	string	requerido	ID del cliente (debe coincidir con el token)
desde	string	opcional	Fecha ISO mínima (ej: 2026-01-01)
limite	integer	opcional	Máx. resultados (default: 50, máx: 200)

Ejemplo

GET /v1/presupuestos?cliente_id=CLI-001&desde=2026-01-01
X-API-Token: eyJhbGci...

Response 200

[
  {
    "id":           "e6703a97-e270-4d5d-a8d9-722672cf1772",
    "cliente_id":   "CLI-001",
    "tipo":         "presupuesto",
    "id_documento": "447",
    "empresa":      "MUNICIPALIDAD DE RAFAELA",
    "timestamp":    "2026-03-11T14:17:57.627630"
  }
]

🔍

Detalle de presupuesto

Retorna el presupuesto completo con todos los campos enviados por OP 2.1. El integrador ERP elige qué campos consumir.

GET /v1/presupuestos/{id} Presupuesto completo con todos los campos ▶

Header requerido

X-API-Token: tu_access_token

Parámetro	Tipo	Requerido	Descripción
{id}	string	requerido	ID del presupuesto (del listado)
cliente_id	string	requerido	ID del cliente dueño del presupuesto

Response 200

{
  "id":                  "e6703a97-...",
  "cliente_id":          "CLI-001",
  "tipo":                "presupuesto",
  "id_presupuesto":      "447",
  "timestamp":           "2026-03-11T14:17:57.627630",
  "Escenario":           "Importado desde OP 2.1",
  "Empresa":             "MUNICIPALIDAD DE RAFAELA",
  "RazonSocial":         "MUNICIPALIDAD DE RAFAELA",
  "NroImpuesto1":        "",
  "Impuesto1Tipo":       "54035",
  "CustomIDContacto":    "OP2.1-408",
  "Nombre":              "MUNICIPALIDAD DE RAFAELA",
  "NroMoneda":           "1",
  "MostrarImpuestos":    "1",
  "IncluyeImpuestos":    "0",
  "descuento_general":   0,
  "Validez":             "",
  "Direccion": {
    "Calle": "", "Ciudad": "", "Provincia": "", "Telefono": ""
    // ... resto de campos de dirección
  },
  "Comercial": {
    "PlazoEntrega":    "30",
    "FormaPago":       "A convenir",
    "Transporte":      ""
    // ... resto de campos comerciales
  },
  "Cotizaciones": {
    "CotMoneda2": "150.5",
    "CotMoneda3": "18.05"
    // ...
  },
  "INFO": { "Info1": "", "Info2": "" // ... Info1 a Info10 },
  "Adicionales": { "Adicional1": "" // ... Adicional1 a Adicional10 },
  "Items": [
    {
      "Codigo":           "VC1",
      "CodigoFabricante":  "VC1",
      "Descripcion":      "CORREDIZA HERRERO. Ancho: 1000. Alto: 1000.\n 2 hojas.",
      "Descripcion2":     "",
      "Descripcion3":     "",
      "Familia":          "OP 2.1",
      "Cantidad":         1,
      "Precio":           6449.00,
      "Costo":            "",
      "PrecioOculto":     "",
      "Probabilidad":     "",
      "Descuento":        0,
      "SobrePrecio":      "",
      "Unidad":           "",
      "Impuesto":         "",
      "Imagen":           "D:\\Imagenes\\Flash478-1.jpg"
    }
  ]
}

✏️

Registrar pedido

Registra un pedido por proveedor. Lo llama OP 2.1 automáticamente — un POST por cada XML de proveedor.

⚠️Endpoint de uso interno de OP 2.1. Requiere el header X-Write-API-Key, cuyo valor es la variable de entorno WRITE_API_KEY en Azure.

🔄La API extrae automáticamente el ID base del IDPedido: "d-2(1)" → id_pedido = "d-2" (base compartido), id_documento = "d-2(1)" (único por proveedor). Si ya existe el id_documento, lo sobreescribe conservando el UUID.

POST /v1/pedidos Registrar pedido por proveedor — devuelve 201 ▶

Header requerido

X-Write-API-Key: WRITE_API_KEY

Campos principales del body

Campo	Tipo	Requerido	Descripción
cliente_id	string	requerido	ID del cliente en OP 2.1
IDPedido	string	requerido	ID completo del proveedor (ej: "d-2(1)"). La API extrae el base automáticamente.
Empresa	string	opcional	Nombre del proveedor
Items	array	requerido	Lista de materiales del proveedor

Ejemplo

POST /v1/pedidos
X-Write-API-Key: tu_write_api_key

{
  "cliente_id":  "CLI-001",
  "IDPedido":    "d-2(1)",
  "Empresa":     "Proveedor Aluar",
  "Items": [
    { "Codigo": "B80", "Descripcion": "Burl Exter Ek2000", "Cantidad": 1, "Precio": null }
  ]
}

Response 201

{
  "id":        "a1b2c3d4-...",  // UUID del documento
  "mensaje":   "Pedido registrado correctamente.",
  "timestamp": "2026-03-19T14:12:18.444624"
}

📦

Listar pedidos

Devuelve un resumen de los pedidos del cliente. Cada fila es un documento por proveedor. Usá el campo id_pedido para llamar al endpoint de grupo y obtener el pedido completo.

💡Flujo recomendado: listar pedidos → obtener id_pedido → llamar a GET /v1/pedidos/grupo/{id_pedido}. El grupo devuelve todos los proveedores completos con sus ítems en una sola llamada.

GET /v1/pedidos Listar pedidos por cliente ▶

Header requerido

X-API-Token: tu_access_token

Parámetro	Tipo	Requerido	Descripción
cliente_id	string	requerido	ID del cliente
desde	string	opcional	Fecha ISO mínima (ej: 2026-01-01)
limite	integer	opcional	Máx. resultados (default: 50, máx: 200)

Response 200

[
  {
    "id":           "a1b2c3d4-...",      // UUID — solo si necesitás un proveedor específico
    "cliente_id":   "CLI-001",
    "tipo":         "pedido",
    "id_pedido":    "d-2",             // ← usar este para GET /grupo/d-2
    "id_documento": "d-2(1)",          // único por proveedor
    "proveedor":    "Proveedor Aluar",
    "timestamp":    "2026-03-19T15:00:00.000000"
  }
]

📦

Grupo de pedido

Devuelve todos los proveedores de un pedido completos en una sola llamada. Es el endpoint principal para consumir pedidos — no hace falta llamar al detalle individual después.

✅Este es el endpoint recomendado para obtener un pedido completo. Devuelve todos los proveedores con sus ítems en una sola respuesta.

GET /v1/pedidos/grupo/{id_base} Todos los proveedores de un pedido ▶

Header requerido

X-API-Token: tu_access_token

Parámetro	Tipo	Requerido	Descripción
{id_base}	string	requerido	Campo `id_pedido` del listado (ej: "d-2")
cliente_id	string	requerido	ID del cliente

Ejemplo

GET /v1/pedidos/grupo/d-2?cliente_id=CLI-001
X-API-Token: eyJhbGci...

Response 200

[
  {
    "id":           "a1b2c3d4-...",
    "id_pedido":    "d-2",
    "id_documento": "d-2(1)",
    "Empresa":      "Proveedor Aluar",
    "Comercial":    { "PlazoEntrega": "19/3/2026" },
    "Items": [
      { "Codigo": "B80", "Descripcion": "Burl Exter Ek2000", "Cantidad": 1 }
    ]
  },
  {
    "id":           "b2c3d4e5-...",
    "id_pedido":    "d-2",
    "id_documento": "d-2(2)",
    "Empresa":      "Proveedor Flamia",
    "Items": [ /* materiales de Flamia */ ]
  }
]

🔍

Detalle de pedido

Retorna el documento completo de un proveedor específico por UUID. Usalo solo cuando necesitás consultar un proveedor puntual sin traer todo el grupo.

⚠️Para obtener un pedido completo con todos sus proveedores, usá GET /v1/pedidos/grupo/{id_base} en lugar de este endpoint.

GET /v1/pedidos/{id} Documento completo de un proveedor específico ▶

Header requerido

X-API-Token: tu_access_token

Parámetro	Tipo	Requerido	Descripción
{id}	string	requerido	UUID del documento (campo `id` del listado)
cliente_id	string	requerido	ID del cliente dueño del pedido

Response 200

{
  "id":           "a1b2c3d4-...",
  "cliente_id":   "CLI-001",
  "tipo":         "pedido",
  "id_pedido":    "d-2",
  "id_documento": "d-2(1)",
  "Empresa":      "Proveedor Aluar",
  "timestamp":    "2026-03-19T15:00:00.000000",
  "Comercial": { "PlazoEntrega": "19/3/2026" // ... },
  "Items": [
    { "Codigo": "B80", "Descripcion": "Burl Exter Ek2000", "Cantidad": 1 }
  ]
}

⚠️

Códigos de error

Código	Significado	Acción recomendada
401	Token inválido o expirado	Llamar a `/v1/auth/refresh` y reintentar
403	Sin autorización para este cliente	Verificar que el cliente_id coincida con el token
404	Documento no encontrado	Verificar el id y el cliente_id
500	Error interno del servidor	Reintentar. Si persiste, contactar a Megevandsoft

📐

Schemas de datos

ItemPresupuesto

Campo	Tipo	Descripción
codigo	string	Código del ítem (ej: V1, VC1)
descripcion	string	Descripción completa del producto
cantidad	float \| null	Cantidad (puede ser null)
precio	float \| null	Precio unitario (puede ser null)
descuento	float	Descuento en % (default: 0)

MaterialPedido

Campo	Tipo	Descripción
codigo	string	Código del material
descripcion	string	Descripción del material
cantidad	float	Cantidad solicitada
precio	float \| null	Precio unitario (opcional)

ℹ️La documentación interactiva completa está en mgs-op21-api.azurewebsites.net/docs — podés probar los endpoints directamente desde el navegador.

👨‍💻

Desarrollador

Esta API fue desarrollada por Megevandsoft. Para consultas técnicas sobre la integración, contactar al desarrollador.

👤

Tomás Gutiérrez

desarrollo2@megevand.com.ar tomasgutierrez.ar@gmail.com

OP 2.1 API de Documentospara Integradores

Descripción general

URL Base

Autenticación

Obtener tokens

Renovar access token

Consultar cliente

Registrar presupuesto

Listar presupuestos

Detalle de presupuesto

Registrar pedido

Listar pedidos

Grupo de pedido

Detalle de pedido

Códigos de error

Schemas de datos

Desarrollador

OP 2.1 API de Documentos
para Integradores