POST /apiv2/reports/statement

Solicite um arquivo de extrato — todas as operações de um token ao longo de um período, em CSV ou PDF. O arquivo é gerado em segundo plano: a requisição retorna um número de pedido imediatamente, e o arquivo é baixado assim que estiver pronto.

Para uma consulta rápida dos mesmos dados sem esperar, use a pré-visualização do extrato — ela responde instantaneamente, mas limita o número de operações retornadas.

URL base do endpoint

https://netts.io/apiv2/reports

Cabeçalhos da requisição

Cabeçalho	Obrigatório	Descrição
X-API-KEY	sim	Chave de API do painel
X-Real-IP	sim	Um endereço da lista de permissões da chave
X-Idempotency-Key	não	Sua própria chave, de 12 a 128 caracteres de A-Z a-z 0-9 . _ : -

Fazer o pedido de um arquivo

curl -s -X POST 'https://netts.io/apiv2/reports/statement' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Content-Type: application/json' \
  -d '{
        "client_request_id": "stmt-2026-09-usdt",
        "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "token_id": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "date_from": "2026-09-01",
        "date_to": "2026-09-30",
        "format": "csv"
      }'

{
  "status": "success",
  "code": 0,
  "msg": "created",
  "data": {
    "order_no": "REPxxxxxxxxxxxx",
    "client_request_id": "stmt-2026-09-usdt",
    "type": "statement",
    "status": "queued",
    "quota_bucket": "free",
    "progress_pct": 0,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "token_id": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "date_from": "2026-09-01",
    "date_to": "2026-09-30",
    "format": "csv",
    "created_at": "2026-09-06 17:01:51.868542+00:00",
    "finished_at": null,
    "expires_at": null,
    "artifact_sha256": null,
    "artifact_size": null,
    "download_url": null
  }
}

Campo	Obrigatório	Observações
client_request_id	sim	Seu identificador. Exclusivo por conta
address	sim	TRON base58, 34 caracteres
token_id	não	TRX por padrão; um contrato TRC20 ou um id TRC10
date_from, date_to	sim	UTC, inclusivo. No máximo 366 dias
format	não	csv por padrão. O PDF é limitado a 5.000 operações

Depois, aguarde a conclusão

curl -s 'https://netts.io/apiv2/reports/REPxxxxxxxxxxxx' \
  -H 'X-API-KEY: your-api-key' -H 'X-Real-IP: 203.0.113.10'

O campo status progride através de queued → running → waiting_cypherarc → done. Dois outros são terminais: error, com o motivo em error_code e error_message, e expired quando a validade do arquivo expirar. Um extrato curto normalmente fica pronto em bem menos de um minuto; trate qualquer status diferente de done como "continue aguardando".

Assim que estiver done, download_url é preenchido — como um caminho, não uma URL completa — e o arquivo pode ser baixado:

curl -s -OJ 'https://netts.io/apiv2/reports/REPxxxxxxxxxxxx/download' \
  -H 'X-API-KEY: your-api-key' -H 'X-Real-IP: 203.0.113.10'

O arquivo vem compactado em formato gzip. Um pedido em CSV é baixado como application/gzip com um nome de arquivo .csv.gz no Content-Disposition; descompacte-o antes de fazer a análise. A resposta de status traz artifact_sha256 e artifact_size para o arquivo compactado exatamente como entregue, para que você possa verificar o download sem uma segunda requisição.

Em vez de fazer sondagem (polling), registre um webhook e receba uma notificação quando o arquivo estiver pronto.

Repetir uma requisição é seguro

Envie o mesmo client_request_id ou o mesmo X-Idempotency-Key, e você receberá o pedido existente de volta em vez de um segundo ser gerado. A resposta inclui "msg": "existing" para que você possa diferenciar os dois.

Reutilizar um identificador com um corpo diferente é um erro, não um novo pedido: isso retorna 409. Os identificadores são exclusivos apenas dentro da sua conta — os identificadores de outra conta nunca entram em conflito com os seus.

Os arquivos duram 30 dias

Depois disso, o pedido passa a ser expired e a tentativa de download retorna 410. Solicite o arquivo novamente caso precise dele mais tarde.

Limites de taxa

10 requisições por segundo por endpoint, compartilhadas entre todos os clientes. Ultrapassar isso resulta em 429 com Retry-After: 1 e a mensagem Endpoint rate limit exceeded (10 req/s shared).

Esse é o único limite. Não há cota mensal, nem teto para a quantidade de arquivos que você pode solicitar, e não há limite para quantos são gerados simultaneamente — uma conta com saldo positivo pode solicitar o quanto o limite de taxa permitir. Pedidos que excederem o que a fila de geração pode processar são retidos e repetidos automaticamente em vez de recusados; assim, um pico de requisições custa latência para você, não falhas.

Erros

HTTP	Significado
400	o endereço tem 34 caracteres, mas falha no checksum base58
401	chave ausente ou inválida, ou o IP de origem não está na lista de permissões
402	saldo da conta abaixo do mínimo de 4 TRX
403	a chave de API está bloqueada; entre em contato com o suporte
409	o mesmo identificador foi usado com um corpo diferente — o corpo da resposta é IDEMPOTENCY_CONFLICT
410	o arquivo expirou
422	um campo está ausente ou malformado, ou o período excede 366 dias
429	limite de taxa excedido — tente novamente após o tempo indicado em Retry-After

Relacionados

• Saldos — consulta de saldos e a pré-visualização instantânea do extrato
• Webhooks de relatórios — notificação quando um arquivo estiver pronto