API OTC - Documentación

Resumen

Esta API permite subir archivos (PDF, imágenes, audio, video), generar un hash SHA-256, almacenar el archivo en IPFS y registrar el hash en Polygon.

Límites y costes por acción

Las acciones que tengan coste adicional pueden limitarse por tipo de cliente y por cliente. El consumo se reinicia según el periodo configurado (por defecto mensual) sin perder el histórico, que queda registrado en action_usage.

polygon_write: registra hashes en Polygon al subir un archivo.
polygon_read: consultas a la red Polygon (si se habilitan).
ipfs_retrieve: accesos de recuperación de contenido distribuido.

Si un cliente llega al límite de una acción, no podrá ejecutar esa acción hasta el siguiente periodo. Las acciones sin coste (o sin límites configurados) se pueden usar sin restricción.

Autenticación

Para los endpoints de archivos, incluye el header X-Client-Api-Key del cliente.

X-Client-Api-Key: tu-api-key-de-cliente

Para gestión de contratos, usa el header X-API-Key.

X-API-Key: tu-api-key-larga

Configuración requerida

Configura estos valores en el archivo config/app.php (incluido en el repositorio) para que la API funcione correctamente:

api_key: clave para endpoints de contratos.
ipfs_api_url: URL del nodo IPFS (por defecto http://127.0.0.1:5001).
ipfs_gateway_url: gateway para construir URLs públicas (por defecto https://ipfs.io/ipfs).
addregistro_cert_path, addregistro_cert_passphrase: ruta y contraseña del certificado PKCS#12 para firmar registros (por defecto addaw.pfx en la raíz del proyecto).
addregistro_tsa_url, addregistro_tsa_user, addregistro_tsa_pass: configuración del servidor de sellado de tiempo (opcional). Para desactivar el TSA usa ADDREGISTRO_TSA_DISABLED=true o deja la URL vacía.
polygon_rpc_url, polygon_from_address, polygon_private_key, polygon_contract_address, polygon_chain_id, polygon_gas_limit, polygon_gas_price, polygon_network para registrar hashes en Polygon.

La conexión a base de datos se configura en config/database.php.

Registro firmado

POST /v1/addRegistro

Recibe un JSON, lo convierte a XML, aplica firma con certificado y agrega marca de tiempo.

Content-Type: application/json

curl -X POST https://block.addaw.org/v1/addRegistro \
  -H "X-Client-Api-Key: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"idCliente":"123","documento":{"tipo":"registro","valor":"ABC-123"}}'

Respuesta:

{
  "client_id": "123",
  "signed_path": "/logs/registrosCertificados/123/2025/01/01/2025-01-01-12-00-00-abcdef123456.xsig",
  "signed_xml": "<fe:Facturae>...</fe:Facturae>"
}

Estado del servicio

GET /v1/health

Devuelve el estado de la base de datos, IPFS y configuración de Polygon.

curl https://block.addaw.org/v1/health

Respuesta:

{
  "status": "ok",
  "checks": {
    "database": { "status": "ok" },
    "ipfs": { "status": "ok", "detail": { "Version": "0.20.0" } },
    "polygon": { "status": "ok" }
  }
}

Endpoint de subida

POST /v1/files

Content-Type: multipart/form-data

Este endpoint es idempotente para el mismo cliente: si subes el mismo archivo (mismo SHA-256), devuelve el registro existente y no genera una nueva transacción.

curl -X POST https://block.addaw.org/v1/files \
  -H "X-Client-Api-Key: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" \
  -F "file=@/ruta/archivo.pdf"

Respuesta:

{
  "sha256": "...",
  "ipfs_cid": "...",
  "polygon_tx_hash": "...",
  "mime_type": "application/pdf",
  "client_id": 1
}

Si el archivo ya existe para ese cliente, la respuesta será 200 con los mismos campos.

Consulta de material

GET /v1/files/{sha256}

curl https://block.addaw.org/v1/files/<sha256> \
  -H "X-Client-Api-Key: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

Respuesta:

{
  "sha256": "...",
  "ipfs_cid": "...",
  "ipfs_url": "https://ipfs.io/ipfs/...",
  "polygon_tx_hash": "...",
  "mime_type": "application/pdf",
  "original_name": "archivo.pdf",
  "size_bytes": 12345,
  "created_at": "2025-01-01 10:00:00"
}

Activación de contratos

POST /v1/contracts/{address}/activate

Activa la dirección del contrato para la red indicada y desactiva cualquier contrato activo previo.

curl -X POST https://block.addaw.org/v1/contracts/0xTuContrato/activate \
  -H "X-API-Key: tu-api-key-larga" \
  -H "Content-Type: application/json" \
  -d '{"network":"polygon","tx_hash":"0xhash","deployed_at":"2025-01-01 12:00:00"}'

Respuesta:

{
  "address": "0xTuContrato",
  "network": "polygon",
  "tx_hash": "0xhash",
  "deployed_at": "2025-01-01 12:00:00",
  "is_active": true
}

POST /v1/contracts/{address}/deactivate

Desactiva el contrato indicado para la red.

curl -X POST https://block.addaw.org/v1/contracts/0xTuContrato/deactivate \
  -H "X-API-Key: tu-api-key-larga" \
  -H "Content-Type: application/json" \
  -d '{"network":"polygon"}'

Configuración para clientes

Esta documentación pública solo describe el uso de la API desde clientes.

Necesitarás una clave de cliente válida para usar los endpoints de archivos.