Guía 6. Crear un proveedor, una orden de compra, aprobarla y registrar la recepción

Objetivo: recorrer el ciclo de compra completo: alta del proveedor, orden, aprobación, recepción de mercancía y, al aprobar, la cuenta por pagar que se genera en finanzas.

Servicio: compras-proveedores-ms, con el gateway como entrada. Todas las rutas van bajo /compras-proveedores-ms/v1.

Roles

Para todo, usa un access token vigente en el encabezado Authorization: Bearer ACCESS_TOKEN.

Antes de empezar

• Usuario con el rol que corresponda a cada paso.
• El artículo debe existir en inventario con su SKU.
• Datos del proveedor: razón social, RFC y correo.

Pasos

1. Da de alta al proveedor (rol COMPRAS):

   curl -s -X POST http://HOST/compras-proveedores-ms/v1/proveedores \
     -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
     -d '{"razonSocial":"Papelería del Centro SA de CV","rfc":"PCE010101AAA","correo":"ventas@proveedor.mx"}'

   Anota el id de la respuesta.

2. Crea la orden de compra (rol COMPRAS). Envía el encabezado Idempotency-Key con un valor único por intento. Si la red falla y repites la petición con la misma clave, no se duplica la orden:

   curl -s -X POST http://HOST/compras-proveedores-ms/v1/ordenes-compra \
     -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"proveedorId":"PROVEEDOR_ID","moneda":"MXN","lineas":[{"articuloSku":"PAP-A4-500","cantidad":10,"precioUnitario":85.00}]}'

   La orden nace en estado BORRADOR. Anota su id.

   Los estados son: BORRADOR → APROBADA → RECIBIDA_PARCIAL → RECIBIDA, y CANCELADA desde borrador o aprobada.

3. Consulta la orden para revisar subtotal y estatus:

   curl -s http://HOST/compras-proveedores-ms/v1/ordenes-compra/ORDEN_ID \
     -H "Authorization: Bearer ACCESS_TOKEN"

4. Aprueba la orden (rol COMPRAS o DIRECCION):

   curl -s -X POST http://HOST/compras-proveedores-ms/v1/ordenes-compra/ORDEN_ID/aprobacion \
     -H "Authorization: Bearer ACCESS_TOKEN"

   Al aprobarse, la orden publica el evento orden-compra-aprobada. Facturación y pagos crea entonces la cuenta por pagar de la orden. Esa cuenta se crea una sola vez aunque el evento llegue dos veces. Ver la guía 7.

5. Envía la mercancía y registra la recepción (rol ALMACEN). Indica la cantidad recibida por SKU:

   curl -s -X POST http://HOST/compras-proveedores-ms/v1/ordenes-compra/ORDEN_ID/recepciones \
     -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
     -d '{"lineas":[{"articuloSku":"PAP-A4-500","cantidad":10}]}'

   Puedes registrar recepciones parciales: la orden pasa a RECIBIDA_PARCIAL y la respuesta muestra cantidadRecibida por línea frente a cantidadOrdenada. Cuando todas las líneas quedan completas, pasa a RECIBIDA.

6. Cancela la orden si ya no procede (rol COMPRAS). Debe llevar motivo:

   curl -s -X POST http://HOST/compras-proveedores-ms/v1/ordenes-compra/ORDEN_ID/cancelacion \
     -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
     -d '{"motivo":"El proveedor no pudo surtir"}'

Verificación

• GET /ordenes-compra/ORDEN_ID muestra el estatus aprobada y, al final de la recepción, las cantidades recibidas.
• En facturación y pagos (guía 7), la cuenta por pagar existe con el total de la orden.

Problemas comunes