Conecta tu ERP con Venvers

Qué trae el kit

Cómo empezar

1. Pide a Venvers tus credenciales: clientId y clientSecret para la API v3, y la X-Api-Key de tu razón social para la bóveda fiscal y los pagos.
2. Importa la colección y el environment en Postman, y llena las variables con tus credenciales.
3. Ejecuta Autenticación → Obtener token y luego cualquier consulta de catálogos para confirmar el acceso.
4. Carga tus catálogos (productos, centros de costo, condiciones de pago) y tus proveedores.
5. Prueba el ciclo completo con una OC de prueba: alta, recepción, factura del proveedor, confronta y pago.

Cómo se conecta

Tu ERP habla con la API de Venvers por HTTPS con JSON. Venvers es el portal donde tus compradores y tus proveedores trabajan: ahí el proveedor confirma la OC y carga su factura, y Venvers la valida ante el SAT. La API te permite mandar lo que nace en tu ERP y traer de vuelta lo que pasa en el portal.

Lo que te entrega Venvers

Autenticación

Hay dos esquemas y cada endpoint usa uno. La referencia del final indica cuál en la columna Auth.

POST https://venvers-api-g8c7a3f2grb0gqas.mexicocentral-01.azurewebsites.net/api/v2/auth/integracion
Content-Type: application/json

{ "clientId": "erp-tuempresa", "clientSecret": "••••••••" }

→ 200
{
  "accessToken": "eyJhbGciOi…",
  "tokenType": "bearer",
  "expiresIn": 28800,
  "scope": "api",
  "clientId": "erp-tuempresa",
  "empresaRFC": "ABC010101AB1",
  "expiresAt": "2026-10-13T22:15:00Z"
}

De la compra al pago

Este es el recorrido completo de una compra y quién hace cada paso. Los pasos de tu ERP son llamadas a la API; los del proveedor ocurren en el portal de Venvers.

Requisiciones (solicitud de pedido)

Si tu empresa captura y autoriza sus requisiciones en Venvers, tu ERP puede tomarlas para crear su propio documento de compra (por ejemplo, una solicitud de pedido en SAP). El modelo es de consulta: tu ERP pregunta por las requisiciones aprobadas que todavía no tienen documento, crea el suyo y confirma el número. Venvers muestra ese número y el estatus en la requisición y avisa al solicitante.

Reglas

• Activación: un administrador de la empresa enciende Configuración → Parámetros → Requisiciones al ERP e indica el nombre del ERP. Mientras esté apagada, estas rutas responden 404.
• Planta por centro de costo: cada centro de costo lleva la planta con la que tu ERP crea el documento (plantaErp en /api/v2/centrosdecosto o en pantalla). Viaja en cada requisición como centroCosto.planta.
• Consulta: GET /api/v2/requisiciones?pendientesErp=true trae las aprobadas que esperan documento; GET /api/v2/requisiciones/{numero} da el detalle con partidas, producto (código interno, claves SAT), importes y solicitante.
• Confirmación: POST /api/v2/requisiciones/{numero}/erp con resultado creada (y numeroErp) o error (y mensaje). Es idempotente: repetir la misma confirmación responde 200.
• Error: el motivo se muestra al solicitante, que corrige y reenvía desde Venvers; la requisición vuelve a aparecer como pendiente.

GET https://venvers-api-g8c7a3f2grb0gqas.mexicocentral-01.azurewebsites.net/api/v2/requisiciones?pendientesErp=true
Authorization: Bearer …

→ 200
{
  "erp": "SAP",
  "total": 1,
  "requisiciones": [
    {
      "id": 45, "numero": "REQ-2026-0012", "fechaSolicitud": "2026-10-28T16:02:11", "fechaAprobacion": "2026-10-28T18:40:02",
      "tipo": "ordinaria", "prioridad": "media", "estatus": "aprobada", "descripcion": "Equipo de cómputo para sucursal Norte",
      "solicitante": { "nombre": "Compras TI", "email": "compras@empresa.com" },
      "centroCosto": { "codigo": "CC-010", "nombre": "Sucursal Norte", "planta": "1000" },
      "partidas": 2, "monto": 1500.00,
      "erp": { "estatus": "pendiente", "numeroErp": null, "mensaje": null, "fechaEnvio": "2026-10-28T18:40:02", "fechaConfirmacion": null }
    }
  ]
}

POST https://venvers-api-g8c7a3f2grb0gqas.mexicocentral-01.azurewebsites.net/api/v2/requisiciones/REQ-2026-0012/erp
Authorization: Bearer …

{
  "numeroErp": "4500012345",
  "resultado": "creada",
  "mensaje": null
}

El detalle de campos, las partidas, los códigos de error y una secuencia de prueba están en Venvers-API-Requisiciones-ERP.pdf, incluido en el kit.

Órdenes de compra

La OC se identifica por su número en tu ERP (noOC). Al crearla decides si llega directo al proveedor o si debe autorizarse dentro de Venvers.

Reglas al crear y editar

• Proveedor: se identifica por proveedor.rfcEmisor (nacional) o proveedor.taxId (extranjero, con RFC genérico XEXX010101000). noProveedor es tu número de proveedor. Si número y RFC apuntan a proveedores distintos, responde 422.
• Tipo de OC (tipoOC): 1 Mercancías · 2 Servicios · 3 Otros · 4 Insumos · 5 Importación. En mercancías e importación el SKU es único por OC.
• Estatus inicial: sin estatus la OC nace publicada para el proveedor; Borrador la deja para autorizar en Venvers; Confirmada la da por aceptada.
• Edición: el PUT reemplaza la OC completa mientras no tenga recepciones ni facturas ligadas; después responde 422.

POST https://venvers-api-g8c7a3f2grb0gqas.mexicocentral-01.azurewebsites.net/api/v2/ordenescompra
Authorization: Bearer …

{
  "noOC": "OC-2026-0001",
  "fechaOC": "2026-10-13",
  "tipoOC": 1,
  "moneda": "MXN",
  "condicionPagoCodigo": "030",
  "proveedor": {
    "noProveedor": "PROV-0042",
    "rfcEmisor": "ANO980101AB1"
  },
  "cfdi": {
    "usoCfdi": "G03",
    "metodoPago": "PPD",
    "formaPago": "99"
  },
  "entrega": {
    "sucursal": "Planta Monterrey",
    "shipTo": "Av. Industrial 450, Apodaca NL"
  },
  "productos": [
    {
      "sku": "TOR-M8-30",
      "descripcion": "TORNILLO HEXAGONAL M8 X 30 MM",
      "unidadMedida": "PZA",
      "cantidad": 500,
      "precioUnitario": 2.35,
      "impuestoTrasladado": 188.0,
      "importe": 1175.0,
      "fechaEntrega": "2026-10-20",
      "tesCodigo": "001"
    },
    {
      "sku": "GUA-NIT-L",
      "descripcion": "GUANTE DE NITRILO TALLA L (CAJA 100)",
      "unidadMedida": "CJA",
      "cantidad": 12,
      "precioUnitario": 189.0,
      "impuestoTrasladado": 362.88,
      "importe": 2268.0,
      "fechaEntrega": "2026-10-20"
    }
  ],
  "estatus": "Enviada"
}

Recepciones y conciliación

La recepción se registra por partida de la OC (cantidad recibida), nunca por monto. Venvers concilia a tres vías: la factura del proveedor debe cuadrar con la OC y con lo recibido.

Para registrar la recepción necesitas el productoOCId de cada partida: viene en productos[].productoOCId al consultar la OC con GET /api/v2/ordenescompra/{noOC}.

POST https://venvers-api-g8c7a3f2grb0gqas.mexicocentral-01.azurewebsites.net/api/v2/recepciones
Authorization: Bearer …

{
  "noOC": "OC-2026-0001",
  "fechaRecepcion": "2026-10-20",
  "notas": "Entrega parcial",
  "detalles": [
    {
      "productoOCId": 101,
      "cantidadRecibida": 300,
      "notas": null
    }
  ]
}

Facturas, confronta y pagos

El proveedor carga su CFDI en el portal y Venvers lo valida ante el SAT. Tu ERP consulta las facturas con GET /api/v2/comprobantes (filtros por emisor, fechas y estatus). Si tu ERP hace su propia confronta (por ejemplo REIM de Oracle), informa el resultado; al pagar, publica el pago y el complemento.

POST https://venvers-api-g8c7a3f2grb0gqas.mexicocentral-01.azurewebsites.net/api/Conciliacion/FacturaConfrontada
X-Api-Key: …

[
  {
    "uuidPrincipal": "51F29F88-2DE1-4890-A523-7EC364E2ADA0",
    "estatus": "aceptada",
    "referencia": "REIM-88231",
    "fecha": "2026-10-21"
  },
  {
    "uuidPrincipal": "0500D3B4-DC2B-40F6-98F4-6CCEB9CE5543",
    "estatus": "rechazada",
    "mensaje": "Monto no coincide con la recepción 4512."
  }
]

→ 200  { "Success": true, "ProcessedItems": 2, "Message": "2 factura(s) con resultado de confronta registrado." }

POST https://venvers-api-g8c7a3f2grb0gqas.mexicocentral-01.azurewebsites.net/api/Conciliacion/PublicarPago
X-Api-Key: …

[
  {
    "uuidPrincipal": "51F29F88-2DE1-4890-A523-7EC364E2ADA0",
    "fechaPago": "2026-11-19",
    "montoPagado": "4000.88",
    "parcialidad": "1"
  }
]

Los endpoints de /api/Conciliacion procesan lotes parciales: cada elemento se procesa por separado y los errores de un elemento no detienen a los demás; el detalle viene en Message.

Convenciones y errores

• Formato: JSON en UTF-8, propiedades en camelCase. Envía Content-Type: application/json.
• Fechas: yyyy-MM-dd (los endpoints de /api/Conciliacion también aceptan dd/MM/yyyy). Las fechas con hora regresan en UTC.
• Montos: decimales con punto, sin separador de miles. Moneda en código ISO (MXN, USD).
• Claves SAT: producto (c_ClaveProdServ, 8 dígitos), unidad (c_ClaveUnidad), uso de CFDI, forma y método de pago según los catálogos del SAT; consúltalas en Catálogos SAT y de referencia.
• Identificadores: usa tus propias claves (noOC, noProveedor, codigoInterno); Venvers las guarda por empresa.

→ 422
{ "message": "Errores en detalles.", "errors": [ "productoOCId 999 no pertenece a la OC 'OC-2026-0001'." ] }

Postman

1. En Postman, Import → selecciona Venvers-API-v3.postman_collection.json y Venvers-API-v3.postman_environment.json.
2. Activa el environment Venvers · API v3 y llena clientId, clientSecret y apiKey. Si tu credencial es de grupo, llena empresaRfc.
3. Ejecuta cualquier petición: la colección pide el token sola y lo reutiliza hasta que vence.
4. Las carpetas siguen el orden del proceso. Crear orden de compra usa la variable noOC; Consultar orden de compra guarda el productoOCId que usa Registrar recepción; Listar facturas guarda uuidFactura para confronta y pagos.

Referencia de endpoints

Las 129 operaciones de la API v3, en el orden del proceso. El detalle de cada campo está en Venvers-API-v3.openapi.json y en los ejemplos de la colección.

Antes de salir a producción

• El token se guarda y se reutiliza hasta que vence; no se pide uno por llamada.
• clientSecret y X-Api-Key viven en una bóveda de secretos, nunca en el código ni en logs.
• Catálogos (productos, centros de costo, condiciones de pago) y proveedores cargados con tus claves.
• Una OC de prueba recorrió el ciclo completo: alta, recepción, factura, confronta y pago.
• Tu integración maneja 401 (renueva token), 422 (muestra el motivo) y 429 (reintenta después).
• Hay un responsable técnico de tu lado para incidencias y Venvers tiene su contacto.