Registrar una compra a sujeto excluido
POST /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
403sin escribir nada (ver Errores). - Para el paso 1, la llave necesita también el módulo Proveedores.
Paso 1 · Ten al proveedor en el catálogo
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 → .
PATCH /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
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:
{
"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
400concode: REFERENCE_NOT_FOUND: el proveedor o la condición de pago que citas no existe en tu empresa o fue eliminado;messagedice cuál. También lo recibes si envías como objeto un proveedor o una condición de pago cuyoides de un registro que tu empresa eliminó. No se escribe nada.400sincode, conmessagecomo lista: la petición no cumple el contrato; cada elemento nombra un campo. No se escribe nada.400sincode, conmessagecomo texto:messagedice 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 eseinternalIden un estado que impide recrearla, o elidde un objeto que enviaste ya existe fuera de tu empresa (code: INTERNAL_ID_DUPLICATED).
El detalle de cada código está en Errores.