POST /apiv2/reports/statement

Solicite un archivo de extracto de cuenta — cada operación de un token durante un período, como CSV o PDF. El archivo se genera en segundo plano: la solicitud devuelve un número de orden de inmediato, y el archivo se descarga una vez que esté listo.

Para un vistazo rápido a los mismos datos sin esperar, use en su lugar la vista previa del extracto — responde inmediatamente pero limita la cantidad de operaciones que devuelve.

URL base del endpoint

https://netts.io/apiv2/reports

Encabezados de solicitud

Encabezado	Requerido	Descripción
X-API-KEY	sí	Clave API del panel de control
X-Real-IP	sí	Una dirección de la lista blanca de la clave
X-Idempotency-Key	no	Su propia clave, de 12 a 128 caracteres de A-Z a-z 0-9 . _ : -

Solicitar un archivo

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	Requerido	Notas
client_request_id	sí	Su identificador. Único por cuenta
address	sí	TRON base58, 34 caracteres
token_id	no	TRX por defecto; un contrato TRC20 o un id TRC10
date_from, date_to	sí	UTC, inclusivo. Como máximo 366 días
format	no	csv por defecto. PDF está limitado a 5000 operaciones

Luego espere por él

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

El campo status pasa por queued → running → waiting_cypherarc → done. Dos más son terminales: error, con el motivo en error_code y error_message, y expired una vez que el archivo ha caducado. Un extracto corto suele estar listo en mucho menos de un minuto; considere cualquier estado que no sea done como "siga esperando".

Una vez que está en done, se completa download_url — como una ruta, no una URL completa — y el archivo se puede descargar:

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'

El archivo llega comprimido con gzip. Una orden CSV se descarga como application/gzip con un nombre de archivo .csv.gz en Content-Disposition; descomprímalo antes de procesarlo. La respuesta de estado incluye artifact_sha256 y artifact_size para el archivo comprimido exactamente tal como se entrega, de modo que pueda verificar la descarga sin una segunda solicitud.

En lugar de realizar sondeos constantes, registre un webhook para recibir una notificación cuando el archivo esté listo.

Repetir una solicitud es seguro

Envíe el mismo client_request_id, o el mismo X-Idempotency-Key, y recibirá la orden existente en lugar de que se genere una segunda. La respuesta incluye "msg": "existing" para que pueda distinguirlas.

Reutilizar un identificador con un cuerpo diferente es un error, no una nueva orden: eso devuelve 409. Los identificadores son únicos solo dentro de su cuenta — los identificadores de otra cuenta nunca colisionarán con los suyos.

Los archivos se conservan durante 30 días

Después de eso, la orden pasa a expired y la descarga devuelve 410. Solicítelo de nuevo si lo necesita más adelante.

Límites de tasa

10 solicitudes por segundo por endpoint, compartidas entre todos los clientes. Superar este límite devuelve 429 con Retry-After: 1 y el mensaje Endpoint rate limit exceeded (10 req/s shared).

Ese es el único límite. No hay cuota mensual, ni límite en cuántos archivos puede solicitar, ni límite en cuántos se generan a la vez — una cuenta con saldo positivo puede solicitar tanto como permita el límite de tasa. Las órdenes que excedan la capacidad de la cola de generación se retienen y se reintentan automáticamente en lugar de rechazarse, por lo que una ráfaga le costará latencia, no fallos.

Errores

HTTP	Significado
400	la dirección tiene 34 caracteres pero falla su suma de comprobación base58
401	clave ausente o inválida, o la IP de origen no está en la lista blanca
402	el saldo de la cuenta está por debajo del mínimo de 4 TRX
403	la clave API está bloqueada; contacte a soporte
409	se utilizó el mismo identificador con un cuerpo diferente — el cuerpo es IDEMPOTENCY_CONFLICT
410	el archivo ha caducado
422	un campo falta o está mal formado, o el período supera los 366 días
429	límite de tasa excedido — reintente después de Retry-After

Relacionado

• Saldos — lectura de saldos y la vista previa instantánea del extracto
• Webhooks de informes — notificación cuando un archivo esté listo