Integraciones

La API trabaja sobre los movimientos de caja de tu empresa: los comprobantes de gastos e ingresos que hoy cargás desde el panel o por WhatsApp. Todo lo que cargues por API aparece en el panel con el origen “integración externa” y el nombre de tu credencial.

La API key es la llave de tu empresa: identifica quién llama y qué puede hacer. Es una por integración (por ejemplo, una para tu ERP y otra para un proceso nocturno), así podés revocar una sin cortar las demás.

Cómo crearla

La creás vos, desde el panel de Sorby, en Administración → Integraciones. Solo la ven quienes tienen el permiso Gestionar integraciones.

1. Tocá Crear API key y ponele un nombre que diga para qué es (por ejemplo, “ERP contable”).
2. Elegí los permisos (ver tabla). Te recomendamos empezar por los mínimos, por ejemplo solo lectura, y ampliar cuando haga falta.
3. Elegí el vencimiento (por defecto, 90 días). Pasada esa fecha la key deja de funcionar y tenés que crear otra.
4. Copiala en el momento. Se muestra una sola vez: no la podemos volver a mostrar. Guardala en un gestor de secretos. Si la perdés, revocala y creá otra.

En la misma pantalla ves el último uso de cada key, cuándo vence y podés revocarla al instante. Una key vencida o revocada deja de funcionar de inmediato.

La key tiene la forma sk_<8 caracteres>_<48 caracteres>.

En cada pedido mandás la key en el encabezado Authorization. Para comprobar que anda, pedí /me:

curl https://api.sorbydata.com/api/v1/me \
  -H "Authorization: Bearer sk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{ "credencial_id": "…", "empresa_id": "…", "nombre": "ERP contable",
  "scopes": ["catalogos:leer", "movimientos:leer", "movimientos:escribir"] }

Tu empresa sale siempre de la key: nunca la mandás vos. Si la key falta, es inválida, fue revocada, está vencida, la respuesta es siempre el mismo 401, sin pistas de cuál de los casos fue.

Antes de registrar un movimiento necesitás los identificadores de tu empresa: el proyecto, el proveedor, la categoría. Todos son GET y piden el permiso catalogos:leer.

POST/movimientos · permiso movimientos:escribir

curl -X POST https://api.sorbydata.com/api/v1/movimientos \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: factura-0001-00012345" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "egreso",
    "total": 125000,
    "moneda": "ARS",
    "fecha_factura": "2026-10-15",
    "proyecto_id": "6650f0c2a1b2c3d4e5f60718",
    "proveedor_id": "6650f0c2a1b2c3d4e5f60999",
    "categoria": "Materiales",
    "medio_pago": "Transferencia",
    "numero_factura": "0001-00012345"
  }'

Campos

(*) type y total siempre. Los demás obligatorios dependen de tu empresa. Un campo que no está en la lista da 400.

La respuesta es 201 con el movimiento:

{ "id": "…", "codigo_operacion": "…", "type": "egreso", "moneda": "ARS", "total": 125000,
  "fecha_factura": "2026-10-15T00:00:00.000Z", "proyecto_id": "…", "proyecto_nombre": "Torre Norte",
  "proveedor_id": "…", "proveedor_nombre": "Corralón Sur", "categoria": "Materiales",
  "medio_pago": "Transferencia", "estado": null, "es_borrador": false,
  "origen": "integracion_externa", "creado_en": "2026-10-15T14:02:11.000Z", … }

La Idempotency-Key: obligatoria

Si tu pedido se corta por un timeout y lo repetís, no queremos duplicar el comprobante. Por eso cada alta lleva un encabezado Idempotency-Key (hasta 200 caracteres) que vos elegís y es único por comprobante; lo más simple es usar el id o el número del comprobante en tu sistema.

• Repetís el mismo pedido con la misma key: devolvemos el movimiento original con 200 y "repetido": true. No se crea otro.
• Usás la misma key con otro contenido: seguimos devolviendo el original. Cambió el comprobante, cambiá la key.
• Si la key corresponde a un movimiento que ya eliminaste, responde 409: usá una nueva.

POST/movimientos/extraer · permisos movimientos:escribir y extraccion:usar

Si tu sistema solo tiene el comprobante escaneado o una nota, mandalo y Sorby interpreta los datos con IA, usando los proyectos, proveedores y categorías de tu empresa. El resultado queda como borrador: una persona lo revisa y lo confirma en el panel. La API no confirma borradores.

Desde un texto

curl -X POST https://api.sorbydata.com/api/v1/movimientos/extraer \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: nota-889" \
  -H "Content-Type: application/json" \
  -d '{ "texto": "Pagué $5000 a Corralón Sur en efectivo por cemento", "proyecto_id": "6650f0c2a1b2c3d4e5f60718" }'

Desde una imagen o un PDF

# subiendo el archivo
curl -X POST https://api.sorbydata.com/api/v1/movimientos/extraer \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: scan-889" \
  -F "archivo=@factura.pdf"

# o indicando una dirección pública
curl -X POST … -H "Content-Type: application/json" \
  -d '{ "archivo_url": "https://tu-sistema.com/facturas/889.pdf" }'

El archivo puede pesar hasta 20 MB. archivo_url debe ser una dirección https pública; no aceptamos direcciones internas o privadas.

Opciones y respuesta

• proyecto_id (opcional): fuerza el proyecto en vez de que la IA lo deduzca.
• modo_guardado: "borrador" (por defecto, lo guarda) o "no_guardar" (solo te devuelve lo extraído, sin id).

{ "movimiento": { "id": "…", "es_borrador": true, "total": 5000, "proveedor_nombre": null, … },
  "advertencias": [ { "campo": "proveedor", "codigo": "proveedor_no_resuelto", "valor_extraido": "Corralón Sur" } ] }

Mandá también la Idempotency-Key: así un reintento no te cobra la IA dos veces. Esta ruta tiene su propio límite, más bajo (ver más abajo).

Los dos piden el permiso movimientos:leer.

GET/movimientos/:id devuelve el movimiento (404 si no existe o no es de tu empresa).

GET/movimientos lista los movimientos de tu empresa, todos, no solo los que cargó la integración. Filtros:

curl "https://api.sorbydata.com/api/v1/movimientos?desde=2026-10-01&hasta=2026-10-31&limite=50" \
  -H "Authorization: Bearer $KEY"

{ "datos": [ … ], "pagina": 1, "limite": 50, "total": 132 }

PUT/movimientos/:id modifica solo los campos que mandes (los mismos del alta, salvo type). DELETE/movimientos/:id lo elimina y responde 204. Los dos piden movimientos:escribir.

• Solo se pueden modificar o eliminar los movimientos cargados por una integración. Si fue cargado por una persona, la respuesta es 403.
• Un movimiento con pagos asociados o un ingreso ya facturado no se modifica ni se elimina por API (409): se resuelve desde el panel.
• Los borradores se pueden completar con PUT; confirmarlos se hace en el panel.

Todos los errores tienen la misma forma, así tu sistema los puede manejar en un solo lugar:

{ "error": { "code": "proyecto_no_encontrado",
             "message": "El proyecto no existe en tu empresa",
             "campo": "proyecto_id", "detalle": null } }

Límites

• Hasta 120 pedidos por minuto por key, y 20 por minuto en la extracción con IA.
• Ante un 429 o un error 5xx, reintentá esperando cada vez más (por ejemplo 1 s, 2 s, 4 s). Con la Idempotency-Key reintentar es seguro.