Migrando de 3.1 a 4.0 Simple

Información importante para actualizar desde 3.1 a 4.0s de la API.

Por favor asegúrate de haber migrado primero a 3.1 antes de migrar a 4.0s 3.1 Guía de migración

4.0 Simple (4.0s) es una presentación de la misma API /api/v4/ documentada en 4.0, escrita para integraciones que abordan registros por sus propios identificadores. No es una versión separada de la API: no hay una URL /api/v4s/, y una solicitud construida a partir de estas páginas es una solicitud ordinaria 4.0. Lo que difiere es la presentación: estas páginas identifican registros por externalId y mantienen la estructura de cliente plana, lo que hace que la transición de 3.1 sea de menor alcance que la completa 4.0. externalId es un identificador aceptado y no uno obligatorio, y 4.0 también lo acepta: todos los endpoints de 4.0 reciben _id o externalId.

Cambios Incompatibles

POST
{base_url}/api/v4/
  • Actualizar solicitudes a .../api/v4/... En lugar de .../api/v3.1/... .
Valores monetarios
  • El dinero ahora se envía y se devuelve como un número entero de centavos. En 3.1 los mismos campos tomaban dólares decimales, por lo que 45.99 en 3.1 se convierte en 4599 en 4.0s.
  • Esto se aplica a los campos de dinero en general, incluidos los totales de órdenes de compra, los impuestos, los descuentos, los precios unitarios y totales de las líneas, los montos de pago, las asignaciones, los precios unitarios de ítems y cualquier otro monto que envíes o recibas, no solo a un único campo.
  • Este es un cambio silencioso: el mismo payload es aceptado en ambas versiones sin error, y significa una cantidad cien veces diferente. Es fácil equivocarse en ambas direcciones.
  • Enviar valores de 3.1 sin cambios a 4.0s cobra cien veces de menos: un 45.99 que significaba $45.99 se lee como centavos y solo cobra alrededor de $0.46.
  • Leer una respuesta de 4.0s como dólares cobra cien veces de más: un 4599 devuelto son $45.99 en centavos, pero leído como dólares se convierte en $4599.00.
  • Afectando
    • POST
      {base_url}/api/v4/site/{site_id}/invoice/addUpdate
    • POST
      {base_url}/api/v4/site/{site_id}/item/addUpdate
POST
{base_url}/api/v4/site/{site_id}/customer/addUpdate
  • El notification_options El campo se eliminó del Cliente, la Orden de compra y la Suscripción. Una escritura de cliente o suscripción que aún lo envíe se rechaza con un 400. En una escritura de orden de compra está obsoleto: todavía se aplica como los destinatarios send.to de la orden de compra y la respuesta incluye una advertencia, pero se rechazará en una versión futura. Elige los destinatarios de una orden de compra o suscripción con send.to en su lugar.
Productos → Artículos
  • El punto final de Productos ha sido renombrado a Artículos. Actualiza las solicitudes a site/{site_id}/item/addUpdate En lugar de site/{site_id}/product/addUpdate .
  • Afectando
    • POST
      {base_url}/api/v4/site/{site_id}/item/addUpdate
Archivos Adjuntos
  • El attachments El campo (una lista simple de URL) ha sido reemplazado por el attachmentRefs Objeto, que organiza adjuntos en internal , external , y sourceDocument sub-campos.
  • Afectando
    • POST
      {base_url}/api/v4/site/{site_id}/invoice/addUpdate
    • POST
      {base_url}/api/v4/site/{site_id}/customer/addUpdate
    • POST
      {base_url}/api/v4/site/{site_id}/subscription/addUpdate