Recetas

Registrar una compra a sujeto excluido

Receta de principio a fin: proveedor, condición de pago y la factura de sujeto excluido.
DisponiblePOST /partners/v1/purchases Ver operación en la Referencia →

Al terminar tendrás una factura de sujeto excluido (documentType: FSE) enviada al MH, con su estado y los enlaces a su PDF y su JSON. El proveedor y la condición de pago se citan por su UUID de Openbox Cloud, así cada compra no reescribe tu catálogo.

Antes de empezar

  • Una sesión iniciada con tu llave (Autenticación).
  • La llave necesita el módulo Compras en su perfil (Permisos por módulo). Sin él, crear la compra responde 403 sin escribir nada (ver Errores).
  • Para el paso 1, la llave necesita también el módulo Proveedores.

Crea el proveedor una sola vez con DisponiblePOST /partners/v1/providers Ver operación en la Referencia → y guarda el id de la respuesta: es el UUID que citarás en cada compra. Si solo lo conoces por tu internalId, recupéralo con DisponibleGET /partners/v1/providers Ver operación en la Referencia → .

La compra usa los datos guardados del proveedor tal cual: su documento, su nombre y la dirección de su sucursal principal son los que recibe el MH. Si falta o cambió alguno, corrígelo antes de comprar con DisponiblePATCH /partners/v1/providers/{id} Ver operación en la Referencia → .

Paso 2 · Elige la condición de pago

Necesitas una condición de pago de compra de tu empresa (por ejemplo, contado). Las condiciones de pago de compra se listan con DisponibleGET /partners/v1/purchases/payment-conditions Ver operación en la Referencia → . Si no tienes su UUID, envía la primera compra con la condición como objeto (id, name y cashPayment), con un UUID nuevo que generes tú en id: Openbox Cloud la crea con ese id. Sigue enviándola como objeto hasta que una compra responda con éxito; desde entonces, las compras siguientes la citan por ese id. Una condición de pago de venta no sirve aquí: son catálogos distintos.

Paso 3 · Crea la compra

Terminal
curl -X POST "$OPENBOX_API_URL/partners/v1/purchases" \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @compra.json

En compra.json, provider y paymentCondition llevan el UUID como texto:

compra.json (fragmento)
{
  "settings": { "notify": "EMAIL", "internalId": "CMP-0001" },
  "data": {
    "header": {
      "documentType": "FSE",
      "purchaseDate": "2026-10-30",
      "provider": "0a1b2c3d-1111-9999-0000-123456789abc",
      "paymentCondition": "5e6f7a8b-2222-9999-0000-123456789abc"
    }
  }
}

purchaseDate es la fecha de emisión del documento que recibe el MH. Las líneas (details) y los totales (totals) completan el cuerpo; su esquema está en la Referencia. En el mismo campo puedes enviar el objeto completo del proveedor o de la condición de pago: Openbox Cloud lo crea o lo actualiza con lo que envías (Referencia u objeto).

La respuesta trae status y haciendaResponse, la respuesta del MH. Revisa ambos antes de dar la compra por presentada: una compra en CONTINGENCIA no tiene el sello del MH. Para volver a consultarla, ve a Consultar y conciliar.

Si algo falla

  • 400 con code: REFERENCE_NOT_FOUND: el proveedor o la condición de pago que citas no existe en tu empresa o fue eliminado; message dice cuál. También lo recibes si envías como objeto un proveedor o una condición de pago cuyo id es de un registro que tu empresa eliminó. No se escribe nada.
  • 400 sin code, con message como lista: la petición no cumple el contrato; cada elemento nombra un campo. No se escribe nada.
  • 400 sin code, con message como texto: message dice el motivo, por ejemplo una dirección del proveedor que no existe en el catálogo. Si el motivo es la validación electrónica del documento o la configuración de facturación electrónica de tu empresa, el proveedor o la condición de pago que enviaste como objeto pueden haber quedado creados o actualizados.
  • 403: la llave no tiene el módulo Compras.
  • 409: ya existe una compra con ese internalId en un estado que impide recrearla, o el id de un objeto que enviaste ya existe fuera de tu empresa (code: INTERNAL_ID_DUPLICATED).

El detalle de cada código está en Errores.

Copyright © 2026