Documento de compra aceptado

Identificador del evento: purchase_document.accepted

En pocas palabras

IDPOS le avisa de que se aceptó un documento de compra: una orden de compra o una orden de servicio a un proveedor. El aviso trae el documento con su proveedor, sus ítems, el almacén y la tienda.

Cuándo llega

Cuando un documento de compra pasa al estado «aceptada». Ocurre en dos casos:

• Se acepta un documento de compra que estaba pendiente.
• Se finaliza un documento de compra que estaba en borrador o pendiente: la aceptación ocurre dentro de ese mismo paso.

Campo	Qué indica
reference	OC- seguido del número para una orden de compra, que tiene almacén. OS- seguido del número para una orden de servicio, que no tiene almacén.
warehouse	En una orden de servicio, todos sus campos vienen nulos.

Importante: el estado puede ser posterior a «aceptada»

El aviso se prepara en segundo plano y trae el estado del documento en ese momento. Si el documento se finalizó en un solo paso, status puede llegar como finished y no como accepted. Este evento significa que el documento fue aceptado: no use status para decidir si lo fue.

Para qué le sirve

• Registrar la orden de compra o de servicio en su ERP o sistema contable, con sus ítems, cantidades y costos.
• Avisar a su almacén de la mercadería que va a recibir.
• Mantener los datos de sus proveedores: nombre, identificación, teléfono, dirección y correo.

Qué hacer al recibirlo

1. Verifique la firma.

   Calcule el HMAC con el cuerpo crudo y compárelo con X-Webhook-Signature. Si no coincide, no procese el evento. Los pasos están en Autenticación y firma.

2. Responda 2xx de inmediato.

   Guarde el evento en una cola y responda sin esperar a procesarlo. Si tarda más que el tiempo de espera, IDPOS lo trata como fallido y lo reintenta.

3. Descarte los duplicados.

   Si ya procesó ese event_id del cuerpo, ya verificado, no lo procese otra vez. Como segunda clave use event_type junto con data.id (por ejemplo, purchase_document.accepted y el id del documento).

4. Procese el evento en segundo plano.

   Registre el documento con data.id y reference. Reconozca el producto de cada línea por sku: purchase_document_items[].id identifica la línea, no el ítem. Lea solo los campos que necesita e ignore los que no reconozca.

Ejemplo

purchase_document.accepted.json

{
  "event_id": "01J9ZR8T0W2Y4A6C8E1G3J5M7P",
  "event_type": "purchase_document.accepted",
  "timestamp": "2026-10-12T14:12:03Z",
  "api_version": "v1",
  "data": {
    "id": "f3b5c7d9-1e4a-4f6c-8b8e-2a4c6e8d0f59",
    "number_reference": "000231",
    "reference": "OC-000231",
    "number": 231,
    "concept": "Reposición mensual de bebidas",
    "status": "accepted",
    "is_paid": false,
    "total_amount": 1656.0,
    "created_at": "2026-10-12T14:10:22Z",
    "purchased_at": "2026-10-12T14:10:00Z",
    "received_at": null,
    "warehouse": {
      "id": "5f7b9d1a-3c5e-4b7a-9d2f-1a3c5e7b9d04",
      "name": "Almacén principal",
      "external_id": "A01"
    },
    "provider": {
      "display_name": "Distribuidora Andina S.A.C.",
      "identification": {
        "type": "ruc",
        "value": "20512345678"
      },
      "phone": "900000000",
      "address": {
        "street": "Av. Industrial 450",
        "locality": "Lima",
        "zip_code": "15001",
        "ubigeo": "150101",
        "latitude": "0.0000000",
        "longitude": "0.0000000",
        "elevation": null,
        "instructions": "Ingreso por el almacén del fondo",
        "type": "ID\\Provider"
      },
      "email": "ventas@distribuidoraandina.example"
    },
    "purchase_document_items": [
      {
        "id": "a4c6e8b0-2d5f-4a7c-9e9f-3b5d7f9a1c60",
        "sku": "BEB-001",
        "name": "Gaseosa 500 ml",
        "quantity": 480.0,
        "unit_cost": 1.85
      },
      {
        "id": "b5d7f9a1-3e6a-4b8d-8f0a-4c6e8a0b2d71",
        "sku": "SNK-014",
        "name": "Papas fritas 150 g",
        "quantity": 240.0,
        "unit_cost": 3.2
      }
    ],
    "store": {
      "id": "6a8c0e2f-5b7d-4d9b-9e3a-4f6b8d0c2e53",
      "name": "Tienda Centro",
      "external_id": "T01"
    }
  }
}

Campos

Cómo leer las tablas: el tipo aparece debajo del nombre del campo y «nulo» indica que puede venir como null. Los demás términos están en la guía de lectura de campos.

Importes y decimales

En este evento total_amount, purchase_document_items[].quantity y purchase_document_items[].unit_cost se envían como números, no como texto. El evento no incluye la moneda del documento.

Documento

Campo	Descripción
id string (UUID)	Identificador del documento de compra
number_reference string · nulo	Número del documento con ceros a la izquierda hasta completar 6 dígitos. Por ejemplo, 000231
reference string · nulo	Referencia del documento: OC- más number_reference para una orden de compra, u OS- más number_reference para una orden de servicio
number entero · nulo	Número del documento
concept string · nulo	Concepto del documento
status string · nulo	Estado del documento cuando IDPOS prepara el aviso. Es accepted o, si el documento avanzó de inmediato, un estado posterior
is_paid booleano	Indica si el documento está pagado
total_amount número	Monto total del documento
created_at string (fecha) · nulo	Fecha de creación
purchased_at string (fecha) · nulo	Fecha de la compra
received_at string (fecha) · nulo	Fecha de recepción de la mercadería

Almacén (warehouse)

Campo	Descripción
warehouse objeto	Almacén del documento. Sus campos vienen nulos en una orden de servicio
warehouse.id string (UUID) · nulo	Identificador del almacén
warehouse.name string · nulo	Nombre del almacén
warehouse.external_id string · nulo	Código externo del almacén

Tienda (store)

Campo	Descripción
store objeto	Tienda
store.id string (UUID) · nulo	Identificador de la tienda
store.name string · nulo	Nombre de la tienda
store.external_id string · nulo	Código externo de la tienda

Proveedor (provider)

Campo	Descripción
provider objeto	Proveedor del documento
provider.display_name string · nulo	Nombre del proveedor
provider.identification objeto	Documento de identidad del proveedor
provider.identification.type string · nulo	Tipo de documento de identidad, por ejemplo ruc
provider.identification.value string · nulo	Número de documento de identidad
provider.phone string · nulo	Teléfono del proveedor, sin código de país
provider.email string · nulo	Correo electrónico del proveedor

Dirección del proveedor (provider.address)

Campo	Descripción
provider.address objeto	Dirección del proveedor. Sus campos vienen nulos si el proveedor no tiene dirección
provider.address.street string · nulo	Calle y número
provider.address.locality string · nulo	Localidad
provider.address.zip_code string · nulo	Código postal
provider.address.ubigeo string · nulo	Código de ubigeo
provider.address.latitude string · nulo	Latitud, como texto con 7 decimales
provider.address.longitude string · nulo	Longitud, como texto con 7 decimales
provider.address.elevation string · nulo	Elevación, como texto con 7 decimales
provider.address.instructions string · nulo	Indicaciones para llegar
provider.address.type string · nulo	Tipo interno del propietario de la dirección. No lo necesita para su integración

Ítems (purchase_document_items[])

Campo	Descripción
purchase_document_items lista	Ítems del documento
purchase_document_items[].id string (UUID)	Identificador de la línea del documento. No es el identificador del ítem: para reconocer el ítem use sku
purchase_document_items[].sku string	Código del ítem
purchase_document_items[].name string	Nombre del ítem
purchase_document_items[].quantity número	Cantidad
purchase_document_items[].unit_cost número	Costo unitario