Transferencias y movimientos

Operaciones de movimiento de fondos y consulta de movimientos. Casi todas son asíncronas: responden con el envelope de operación y el resultado final llega por WebSocket.

Concepto de transferencia (concept)

Enum requerido en POST /api/v1/transfer, /api/v1/transfer-pull, /api/v1/debit-order y /api/v1/chargeback-order:

ALQ, APC, BRH, BRN, CUO, EXP, FAC, HAB, HON, OIN, OIH, PRE,
ROP, SEG, SIS, SON, VAR, PCT, CCT, DCT, ECT

Descripción de cada código: catálogo de conceptos.

---

POST /api/v1/transfer — Transferencia

Body:

Campo	Tipo	Requerido	Notas
from	AccountIdentifier	sí	cuenta origen
to	AccountIdentifier	sí	cuenta destino
amount	string	sí	decimal positivo, ej. "2500.00"
concept	enum	sí	ver arriba
description	string	sí

Ejemplo:

{
  "from": "0000003100010000000001",
  "to": "acme.caja01",
  "amount": "2500.00",
  "concept": "VAR",
  "description": "Pago factura 001"
}

Respuesta: { "operationId": "7d...", "status": "pending", "message": "Transfer accepted" } (owner y ttl opcionales). Devuelve un error si se reusa la clave de idempotencia (ver Errores).

---

POST /api/v1/transfer-pull — Pull (débito solicitado)

Solicita un débito desde una cuenta deudora hacia una cuenta recaudadora.

Body: mismos campos que POST /api/v1/transfer (from = recaudador, to = deudor).

Respuesta: envelope de operación. Devuelve un error si se reusa la clave de idempotencia (ver Errores).

---

POST /api/v1/debit-order — Orden de débito

Body: mismos campos que POST /api/v1/transfer.

Respuesta: envelope de operación. Devuelve un error si se reusa la clave de idempotencia (ver Errores).

---

POST /api/v1/chargeback-order — Contracargo

Body:

Campo	Tipo	Requerido	Notas
from	AccountIdentifier	sí	comprador (se debita)
to	AccountIdentifier	sí	vendedor (recibió los fondos)
amount	string	sí	decimal positivo
concept	enum	sí	ver arriba
description	string	sí
reason	string	no	máx. 22 (Coelsa)
original_operation_id	string	sí	máx. 22
original_operation_type	string	sí	máx. 13, ej. "Transferencia"

Ejemplo:

{
  "from": "comprador.alias",
  "to": "0000003100010000000001",
  "amount": "500.00",
  "concept": "VAR",
  "description": "Contracargo compra",
  "reason": "producto no recibido",
  "original_operation_id": "abc123hash",
  "original_operation_type": "Transferencia"
}

Respuesta: envelope de operación. Devuelve un error si se reusa la clave de idempotencia (ver Errores).

---

POST /api/v1/transfer-reverse — Reversar transferencia

Reversa una transferencia previa.

Body:

Campo	Tipo	Requerido	Notas
operation_id	string (uuid)	sí	la transferencia original a reversar

Ejemplo: { "operation_id": "7d3f2a1c-..." }

Respuesta: envelope de operación.

---

GET /api/v1/movement/:operation_id? — Consultar movimientos

Con operation_id: devuelve el detalle de una operación.

Sin operation_id: modo listado. Query params:

Param	Tipo	Default	Notas
identifier	AccountIdentifier	—	filtra por cuenta
page	number	1
limit	number	10	máx. 100. 0 = todos
date_from	string (ISO 8601)	—
date_to	string (ISO 8601)	—

Detalle de una operación:

{
  "operation_id": "7d3f2a1c-...",
  "account_id": "3f9a1c2e-...",
  "operation_status": "fulfilled",
  "kind": "transfer",
  "created": "2026-07-24T12:00:00.000Z",
  "updated": "2026-07-24T12:00:03.000Z",
  "data": { },
  "external_ref_id": "COELSA-OP-123"
}

En modo listado la respuesta es { "data": [ /* detalles */ ], "pagination": { ... } }.

---

Catálogo de conceptos

Valores válidos del campo concept y su significado:

Código	Descripción
ALQ	Alquiler
APC	Aportes a capital
BRH	Bienes y retiros humanitarios
BRN	Bienes y retiros no humanitarios
CUO	Cuotas
EXP	Exportación
FAC	Facturación
HAB	Haberes
HON	Honorarios
OIN	Otros ingresos
OIH	Otros ingresos humanitarios
PRE	Prestaciones
ROP	Reparación de obras
SEG	Seguros
SIS	Sistema
SON	Servicios conexos
VAR	Varios
PCT	Pago con tarjeta
CCT	Cobro con transferencia
DCT	Débito con tarjeta
ECT	Extracción con tarjeta