prueba-sdk

Servidor HTTP local para probar @mdpsdk/mdp-sdk desde Postman.

Solo desarrollo: no hay autenticación en las rutas. No exponer a internet.

Arranque

cp .env.example .env   # credenciales de verificación básica y cumplimiento en el servidor
npm install
npm run dev

Deja la terminal abierta: verás prueba-sdk escuchando en http://localhost:3000 y el proceso no debe volver al prompt hasta Ctrl+C. Si vuelve al instante, prueba npm run start:prod tras npm run build, u otro puerto (PORT=3001 en .env).

Base URL por defecto: http://localhost:3000 (variable PORT opcional).

Documentación interactiva del contrato integrador:

cd ../docs
npm install
npm run docs:onboarding

Abrir http://localhost:4400/scalar/ (OpenAPI 0.4.1).

Debug submit-eu-us

En .env activa:

PRUEBA_SDK_DEBUG=true
MDP_SDK_DEBUG=true

Reinicia npm run dev. En la terminal del servidor verás el paso y el body enviado al proveedor de cumplimiento. En Postman, el JSON de error puede incluir details.responseData.

Smoke test auth sin HTTP:

npm run cli

Rutas — Health y auth debug

| Método | Ruta | Descripción | |--------|------|-------------| | GET | /health | Estado del servidor |

Requests de comprobación de credenciales están en la colección Postman (carpeta Auth) — no forman parte del contrato OpenAPI integrador.

Rutas — Onboarding

Contrato alineado con docs/openapi/mdp-onboarding-sdk.yaml (SDK 0.4.1).

| Método | Ruta | Body | Query | |--------|------|------|-------| | POST | /onboarding/start | type, externalCustomerId, email o profile.email, profile? | — | | POST | /onboarding/verification-url | externalCustomerId | — | | GET | /onboarding/:externalCustomerId/status | — | type obligatorio (personal | business) | | POST | /onboarding/:externalCustomerId/submit-eu-us | target (+ ownerId / ownerInquiryId KYB) | — | | GET | /onboarding/:externalCustomerId/terms | — | type?, ownerId? | | POST | /onboarding/:externalCustomerId/compliance/activate | walletAddress, asset?, accountName? | — | | POST | /onboarding/compliance/activate | externalCustomerId, walletAddress, … | — (legacy) | | GET | /onboarding/:externalCustomerId/owners | — | mapas KYB en query según colección Postman | | POST | /onboarding/:externalCustomerId/owners/:ownerId/verification-url | ownerInquiryId | — | | GET | /onboarding/:externalCustomerId/owners/:ownerId | — | ownerInquiryId | | POST | /onboarding/owners/occupation | email, name, occupationCode | — | | POST | /onboarding/owners/sync-status | inquiryId | debug |

Flujo mínimo (Postman)

1. POST /onboarding/start — guardar externalCustomerId; enviar verificationUrl al usuario.
2. Usuario completa verificación básica.
3. GET /onboarding/{externalCustomerId}/status?type=personal
4. POST /onboarding/{externalCustomerId}/submit-eu-us con { "target": "person" } cuando basicVerification.status = approved.
5. Enviar termsOfServiceUrl al usuario (respuesta submit o GET .../terms).
6. Usuario acepta términos (fuera del SDK).
7. POST /onboarding/{externalCustomerId}/compliance/activate con { "walletAddress": "0x..." }.
8. GET .../status hasta euUsVerification.status = compliance_approved o account_ready.

accountCreated: false en activate no es error: la cuenta ya existía y solo se reactivó cumplimiento (reintentos idempotentes).

KYB: tras aprobar empresa, GET /onboarding/{id}/owners y seguir rutas de socios (mapas ownerInquiryIds / ownerIdentityIds en tu BD).

Si falta email en verificación básica, envía personalProfile.email en submit — el SDK lo sincroniza antes de EU/US.

Colección Postman

Importar postman/mdp-sdk-prueba.postman_collection.json.

Variables de colección: baseUrl, externalCustomerId, ownerId (opcional legacy: inquiryId, identityId).

Ejemplo — start KYB Chile

POST {{baseUrl}}/onboarding/start
Content-Type: application/json

{
  "type": "business",
  "externalCustomerId": "emp_postman_001",
  "profile": {
    "email": "[email protected]",
    "legalName": "ACME SA",
    "taxId": "123",
    "address": {
      "street1": "Av. Test 1",
      "city": "Santiago",
      "state": "RM",
      "postalCode": "8320000",
      "country": "CL"
    }
  }
}