> ## Documentation Index > Fetch the complete documentation index at: https://docs.hg.cash/llms.txt > Use this file to discover all available pages before exploring further. # Criar reclamação com comprovante anexado > Cria uma reclamação com a evidência do comprovante de transferência anexada como PDF ou JPEG codificado em base64. Todos os campos de metadados devem ser enviados explicitamente; a API não analisa nem extrai dados do arquivo. Chamadas ADMIN devem incluir `accountId`. Chamadas USER podem omitir `accountId` ou associar a reclamação apenas à própria conta. Requer que o recurso Reclamações (`canAccessClaims`) esteja habilitado para quem chama. ## OpenAPI ````yaml /api-reference/openapi.pt-BR.yaml post /claims openapi: 3.1.0 info: title: HG.Cash API description: > # 🚀 API de transações HG.Cash API REST moderna para usuários criarem transações de saída a partir de suas contas. ## 🧾 Como funciona - A HG.Cash atribui contas ao seu usuário - Quando essas contas têm movimentação (entrada ou saída), a HG.Cash notifica o seu backend usando a URL de webhook configurada no painel - **Assinatura de webhooks (HMAC)**: Nas configurações da conta é possível gerar um segredo de assinatura. Quando configurado, cada POST de webhook inclui o cabeçalho `X-HG-Webhook-Signature: sha256=` com HMAC-SHA256 do corpo JSON usando o seu segredo. Verifique no seu endpoint para garantir autenticidade. - Para criar saques é necessário chamar o endpoint **Cash Out**: **Criar solicitação de transação** (`POST /transactions`) ## 📊 Primeiros passos 1. **Gere seu token de API** na página de configurações da conta 2. **Teste os endpoints** com a documentação interativa 3. **Implemente** nos seus serviços de backend (nunca exponha tokens no frontend) 4. **Monitore** a integração e trate erros adequadamente ## 🔐 Autenticação Esta API usa autenticação **Bearer Token**. Inclua o token de API do usuário no cabeçalho Authorization, por exemplo `Authorization: Bearer cash_your_token_here`. ## ⚠️ Segurança - Não compartilhe nem exponha o token de autenticação da API - Armazene tokens apenas em servidores backend seguros - Todas as chamadas devem ser feitas a partir de backends seguros - Se o token for comprometido, entre em contato com os administradores imediatamente version: 1.0.0 contact: name: HG.Cash API Support email: api-support@hg.cash license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://hg.cash/api/v1 description: Servidor de produção - url: http://dev.hg.cash/api/v1 description: Servidor de desenvolvimento security: - bearerAuth: [] tags: - name: Transações description: >- Gestão de transações — Criar e gerenciar transações no sistema HG.Cash. Todos os endpoints de transação exigem autenticação. - name: Contas description: >- Contas — Obter informações de conta e saldos do usuário autenticado. Todos os endpoints de conta exigem autenticação. - name: Dados de referência description: >- Dados de referência — Obter dados de referência como status e tipos de transação. Esses endpoints exigem autenticação. - name: Webhooks description: Webhooks — Notificações de eventos enviadas ao seu endpoint HTTP. - name: Brasil description: Brasil — Criar e consultar transações PIX (BRL). - name: Chile description: Chile — Checkout hospedado e payouts bancários (CLP). - name: Bolívia description: Bolívia — Cash-in com QR e payouts ACH (BOB). - name: Checkouts description: Sessões de checkout hospedado para AR, BR, CL e BO - name: Claims description: Reclamações com evidência de comprovante de transferência paths: /claims: post: tags: - Claims summary: Criar reclamação com comprovante anexado description: > Cria uma reclamação com a evidência do comprovante de transferência anexada como PDF ou JPEG codificado em base64. Todos os campos de metadados devem ser enviados explicitamente; a API não analisa nem extrai dados do arquivo. Chamadas ADMIN devem incluir `accountId`. Chamadas USER podem omitir `accountId` ou associar a reclamação apenas à própria conta. Requer que o recurso Reclamações (`canAccessClaims`) esteja habilitado para quem chama. operationId: createClaim requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateClaimRequest' example: accountId: 550e8400-e29b-41d4-a716-446655440123 from: Juan Pérez to: Mi cuenta HG operationNumber: '987654321' coelsaCode: 67REZ8NPQDQ460QK94KVGO amount: 1500 currency: ARS file: contentBase64: mimeType: application/pdf filename: comprobante.pdf responses: '201': description: Criado content: application/json: schema: $ref: '#/components/schemas/CreateClaimResponse' '400': description: >- Erro de validação (campos inválidos, base64, tipo MIME ou arquivo muito grande) '401': description: Não autorizado '403': description: >- Proibido — recurso de reclamações desabilitado ou conta fora do escopo '404': description: Conta não encontrada '429': description: Limite de requisições excedido '500': description: Erro interno do servidor components: schemas: CreateClaimRequest: type: object description: > Dados para criar uma reclamação com o comprovante de transferência anexado. Todos os metadados são enviados explicitamente; a API não analisa nem extrai dados do arquivo. required: - from - to - operationNumber - coelsaCode - amount - currency - file properties: accountId: type: string format: uuid description: >- Obrigatório para chamadas ADMIN; opcional para USER (associa a reclamação apenas à sua própria conta). example: 550e8400-e29b-41d4-a716-446655440123 from: type: string description: Conta de origem ou nome do pagador conforme o comprovante. example: Juan Pérez to: type: string description: Nome da conta de destino conforme o comprovante. example: Mi cuenta HG operationNumber: type: string description: Número da operação bancária do comprovante. example: '987654321' coelsaCode: type: string pattern: ^[A-Z0-9]{22}$ description: >- Código de identificação COELSA (exatamente 22 caracteres alfanuméricos maiúsculos). example: 67REZ8NPQDQ460QK94KVGO amount: oneOf: - type: number - type: string description: Valor positivo com no máximo 2 casas decimais. example: 1500 currency: type: string enum: - ARS - USD - USDT example: ARS file: type: object required: - contentBase64 - mimeType - filename properties: contentBase64: type: string description: >- Bytes de PDF ou JPEG codificados em base64 (máx. 10 MB decodificado). Um prefixo `data:` é removido automaticamente. example: mimeType: type: string enum: - application/pdf - image/jpeg - image/jpg example: application/pdf filename: type: string description: >- Nome do arquivo original; a extensão deve corresponder ao `mimeType`. example: comprobante.pdf CreateClaimResponse: type: object required: - id - status - operationNumber - coelsaCode - amount - currency - extractedData - originalFilename - mimeType - createdAt properties: id: type: string format: uuid status: type: string enum: - OPEN - UNDER_REVIEW - RESOLVED - REJECTED accountId: type: string format: uuid nullable: true operationNumber: type: string coelsaCode: type: string amount: type: string description: Valor decimal com 2 casas decimais. example: '1500.00' currency: type: string enum: - ARS - USD - USDT extractedData: type: object properties: from: type: string nullable: true to: type: string nullable: true originalFilename: type: string mimeType: type: string createdAt: type: string format: date-time securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Token de autenticação da API do usuário com o formato `cash_<64-char-hex>`. Valor de exemplo `cash_16cdc3b6f83c72d9d2680adca4f430962981f6bf32613a129dded0aa060387d2`. ````