NeavisiónDocs
Contratos JSON
Documentación / Integración

Contrato del futuro pull

Especificación para una exportación de sólo lectura con carga inicial y cambios incrementales.

Disponibilidad

Ampliación prevista

Las rutas de esta página todavía no existen. El consumidor puede preparar sus modelos con la referencia actual; la autenticación, URL, límites y contrato finales deberán confirmarse antes de conectarse.

Base prevista: https://finanzas.neavision.com.ar/api/v1/integration. Permisos exclusivos de exportación y token propio para el sistema interno. Sin imágenes, bytes de archivos, rutas de Storage, tokens, usuarios ni idempotencia administrativa.

Carga inicial consistente

GET /snapshot?limit=200 abriría un corte consistente con snapshotId y cursor opacos. Las siguientes páginas usarían ese cursor para continuar el mismo corte. Al terminar, devolvería checkpoint para comenzar changes. El cursor incluiría identidad de consulta, recursos autorizados y expiración; no sería un offset persistido.

Exportar proveedores/clientes/productos, facturas con sus líneas/cuotas, pagos/cobros/créditos, órdenes, remitos, movimientos y compromisos/recurrencias si se habilitan. Las relaciones se conservan aunque lleguen en distintas páginas.

Cambios y anulaciones

GET /changes?cursor=<checkpoint>&limit=200 devolvería upsert y void, ordenados por una secuencia de cambios confirmados. El mecanismo debe detectar commits tardíos; no utilizar updatedAt ni MAX(audit_log.id) sin resolver la concurrencia.

La respuesta debería exponer schemaVersion, snapshotId/asOf, data, nextCursor y hasMore. El checkpoint sólo avanza después de guardar toda la página en el destino. Si expira, CURSOR_EXPIRED obliga a una nueva carga inicial.

JSON
{
  "schemaVersion": "1",
  "asOf": "2026-10-01T12:00:00Z",
  "data": [
    {
      "sequence": "12345",
      "operation": "upsert",
      "resource": "invoices",
      "id": "20000000-0000-4000-8000-000000000001",
      "version": 1,
      "record": {
        "id": "20000000-0000-4000-8000-000000000001",
        "version": 1,
        "createdAt": "2026-10-01T12:00:00Z",
        "updatedAt": "2026-10-01T12:00:00Z",
        "voidedAt": null,
        "supplierId": "10000000-0000-4000-8000-000000000001",
        "number": "00001-00000042",
        "invoiceType": "A",
        "issueDate": "2026-10-01",
        "dueDate": "2026-10-31",
        "amount": "100000.00",
        "currency": "ARS",
        "concept": "Compra de armazones",
        "category": "Mercadería",
        "reconciliationStatus": "confirmed",
        "receivingRequired": true,
        "lines": [
          {
            "id": "linea-1",
            "kind": "goods",
            "productId": "30000000-0000-4000-8000-000000000001",
            "description": "Armazón modelo ejemplo",
            "quantity": "10",
            "unit": "unidad",
            "supplierCode": "ARM-001"
          }
        ]
      }
    },
    {
      "sequence": "12346",
      "operation": "void",
      "resource": "payments",
      "id": "50000000-0000-4000-8000-000000000001",
      "version": 2,
      "voidedAt": "2026-10-01T12:05:00Z"
    }
  ],
  "nextCursor": "cursor-opaco",
  "hasMore": false
}

Saldos y stock derivados

Definir expresamente cómo se actualizan las proyecciones cuando cambia un registro relacionado. Opciones: exportar entidades fuente y recalcular en el destino con estas reglas, o enviar proyecciones y eventos de invalidación por factura/producto. No confiar sólo en invoices.version para refrescar su saldo.

El corte asOf debe ser el mismo para todas las páginas. Para stock conservar las entradas por remito y movimientos manuales sin duplicarlas. Un void de remito elimina su contribución; un cambio de cantidad o producto sustituye la contribución anterior.

Comportamiento del consumidor

  1. Guardar las entidades por (resource,id); conservar IDs de línea y cuota.
  2. Aplicar cada página en una transacción local. Ignorar versiones anteriores y deduplicar por sequence.
  3. Guardar nextCursor junto con la página aplicada; ante fallo, repetir el mismo cursor.
  4. Marcar las anulaciones y recalcular dependencias.
  5. Separar recepción de datos de emisión fiscal, pagos y movimientos locales propios.
  6. Conciliar conteos, saldos por moneda, cantidades y relaciones al terminar.

Condiciones de aceptación

Probar creación, cambios y anulaciones; anticipo aplicado después; factura recibida por partes; cambio de vínculo; varias monedas; paginación; timeout y reintento; cursor vencido; transacciones concurrentes y commits tardíos. Verificar que el token no escriba, que no acceda a recursos fuera de sus permisos y que no se exporten secretos ni originales.

Buscar documentación