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.

Ó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 123 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.