Solicitudes de certificado

Nombras al titular y el producto, y recibes una URL alojada de un solo uso donde la persona completa la emisión en el portal de tu organización: verificación de identidad, pago y generación de llaves en su navegador. Ni el webhook ni la consulta llevan material de llave — la llave privada nunca sale del navegador del titular.

Consultar productos y precios#

GET /api/v1/certificate-products Bearer

Catálogo activo del portal. Importes en centavos de USD, antes de impuestos. partner_subtotal_cents es el neto configurado para tercero vinculado; null requiere confirmar las condiciones comerciales. El catálogo es una consulta, no una reserva de precio.

Devuelve · 200 con los productos habilitados para la organización de la llave.

cURL

curl "https://edge.datil.com/api/v1/certificate-products" \
  -H "Authorization: Bearer $DATIL_API_KEY"

Respuesta · 200

{
  "ok": true,
  "products": [
    {
      "plan": null,
      "cert_type": "persona_natural",
      "validity": "y1",
      "name": "Persona natural, un año",
      "currency": "USD",
      "retail_subtotal_cents": 1800,
      "partner_subtotal_cents": null,
      "partner_price_configured": false,
      "includes_tax": false,
      "billed_on": null
    }
  ]
}

Crear una solicitud#

POST /api/v1/certificate-requests Bearer

Devuelve la URL alojada del titular. Es de un solo uso — se consume al abrirse — y reenviar el mismo reference_id devuelve la MISMA URL en vez de crear otra solicitud dentro de la misma organización y ambiente. Los enlaces nuevos vencen en siete días. El titular autenticado puede reanudar su trámite. environment: test verifica identidad sin emitir, cobrar ni guardar imágenes, y envía un webhook de prueba.

Content-Type: application/json

Cuerpo de la solicitud

environment string

Ambiente de la solicitud. Por defecto production ; envía test también al consultar o modificar una solicitud de prueba. Misma URL base y llave, referencias separadas por ambiente.

productiontest

callback_secret string

Secreto de 32 a 256 bytes para HMAC-SHA256 del webhook. Se guarda cifrado y nunca se devuelve. Sin secreto, el webhook no lleva firma.

reference_id string requerido

Tu número de trámite. Es también la clave de idempotencia.

holder objeto requerido

Quién recibe el certificado.

holder.national_id string requerido

Cédula de la persona que realiza la verificación de identidad.

holder.email string requerido

Correo del titular. Tu integración entrega la URL devuelta; crear la solicitud no envía un correo.

holder.name string

Nombre del titular.

plan string

Clave del producto en el catálogo de tu organización. Alternativa a validity + cert_type ; uno de los dos es obligatorio.

validity string

Duración del certificado ( d7 , m1 , y1 , y2 , y3 , y4 , y5 ) cuando no envías plan .

cert_type string

Tipo exacto: persona_natural , representante_legal o miembro_empresa . Debe existir en el catálogo del portal.

billing_mode string

platform : checkout del titular. organization_billed : la empresa financia al titular sin reventa; se fija la tarifa Datil al crear la solicitud y se descuenta del saldo al abrirla. partner_billed : reventa, solo para terceros vinculados aprobados en producción. Por defecto platform .

platformpartner_billedorganization_billed

return_url string

URL HTTPS del enlace «Volver» que ve el titular al terminar.

callback_url string

URL HTTPS que recibe los metadatos del certificado al emitirse.

fulfillment string

Entrega adicional del certificado emitido. Por defecto none .

nonelegacy_upload

fulfillment_ref string

La cuenta destino, obligatoria cuando fulfillment es legacy_upload .

Devuelve · 201 con la URL alojada. 422 con error : reference_id_required , holder_national_id_required , product_selector_required , unknown_product , invalid_callback_url , tenant_not_active .

cURL

curl -X POST https://edge.datil.com/api/v1/certificate-requests \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reference_id": "CERT-2026-0001",
  "holder": {
    "national_id": "0919372607",
    "name": "Juan Pérez",
    "email": "juan@example.com"
  },
  "validity": "y2",
  "cert_type": "persona_natural",
  "billing_mode": "platform",
  "callback_url": "https://tu-sistema.com/webhooks/certificados"
}'

Respuesta · 201

{
  "ok": true,
  "reference_id": "CERT-2026-0001",
  "certificate_request_id": "6b1d0f4a-7c2e-4b8d-9f1a-3e5c7a9b1d3f",
  "url": "https://acme.datil.id/certificate-requests/8fQ2mZs1",
  "status": "pending",
  "environment": "production",
  "link_expires_at": "2026-09-28T14:05:00Z"
}

Consultar una solicitud#

GET /api/v1/certificate-requests/:reference_id Bearer

El estado de la emisión, el pago y — cuando el certificado ya existe — sus metadatos: número de serie, tipo y vigencia. Estados de solicitud: pending , opened , issued , test_completed , failed . failed indica un fallo terminal de entrega del webhook, no de emisión. Consulta también order.status , delivery y next_action .

Parámetros

reference_id string requerido

Tu número de trámite.

environment string

Ambiente de la solicitud. Por defecto production ; envía test también al consultar o modificar una solicitud de prueba. Misma URL base y llave, referencias separadas por ambiente.

productiontest

Devuelve · 200 con la solicitud · 404 not_found · 401 sin llave válida.

cURL

curl "https://edge.datil.com/api/v1/certificate-requests/CRED-2026-0001" \
  -H "Authorization: Bearer $DATIL_API_KEY"

Respuesta · 200

{
  "ok": true,
  "certificate_request": {
    "reference_id": "CERT-2026-0001",
    "environment": "production",
    "link_expires_at": "2026-09-01T14:05:00Z",
    "next_action": "none",
    "delivery": {
      "status": "delivered",
      "event_id": "certificate_request.issued:6b1d0f4a-7c2e-4b8d-9f1a-3e5c7a9b1d3f",
      "response_code": 200,
      "authenticated": false
    },
    "certificate_request_id": "6b1d0f4a-7c2e-4b8d-9f1a-3e5c7a9b1d3f",
    "status": "issued",
    "billing_mode": "platform",
    "url": "https://acme.datil.id/certificate-requests/8fQ2mZs1",
    "created_at": "2026-08-25T14:05:00Z",
    "opened_at": "2026-08-25T14:09:00Z",
    "completed_at": "2026-08-25T14:22:00Z",
    "holder": {
      "national_id": "0919372607",
      "name": "Juan Pérez",
      "email": "juan@example.com"
    },
    "product": {
      "plan": null,
      "validity": "y2",
      "cert_type": "persona_natural"
    },
    "order": {
      "id": "2f7c9b1e-5a3d-4e8f-9c1b-7d5a3e1f9b7c",
      "status": "issued"
    },
    "certificate": {
      "serial": "4a2f9c1b7d5e3a1f",
      "cert_type": "persona_natural",
      "validity": "y2",
      "issued_at": "2026-08-25T14:22:00Z",
      "expires_at": "2028-08-25T14:22:00Z"
    },
    "payment": {
      "billing_mode": "platform",
      "amount_cents": 2400,
      "status": "paid"
    },
    "fulfillment": {
      "mode": "none",
      "status": null
    },
    "callback_delivered": true
  }
}

Regenerar el enlace#

POST /api/v1/certificate-requests/:reference_id/regenerate-link Bearer

Invalida el token anterior y renueva su vencimiento por siete días. Conserva la misma orden y el pago. Una solicitud ya abierta requiere la sesión del titular; regenerar no reinicia la emisión.

Content-Type: application/json

Parámetros

reference_id string requerido

Tu número de trámite.

Cuerpo de la solicitud

environment string

Ambiente de la solicitud. Por defecto production ; envía test también al consultar o modificar una solicitud de prueba. Misma URL base y llave, referencias separadas por ambiente.

productiontest

Devuelve · 200 con el nuevo enlace · 404 not_found · 409 request_not_resumable si la solicitud ya terminó o está emitiendo.

cURL

curl -X POST https://edge.datil.com/api/v1/certificate-requests/CRED-2026-0001/regenerate-link \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": "test"
}'

Respuesta · 200

{
  "ok": true,
  "url": "https://acme.datil.id/certificate-requests/nuevo-token",
  "link_expires_at": "2026-09-28T14:05:00Z"
}

Reenviar el webhook#

POST /api/v1/certificate-requests/:reference_id/retry-callback Bearer

Encola la entrega del resultado ya emitido o de la prueba completada. Conserva el event_id ; no repite la emisión ni el cobro. Los jobs en curso se deduplican.

Content-Type: application/json

Parámetros

reference_id string requerido

Tu número de trámite.

Cuerpo de la solicitud

environment string

Ambiente de la solicitud. Por defecto production ; envía test también al consultar o modificar una solicitud de prueba. Misma URL base y llave, referencias separadas por ambiente.

productiontest

Devuelve · 202 con el evento encolado · 404 not_found · 409 delivery_not_available antes de completar o sin callback configurado.

cURL

curl -X POST https://edge.datil.com/api/v1/certificate-requests/CRED-2026-0001/retry-callback \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "environment": "test"
}'

Respuesta · 202

{
  "ok": true,
  "event_id": "certificate_request.test_completed:6b1d0f4a-7c2e-4b8d-9f1a-3e5c7a9b1d3f"
}

Consultar productos y precios#

Crear una solicitud#

Consultar una solicitud#

Regenerar el enlace#

Reenviar el webhook#

Cookies