NicolasCantu
924ab8e185
**Motivations :** * transaction_id doit être un identifiant de transaction Bitcoin consultable sur mempool * Les UUID n'ont pas d'utilité pour identifier une transaction Bitcoin * Simplification de l'architecture en supprimant la logique de queue inutile **Root causes :** * transaction_id était généré comme UUID au lieu d'utiliser le txid Bitcoin * Logique de queue/job complexe pour gérer des identifiants temporaires * Réponse HTTP 202 alors que la transaction est créée immédiatement **Correctifs :** * transaction_id est maintenant directement le txid Bitcoin (64 hex) * Suppression complète de la logique de queue et de job (Map, cleanup, etc.) * Création immédiate de la transaction Bitcoin dans enqueue() * getStatus() interroge directement Bitcoin au lieu d'une Map en mémoire * Réponse HTTP 200 OK au lieu de 202 Accepted * Suppression de la dépendance uuid (plus utilisée) **Evolutions :** * API simplifiée : plus de queue, transactions créées directement * transaction_id consultable immédiatement sur mempool * Documentation complète des réponses JSON (API_RESPONSES.md) * Scripts de test mis à jour pour valider le format txid Bitcoin **Page affectées :** * src/services/AnchorQueueService.ts : refactor complet, suppression queue * src/controllers/AnchorController.ts : mise à jour pour txid, status 200 * src/index.ts : suppression cleanup périodique * test-api-ok.sh : validation format txid, status 200 * test-api.sh : validation format txid, status 200 * README.md : mise à jour exemples avec txid Bitcoin * API_RESPONSES.md : nouvelle documentation complète des réponses JSON
383 lines
11 KiB
Markdown
383 lines
11 KiB
Markdown
# 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.
|