# Documentation des Réponses JSON - LeCoffre Anchor API

## 📋 Vue d'ensemble

L'API d'ancrage Bitcoin Signet retourne des réponses JSON standardisées. Le `transaction_id` est maintenant directement le `txid` Bitcoin (64 caractères hexadécimaux), consultable sur mempool.

---

## 🔍 Endpoints et Réponses

### 1. GET `/health`

**Description** : Vérifie l'état de santé de l'API et la connexion Bitcoin.

**Réponse 200 OK** :
```json
{
  "ok": true,
  "service": "anchor-api",
  "bitcoin": {
    "connected": true,
    "blocks": 141690,
    "network": "signet",
    "explorer": "mempool2.4nkweb.com"
  },
  "context": {
    "api_version": "1.0.0",
    "network": "Bitcoin Signet",
    "explorer_url": "https://mempool2.4nkweb.com/fr/",
    "status": "operational"
  },
  "timestamp": "2025-11-14T10:30:00.000Z"
}
```

**Réponse 503 Service Unavailable** (si Bitcoin non connecté) :
```json
{
  "ok": false,
  "service": "anchor-api",
  "error": "Bitcoin connection failed",
  "timestamp": "2025-11-14T10:30:00.000Z"
}
```

**Champs** :
- `ok` : `boolean` - État général de l'API
- `service` : `string` - Nom du service
- `bitcoin.connected` : `boolean` - État de la connexion Bitcoin
- `bitcoin.blocks` : `number` - Nombre de blocs dans la blockchain
- `bitcoin.network` : `string` - Réseau Bitcoin (signet)
- `bitcoin.explorer` : `string` - URL de l'explorateur
- `context.status` : `"operational" | "degraded"` - État opérationnel
- `timestamp` : `string` - ISO 8601 timestamp

---

### 2. POST `/api/anchor/document`

**Description** : Crée une transaction Bitcoin pour ancrer un hash de document.

**Headers requis** :
```
x-api-key: your-secure-api-key
Content-Type: application/json
```

**Body** :
```json
{
  "documentUid": "doc-12345",
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "callback_url": "http://local.4nkweb.com:3001/api/v1/anchors/callback"
}
```

**Réponse 200 OK** :
```json
{
  "transaction_id": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "status": "pending",
  "confirmations": 0,
  "block_height": null,
  "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "documentUid": "doc-12345",
  "context": {
    "network": "Bitcoin Signet",
    "explorer": "mempool2.4nkweb.com",
    "api_version": "1.0.0",
    "request_timestamp": "2025-11-14T10:30:00.000Z",
    "document_uid": "doc-12345",
    "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "status": "pending"
  },
  "explorer_url": "https://mempool2.4nkweb.com/fr/tx/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825"
}
```

**Réponse 400 Bad Request** (champs manquants) :
```json
{
  "error": "Missing required fields: documentUid, hash"
}
```

**Réponse 400 Bad Request** (format hash invalide) :
```json
{
  "error": "Invalid hash format (must be 64 hex characters)"
}
```

**Réponse 500 Internal Server Error** :
```json
{
  "error": "Internal server error",
  "message": "Insufficient funds for anchoring transaction"
}
```

**Champs** :
- `transaction_id` : `string` - **TXID Bitcoin (64 hex)** - Identifiant de transaction consultable sur mempool
- `status` : `"pending" | "confirmed"` - État de la transaction
- `confirmations` : `number` - Nombre de confirmations (0 si pending)
- `block_height` : `number | null` - Hauteur du bloc (null si non confirmé)
- `txid` : `string` - TXID Bitcoin (identique à `transaction_id`)
- `hash` : `string` - Hash du document ancré (64 hex)
- `documentUid` : `string` - Identifiant du document
- `explorer_url` : `string | null` - URL de la transaction sur mempool
- `context` : `object` - Informations contextuelles

**Note importante** : Le `transaction_id` est maintenant directement le `txid` Bitcoin, plus d'UUID.

---

### 3. GET `/api/anchor/status/:transactionId`

**Description** : Récupère le statut d'une transaction d'ancrage par son `transaction_id` (txid Bitcoin).

**Headers requis** :
```
x-api-key: your-secure-api-key
```

**Réponse 200 OK** :
```json
{
  "transaction_id": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "status": "confirmed",
  "confirmations": 6,
  "block_height": 141690,
  "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "documentUid": "doc-12345",
  "explorer_url": "https://mempool2.4nkweb.com/fr/tx/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "network": "signet",
  "timestamp": "2025-11-14T10:25:00.000Z",
  "fee": -0.00000234,
  "size": 250,
  "anchor_info": {
    "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "document_uid": "doc-12345",
    "op_return_data": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "anchored_at": "2025-11-14T10:25:00.000Z",
    "block_height": 141690,
    "confirmations": 6,
    "explorer_url": "https://mempool2.4nkweb.com/fr/tx/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
    "network": "signet"
  }
}
```

**Réponse 400 Bad Request** :
```json
{
  "error": "Missing transaction_id"
}
```

**Réponse 404 Not Found** :
```json
{
  "error": "Transaction not found"
}
```

**Réponse 500 Internal Server Error** :
```json
{
  "error": "Internal server error",
  "message": "Bitcoin RPC error"
}
```

**Champs** :
- `transaction_id` : `string` - TXID Bitcoin (64 hex)
- `status` : `"pending" | "confirmed"` - État de la transaction
- `confirmations` : `number` - Nombre de confirmations
- `block_height` : `number | null` - Hauteur du bloc
- `txid` : `string` - TXID Bitcoin (identique à `transaction_id`)
- `hash` : `string` - Hash du document ancré
- `documentUid` : `string` - Identifiant du document
- `explorer_url` : `string` - URL mempool
- `network` : `string` - Réseau Bitcoin (signet)
- `timestamp` : `string | undefined` - ISO 8601 timestamp de la transaction
- `fee` : `number | undefined` - Frais de transaction en BTC
- `size` : `number | undefined` - Taille de la transaction en bytes
- `anchor_info` : `object` - Informations détaillées sur l'ancrage

---

### 4. POST `/api/anchor/verify`

**Description** : Vérifie si un hash est ancré dans la blockchain Bitcoin.

**Headers requis** :
```
x-api-key: your-secure-api-key
Content-Type: application/json
```

**Body** :
```json
{
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825"
}
```

**Réponse 200 OK** (hash vérifié) :
```json
{
  "verified": true,
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "anchor_info": {
    "transaction_id": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
    "block_height": 141690,
    "confirmations": 6,
    "timestamp": "2025-11-14T10:25:00.000Z",
    "fee": -0.00000234,
    "size": 250,
    "explorer_url": "https://mempool2.4nkweb.com/fr/tx/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
    "network": "signet",
    "op_return_data": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "anchored_at": "2025-11-14T10:25:00.000Z"
  },
  "context": {
    "network": "Bitcoin Signet",
    "explorer": "mempool2.4nkweb.com",
    "api_version": "1.0.0",
    "verification_timestamp": "2025-11-14T10:30:00.000Z"
  }
}
```

**Réponse 200 OK** (hash non trouvé) :
```json
{
  "verified": false,
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "context": {
    "network": "Bitcoin Signet",
    "explorer": "mempool2.4nkweb.com",
    "api_version": "1.0.0",
    "verification_timestamp": "2025-11-14T10:30:00.000Z",
    "message": "Hash not found in blockchain"
  }
}
```

**Réponse 400 Bad Request** :
```json
{
  "error": "Missing required field: hash"
}
```

**Réponse 400 Bad Request** (format invalide) :
```json
{
  "error": "Invalid hash format (must be 64 hex characters)"
}
```

**Champs** :
- `verified` : `boolean` - Si le hash est ancré dans la blockchain
- `hash` : `string` - Hash vérifié
- `anchor_info` : `object | undefined` - Présent uniquement si `verified: true`
  - `transaction_id` : `string` - TXID Bitcoin
  - `block_height` : `number` - Hauteur du bloc
  - `confirmations` : `number` - Nombre de confirmations
  - `timestamp` : `string | undefined` - ISO 8601 timestamp
  - `fee` : `number | undefined` - Frais en BTC
  - `size` : `number | undefined` - Taille en bytes
  - `explorer_url` : `string` - URL mempool
  - `network` : `string` - Réseau (signet)
  - `op_return_data` : `string` - Données OP_RETURN
  - `anchored_at` : `string | undefined` - ISO 8601 timestamp
- `context` : `object` - Informations contextuelles
  - `message` : `string | undefined` - Message explicatif si non vérifié

---

## 🔑 Points importants

### Transaction ID

- **Avant** : UUID généré (ex: `4b38a41d-f429-4844-b6bd-01dfc5c42625`)
- **Maintenant** : TXID Bitcoin direct (ex: `7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825`)
- **Format** : 64 caractères hexadécimaux
- **Consultable** : Directement sur mempool avec l'URL `https://mempool2.4nkweb.com/fr/tx/{transaction_id}`

### Statuts

- `pending` : Transaction créée mais non encore confirmée (0 confirmations)
- `confirmed` : Transaction confirmée dans un bloc (≥1 confirmation)

### Codes HTTP

- `200` : Succès
- `202` : ~~Accepté (plus utilisé, maintenant 200)~~ → **200 OK** (transaction créée immédiatement)
- `400` : Erreur de validation (champs manquants, format invalide)
- `401` : Non autorisé (API key invalide)
- `404` : Transaction non trouvée
- `500` : Erreur serveur interne
- `503` : Service indisponible (Bitcoin non connecté)

---

## 📝 Exemples d'utilisation

### Créer un ancrage

```bash
curl -X POST http://dev3.4nkweb.com:3002/api/anchor/document \
  -H "x-api-key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "documentUid": "doc-12345",
    "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "callback_url": "http://local.4nkweb.com:3001/api/v1/anchors/callback"
  }'
```

### Vérifier le statut

```bash
curl -X GET "http://dev3.4nkweb.com:3002/api/anchor/status/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825" \
  -H "x-api-key: your-secure-api-key"
```

### Vérifier un hash

```bash
curl -X POST http://dev3.4nkweb.com:3002/api/anchor/verify \
  -H "x-api-key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825"
  }'
```

---

## 🔄 Callbacks

Si un `callback_url` est fourni lors de l'ancrage, l'API envoie une requête POST avec :

```json
{
  "transaction_id": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "document_uid": "doc-12345",
  "status": "pending",
  "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "confirmations": 0,
  "block_height": null
}
```

Le callback est envoyé en arrière-plan et n'affecte pas la réponse de l'API.