Conceptos clave

Algunas reglas aplican a todos los endpoints. Léelas una vez y las tablas de campos tendrán más sentido.


_id y externalId

_id es el id de Hyfin para el registro, y cada creación lo devuelve. Guárdalo y envíalo de nuevo cada vez que actualices ese registro.

externalId es tu propio id del registro, como tu número de orden de compra o de cliente. Hyfin lo devuelve cuando consultas el registro. Un envío sin _id con un externalId que ya usaste actualiza ese registro en lugar de crear uno nuevo.

Los webhooks de pago se refieren a las órdenes de compra solo por _id, así que una integración que omite guardarlo no puede asociar un pago con su orden de compra.

El dinero va en centavos

Cada monto en 4.0 es un número entero de centavos, tanto en las solicitudes como en las respuestas. Envía 4599 para $45.99. Los webhooks de pago también usan centavos en los sitios con webhook versión 4.0, la predeterminada para sitios nuevos.

Fechas y marcas de tiempo

Un campo Date es un día calendario sin hora, escrito YYYY-MM-DD, como 2026-10-23. Si se envía una hora o zona horaria con él, se descarta, no se convierte, por lo que la fecha permanece tal como se escribió. Las respuestas de Orden de compra devuelven invoiceDate y dueDate como marca de tiempo a la medianoche UTC de esa fecha, como 2026-10-23T00:00:00.000Z.

Un campo Timestamp es un momento en el tiempo en formato ISO 8601, con milisegundos y zona horaria: YYYY-MM-DDTHH:mm:ss.SSSZ, como 2026-10-23T15:04:05.123Z. Las respuestas devuelven las marcas de tiempo en UTC. El parámetro de consulta updated_after acepta solo este formato exacto.

Quién es dueño de cada registro

Tu software es dueño de los clientes, contactos, artículos, órdenes de compra y suscripciones. Envíalos a Hyfin cuando se creen o cambien. Hyfin es dueño de los pagos: los recibe y luego te avisa mediante el webhook de pago. Para registrar un pago recibido fuera de Hyfin, como un cheque, usa Add/Update Payment.

Estados de pago

El webhook de pago envía una llamada cada vez que un pago alcanza un nuevo status, por lo que un mismo pago puede llegar más de una vez, por ejemplo como captured y después como settled. Haz la coincidencia por el _id del pago y actualiza el pago que ya tienes en lugar de agregar uno nuevo.

Clientes y contactos

Un cliente es la cuenta a la que le emites órdenes de compra. Un contacto es una persona de ese cliente que recibe los mensajes de texto y los correos. Un cliente puede tener varios contactos: envíalos en primaryContact y contacts, o con Add/Update Contact.