Integra certificados: compra empresarial, referidos y distribución

La API crea solicitudes alojadas en el portal del partner. La integración entrega al titular la URL de la respuesta y consulta el resultado por API o webhook. Crear una solicitud no envía un correo automáticamente. La llave privada se genera en el navegador del titular; la consulta y el webhook contienen únicamente metadatos.

Encuentra tu punto de entrada

Un portal y una API son canales de operación, no modalidades comerciales. Una misma cuenta puede usar ambos. Integraciones (/integrations) permite seleccionar una organización que administras y abrir las credenciales del producto; si no tienes una, puedes crearla y continuar. Certificados/firma y facturación usan credenciales y permisos independientes.

Alta y lanzamiento del partner

Elige la modalidad según tu operación

• Referidos: recomiendas certificados y Datil cobra y factura al cliente. Tú facturas a Datil la comisión conciliada. Es la opción para quien quiere referir clientes sin gestionar su cobro. Crear cuenta de referidos.
• Mayorista / tercero vinculado: vendes certificados, firma de documentos, paquetes y planes publicados con tu propia facturación y precio minorista; Datil te factura el producto con las condiciones de prepago o crédito aprobadas. Es la opción para un distribuidor que administra su cartera y margen. Requiere contrato, expediente y registro ARCOTEL verificado antes de producción. Crear cuenta mayorista.
• Firma para tu propia organización: si un club o una empresa necesita firmar afiliaciones, contratos o documentos con garantes, el punto de entrada es Firma de documentos. Integrar ese proceso no exige incorporarse al programa de distribución. Consulta la solución e integración de firma y la API de solicitudes de firma. La API de certificados de esta guía emite certificados; no crea por sí sola una solicitud de firma de PDF.

El alta de partner crea una organización con certificados, firma de documentos y verificación de identidad habilitados para configuración. El creador recibe la membresía de propietario. Una organización existente puede solicitar su incorporación desde /admin/partner; durante la configuración del programa, su portal público y API quedan limitados a las pruebas de certificados y solicitudes de firma.

Portal e integración

El partner dispone de un portal alojado con su marca para el trámite del titular. Puede compartirlo con sus clientes sin desarrollar una integración. Si utiliza su propio sistema, la API crea una solicitud y devuelve el enlace alojado que debe entregar al titular; los resultados se consultan por API o webhook. Este enlace abre el portal de Datil: no es un componente de firma incrustado dentro de otra aplicación.

El espacio Partner (/admin/partner) reúne cuatro pasos: identidad y marca, catálogo activo, credencial con alcances certificates y signatures y una operación de prueba completada. Los avances se calculan a partir de los registros guardados. El editor de organización administra nombre, logo, colores, razón social y RUC; el catálogo administra precios y vigencias. La herramienta de pruebas llama a la API real con environment: "test" y permite abrir la ceremonia. Actualizar progreso consulta los resultados y la entrega del webhook.

El alta comienza en sandbox. Solicitar aprobación pasa a review y aparece en Console → Partners. El personal de Datil revisa la contratación y los requisitos de la modalidad, configura el margen si corresponde y aprueba. Sin margen previo, la aprobación asigna 20% para comision o 30% para tercero_vinculado; un margen ya pactado se conserva. Estos valores no se aplican retroactivamente a partners existentes. Los descuentos por volumen requieren un acuerdo y una configuración comercial explícita.

La aprobación habilita los productos de la organización y cambia el estado a approved, pero no publica el portal. Publicar portal pasa a live solamente si hay razón social y RUC, un producto activo, una llave vigente con alcance de certificados y al menos una prueba completada. Si esa prueba incluye callback, su entrega debe estar confirmada. La organización debe estar activa y tener habilitado el producto. El partner no puede aprobarse ni modificar su margen.

Durante sandbox, review y approved, se aceptan los endpoints de certificados y solicitudes de firma con environment=test. Esto incluye GET /api/v1/certificate-products?environment=test; omitir el ambiente devuelve 403 partner_sandbox_only. Los enlaces de pruebas existentes siguen accesibles para sus titulares. El portal de producción permanece cerrado. El límite de incorporación es de 50 solicitudes de prueba por organización; las repeticiones con la misma referencia son idempotentes y no consumen otra solicitud. Una referencia nueva sobre el límite devuelve 422 sandbox_request_limit_reached. Este límite cuenta solicitudes, no intentos individuales de verificación.

Cualquier organización, incluidas las cuentas antiguas, solo puede usar partner_billed en producción con modalidad tercero_vinculado, estado live y margen configurado. Un referidor recibe 422 partner_billed_not_enabled; sus clientes pagan mediante la plataforma. En pruebas se puede ensayar esa modalidad sin cobros.

Catálogo único del distribuidor

En Partner → Una cuenta, todos tus productos (/admin/partner#partner-product-catalog) se comparan cuatro familias. No hace falta otro registro por producto:

Una firma se tarifa por persona y solicitud, no por cada marca visual en un PDF. Con tu certificado corresponde al remitente autenticado que firma con su certificado; los destinatarios que aportan un certificado usan Tu certificado + identidad. Certificado incluido cubre la emisión de uso único y la verificación para esa solicitud; no entrega un certificado de larga duración reutilizable.

El catálogo muestra importes en USD antes de impuestos: precio sugerido, precio objetivo de reventa, importe Datil y margen bruto del distribuidor. El precio objetivo sirve para cotizar; no cambia por sí solo un cobro. Los precios de certificados se publican desde su catálogo; en firma se configuran en el flujo o solicitud. Para reventa con cobro propio se usa payer: "requester": el distribuidor paga el uso y factura a su cliente. En certificados el equivalente es billing_mode: "partner_billed". Los paquetes abastecen solicitudes operadas desde la organización compradora y los planes se activan en ella; no se transfieren automáticamente a otra organización.

Datil configura el descuento general y las excepciones por producto. Para terceros vinculados habilitados, las tarifas se aplican al uso de firma, al checkout de paquetes y a los planes pagados con tarjeta o saldo. Los paquetes redondean al centavo por unidad; el precio total y el saldo de unidades usan el mismo valor. El precio contratado queda guardado en la compra o suscripción; un cambio posterior no modifica una compra preparada ni una renovación cuyo precio ya está fijado. Las condiciones propuestas durante el alta no aplican descuentos antes de la aprobación y el lanzamiento.

Solo el personal de Datil puede configurar descuentos y costos directos estimados. El distribuidor puede guardar precios objetivo; no puede cambiar su descuento ni acceder a los costos de Datil. La contribución estimada de Datil es importe Datil menos costo configurado, no utilidad neta. Un costo desconocido aparece sin configurar. Las excepciones comerciales se incorporan al anexo de los nuevos contratos; modificar solo costos internos no cambia el acuerdo. Los contratos ya firmados se conservan.

El acuerdo de referidos paga la comisión sobre el valor neto cobrado de todos los servicios de los clientes atribuidos al partner: certificados, firma de documentos (cada emisión de un certificado de uso único y cada firma con certificado propio), paquetes de firmas y planes. Las compras del partner para su propia organización no generan comisión.

Probar los dos servicios

Una llave con ambos alcances permite usar POST /api/v1/certificate-requests y POST /api/v1/signature-requests con environment: "test". Cada servicio permite hasta 50 solicitudes por organización durante el alta; reintentar una referencia existente no consume otra solicitud. Firma admite mode: "transactional" para certificado incluido y mode: "byo_cert" para certificado propio. Consulta el cuerpo completo en la referencia de solicitudes de firma.

Las pruebas no cobran, emiten certificados ni firman el PDF. Conservan los artefactos de prueba y el historial de la solicitud, sin retener biometría. Los webhooks de prueba sí se entregan. El lanzamiento acepta una emisión o una solicitud de firma completada; si tiene webhook, su entrega debe estar confirmada. La llave conserva sus permisos por alcance y no puede usar producción antes del lanzamiento.

Contratos, facturación y registro

El contrato mayorista estándar no establece cuota fija ni consumo mínimo mensual. El descuento inicial propuesto es 30%; el personal de Datil puede pactar otro margen en Configuración → Partner. Cada partner tiene un anexo comercial propio en /admin/partner/legal. El anexo documenta precios particulares, productos, impuestos y condiciones de pago: no modifica por sí mismo los precios operativos, el saldo ni los límites de crédito. Estos deben configurarse también en los módulos comerciales correspondientes. El crédito nunca se concede por el mero registro o acceso a pruebas.

Console → Acuerdos → Preparar borradores de partners incorpora dos instrumentos editables: partner_referral y partner_wholesale. Los borradores preparados desde Console requieren publicación explícita. El despliegue de Trust publica automáticamente las primeras ediciones estándar que todavía no se han editado, con PDF y hash; conserva versiones publicadas, retiradas y borradores personalizados. Consulta el procedimiento de despliegue. El acuerdo de referidos contiene atribución, base de comisión neta, liquidación, factura, pago, retenciones, independencia, privacidad y terminación. La plantilla mayorista cubre el flujo alojado; operar biometría o CSR fuera de él requiere una habilitación y un anexo técnico específicos. Los campos {{partner_name}}, {{partner_ruc}}, {{partner_representative}}, {{partner_id}}, {{partner_email}}, {{partner_address}}, {{datil_representative}}, {{datil_id}}, {{datil_email}}, {{datil_address}}, {{margin_percent}}, {{payment_mode}}, {{pricing_annex}} y, desde la edición 1.1, {{certificate_specification}} se completan al preparar cada contrato. Un campo pendiente impide enviarlo.

El partner proporciona su representante desde Partner → Completar expediente. El personal de Datil configura el firmante institucional en el mismo apartado de la organización datil; el correo inicial es eraad@datil.com. Nombre, cédula, domicilio y correo deben estar completos. El cambio de firmante afecta nuevos contratos, no reescribe los existentes.

El personal revisa el PDF y usa Enviar a ambas partes para firma después de aprobar las condiciones. El contrato se crea como solicitud de firma de producción en la organización Datil, usando certificados propios de los representantes, con invitaciones y secuencia de firma del sistema existente. No hereda webhooks de integraciones externas. Se conservan versión, hashes, partes y referencia de la solicitud. Reintentar el mismo envío recupera la misma solicitud. Un cambio en representante, modalidad, margen, identidad jurídica o anexo invalida la comprobación de ese contrato para un nuevo lanzamiento; exige enviar y completar el contrato correspondiente a los nuevos datos.

Para terceros vinculados, el expediente recoge la solicitud, identificación del representante, certificado de votación cuando corresponda, nombramiento inscrito, constitución y reformas inscritas, cumplimiento de obligaciones y descripción de servicios. El contrato firmado acredita la relación contractual. El personal registra la revisión de cada documento; las excepciones aplicables a extranjeros o entidades públicas requieren justificación. Después de ambas firmas y la revisión, registra número, fecha y PDF del registro ARCOTEL. La plataforma conserva la evidencia y controla la habilitación; la presentación del trámite ante ARCOTEL se realiza por sus canales oficiales. Requisitos de ARCOTEL.

La firma del contrato es real aun cuando el portal del partner siga en pruebas. Una ceremonia de pruebas nunca satisface la habilitación legal. Publicar portal exige estas comprobaciones además de la configuración técnica y la prueba de integración.

Especificación del certificado

La especificación del certificado compara los dos certificados: vigencia, titular, uso previsto, clave privada, verificación de identidad, emisión, casos de certificado nuevo, garantías, exclusiones y cargos. Las páginas Certificados, Firma de documentos y Socios muestran la misma especificación, con los precios del catálogo y de la lista de firma. La edición 2.1 del Contrato de Servicios de Certificación y la edición 1.1 de los acuerdos de partners contienen la misma especificación; cada edición rige desde su publicación en Console → Acuerdos.

Antes de la venta, el partner entrega a cada cliente, por escrito o por un medio electrónico que el cliente pueda conservar, al menos esta información:

• el tipo de certificado y su vigencia;
• el precio total con impuestos y quién lo paga;
• los usos previstos y la condición de aceptación del SRI;
• que cada emisión se cobra, incluidos un certificado nuevo y un nuevo intento después de una interrupción;
• que Datil no puede recuperar la clave privada ni la contraseña;
• los casos de certificado nuevo y la revocación;
• la dirección de la especificación oficial, que el partner puede reproducir sin modificarla;
• el aviso de tratamiento de datos personales de Datil.

El partner no ofrece usos, plazos, recuperaciones ni garantías distintos de los de la especificación. Paga el titular o el firmante cuando el flujo de firma (payer: "signer") o la solicitud del certificado lo configuran; en los demás casos paga quien contrata: la organización que envía la solicitud de firma, o la organización o el distribuidor con billing_mode: "organization_billed" o "partner_billed".

Los certificados de Datil sirven para firmar comprobantes electrónicos del SRI. El SRI los acepta mientras mantenga actualizadas en sus sistemas las cadenas raíz e intermedias vigentes de Datil; esa actualización no depende de Datil. El estado de revocación se publica por OCSP en http://ocsp.datil.com y en la lista de certificados revocados.

Certificado de firma de documentos: una emisión por ceremonia

Una ceremonia es una persona en una solicitud de firma. Con mode: "transactional", o cuando el firmante elige el certificado incluido, la persona revisa todos sus documentos y acepta firmarlos; esa aceptación es su intención de firma y queda registrada. Después verifica su identidad, y la firma continúa sin otra revisión ni otro clic: la página de firma genera la clave en el navegador, descarga cada documento y comprueba que sea la versión revisada, Datil emite un certificado de uso único para esa ceremonia, y el navegador firma todos los documentos en un solo paso y borra la clave antes de enviar el primer documento firmado. Cada documento firmado se envía por partes, de modo que una conexión móvil lenta no interrumpe el envío. La clave no sale del navegador ni se entrega como archivo.

Los documentos firmados, nunca la clave, esperan cifrados en ese navegador hasta que Datil recibe cada uno, por un máximo de 24 horas, la vigencia del certificado. Una ventana privada no conserva esos documentos al cerrarse, así que la página de firma no permite aceptar y firmar en ella y pide abrir el enlace en una ventana normal. Cuando la página muestra Firmas listas se puede cerrar: abrir el enlace otra vez en el mismo navegador termina el envío, sin otra verificación de identidad, sin otra emisión y sin cargo. Datil comprueba que cada documento enviado sea exactamente el que firmó el navegador.

La primera emisión de una solicitud pagada por el remitente (payer: "requester") usa la reserva creada al enviar la solicitud. Cada emisión adicional reserva el precio de Certificado incluido en la misma fuente de fondos: billetera personal, unidad de paquete o saldo de la organización. En una solicitud pagada por el firmante (payer: "signer"), el pago del firmante cubre la primera emisión y las emisiones adicionales se cobran a la organización. Sin saldo suficiente no se emite el certificado y la página de firma informa el motivo.

Con un certificado propio (mode: "byo_cert"), no se emite un certificado: el firmante usa su archivo .p12 en el navegador y el servicio se cobra al completar la firma. Con tu certificado corresponde al remitente que firma sin verificación con cámara; Tu certificado + identidad, a los destinatarios que verifican su identidad.

Efectos en la API

• GET /api/v1/signature-requests/:reference_id no informa la interrupción ni la firma pendiente de envío como estados propios. La persona conserva un estado no final (invited, viewing o signing) y su enlace anterior muestra que la firma se interrumpió.
• Aprobar un nuevo intento cambia el signing_url de la persona por un enlace nuevo, con estado invited o waiting según el orden de firma.
• La organización solicitante es responsable del tratamiento de los datos del firmante y Datil es encargado, así que Datil usa solo los canales que la solicitud habilitó. Con send_invitations: true, Datil envía el enlace nuevo por correo. Con send_invitations: false, no envía correo: el detalle de la solicitud muestra el enlace con Copiar enlace.
• Si la solicitud tiene callback_url, Datil envía el evento signer.new_attempt_enabled con el enlace nuevo, con las mismas cabeceras y el mismo token Bearer de la organización que el callback final. X-Datil-Event-Type es signer.new_attempt_enabled y X-Datil-Event-Id es estable por persona e intento; deduplica por ese valor. El cuerpo contiene event_id, event_type, environment, reference_id, signer (national_id, name, email, order, status) y signing_url. Datil reintenta hasta cinco veces si no recibe una respuesta 2xx.
• El evento signer.signature_pending_upload usa la misma entrega que signer.new_attempt_enabled y el mismo cuerpo; su signing_url es el enlace que el firmante debe abrir en el mismo navegador. Datil lo envía una vez por persona e intento.
• El evento signer.new_attempt_requested usa la misma entrega y el mismo cuerpo, con reason (signer_lost_page) y sin signing_url: el enlace nuevo llega con signer.new_attempt_enabled cuando se aprueba el nuevo intento.
• El callback final de la solicitud se envía al completarse la solicitud. La interrupción y la aprobación constan en el historial de la solicitud del portal.
• En environment: "test" no se emiten certificados ni se cobra.

Credenciales y ambientes

Base canónica: https://edge.datil.com. Autenticación: Authorization: Bearer <API_KEY> con una llave de la organización y alcance certificates. Las llaves emitidas por Integraciones identifican la organización, se muestran una sola vez y pueden revocarse. El secreto del webhook es independiente de esta llave.

Pruebas y producción utilizan los mismos endpoints y mecanismo de autenticación. environment acepta test o production; omitirlo significa production. En consultas GET se envía como parámetro de URL; en POST como campo JSON. La idempotencia se delimita por organización, ambiente y reference_id. El mismo identificador puede existir en ambos ambientes sin compartir solicitud, enlace u orden.

Una llave con alcance certificates puede operar ambos ambientes. Crear dos llaves con nombres distintos ayuda a la operación, pero no impone una restricción por ambiente. La integración debe enviar environment explícitamente.

Productos y precio

GET /api/v1/certificate-products devuelve únicamente el catálogo activo del portal:

Para tercero vinculado, el neto se calcula con la misma regla que la liquidación: tarifa base Datil para tipo y vigencia, menos el porcentaje de margen configurado. La consulta no fija ni reserva una tarifa. El precio minorista no es necesariamente el precio que Datil cobra al partner. Un valor null requiere confirmar las condiciones comerciales; no significa que el certificado sea gratuito.

billing_mode: "partner_billed" marca la orden como pagada sin crear un intento de pago ni exigir checkout al titular. No crea un cronograma de cuotas. El importe mostrado en payment.amount_cents pertenece a la orden del portal, no a la liquidación del partner. El devengo de tercero vinculado se produce al emitir el certificado. La modalidad comercial y el precio deben estar acordados y configurados para la organización.

La empresa paga; el titular recibe el certificado

Usa billing_mode: "organization_billed" para empleados o beneficiarios sin reventa. La empresa necesita saldo general suficiente y su razón social y RUC configurados. El titular conserva el control de su identidad y de su clave privada; no vuelve a pasar por checkout.

La creación fija la tarifa minorista Datil por tipo y vigencia, el IVA y los datos fiscales de la empresa. Los precios personalizados del portal y los descuentos de distribuidor no alteran esa compra. payment.amount_cents muestra el total fijado, incluido IVA. Repetir la referencia conserva esa cotización.

El saldo se debita una sola vez cuando el titular abre por primera vez la solicitud de producción. Sin saldo suficiente, la solicitud permanece pendiente y su enlace no se consume: la empresa recarga y el titular reintenta, iniciando sesión si ya tiene cuenta. La orden pagada entra en la conciliación fiscal de Datil y se factura a la empresa financiadora; el proceso requiere la configuración del emisor y el servicio fiscal disponibles. No genera una venta ni comisión en la contabilidad del distribuidor. Si cambia la tasa fiscal y la orden ya no coincide con el total fijado, no se debita; crea una nueva solicitud con otra referencia.

organization_billing_details_required indica que faltan los datos fiscales de la empresa; funding_price_unavailable indica que no hay una tarifa válida. En environment: "test" no se debita saldo ni se crea una orden de emisión real. Los webhooks de prueba sí se entregan.

Esta modalidad no concede permiso para revender certificados o facturarlos al beneficiario. Para ese modelo se requiere partner_billed y el alta de tercero vinculado.

Configuración de precios

En el portal de la organización, Administración → Certificados a la venta (/admin/certificate-products) configura el precio minorista por tipo de titular y vigencia. «Completar precios vacíos» prepara un borrador con la lista Datil o el precio predeterminado; no activa productos ni guarda cambios. El operador revisa las vigencias y pulsa Guardar.

La lista base de Datil se administra en su propio portal, en la misma pantalla. Los valores predeterminados de persona natural son USD 4,50 / 4,99 / 8,49 / 14,49 / 21,49 / 28,49 / 34,99 para d7 / m1 / y1 / y2 / y3 / y4 / y5. Para representante legal y miembro de empresa son USD 14,99 / 19,99 / 26,99 / 33,99 / 39,99 para uno a cinco años. Todos son precios minoristas antes de impuestos; el catálogo configurado tiene prioridad. Un producto vinculado a un plan toma su precio de Console → Precios (/prices) para ese plan y mercado.

El personal de Datil configura la modalidad y el margen del partner en Configuración → Partner (/admin/settings/partner). El partner no puede asignarse su propio descuento. El margen vacío no aplica una tarifa mayorista por defecto: indica que faltan condiciones comerciales. Los enlaces a catálogo, términos y credenciales están reunidos en Console → Partners. El secreto de API se emite desde Configuración → Integración (/admin/settings/integration).

Procedimiento de pruebas

1. Obtener una llave de la organización y consultar el catálogo. Seleccionar un producto existente.
2. Crear la solicitud con environment: "test", una referencia propia, una cédula válida, correo del titular, un callback HTTPS público y un secreto aleatorio de 32 a 256 bytes.
3. Entregar la URL devuelta al titular. Una cuenta existente debe iniciar sesión; una cuenta diferente no puede apropiarse del trámite.
4. Aceptar el procesamiento temporal, verificar la identidad con Registro Civil y completar la prueba de vida real. Los servicios de verificación deben estar disponibles y pueden aplicar sus límites operativos.
5. Completar la prueba y recibir certificate_request.test_completed. Consultar el resultado usando ?environment=test.
6. Comprobar la firma del webhook, el rechazo de un cuerpo alterado, la deduplicación por event_id y el reenvío mediante retry-callback.

El ensayo no crea una orden de certificado, genera llaves, emite certificados, firma documentos, cobra ni entrega certificados a un sistema externo. fulfillment se desactiva en pruebas. Datil mantiene los datos aportados en la solicitud, la cuenta del titular, los tiempos de apertura/completado y el historial de entrega. Las fotografías, la respuesta de Registro Civil y los resultados biométricos no se persisten en Datil: se procesan temporalmente en la sesión. Esto no es una promesa sobre las políticas de retención de los proveedores de verificación.

El ensayo valida identidad e integración; no reproduce la revisión jurídica de documentos de representante legal ni la emisión ante la autoridad certificadora. Recargar antes de completar requiere repetir la verificación de identidad. Una verificación completada tiene cinco minutos de validez para finalizar el ensayo.

Ejemplo de cuerpo para POST /api/v1/certificate-requests (los datos y el secreto son ilustrativos):

{
  "reference_id": "CERT-PRUEBA-001",
  "environment": "test",
  "holder": {
    "national_id": "0919372607",
    "name": "Juan Pérez",
    "email": "juan@example.com"
  },
  "validity": "y1",
  "cert_type": "persona_natural",
  "billing_mode": "partner_billed",
  "callback_url": "https://partner.example.com/webhooks/certificados",
  "callback_secret": "reemplazar-por-un-secreto-aleatorio-de-al-menos-32-bytes"
}

La respuesta 201 contiene reference_id, certificate_request_id, url, status, environment y link_expires_at, además de ok. Repetir la misma referencia devuelve la solicitud existente y no modifica sus datos ni su secreto.

Estados y recuperación

GET /api/v1/certificate-requests/:reference_id devuelve tres dimensiones distintas:

order es null antes de abrir producción y siempre en pruebas. En producción, order.status puede ser exactamente:

selecting, awaiting_payment, paid, verifying_identity, uploading_documents, pending_review, generating_keys, issuing, issued, issuance_interrupted, active, expired, revoked, refunded, discarded, rejected.

delivery.status es not_configured, pending, delivered o failed. Incluye event_id, response_code y authenticated (hay un secreto configurado; no es confirmación de que el receptor haya verificado la firma). callback_delivered confirma que se recibió una respuesta HTTP 2xx.

next_action puede ser open_url, regenerate_link, resume_verification, complete_payment, await_review, await_issuance o none. La expiración del enlace no cambia el estado de la solicitud.

Abandonar la página no borra la solicitud ni crea un estado abandoned; se conserva el último estado. Un fallo recuperable de identidad permite corregir datos o repetir la cámara dentro del trámite. En producción, una negativa de revisión se refleja en order.status: rejected; una nueva solicitud requiere otra referencia y la resolución comercial correspondiente. Reabrir o regenerar un enlace no crea una orden adicional ni repite un pago.

Los webhooks notifican la emisión o la finalización del ensayo, no cada paso de identidad, abandono o revisión. Para esos estados se consulta la API. certificate es null hasta que existe un certificado y siempre en pruebas. Sus campos públicos son serial, cert_type, validity, issued_at y expires_at.

Certificado nuevo del titular

El titular necesita un certificado nuevo cuando el certificado expira (order.status: expired), cuando pierde el archivo o la contraseña, cuando la clave privada se compromete y cuando cambian los datos del certificado, incluida la representación legal. En caso de pérdida, compromiso o cambio de datos, el titular solicita la revocación (order.status: revoked). Datil no puede recuperar la clave privada ni la contraseña.

Un certificado nuevo es una solicitud nueva, con otra reference_id, una nueva verificación de identidad y una nueva emisión, que se cobra al precio del catálogo para el tipo y la vigencia elegidos. Con partner_billed, Datil factura al distribuidor cada emisión. La revocación anticipada no devuelve el precio.

Entrega del certificado

El titular acepta en una sola pantalla dos consentimientos separados, sin marcar de antemano: el tratamiento de datos, incluida la biometría, y el contrato de servicios. Cada aceptación queda registrada por separado. Antes de la emisión crea la contraseña del archivo: de 8 a 128 caracteres ASCII imprimibles, sin contraseñas comunes, con la opción de generar una frase. También confirma que Datil no guarda esa contraseña ni puede recuperarla.

La clave se genera en el navegador del titular cuando se abre la pantalla de la contraseña. Emitir y descargar mi certificado envía la solicitud de firma de certificado, recibe el certificado y arma el archivo .p12 en la página. El empaquetado sigue el perfil de la orden; el predeterminado es el compatible, que FirmaEC abre. El archivo no se descarga solo: la pantalla de descarga muestra dos declaraciones sin marcar, «Entiendo que Dátil no guarda una copia de mi certificado ni de su contraseña» y «Guardaré el archivo y la contraseña en un lugar seguro», y el botón Descargar mi certificado, que se activa cuando el titular acepta ambas.

Ese clic es la entrega. Datil registra quién lo hizo, cuándo, desde qué IP y navegador, y el texto exacto de cada declaración con su SHA-256. Después la página muestra el nombre del archivo, dónde quedó y Descargar de nuevo, que funciona mientras la página siga abierta; cada descarga queda registrada. Listo es opcional: borra la clave y el archivo de la memoria de la página, igual que cerrarla. Datil no conserva copias. El correo de entrega se envía después de la entrega y no contiene el archivo ni la contraseña.

Si la página se cierra después de la emisión y antes de ese clic, la orden pasa a issuance_interrupted cuando termina el periodo de gracia: 2 minutos, o 30 minutos si la página estaba oculta cuando se perdió la conexión, por ejemplo al cambiar de aplicación en el teléfono. La misma página puede volver dentro de ese periodo y continuar. Después de la entrega, cerrar la página no interrumpe nada. Una nueva emisión requiere la aprobación del personal de Datil o de un propietario o administrador de la organización vendedora. La aprobación revoca el certificado perdido, que no se elimina, y la nueva emisión se cobra.

Los navegadores integrados en aplicaciones, como WhatsApp o Instagram, piden abrir el enlace en el navegador del dispositivo antes de la emisión.

La consulta y el webhook contienen metadatos del certificado. Nunca incluyen el archivo .p12 ni su contraseña.

Enlace de un solo uso

La primera apertura autorizada consume el acceso anónimo. En producción, consumir el enlace y crear la orden se realiza en una transacción: si falla la creación, el enlace sigue sin consumir. El mismo titular con sesión puede reanudar la orden. Otra persona recibe 410; si ya existe la cuenta del titular, se exige iniciar sesión antes de consumir el enlace.

Los enlaces nuevos vencen a los siete días; los enlaces antiguos sin vencimiento conservan su comportamiento. Para invalidar el token anterior y obtener otro:

POST /api/v1/certificate-requests/CERT-PRUEBA-001/regenerate-link
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"environment":"test"}

Devuelve 200 con url y link_expires_at. El nuevo enlace dura siete días y conserva la solicitud, la orden y el pago. Si el trámite ya estaba abierto, el titular debe tener sesión; la regeneración no concede un segundo acceso anónimo. Un token reemplazado responde 404. Una solicitud finalizada, rechazada, descartada, reembolsada o en emisión responde 409 request_not_resumable. No debe usarse una referencia nueva para recuperar un trámite pagado.

Webhooks autenticados

Al crear la solicitud, enviar callback_secret activa HMAC-SHA256. El secreto se almacena cifrado y no aparece en respuestas de la API. Si se omite, el webhook se envía sin firma; las integraciones que requieren autenticación deben configurarlo desde la creación. No se envía la API key al callback.

Cabeceras:

X-Datil-Signature: t=<segundos Unix>,v1=<hexadecimal HMAC-SHA256>
X-Datil-Event-Id: <tipo de evento>:<certificate_request_id>
X-Datil-Event-Type: certificate_request.issued | certificate_request.test_completed
X-Datil-Environment: production | test

La firma cubre timestamp + "." + cuerpo HTTP original, codificado en UTF-8. Verificar el cuerpo sin parsearlo ni volverlo a serializar, comparar en tiempo constante y rechazar timestamps fuera de una tolerancia de cinco minutos con reloj sincronizado. El ambiente y el tipo del evento también están dentro del cuerpo firmado; validar esos valores después de verificarlo. Los identificadores son estables entre intentos y reenvíos manuales: deduplicar por event_id.

Verificación con Node.js, antes de procesar JSON:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyDatilWebhook(rawBody, header, secret, now = Date.now()) {
  if (!Buffer.isBuffer(rawBody) || typeof header !== "string") return false;
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header);
  if (!match) return false;
  const timestamp = Number(match[1]);
  if (!Number.isSafeInteger(timestamp) || Math.abs(now / 1000 - timestamp) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(match[1] + ".")
    .update(rawBody)
    .digest();
  return timingSafeEqual(expected, Buffer.from(match[2], "hex"));
}

Ejemplo de resultado de producción (solo metadatos; nunca incluye el .p12 ni su contraseña):

{
  "event_id": "certificate_request.issued:6b1d0f4a-7c2e-4b8d-9f1a-3e5c7a9b1d3f",
  "event_type": "certificate_request.issued",
  "environment": "production",
  "reference_id": "CERT-001",
  "status": "issued",
  "holder": {"national_id": "0919372607", "name": "Juan Pérez", "email": "juan@example.com"},
  "certificate": {"serial": "123456", "cert_type": "persona_natural", "validity": "y1", "issued_at": "2026-09-21T14:00:00Z", "expires_at": "2027-09-21T14:00:00Z"},
  "order": {"id": "2f7c9b1e-5a3d-4e8f-9c1b-7d5a3e1f9b7c", "status": "issued"}
}

El cuerpo incluye event_id, event_type, environment, reference_id, status, holder, certificate y order. En pruebas, status es test_completed y los dos últimos campos son null; nunca se representa un certificado de prueba como emitido.

Un 2xx confirma la entrega. El receptor debe guardar/deduplicar el evento antes de confirmar y procesarlo de forma asíncrona. Datil realiza hasta cinco intentos, con esperas de 60, 120, 240 y 480 segundos tras los fallos, más la latencia de cola; el timeout HTTP es de 30 segundos. Una URL bloqueada por las reglas de salida se cancela sin agotar los cinco intentos.

Para reencolar el mismo evento terminado:

POST /api/v1/certificate-requests/CERT-PRUEBA-001/retry-callback
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"environment":"test"}

Responde 202 con el event_id; no repite verificación, emisión ni cobro. Una solicitud sin resultado o sin callback responde 409 delivery_not_available. Repetir mientras hay un job en curso lo deduplica. Una respuesta 202 no implica entrega: consultar delivery.

El contrato JSON completo se publica en GET /api/v1/openapi con autenticación de la organización.