Add/Update Orden de compra

Usa esto cuando an orden de compra esté lista en tu sistema y quieras que el cliente la reciba y la pague, o cuando cambie.


The following endpoint can be used to add or update a orden de compra within the Hyfin application. When a orden de compra is added to Hyfin, a payment request will be automatically generated and the customer will be notified via text message, email or both, as described under Who gets notified below.

If you choose to omit the customer info, a payment link will be provided in the API response. The payment link can be used on a self-checkout system or kiosk.

If the customer is viewing the orden de compra on their device and the orden de compra is updated, a message will display letting the customer know the orden de compra has been updated and the new version of the orden de compra will automatically be displayed on the customers device.

Quién recibe notificaciones

Cada cliente está bajo un solo control de notificaciones, determinado a partir del sitio y del cliente. Nunca se almacena y no se puede establecer directamente.

  • Control por contacto : cada dirección de correo electrónico y número de teléfono de los contactos del cliente tiene su propia doNotContact marca, y esa marca es lo único que detiene los mensajes automáticos hacia ella. Este es el control para los clientes creados en la app, para todos los clientes de un sitio de QuickBooks que no asigna métodos de pago a notificaciones, y para las integraciones en la API v4.
  • Control por cliente : las notificationOptions del cliente (una opción para cada uno: correo electrónico, mensaje de texto y WhatsApp) deciden para cada dirección de cada contacto. Si falta una opción, se notifica. Este es el control para todos los clientes de un sitio de QuickBooks que asigna métodos de pago a notificaciones, y para los clientes cuya integración definió esas opciones en una versión anterior a la 4.0.

En la API v4:

  • Una escritura de cliente o suscripción que incluya notificationOptions se rechaza con un error 400 y el mensaje "notification_options is not accepted on API v4. Set do_not_contact on the contact emails and phone_numbers instead."
  • En una escritura de Orden de compra, notificationOptions está obsoleta y se rechazará en una versión futura. Todavía se aplica, exactamente como en la 3.1: se convierte en los destinatarios de la Orden de compra send.to , y la respuesta es exitosa con una entrada de warnings . Si se envía junto con send.to se rechaza con un error 400. Cambie a send.to ahora.
  • Una escritura de cliente en un sitio que no está conectado a QuickBooks pasa a ese cliente al control por contacto. Sus opciones de notificación se copian en doNotContact en cada dirección una sola vez, luego se eliminan, y los doNotContact valores de la solicitud se aplican después de eso.
  • En un sitio de QuickBooks con mapPaymentMethodsToNotifications activado, los métodos de pago de QuickBooks deciden las notificaciones de todos los clientes, por lo que una escritura de cliente que incluya doNotContact se rechaza con un error 400 que nombra esa configuración. Omita la marca, o pida al comerciante que desactive la configuración.
  • onHold: false en una escritura de Orden de compra no libera una Orden de compra retenida porque no llega a nadie. Agregue un destinatario para que se pueda enviar.
  • La lectura del cliente nunca devuelve notificationOptions .

Punto Final

The following endpoint can be used to add or update a orden de compra. You must replace the {base_url} and {site_id} variable with the site id that was provided when the site was created.

POST
{base_url}/api/v4/site/{site_id}/invoice/addUpdate

Solicitud
Campo
Tipo
Descripción
externalId
String
Tu propio id para esta orden de compra, desde tu software. Envía de nuevo el mismo externalId para actualizar esta orden de compra en lugar de agregar una nueva. Usamos este valor para hacer la coincidencia, pero no evitamos duplicados, así que manténgalo único dentro del sitio.
invoiceNumber
String
El número asignado desde el sistema de origen y que se muestra al cliente en la orden de compra. Dos orden de compra de un sitio pueden compartir un número, y un pago aplicado por número se asigna a la primera coincidencia encontrada, así que manténgalo único dentro del sitio.
totals
Los montos totales de orden de compra. Cuando se proporcionan lines, total se valida contra ellas y debe ser igual a la suma de cada lines[].total, más taxes, menos discounts. Una solicitud cuyos totales no concuerden es rechazada. Si omite lines, no se realiza esta verificación.
customer
Una referencia al registro del cliente.
invoiceTermName
String
El nombre de un plazo de orden de compra configurado para el sitio, como Net 30. Cuando se envía, la fecha de vencimiento se calcula a partir del plazo y la fecha de la orden de compra, y reemplaza cualquier dueDate que envíe. Un nombre que no coincide con ningún plazo se rechaza con Invoice term "" not found. Cuando se omite en una orden de compra nueva, se usa el plazo de orden de compra del cliente si lo tiene.
lines
Una lista de elementos de línea en la orden de compra. Requerido si no se pasa la description.
description
String
Una breve descripción de los productos/servicios en la orden de compra. Requerido si no se pasan las lines.
invoiceDate
La fecha de la orden de compra. Si se establece en el futuro, la orden de compra no se envía por mensaje de texto ni por correo electrónico al cliente hasta esa fecha. Si se deja en blanco, se usa la fecha de hoy. Una fecha sin hora. Si se envía una hora o zona horaria con ella, se descarta, no se convierte, por lo que la fecha permanece tal como se escribió. Format = YYYY-MM-DD
customerMemo
String
Una nota presentada al cliente en la parte inferior de la orden de compra.
internalMemo
String
Un memo agregado en la parte inferior de la orden de compra. Solo visible para el personal interno, nunca se muestra a los clientes.
payments
Una lista de pagos realizados en la orden de compra.
webhookUrl
String
La URL a la que se envía una publicación cuando se realizan ciertas acciones en orden de compra. Se envía un webhook cuando un pago alcanza un nuevo estado, y cuando un mensaje de texto, correo electrónico o mensaje de WhatsApp se envía, se entrega, se lee, se retrasa o falla, o cuando el cliente hace clic en el enlace de pago.
options
Opciones para configurar en la orden de compra.
attachmentRefs
Una lista de adjuntos.
send
A quién se envía orden de compra, por canal. Un canal que incluyas se usa tal como lo indiques, y una lista vacía ([]) desactiva ese canal. Un canal que omitas conserva los destinatarios que orden de compra ya tiene, o se llena con los contactos del cliente, según el control de notificaciones del cliente, cuando aún no tiene ninguno. En una creación, omite send para que los contactos del cliente decidan cada canal cuando se envíe orden de compra. En una actualización, omitirlo conserva los destinatarios ya elegidos. Una lectura devuelve send.to como null hasta que se hayan elegido destinatarios. billTo.emails y billTo.sms siguen siendo la anulación de quién recibe esos canales, pero nunca reactivan un canal que send desactivó.
onHold
Boolean
Indica si la primera cuota no pagada está retenida, de modo que su solicitud de pago no se envía hasta que se libere la retención. En una lectura es true cuando esa cuota está retenida y false en caso contrario. En una escritura, establécelo en true para retener esa cuota, o en false en una actualización para liberarla. Omítelo para dejar la retención como está. La retención pertenece a la cuota, no a orden de compra.
false libera una retención que tú o el comercio colocaron. No libera la retención que recibe orden de compra cuando no llega a nadie y no se cobrará automáticamente: send.to desactiva todos los canales, o todas las direcciones del cliente son de no contactar y no hay una anulación billTo. Esa orden de compra permanece retenida y la escritura aun así se realiza correctamente, también cuando tú mismo proporcionas installments o estableces installments[].onHold en false. Asígnale un destinatario para que se envíe.
Una escritura que envíe tanto onHold como installments[].onHold en la primera cuota no pagada debe darles el mismo valor. De lo contrario se rechaza con un 400 y el mensaje "Invalid on_hold, it conflicts with on_hold on the first unpaid installment. Send one of them, or the same value in both". Un valor que no sea booleano se rechaza con "Invalid on_hold, must be a boolean".
deleted
Boolean
Esta bandera representa si el registro ha sido eliminado y ya no está disponible para ser utilizado.
			
{
  "externalId": "439772921",
  "invoiceNumber": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 4599
  },
  "customer": {
    "externalId": "39772634",
    "firstName": "John",
    "lastName": "Doe",
    "mobilePhone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "options": {
    "tippingEnabled": false
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}


		
Respuesta
Campo
Tipo
Descripción
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if success is true.
One of added, updated
_id
String
The id we assign to the record.
updatedAt
The date the record was last updated. Un momento en el tiempo en formato ISO 8601, con zona horaria. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
link
String
La página de pago para el cliente de la orden de compra. Se devuelve en cada alta o actualización exitosa, para que usted mismo pueda enviársela al cliente.
missingCustomer
Boolean
Indica si orden de compra hace referencia a un cliente que aún no se ha sincronizado, por lo que el cliente se asociará cuando llegue.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https://site.url/KA39T1A45JL",
  "missingCustomer": false
}


		

Ver también