Introdução

O que você vai conseguir

Reclamações permitem informar comprovantes de transferências bancárias na Argentina quando um pagamento de entrada não aparece na sua lista de transações HG.cash — ou quando você precisa que a HG.cash revise a evidência e associe à conta correta. No painel HG.cash (Reclamações na barra lateral), você pode:

Criar uma reclamação enviando até 5 imagens ou PDFs por envio
Revisar campos extraídos (código COELSA, número da operação, valor, origem/destino) antes de confirmar
Acompanhar status e histórico de comentários de cada reclamação
Receber e-mail quando uma reclamação for associada automaticamente a uma transação pelo código COELSA

A equipe HG.cash pode revisar, alterar status, adicionar comentários internos e (para admins com escopo) filtrar por usuário ou conta. Além do painel, você também pode criar e consultar reclamações de forma programática pela API REST — veja Criar e consultar reclamações via API.

Visão geral

Etapa	Quem	O que acontece
Prepare	Usuário merchant ou admin	Arquivos vão para armazenamento temporário; a HG.cash extrai dados estruturados do comprovante argentino (COELSA, operação, valor, de/para).
Confirm	Mesmo	Você confirma ou edita campos, opcionalmente vincula uma conta, e a reclamação fica salva com evidência no bucket `claims`.
Match automático	Sistema (produção)	A cada ~20 minutos, reclamações OPEN ou UNDER_REVIEW das últimas 48 horas com COELSA válido são pareadas com a última transação com o mesmo código.
Revisão manual	Admin HG.cash	Atualização de status e comentários quando o match automático não se aplica ou exige julgamento humano.

Reclamações focam em comprovantes de transferência ARS na Argentina. O código COELSA (22 caracteres alfanuméricos quando presente) é a chave principal para conciliação automática.

Status da reclamação

Status	Significado
`OPEN`	Enviada; aguardando match automático ou ação do admin.
`UNDER_REVIEW`	Em revisão ativa pela HG.cash.
`RESOLVED`	Encerrada com sucesso — muitas vezes após encontrar a transação por COELSA ou resolução manual.
`REJECTED`	Não aceita (evidência inválida, duplicata ou outro motivo nos comentários).

Mudanças de status e comentários ficam registrados com data/hora. Admins podem comentar sem alterar o status.

O que fica armazenado em cada reclamação

Cada registro pode incluir:

Arquivo de evidência — imagem ou PDF em armazenamento seguro (visualização via URLs assinadas de curta duração no painel)
Código COELSA e número da operação — lidos do comprovante ou informados por você
Valor e moeda (padrão ARS quando extraído)
Dados extraídos — indícios estruturados de origem/destino (from, to)
Conta vinculada — conta opcional na criação (admins precisam de escopo sobre essa conta)
Vínculo à transação — quando um crédito correspondente é encontrado

Papéis e acesso

Papel	Capacidades típicas
USER	Criar reclamações (prepare → confirm), listar as próprias, ver arquivos e comentários próprios.
ADMIN	Listar reclamações das contas permitidas, filtrar por usuário/conta/status, atualizar status, comentar, exportar (com CAN_EXPORT habilitado).
Admin com escopo	Igual ao admin, limitado às contas permitidas (conta da reclamação ou da transação).

A seção Reclamações precisa estar habilitada (canAccessClaims). Se não vir Reclamações na barra lateral, contate o suporte HG.cash.

Criar e consultar reclamações via API

Você pode criar e ler reclamações de forma programática com o mesmo token Bearer usado no restante da API. O recurso Reclamações (canAccessClaims) precisa estar habilitado para quem chama. Diferente do painel, a API não analisa nem extrai dados do comprovante. Você precisa enviar cada campo de metadados explicitamente e anexar um único arquivo em base64.

Endpoint	Descrição
`POST /claims`	Cria uma reclamação com a evidência do comprovante. Envie `from`, `to`, `operationNumber`, `coelsaCode`, `amount`, `currency` e um `file` (base64 `contentBase64`, `mimeType`, `filename`).
`GET /claims/{id}`	Obtém uma reclamação por ID, incluindo uma `fileUrl` assinada de duração limitada para baixar o comprovante.

Regras principais do endpoint de criação:

Os metadados são explícitos — from, to, operationNumber, coelsaCode, amount e currency são todos obrigatórios. Não há etapa de OCR nem de LLM.
O código COELSA deve ter exatamente 22 caracteres alfanuméricos maiúsculos.
O arquivo é um único anexo: application/pdf, image/jpeg ou image/jpg codificado em base64, de até 10 MB decodificado, com uma extensão de filename que corresponda ao seu mimeType.
Escopo de conta — chamadas ADMIN devem incluir accountId; chamadas USER podem omiti-lo ou associar a reclamação apenas à própria conta.

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 ou imagem em base64>",
      "mimeType": "application/pdf",
      "filename": "comprobante.pdf"
    }
  }'

Para os esquemas completos de requisição e resposta, veja o grupo Claims na Referência da API.

Notificações de webhook

Quando o status de uma reclamação muda —por uma atualização de um administrador ou pela autoconciliação da COELSA— a HG.cash envia um webhook (POST) para a URL de webhook padrão do seu usuário com topic CLAIM e eventType status_change. O corpo corresponde aos campos de GET /claims/{id} (sem fileUrl) mais os metadados de roteamento, e um campo comment opcional inclui o texto do último comentário quando a atualização o incluiu. Webhooks não são enviados na criação de uma reclamação (a resposta de criação já contém a reclamação) nem em atualizações que apenas adicionam um comentário. Configure a URL do seu webhook padrão e o segredo de assinatura em Configurações. Veja Status da reclamação atualizado para o payload completo e Receber webhooks para entrega, retentativas e verificação de assinatura.

Conciliação automática

Em produção, um job agendado roda aproximadamente a cada 20 minutos:

Seleciona reclamações em OPEN ou UNDER_REVIEW das últimas 48 horas com COELSA preenchido.
Encontra a última Transaction não excluída com o mesmo COELSA (sem diferenciar maiúsculas/minúsculas).
Define RESOLVED, adiciona comentário de sistema com o ID da transação, envia e-mail de reclamação conciliada quando houver e-mail do usuário e emite um webhook CLAIM / status_change quando a URL do seu webhook padrão estiver configurada.

Se a transação ainda não existir, mantenha a reclamação em OPEN — o match pode concluir quando o movimento for ingerido. Para reclamações mais antigas ou sem COELSA no comprovante, use revisão manual.

Quando usar uma reclamação

Use Reclamações quando:

Um pagador enviou transferência ARS para sua conta HG.cash e o crédito não aparece
Você tem comprovante (captura ou PDF) com COELSA ou operação
Precisa que a HG.cash rastreie ou associe o pagamento a uma conta específica

Reclamações não substituem Checkouts (páginas de pagamento hospedadas) nem a API REST para recebimentos programáticos. Para PIX no Brasil ou PayRetailers no Chile, veja Países e Checkouts.

Antes de começar

Acesso a Reclamações no painel
Arquivos em imagem ou PDF (máximo 5 por envio)
Código COELSA no comprovante quando possível — acelera muito a resolução automática
Para admins: clareza sobre a conta destino ao vincular na criação

Para cobrança com páginas hospedadas e webhooks, veja Checkouts. Para meios de entrada por país, veja Países.

Liquidação

Checkouts

Reclamações

Desenvolvedores

O que você vai conseguir

Visão geral

Status da reclamação

O que fica armazenado em cada reclamação

Papéis e acesso

Criar e consultar reclamações via API

Notificações de webhook

Conciliação automática

Quando usar uma reclamação

Antes de começar

​O que você vai conseguir

​Visão geral

​Status da reclamação

​O que fica armazenado em cada reclamação

​Papéis e acesso

​Criar e consultar reclamações via API

​Notificações de webhook

​Conciliação automática

​Quando usar uma reclamação

​Antes de começar

O que você vai conseguir

Visão geral

Status da reclamação

O que fica armazenado em cada reclamação

Papéis e acesso

Criar e consultar reclamações via API

Notificações de webhook

Conciliação automática

Quando usar uma reclamação

Antes de começar