Documentación de la API API v1
Documentación

Flujos

Un flujo es un tipo de solicitud: su URL de entrada, su política (verificación de identidad, OTP, cadena de confianza, pago, validez, evidencia), la entrega del resultado a tu sistema y la transformación de formatos. Estas rutas administran todo lo que la consola permite configurar, con las mismas reglas. La llave necesita el alcance settings (o ningún alcance). Nunca devolvemos un secreto: la contraseña de entrega, la clave del endpoint de token y la API key del flujo se escriben, pero no se leen; la respuesta dice si existen y cuándo se emitieron. Cada cambio sube version ; una solicitud conserva la versión con la que se creó. Los errores 422 traen errors , una lista de código:campo ( invalid_value , out_of_range , invalid_email , required , unknown_field , not_an_object , unknown_price_key , immutable , taken , must_be_public_https ).

Listar los flujos#

GET /api/v1/flows Bearer

Todos los flujos de tu organización, incluido el flujo por defecto direct-signing .

Devuelve · 200 con los flujos · 401 sin llave válida o sin el alcance settings .

cURL 
curl "https://edge.datil.com/api/v1/flows" \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 200 
{
  "ok": true,
  "flows": [
    {
      "slug": "credito",
      "name": "Crédito de consumo",
      "description": "Contrato y pagaré de un crédito.",
      "active": true,
      "version": 1,
      "ingress_url": "https://acme.datil.id/i/acme/credito",
      "token_url": "https://acme.datil.id/i/acme/credito/token",
      "requires_otp": false,
      "identity_checks": {
        "id_card": "front_and_back",
        "active_challenge": true,
        "face_quality": true,
        "face_match_threshold": 95.0,
        "environment": "adapt",
        "signature_graphic": true,
        "max_attempts": 3,
        "review_emails": [
          "cumplimiento@example.com"
        ]
      },
      "required_checks": [
        "registry",
        "environment",
        "id_card_front",
        "id_card_back",
        "active_challenge",
        "liveness",
        "face_quality",
        "face_match",
        "signature_graphic"
      ],
      "trust_chain": "transactional",
      "ca_lineage": null,
      "csr_profile": null,
      "cert_holder": "any",
      "payer": "requester",
      "requires_payment": false,
      "price_key": null,
      "validity_window_hours": 72,
      "completion_copy_emails": [
        "operaciones@example.com"
      ],
      "attach_biometric_evidence": true,
      "delivery": {
        "url": "https://tu-sistema.com/firmas/recibir",
        "auth_user": "datil",
        "auth_header": "Authorization",
        "auth_password_set": true
      },
      "signature_placement": {
        "origin": "bottom_left",
        "unit": "cm",
        "page_height_cm": 27.2,
        "page": null,
        "x": null,
        "y": null,
        "anchor": "bottom_right",
        "pages": "last",
        "x_path": null,
        "y_path": null,
        "page_path": null
      },
      "transform": {
        "inbound_mapping": {
          "reference_id": "$.no_de_tramite"
        },
        "outbound_template": {
          "no_de_tramite": "{{reference_id}}"
        },
        "inbound_auth": {
          "type": "bearer"
        },
        "inbound_response": {
          "link": "{{signing_url}}"
        }
      },
      "credentials": {
        "username": null,
        "password_set": false,
        "password_set_at": null,
        "api_key_set": false,
        "api_key_set_at": null
      },
      "created_at": "2026-08-25T14:05:00Z",
      "updated_at": "2026-08-25T14:05:00Z"
    }
  ]
}

Crear un flujo#

POST /api/v1/flows Bearer

Crea el tipo de solicitud. Su URL de entrada es ingress_url ; los campos que no envías toman su valor por defecto.

Content-Type: application/json

Cuerpo de la solicitud

slug string requerido

Clave del flujo en la URL de entrada: minúsculas, números y guiones, hasta 63. Inmutable: se envía solo al crear.

name string requerido

Nombre del tipo de solicitud.

description string

Descripción libre.

active boolean

false : la URL de entrada deja de recibir solicitudes.

requires_otp boolean

Exige un código por SMS antes de firmar.

identity_checks objeto

La verificación de identidad. Ver «La configuración identity_checks». Los campos que no envías conservan su valor; null vuelve a la base.

trust_chain string

Certificado por defecto: emitido por Datil, propio del firmante o a su elección.

transactionalbyo_certsigner_choice

ca_lineage string

CA del certificado de un solo uso. null hereda el perfil de la organización.

newlegacy

csr_profile string

Estructura del certificado que genera el navegador. null hereda.

newlegacy

cert_holder string

Con certificado propio: personal, de empresa o cualquiera.

anypersoncompany

payer string

signer : se cobra al firmante antes de firmar.

requestersigner

price_key string

Clave de un precio del catálogo de tu organización. null : el precio por defecto.

validity_window_hours integer

Horas que la solicitud puede firmarse tras crearse. Al menos 1.

completion_copy_emails array

Correos que reciben el paquete firmado al completarse la solicitud.

attach_biometric_evidence boolean

Agrega la evidencia biométrica como documento firmado y la entrega como archivo_biometria .

delivery objeto

La entrega del resultado a tu web service.

delivery.url string

URL HTTPS pública que recibe el resultado.

delivery.auth_user string

Usuario de HTTP Basic.

delivery.auth_password string

Contraseña de HTTP Basic. Se guarda cifrada y nunca se devuelve; null la borra.

delivery.auth_header string

Nombre del header de autenticación. Por defecto Authorization .

signature_placement objeto

Dónde va el sello en cada solicitud del flujo: origin ( top_left , bottom_left ), unit ( cm , mm , pt ), page_height_cm , y coordenadas fijas ( page , x , y , anchor , pages : all o last ) o las rutas para leerlas de cada documento ( x_path , y_path , page_path ). null : se usa lo que envía cada documento.

transform objeto

Transformación declarativa de formatos: inbound_mapping , outbound_template , inbound_auth , inbound_response . Cada uno es un objeto; null lo vacía.

Devuelve · 201 con el flujo · 422 con errors (por ejemplo out_of_range:identity_checks.max_attempts , taken:slug ).

cURL 
curl -X POST https://edge.datil.com/api/v1/flows \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "credito",
  "name": "Crédito de consumo",
  "description": "Contrato y pagaré de un crédito.",
  "requires_otp": false,
  "identity_checks": {
    "id_card": "front_and_back",
    "active_challenge": true,
    "face_quality": true,
    "face_match_threshold": 95,
    "environment": "adapt",
    "signature_graphic": true,
    "max_attempts": 3,
    "review_emails": [
      "cumplimiento@example.com"
    ]
  },
  "trust_chain": "transactional",
  "payer": "requester",
  "validity_window_hours": 72,
  "completion_copy_emails": [
    "operaciones@example.com"
  ],
  "attach_biometric_evidence": true,
  "delivery": {
    "url": "https://tu-sistema.com/firmas/recibir",
    "auth_user": "datil",
    "auth_password": "s3creta"
  },
  "signature_placement": {
    "origin": "bottom_left",
    "unit": "cm",
    "anchor": "bottom_right",
    "pages": "last"
  },
  "transform": {
    "inbound_mapping": {
      "reference_id": "$.no_de_tramite"
    },
    "outbound_template": {
      "no_de_tramite": "{{reference_id}}"
    },
    "inbound_auth": {
      "type": "bearer"
    },
    "inbound_response": {
      "link": "{{signing_url}}"
    }
  }
}'
Respuesta · 201 
{
  "ok": true,
  "flow": {
    "slug": "credito",
    "name": "Crédito de consumo",
    "description": "Contrato y pagaré de un crédito.",
    "active": true,
    "version": 1,
    "ingress_url": "https://acme.datil.id/i/acme/credito",
    "token_url": "https://acme.datil.id/i/acme/credito/token",
    "requires_otp": false,
    "identity_checks": {
      "id_card": "front_and_back",
      "active_challenge": true,
      "face_quality": true,
      "face_match_threshold": 95.0,
      "environment": "adapt",
      "signature_graphic": true,
      "max_attempts": 3,
      "review_emails": [
        "cumplimiento@example.com"
      ]
    },
    "required_checks": [
      "registry",
      "environment",
      "id_card_front",
      "id_card_back",
      "active_challenge",
      "liveness",
      "face_quality",
      "face_match",
      "signature_graphic"
    ],
    "trust_chain": "transactional",
    "ca_lineage": null,
    "csr_profile": null,
    "cert_holder": "any",
    "payer": "requester",
    "requires_payment": false,
    "price_key": null,
    "validity_window_hours": 72,
    "completion_copy_emails": [
      "operaciones@example.com"
    ],
    "attach_biometric_evidence": true,
    "delivery": {
      "url": "https://tu-sistema.com/firmas/recibir",
      "auth_user": "datil",
      "auth_header": "Authorization",
      "auth_password_set": true
    },
    "signature_placement": {
      "origin": "bottom_left",
      "unit": "cm",
      "page_height_cm": 27.2,
      "page": null,
      "x": null,
      "y": null,
      "anchor": "bottom_right",
      "pages": "last",
      "x_path": null,
      "y_path": null,
      "page_path": null
    },
    "transform": {
      "inbound_mapping": {
        "reference_id": "$.no_de_tramite"
      },
      "outbound_template": {
        "no_de_tramite": "{{reference_id}}"
      },
      "inbound_auth": {
        "type": "bearer"
      },
      "inbound_response": {
        "link": "{{signing_url}}"
      }
    },
    "credentials": {
      "username": null,
      "password_set": false,
      "password_set_at": null,
      "api_key_set": false,
      "api_key_set_at": null
    },
    "created_at": "2026-08-25T14:05:00Z",
    "updated_at": "2026-08-25T14:05:00Z"
  }
}

Consultar un flujo#

GET /api/v1/flows/:slug Bearer

Toda la configuración del flujo, sin secretos.

Parámetros

slug string requerido

La clave del flujo.

Devuelve · 200 con el flujo · 404 not_found .

cURL 
curl "https://edge.datil.com/api/v1/flows/:slug" \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 200 
{
  "ok": true,
  "flow": {
    "slug": "credito",
    "name": "Crédito de consumo",
    "description": "Contrato y pagaré de un crédito.",
    "active": true,
    "version": 1,
    "ingress_url": "https://acme.datil.id/i/acme/credito",
    "token_url": "https://acme.datil.id/i/acme/credito/token",
    "requires_otp": false,
    "identity_checks": {
      "id_card": "front_and_back",
      "active_challenge": true,
      "face_quality": true,
      "face_match_threshold": 95.0,
      "environment": "adapt",
      "signature_graphic": true,
      "max_attempts": 3,
      "review_emails": [
        "cumplimiento@example.com"
      ]
    },
    "required_checks": [
      "registry",
      "environment",
      "id_card_front",
      "id_card_back",
      "active_challenge",
      "liveness",
      "face_quality",
      "face_match",
      "signature_graphic"
    ],
    "trust_chain": "transactional",
    "ca_lineage": null,
    "csr_profile": null,
    "cert_holder": "any",
    "payer": "requester",
    "requires_payment": false,
    "price_key": null,
    "validity_window_hours": 72,
    "completion_copy_emails": [
      "operaciones@example.com"
    ],
    "attach_biometric_evidence": true,
    "delivery": {
      "url": "https://tu-sistema.com/firmas/recibir",
      "auth_user": "datil",
      "auth_header": "Authorization",
      "auth_password_set": true
    },
    "signature_placement": {
      "origin": "bottom_left",
      "unit": "cm",
      "page_height_cm": 27.2,
      "page": null,
      "x": null,
      "y": null,
      "anchor": "bottom_right",
      "pages": "last",
      "x_path": null,
      "y_path": null,
      "page_path": null
    },
    "transform": {
      "inbound_mapping": {
        "reference_id": "$.no_de_tramite"
      },
      "outbound_template": {
        "no_de_tramite": "{{reference_id}}"
      },
      "inbound_auth": {
        "type": "bearer"
      },
      "inbound_response": {
        "link": "{{signing_url}}"
      }
    },
    "credentials": {
      "username": null,
      "password_set": false,
      "password_set_at": null,
      "api_key_set": false,
      "api_key_set_at": null
    },
    "created_at": "2026-08-25T14:05:00Z",
    "updated_at": "2026-08-25T14:05:00Z"
  }
}

Modificar un flujo#

PATCH /api/v1/flows/:slug Bearer

Cambia solo los campos que envías. Dentro de identity_checks , delivery y transform , también solo los que envías; signature_placement se reemplaza completo. Las solicitudes ya creadas conservan la versión anterior.

Content-Type: application/json

Parámetros

slug string requerido

La clave del flujo.

Cuerpo de la solicitud

name string

Nombre del tipo de solicitud.

description string

Descripción libre.

active boolean

false : la URL de entrada deja de recibir solicitudes.

requires_otp boolean

Exige un código por SMS antes de firmar.

identity_checks objeto

La verificación de identidad. Ver «La configuración identity_checks». Los campos que no envías conservan su valor; null vuelve a la base.

trust_chain string

Certificado por defecto: emitido por Datil, propio del firmante o a su elección.

transactionalbyo_certsigner_choice

ca_lineage string

CA del certificado de un solo uso. null hereda el perfil de la organización.

newlegacy

csr_profile string

Estructura del certificado que genera el navegador. null hereda.

newlegacy

cert_holder string

Con certificado propio: personal, de empresa o cualquiera.

anypersoncompany

payer string

signer : se cobra al firmante antes de firmar.

requestersigner

price_key string

Clave de un precio del catálogo de tu organización. null : el precio por defecto.

validity_window_hours integer

Horas que la solicitud puede firmarse tras crearse. Al menos 1.

completion_copy_emails array

Correos que reciben el paquete firmado al completarse la solicitud.

attach_biometric_evidence boolean

Agrega la evidencia biométrica como documento firmado y la entrega como archivo_biometria .

delivery objeto

La entrega del resultado a tu web service.

delivery.url string

URL HTTPS pública que recibe el resultado.

delivery.auth_user string

Usuario de HTTP Basic.

delivery.auth_password string

Contraseña de HTTP Basic. Se guarda cifrada y nunca se devuelve; null la borra.

delivery.auth_header string

Nombre del header de autenticación. Por defecto Authorization .

signature_placement objeto

Dónde va el sello en cada solicitud del flujo: origin ( top_left , bottom_left ), unit ( cm , mm , pt ), page_height_cm , y coordenadas fijas ( page , x , y , anchor , pages : all o last ) o las rutas para leerlas de cada documento ( x_path , y_path , page_path ). null : se usa lo que envía cada documento.

transform objeto

Transformación declarativa de formatos: inbound_mapping , outbound_template , inbound_auth , inbound_response . Cada uno es un objeto; null lo vacía.

Devuelve · 200 con el flujo · 422 con errors ( immutable:slug si intentas cambiar la clave) · 404 not_found .

cURL 
curl -X PATCH https://edge.datil.com/api/v1/flows/:slug \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "identity_checks": {
    "max_attempts": 5,
    "face_match_threshold": 97.5
  },
  "validity_window_hours": 48
}'
Respuesta · 200 
{
  "ok": true,
  "flow": {
    "slug": "credito",
    "name": "Crédito de consumo",
    "description": "Contrato y pagaré de un crédito.",
    "active": true,
    "version": 1,
    "ingress_url": "https://acme.datil.id/i/acme/credito",
    "token_url": "https://acme.datil.id/i/acme/credito/token",
    "requires_otp": false,
    "identity_checks": {
      "id_card": "front_and_back",
      "active_challenge": true,
      "face_quality": true,
      "face_match_threshold": 95.0,
      "environment": "adapt",
      "signature_graphic": true,
      "max_attempts": 3,
      "review_emails": [
        "cumplimiento@example.com"
      ]
    },
    "required_checks": [
      "registry",
      "environment",
      "id_card_front",
      "id_card_back",
      "active_challenge",
      "liveness",
      "face_quality",
      "face_match",
      "signature_graphic"
    ],
    "trust_chain": "transactional",
    "ca_lineage": null,
    "csr_profile": null,
    "cert_holder": "any",
    "payer": "requester",
    "requires_payment": false,
    "price_key": null,
    "validity_window_hours": 72,
    "completion_copy_emails": [
      "operaciones@example.com"
    ],
    "attach_biometric_evidence": true,
    "delivery": {
      "url": "https://tu-sistema.com/firmas/recibir",
      "auth_user": "datil",
      "auth_header": "Authorization",
      "auth_password_set": true
    },
    "signature_placement": {
      "origin": "bottom_left",
      "unit": "cm",
      "page_height_cm": 27.2,
      "page": null,
      "x": null,
      "y": null,
      "anchor": "bottom_right",
      "pages": "last",
      "x_path": null,
      "y_path": null,
      "page_path": null
    },
    "transform": {
      "inbound_mapping": {
        "reference_id": "$.no_de_tramite"
      },
      "outbound_template": {
        "no_de_tramite": "{{reference_id}}"
      },
      "inbound_auth": {
        "type": "bearer"
      },
      "inbound_response": {
        "link": "{{signing_url}}"
      }
    },
    "credentials": {
      "username": null,
      "password_set": false,
      "password_set_at": null,
      "api_key_set": false,
      "api_key_set_at": null
    },
    "created_at": "2026-08-25T14:05:00Z",
    "updated_at": "2026-08-25T14:05:00Z"
  }
}

Eliminar un flujo#

DELETE /api/v1/flows/:slug Bearer

Su URL de entrada deja de recibir solicitudes. Las solicitudes creadas conservan la configuración con la que se crearon. El flujo por defecto no se elimina.

Parámetros

slug string requerido

La clave del flujo.

Devuelve · 200 · 409 default_flow · 404 not_found .

cURL 
curl -X DELETE https://edge.datil.com/api/v1/flows/:slug \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 200 
{
  "ok": true,
  "slug": "credito",
  "deleted": true
}

Emitir usuario y clave del endpoint de token#

POST /api/v1/flows/:slug/credentials/token Bearer

Las credenciales con las que tu sistema pide un token en token_url . La clave se devuelve una sola vez; guardamos solo su hash. Emitir de nuevo reemplaza la anterior.

Content-Type: application/json

Parámetros

slug string requerido

La clave del flujo.

Cuerpo de la solicitud

username string requerido

El usuario.

Devuelve · 201 con el usuario y la clave · 422 required:username · 404 not_found .

cURL 
curl -X POST https://edge.datil.com/api/v1/flows/:slug/credentials/token \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "core_bancario"
}'
Respuesta · 201 
{
  "ok": true,
  "username": "core_bancario",
  "password": "Zt6m1Kq8xW3pR0vY9cB2nA",
  "flow": {
    "slug": "credito",
    "name": "Crédito de consumo",
    "description": "Contrato y pagaré de un crédito.",
    "active": true,
    "version": 1,
    "ingress_url": "https://acme.datil.id/i/acme/credito",
    "token_url": "https://acme.datil.id/i/acme/credito/token",
    "requires_otp": false,
    "identity_checks": {
      "id_card": "front_and_back",
      "active_challenge": true,
      "face_quality": true,
      "face_match_threshold": 95.0,
      "environment": "adapt",
      "signature_graphic": true,
      "max_attempts": 3,
      "review_emails": [
        "cumplimiento@example.com"
      ]
    },
    "required_checks": [
      "registry",
      "environment",
      "id_card_front",
      "id_card_back",
      "active_challenge",
      "liveness",
      "face_quality",
      "face_match",
      "signature_graphic"
    ],
    "trust_chain": "transactional",
    "ca_lineage": null,
    "csr_profile": null,
    "cert_holder": "any",
    "payer": "requester",
    "requires_payment": false,
    "price_key": null,
    "validity_window_hours": 72,
    "completion_copy_emails": [
      "operaciones@example.com"
    ],
    "attach_biometric_evidence": true,
    "delivery": {
      "url": "https://tu-sistema.com/firmas/recibir",
      "auth_user": "datil",
      "auth_header": "Authorization",
      "auth_password_set": true
    },
    "signature_placement": {
      "origin": "bottom_left",
      "unit": "cm",
      "page_height_cm": 27.2,
      "page": null,
      "x": null,
      "y": null,
      "anchor": "bottom_right",
      "pages": "last",
      "x_path": null,
      "y_path": null,
      "page_path": null
    },
    "transform": {
      "inbound_mapping": {
        "reference_id": "$.no_de_tramite"
      },
      "outbound_template": {
        "no_de_tramite": "{{reference_id}}"
      },
      "inbound_auth": {
        "type": "bearer"
      },
      "inbound_response": {
        "link": "{{signing_url}}"
      }
    },
    "credentials": {
      "username": null,
      "password_set": false,
      "password_set_at": null,
      "api_key_set": false,
      "api_key_set_at": null
    },
    "created_at": "2026-08-25T14:05:00Z",
    "updated_at": "2026-08-25T14:05:00Z"
  }
}

Emitir la API key del flujo#

POST /api/v1/flows/:slug/credentials/api-key Bearer

La llave Bearer de la URL de entrada (autenticación bearer ). Se devuelve una sola vez; emitir de nuevo reemplaza la anterior.

Content-Type: application/json

Parámetros

slug string requerido

La clave del flujo.

Devuelve · 201 con la llave · 404 not_found .

cURL 
curl -X POST https://edge.datil.com/api/v1/flows/:slug/credentials/api-key \
  -H "Authorization: Bearer $DATIL_API_KEY"
Respuesta · 201 
{
  "ok": true,
  "api_key": "q9W2eR7tY1uI8oP3aS6dF0gH5jK4lZ2xC7vB1nM9",
  "flow": {
    "slug": "credito",
    "name": "Crédito de consumo",
    "description": "Contrato y pagaré de un crédito.",
    "active": true,
    "version": 1,
    "ingress_url": "https://acme.datil.id/i/acme/credito",
    "token_url": "https://acme.datil.id/i/acme/credito/token",
    "requires_otp": false,
    "identity_checks": {
      "id_card": "front_and_back",
      "active_challenge": true,
      "face_quality": true,
      "face_match_threshold": 95.0,
      "environment": "adapt",
      "signature_graphic": true,
      "max_attempts": 3,
      "review_emails": [
        "cumplimiento@example.com"
      ]
    },
    "required_checks": [
      "registry",
      "environment",
      "id_card_front",
      "id_card_back",
      "active_challenge",
      "liveness",
      "face_quality",
      "face_match",
      "signature_graphic"
    ],
    "trust_chain": "transactional",
    "ca_lineage": null,
    "csr_profile": null,
    "cert_holder": "any",
    "payer": "requester",
    "requires_payment": false,
    "price_key": null,
    "validity_window_hours": 72,
    "completion_copy_emails": [
      "operaciones@example.com"
    ],
    "attach_biometric_evidence": true,
    "delivery": {
      "url": "https://tu-sistema.com/firmas/recibir",
      "auth_user": "datil",
      "auth_header": "Authorization",
      "auth_password_set": true
    },
    "signature_placement": {
      "origin": "bottom_left",
      "unit": "cm",
      "page_height_cm": 27.2,
      "page": null,
      "x": null,
      "y": null,
      "anchor": "bottom_right",
      "pages": "last",
      "x_path": null,
      "y_path": null,
      "page_path": null
    },
    "transform": {
      "inbound_mapping": {
        "reference_id": "$.no_de_tramite"
      },
      "outbound_template": {
        "no_de_tramite": "{{reference_id}}"
      },
      "inbound_auth": {
        "type": "bearer"
      },
      "inbound_response": {
        "link": "{{signing_url}}"
      }
    },
    "credentials": {
      "username": null,
      "password_set": false,
      "password_set_at": null,
      "api_key_set": false,
      "api_key_set_at": null
    },
    "created_at": "2026-08-25T14:05:00Z",
    "updated_at": "2026-08-25T14:05:00Z"
  }
}
Sin conexión — reintentando…

Preferencias de cookies

Esenciales

Sesión, seguridad, idioma y tema. Sin ellas el sitio no funciona.

Siempre activas

Cuenta las visitas y prueba qué versión de una página funciona mejor. Solo cookies propias.

Mide y mejora nuestros anuncios en Google y Meta. Compartimos el clic del anuncio y, si nos das tu correo o teléfono, solo su huella cifrada.