Manyao — API REST Documentación

Introducción

La API de Manyao permite integrar firma digital de documentos con validación biométrica y certificación blockchain. Usa OAuth 2.0 con client_credentials.

Base URLhttps://manyao.pe/v1

FormatoJSON

AuthBearer Token

🔑Autenticación/auth/

POST/auth/token

Generar access token

Genera un Bearer token usando tus credenciales de API Key. Soporta Basic Auth o credenciales en el body. Cada token queda vinculado a los documentos que crea — solo puede consultar sus propios recursos.

Parámetros

Parámetro	Tipo		Descripción
client_id	string	Req	Tu API Key ID
client_secret	string	Req	Tu API Key Secret
grant_type	string	Req	Siempre `client_credentials`
expires_in	integer	Opt	Duración en segundos. Default: 3600. Máx: 2592000s (30 días)
max_uses	integer	Opt	Máximo de documentos/sesiones a crear. Default: 1. Al agotarse el token queda `exhausted`.

Request

curl -X POST 'https://manyao.pe/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "mk_live_4a8acd51...",
    "client_secret": "09cf848c8967...",
    "grant_type": "client_credentials",
    "expires_in": 3600
  }'

Respuesta — 200

{
  "success": true,
  "access_token": "7b53c0c85ae9a7bd...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-04-16 02:00:00",
  "max_uses": 1,
  "scope": "documents:create documents:read"
}

Errores

Código	Motivo	Solución
`400`	Credenciales no enviadas o grant_type incorrecto	Verifica client_id, client_secret y grant_type=client_credentials
`401`	Credenciales inválidas	Revisa tus API Keys en el panel → API Keys
`403`	API Key suspendida, revocada o IP no permitida	Verifica el estado de tu API Key y la lista de IPs
`429`	Rate limit excedido	Espera antes de reintentar

POST/auth/revoke

Revocar token

Revoca un access token antes de su expiración. Útil para logout o cuando el token fue comprometido. El token queda inválido inmediatamente.

Parámetros

Parámetro	Tipo		Descripción
token	string	Req	El access token a revocar. Enviar en el body

Request

curl -X POST 'https://manyao.pe/v1/auth/revoke' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json' \
  -d '{"token": "{{token}}"}'

Respuesta — 200

{ "success": true, "revoked": true }

Errores

Código	Motivo	Solución
`400`	Token no enviado en el body	Incluye el campo token en el body JSON
`404`	Token no encontrado o ya revocado	El token ya fue revocado o nunca existió

GET/auth/verify

Verificar token actual

Verifica si el token actual es válido y devuelve información sobre su vigencia y usos restantes.

Request

curl -X GET 'https://manyao.pe/v1/auth/verify' \
  -H 'Authorization: Bearer {{token}}'

Respuesta — 200

{
  "success": true,
  "valid": true,
  "expires_in": 2847,
  "issued_at": "2026-04-16T00:00:00",
  "expires_at": "2026-04-16T01:00:00",
  "max_uses": 1,
  "uses_remaining": 0
}

Errores

Código	Motivo	Solución
`401`	Token inválido o expirado	Genera un nuevo token con POST /auth/token

📄Documentos/documents/

POST/documents

Crear documento para firma

Crea un documento y genera el enlace de firma. Soporta PDF, JSON, XML, URL, TEXT, IMAGE, OBJECT.

Parámetros

Parámetro	Tipo		Descripción
title	string	Req	Título del documento
content_type	string	Req	`PDF`, `JSON`, `XML`, `URL`, `TEXT`, `IMAGE`, `OBJECT`
content_hash	string	Req	SHA256(content_type + content_base64)
signers	array	Cond	Firmantes: `[{dni, doc_type, email?, title?, metadata?}]`. Requerido si `signing_mode=closed`; opcional si `open`
content_base64	string	Opt	Contenido en Base64 (PDF, imagen, texto, etc.)
initial_status	string	Opt	`pending` (QR, default) o `draft` (email)
expires_in_hours	integer	Opt	Horas de vigencia (default: 168)
callback_url	string	Opt	URL para webhook al completar
external_id	string	Opt	ID de referencia en tu sistema
force_cache_refresh	boolean	Opt	Fuerza descarga fresca de modelos en el lector biométrico (ignora caché del browser)
skip_heavy_model	boolean	Opt	Omite el modelo de reconocimiento facial pesado — para conexiones lentas (solo DNI). El emisor acepta el riesgo.
signing_mode	string	Opt	`closed` (default) requiere lista de firmantes. `open` permite que cualquiera con el link firme.
max_open_signers	integer	Opt	Solo en `open`. Limite total de firmas. `0` = sin limite (default).
rate_limit_per_ip	integer	Opt	Solo `open`. Firmas maximas por IP en este documento. Default `5`. `0` = sin limite.
rate_limit_per_ip_hour	integer	Opt	Solo `open`. Firmas por hora por IP. Default `5`. `0` = sin limite.
rate_limit_docs_per_ip	integer	Opt	Solo `open`. Documentos distintos firmados por la misma IP en 24h. Default `1`. `0` = sin limite.
signing_blocked	boolean	Opt	Si `true`, pausa nuevas firmas (aplica a ambos modos). Default `false`.

Objeto signer: dni Req · doc_type Req (dni-pe: RENIEC, pe-carnet: peruanos/residentes con CE/Pasaporte, dni-pa: Tribunal Electoral PA, ci-pe: residentes con CE o Pasaporte) · email Opt (requerido si initial_status=draft) · title Opt (etiqueta personalizada en el widget) · metadata Opt (object — pares clave‑valor para tu referencia)

Campo metadata: Objeto JSON con pares clave‑valor libres. Las claves actúan como etiquetas de columna y los valores como datos de referencia para tu sistema. Se devuelven en webhooks y consultas. El widget puede mostrarlos como badges si está configurado.
Ejemplo: {"cliente": "Acme Corp", "ref": "contrato-99", "cargo": "Gerente"}

Documentos abiertos (signing_mode=open): permiten que cualquiera con el link firme. Util para NDAs, consentimientos, formularios de tratamiento de datos. Los firmantes se crean dinamicamente al hacer identify, validados contra los rate limits configurados (HTTP 429 si exceden). El campo signing_blocked=true pausa nuevas firmas en cualquier momento.

Request — closed (default)

curl -X POST 'https://manyao.pe/v1/documents' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Contrato de Servicios",
    "content_type": "PDF",
    "content_base64": "JVBERi0xLjQ...",
    "content_hash": "sha256_del_contenido",
    "signers": [{"dni":"12345678","doc_type":"dni-pe"}],
    "callback_url": "https://tuapp.com/webhook"
  }'

Request — open (NDA, consentimiento)

curl -X POST 'https://manyao.pe/v1/documents' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "NDA - Reunion Confidencial",
    "content_type": "PDF",
    "content_base64": "JVBERi0xLjQ...",
    "content_hash": "sha256_del_contenido",
    "signers": [],
    "signing_mode": "open",
    "max_open_signers": 50,
    "rate_limit_per_ip": 3,
    "rate_limit_per_ip_hour": 2,
    "rate_limit_docs_per_ip": 1,
    "expires_in_hours": 168
  }'

Respuesta — 201

{
  "success": true,
  "document": {
    "id": "a1b2c3d4-e5f6-...",
    "title": "Contrato de Servicios",
    "status": "pending",
    "sign_url": "https://manyao.pe/05/?id=a1b2c3d4-...",
    "signers": [{"id":1,"dni":"12345678","status":"pending"}],
    "expires_at": "2026-04-23 00:40:34",
    "cost": 0.50,
    "force_cache_refresh": false,
    "skip_heavy_model": false
  }
}

GET/documents/{id}

Obtener estado del documento

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}' \
  -H 'Authorization: Bearer {{token}}'

{
  "success": true,
  "document": {
    "id": "a1b2c3d4-...",
    "title": "Contrato",
    "status": "signing",
    "signers_total": 2,
    "signers_completed": 1,
    "force_cache_refresh": false,
    "skip_heavy_model": false,
    "signing_mode": "closed",
    "max_open_signers": 0,
    "rate_limit_per_ip": 5,
    "rate_limit_per_ip_hour": 5,
    "rate_limit_docs_per_ip": 1,
    "signing_blocked": false,
    "signers": [{"dni":"12345678","status":"completed","full_name":"Juan Perez","signed_at":"..."}]
  }
}

GET/documents

Listar documentos

curl -X GET 'https://manyao.pe/v1/documents?page=1&limit=20&status=completed' \
  -H 'Authorization: Bearer {{token}}'

POST/documents/{id}/signers

Agregar firmante

curl -X POST 'https://manyao.pe/v1/documents/{{document_id}}/signers' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json' \
  -d '{"dni":"12345678","doc_type":"dni-pe","email":"juan@empresa.com"}'

DELETE/documents/{id}/signers/{sId}

Eliminar firmante

curl -X DELETE 'https://manyao.pe/v1/documents/{{document_id}}/signers/42' \
  -H 'Authorization: Bearer {{token}}'

POST/documents/{id}/send

Enviar notificación email

curl -X POST 'https://manyao.pe/v1/documents/{{document_id}}/send' \
  -H 'Authorization: Bearer {{token}}'

POST/documents/{id}/cancel

Cancelar documento

Estado terminal irreversible. Solo puede ejecutarlo el mismo token Bearer que creó el documento. Registra el evento en el log de auditoría y escribe cancel.json en el paquete WORM.

Parámetros

Parámetro	Tipo		Descripción
reason	string	Opt	Motivo de cancelación. Se registra en WORM y base de datos

Request

curl -X POST 'https://manyao.pe/v1/documents/{{document_id}}/cancel' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "Contrato revisado, se emitirá nueva versión"}'

Respuesta — 200

{
  "success": true,
  "message": "Documento cancelado",
  "uuid": "a1b2c3d4-...",
  "status": "cancelled",
  "reason": "Contrato revisado, se emitirá nueva versión",
  "cancelled_at": "2026-04-16 00:40:41"
}

Errores

Código	Motivo
`400`	Documento ya en estado terminal (completed, cancelled, expired)
`403`	Token no es el mismo que creó el documento
`404`	Documento no encontrado

POST/documents/{id}/close

Cerrar con firmas parciales

curl -X POST 'https://manyao.pe/v1/documents/{{document_id}}/close' \
  -H 'Authorization: Bearer {{token}}'

POST/documents/{id}/reopen

Reabrir documento

curl -X POST 'https://manyao.pe/v1/documents/{{document_id}}/reopen' \
  -H 'Authorization: Bearer {{token}}'

GET/documents/{id}/forensic/{sId}

Datos forenses del firmante

Devuelve la firma manuscrita, datos biométricos y hashes blockchain del firmante. Solo disponible cuando el firmante tiene status = completed.

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/forensic/{{signer_id}}' \
  -H 'Authorization: Bearer {{token}}'

Respuesta — 200

{
  "signer_name": "JUAN PEREZ GARCIA",
  "signed_at": "2026-04-16 10:30:00",
  "signature_image": "data:image/png;base64,...",
  "signature_biometric": "{"points":289,"duration_ms":6671}",
  "device_type": "mobile",
  "device_id": "0a8f4298d3e5a77d...",
  "hash_signature": "abc123...",
  "tx_signature": "0x7a3f...b2c1"
}

GET/documents/{id}/log-download

Descargar ZIP WORM

Descarga el paquete ZIP con todos los registros de trazabilidad biométrica. Solo disponible cuando status = completed. Requiere el mismo token que creó el documento.

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/log-download' \
  -H 'Authorization: Bearer {{token}}' \
  --output trazabilidad.zip

Estructura del ZIP

{uuid}/
  document.json              metadatos del documento al crearse
  access.json                registro de acceso del firmante
  cancel.json                evento de cancelación (si aplica)
  {doc_type}-{numero}/
    manifest.json            manifiesto del paquete WORM
    persona.json             datos del firmante verificados
    pipeline.json            pipeline de validación
    session.json             datos de sesión biométrica
    biometric_analysis.json  análisis biométrico completo
    behavior.json            análisis de comportamiento
    selfie.jpg               foto selfie capturada
    frente.jpg               foto frente del documento
    reverso.jpg              foto reverso del documento

📥Descargas/documents/{id}/download

Disponible cuando status = completed. Requiere el mismo Bearer token con que se creo el documento.

GET/documents/{id}/download

Descargar PDF firmado

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/download' \
  -H 'Authorization: Bearer {{token}}' --output firmado.pdf

PDF con todas las firmas biometricas. Purga permanente tras responder HTTP 200 al webhook.

GET/documents/{id}/log-download

Descargar ZIP de trazabilidad WORM

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/log-download' \
  -H 'Authorization: Bearer {{token}}' --output log.zip

ZIP con selfies, fotos, analisis biometrico, sesion y logs de cada firmante. URL en campo download_log_url del webhook.

🏆Certificados/documents/{id}/certificate/

Disponible cuando status = completed. Incluye foto, firma, prueba de vida y blockchain.

GET/documents/{id}/certificate

Certificados de todos los firmantes

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/certificate' \
  -H 'Authorization: Bearer {{token}}'

GET/documents/{id}/certificate/{sId}/image

Imagen PNG del certificado

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/certificate/42/image' \
  -H 'Authorization: Bearer {{token}}' --output cert.png

GET/documents/{id}/certificate/{sId}/json

JSON de evidencia criptográfica

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/certificate/42/json' \
  -H 'Authorization: Bearer {{token}}'

GET/documents/{id}/certificate/download

Descargar ZIP completo

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/certificate/download' \
  -H 'Authorization: Bearer {{token}}' --output evidencia.zip

GET/documents/{id}/certificate/{sId}/verify

Link y QR de verificación

curl -X GET 'https://manyao.pe/v1/documents/{{document_id}}/certificate/42/verify' \
  -H 'Authorization: Bearer {{token}}'

🔐Sesiones de Acceso/sessions/

POST/sessions

Crear sesión biométrica

Parámetro	Tipo		Descripción
doc_type	string	Req	`dni-pe`, `dni-pa`, `ci-pe`
doc_number	string	Opt	Número de documento a validar
callback_url	string	Opt	URL webhook al verificar
metadata	object	Opt	Datos de referencia

curl -X POST 'https://manyao.pe/v1/sessions' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json' \
  -d '{"doc_type":"dni-pe","callback_url":"https://tuapp.com/callback"}'

GET/sessions/{uuid}

Estado (polling, público)

curl -X GET 'https://manyao.pe/v1/sessions/{{session_uuid}}'

GET/sessions/{uuid}/result

Resultado completo (auth)

curl -X GET 'https://manyao.pe/v1/sessions/{{session_uuid}}/result' \
  -H 'Authorization: Bearer {{token}}'

GET/sessions

Listar sesiones

curl -X GET 'https://manyao.pe/v1/sessions?page=1&limit=20' \
  -H 'Authorization: Bearer {{token}}'

Códigos de Error

Código	Descripción	Solución
400	Bad Request	Verifica los parámetros
401	Unauthorized	Token inválido o expirado
402	Payment Required	Saldo insuficiente
403	Forbidden	IP o dominio no permitido
404	Not Found	Recurso no encontrado
429	Too Many Requests	Rate limit excedido
500	Internal Error	Contacta soporte

manyao.pe — Firma digital con validación biométrica