Introducción

Lo que vas a lograr

Reclamos te permiten informar comprobantes de transferencias bancarias en Argentina cuando un pago entrante no aparece en tu listado de transacciones de HG.cash — o cuando necesitás que HG.cash revise la evidencia y la asocie a la cuenta correcta. En el panel de HG.cash (Reclamos en la barra lateral) podés:

Crear un reclamo subiendo hasta 5 imágenes o PDFs por envío
Revisar los campos extraídos (código COELSA, número de operación, monto, origen/destino) antes de confirmar
Seguir el estado y el historial de comentarios de cada reclamo
Recibir un email cuando un reclamo se vincula automáticamente a una transacción por código COELSA

El equipo de HG.cash puede revisar, cambiar el estado, agregar comentarios internos y (para administradores con alcance) filtrar por usuario o cuenta. Además del panel, también podés crear y consultar reclamos de forma programática mediante la API REST — ver Crear y consultar reclamos con la API.

Resumen

Paso	Quién	Qué ocurre
Prepare	Usuario comercio o admin	Los archivos se suben a almacenamiento temporal; HG.cash extrae datos estructurados del comprobante argentino (COELSA, operación, monto, desde/hacia).
Confirm	Mismo	Confirmás o editás campos, opcionalmente vinculás una cuenta, y el reclamo queda guardado con evidencia en el bucket `claims`.
Match automático	Sistema (producción)	Cada ~20 minutos, reclamos OPEN o UNDER_REVIEW de las últimas 48 horas con COELSA válido se emparejan con la última transacción con el mismo código.
Revisión manual	Admin HG.cash	Cambios de estado y comentarios cuando el match automático no aplica o requiere criterio humano.

Los reclamos están orientados a comprobantes de transferencia ARS en Argentina. El código COELSA (22 caracteres alfanuméricos cuando está presente) es la clave principal para la conciliación automática.

Estados del reclamo

Estado	Significado
`OPEN`	Enviado; esperando match automático o acción del admin.
`UNDER_REVIEW`	En revisión activa por HG.cash.
`RESOLVED`	Cerrado correctamente — a menudo tras encontrar la transacción por COELSA o resolución manual.
`REJECTED`	No aceptado (evidencia inválida, duplicado u otro motivo en comentarios).

Los cambios de estado y comentarios quedan registrados con marca de tiempo. Los admins pueden agregar comentarios sin cambiar el estado.

Datos guardados en cada reclamo

Cada registro puede incluir:

Archivo de evidencia — imagen o PDF en almacenamiento seguro (visible con URLs firmadas de duración limitada en el panel)
Código COELSA y número de operación — leídos del comprobante o ingresados por vos
Monto y moneda (por defecto ARS si se extrae)
Datos extraídos — pistas estructuradas de origen/destino (from, to)
Cuenta vinculada — cuenta opcional al crear (los admins deben tener alcance sobre esa cuenta)
Vínculo a transacción — cuando se encuentra un ingreso coincidente

Roles y acceso

Rol	Capacidades habituales
USER	Crear reclamos (prepare → confirm), listar los propios, ver archivos y comentarios propios.
ADMIN	Listar reclamos de cuentas permitidas, filtrar por usuario/cuenta/estado, actualizar estado, comentar, exportar (con CAN_EXPORT habilitado).
Admin con alcance	Igual que admin, limitado a cuentas permitidas (cuenta del reclamo o de la transacción).

La sección Reclamos debe estar habilitada (canAccessClaims). Si no ves Reclamos en la barra lateral, contactá a soporte de HG.cash.

Crear y consultar reclamos con la API

Podés crear y leer reclamos de forma programática con el mismo token Bearer que usás para el resto de la API. La función Reclamos (canAccessClaims) debe estar habilitada para quien llama. A diferencia del panel, la API no analiza ni extrae datos del comprobante. Tenés que enviar cada campo de metadatos de forma explícita y adjuntar un único archivo en base64.

Endpoint	Descripción
`POST /claims`	Crea un reclamo con la evidencia del comprobante. Enviá `from`, `to`, `operationNumber`, `coelsaCode`, `amount`, `currency` y un `file` (base64 `contentBase64`, `mimeType`, `filename`).
`GET /claims/{id}`	Obtiene un reclamo por ID, incluyendo una `fileUrl` firmada de duración limitada para descargar el comprobante.

Reglas clave del endpoint de creación:

Los metadatos son explícitos — from, to, operationNumber, coelsaCode, amount y currency son todos obligatorios. No hay paso de OCR ni de LLM.
El código COELSA debe tener exactamente 22 caracteres alfanuméricos en mayúsculas.
El archivo es un único adjunto: application/pdf, image/jpeg o image/jpg codificado en base64, de hasta 10 MB decodificado, con una extensión de filename que coincida con su mimeType.
Alcance de cuenta — las llamadas ADMIN deben incluir accountId; las llamadas USER pueden omitirlo o asociar el reclamo solo a su propia cuenta.

curl -X POST https://hg.cash/api/v1/claims \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cash_your_token_here" \
  -d '{
    "from": "Juan Pérez",
    "to": "Mi cuenta HG",
    "operationNumber": "987654321",
    "coelsaCode": "67REZ8NPQDQ460QK94KVGO",
    "amount": 1500.00,
    "currency": "ARS",
    "file": {
      "contentBase64": "<bytes de PDF o imagen en base64>",
      "mimeType": "application/pdf",
      "filename": "comprobante.pdf"
    }
  }'

Para los esquemas completos de solicitud y respuesta, ver el grupo Claims en la Referencia API.

Notificaciones de webhook

Cuando cambia el estado de un reclamo —por una actualización de un administrador o por la autoconciliación de COELSA— HG.cash envía un webhook (POST) a la URL de webhook predeterminada de tu usuario con topic CLAIM y eventType status_change. El cuerpo coincide con los campos de GET /claims/{id} (sin fileUrl) más los metadatos de enrutamiento, y un campo comment opcional incluye el texto del último comentario cuando la actualización lo incluyó. Los webhooks no se envían al crear un reclamo (la respuesta de creación ya contiene el reclamo) ni en actualizaciones que solo agregan un comentario. Configurá tu URL de webhook predeterminada y el secreto de firma en Configuración. Ver Estado de reclamo actualizado para el payload completo y Recibir webhooks para entrega, reintentos y verificación de firma.

Conciliación automática

En producción, un job programado corre aproximadamente cada 20 minutos:

Toma reclamos en OPEN o UNDER_REVIEW de las últimas 48 horas con COELSA no vacío.
Busca la última Transaction no eliminada con el mismo COELSA (sin distinguir mayúsculas/minúsculas).
Pasa el reclamo a RESOLVED, agrega un comentario de sistema con el ID de transacción, envía email de reclamo conciliado si hay email de usuario y emite un webhook CLAIM / status_change cuando tu URL de webhook predeterminada está configurada.

Si la transacción aún no existe, dejá el reclamo en OPEN — el match puede completarse cuando se ingeste el movimiento. Para reclamos más viejos o sin COELSA en el comprobante, dependé de la revisión manual.

Cuándo usar un reclamo

Usá Reclamos cuando:

Un pagador envió una transferencia ARS a tu cuenta HG.cash y no ves el crédito
Tenés un comprobante (captura o PDF) con COELSA u operación
Necesitás que HG.cash rastree o asocie el pago a una cuenta concreta

Los reclamos no reemplazan las páginas de pago Checkouts ni la API REST para cobros programáticos. Para PIX en Brasil o PayRetailers en Chile, ver Países y Checkouts.

Antes de empezar

Acceso a Reclamos en el panel
Archivos en imagen o PDF (máximo 5 por envío)
Código COELSA en el comprobante cuando sea posible — acelera mucho la resolución automática
Para admins: claridad sobre la cuenta destino al vincular al crear

Para cobro con páginas hospedadas y webhooks, ver Checkouts. Para medios de ingreso por país, ver Países.

Liquidaciones

Checkouts

Reclamos

Desarrolladores

Lo que vas a lograr

Resumen

Estados del reclamo

Datos guardados en cada reclamo

Roles y acceso

Crear y consultar reclamos con la API

Notificaciones de webhook

Conciliación automática

Cuándo usar un reclamo

Antes de empezar

​Lo que vas a lograr

​Resumen

​Estados del reclamo

​Datos guardados en cada reclamo

​Roles y acceso

​Crear y consultar reclamos con la API

​Notificaciones de webhook

​Conciliación automática

​Cuándo usar un reclamo

​Antes de empezar

Lo que vas a lograr

Resumen

Estados del reclamo

Datos guardados en cada reclamo

Roles y acceso

Crear y consultar reclamos con la API

Notificaciones de webhook

Conciliación automática

Cuándo usar un reclamo

Antes de empezar