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

externalId es tu propio id del registro, como tu número de orden de compra o de cliente. Si envías de nuevo el mismo externalId, Hyfin actualiza ese registro en lugar de crear uno nuevo.

_id es el id de Hyfin para el registro, y cada creación lo devuelve. Guárdalo: los webhooks de pago se refieren a las órdenes de compra por _id, y los endpoints Get de 4.0 buscan los registros con él.

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, 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.

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.