Documentación

Webhooks (Catch)

Los webhooks de tipo catch te permiten integrar URBEM con tu aplicación al suscribirte a ciertos eventos. Cuando uno de los siguientes eventos ocurre, enviaremos un request HTTP POST a la URL configurada para el webhook. Puedes configurar múltiples webhooks para el mismo evento y éste recibirá un request por cada webhook.


Eventos

Al configurar un nuevo webhook puedes seleccionar un evento de los disponibles:

Nombre Descripción
Casos ciudadanos creados Se dispara cada vez que una persona de tu organización crea un caso ciudadano a través de URBEM dashboard, cuando un ciudadano inicia un servicio desde URBEM web o cuando se crea desde el URBEM API de tu organización.
Casos ciudadanos actualizados Se dispara cada vez que un caso ciudadano cambia de status o paso actual o cuando una persona de tu organización marca el paso como "Resuelto".
Pagos creados Se dispara cada vez que un ciudadano realiza un pago (fallido, exitoso o pendiente) a cualquier servicio de tu organización.
Pagos exitosos Se dispara cada vez que un ciudadano realiza un pago exitoso a cualquier servicio de tu organización.
Pagos fallidos Se dispara cada vez que un ciudadano realiza un pago fallido a cualquier servicio de tu organización.
Documentos enviados Se dispara cada vez que un ciudadano envía documentos a cualquier servicio de tu organización como parte de un Caso ciudadano.
Documentos rechazados Se dispara cada vez que una persona de tu organización revisa los documentos enviados por un ciudadano como parte de un caso ciudadano y rechaza alguno.
Documentos aprobados Se dispara cada vez que una persona de tu organización revisa los documentos enviados por un ciudadano como parte de un caso ciudadano y aprueba todos.
Documento firmado Se dispara cada vez que una persona de tu organización firma un documento interno para un caso ciudadano.
Resultado firmado Se dispara cada vez que una persona de tu organización firma un documento de resultado para un caso ciudadano.

Payloads

Cada tipo de evento tiene su propio formato de payload con la información relevante del mismo.

Para los eventos: Casos ciudadanos creados y Casos ciudadanos actualizados, el payload corresponde a un objeto citizen_case. Ejemplo:

{
  id: 41,
  procedure: "Acta de nacimiento",
  procedure_id": "acta_de_nacimiento_6ccff29a-1625-477f-9d11-9b6a791d0ffa",
  subject": null,
  citizen_name": "Ana Ruiz",
  citizen_email": "ana@mail.com",
  citizen_phone": 8182599162,
  citizen_fb_id": "1234567890",
  folio": "ABC123",
  amount": 50000,
  status": "make_payment",
  custom_data": {},
  address": "Calle #1515, colonia Centro",
  assigned_to": "oscar@urbem-org.com",
  created_by": "URBEM dashboard",
  created_at": "2019-02-14T20:49:07.357-06:00",
  updated_at": "2019-02-14T20:49:07.357-06:00",
  description": "Descripción del caso...",
  attachments": [],
  done": false,
  current_step_id": 'paso-123',
  completed_by": null
}

Para los eventos: pagos creados, pagos exitosos y pagos fallidos, el payload corresponde a un objeto payment. Ejemplo:

{
  "folio": "155-1F5D02",
  "name": "Luis Espinoza Ruiz",
  "email": "luis1@mail.com",
  "address": "Calle #333",
  "city": "Monterrey",
  "state": "Nuevo León",
  "zip_code": "25090",
  "amount": 70966,
  "citizen_case_id": 123,
  "procedure": "Licencia de conducir",
  "procedure_id": "licencia-111",
  "metadata": {
    "codigo_descuento": "XHF20"
  },
  "status": "failed",
  "description": "Pago para Licencia de Conducir",
  "created_at": "2019-01-24T15:06:50.575-06:00",
  "concepts": [
    {
      "title": "Servicio",
      "value": 200.0
    },
    {
      "title": "Otro",
      "value": 230.5
    }
  ]
}

Para los eventos: documentos enviados, documentos rechazados y documentos aprobados, el payload corresponde a un objeto revision. Ejemplo:

{
  "id": 1,
  "citizen_case_id": 123,
  "action": "get_result",
  "comments": "Todo bien",
  "procedure": "Licencia de Conducir",
  "procedure_id": "licencia-111"
  "completed": true,
  "approved": false,
  "attachments_count": 1,
  "created_at": "2018-10-11T16:28:06.618-05:00",
  "updated_at": "2018-10-11T17:11:00.074-05:00",
  "assigned_to": "responsable@mail.com",
  "citizen_attachments": [
    {
      "id": 1,
      "status": "rejected",
      "rejected_reason": "mal formato",
      "requirement_name": "Identificación Oficial",
      "created_at": "2018-10-11T16:28:06.643-05:00",
      "attachment": {
        "id": 68,
        "url": "https://citizen_docs.url/identificacion.jpg",
        "filename": "identificación.jpg"
      }
    }
  ]
}

Para los eventos: documento firmado y resultado firmado, el payload corresponde a un objeto documento. Ejemplo:

{
  "id":"44b01210-8c02-4296-b046-712ed42354f3",
  "citizen_case_id": 2,
  "procedure_id": "licencia-111",
  "signed": true,
  "signed_at": "2020-01-15T18:10:51.485-06:00",
  "signed_by": ["user@mail.com"],
  "signed_document_url": "https://signed_docs.url/signed_doc.pdf",
  "signed_document_filename": "signed_doc.pdf",
  "document":{
    "url": "https://original_docs.url/original_doc.pdf",
    "filename": "original_doc.pdf",
    "format":"file"
  },
  "digest_hex": "745bf836d5cadbab85699d0ec1b3fc215a499dd10250b61a3044f4b10006ca77",
  "created_at": "2020-01-15T18:09:56.402-06:00",
  "uploaded_by": "responsable@mail.com",
  "signature": "b21b073060a5b85c5d2a5b3b6ea80c17fe17cd308cd5a99ce59cc715757d3...",
  "conservation_document_url": "https://conservation_docs.url/conservation_doc.bin"
}

Estatus de un webhook

Cada webhook configurado tiene un estatus. Al inicio de la configuración de cualquier webhook este estatus será Pendiente. Una vez que se dispare el evento correspondiente al seleccionado para el webhook y se lleve a cabo el HTTP POST, tu aplicación deberá regresar un status 2xx para que el webhook pase de estatus Pendiente a estatus Válido. En caso de cualquier código de error como respuesta el webhook pasará a un estatus Inválido.

En caso de una respuesta fallida, URBEM reintentará el request hasta 5 veces antes de marcar un webhook como inválido.


Webhooks (Retrieve)

Los webhooks de tipo retrieve te permiten integrar URBEM con tu aplicación para consultar adeudos específicos por ciudadano y generar costos automáticamente.


Configuración para consulta de adeudo

En el momento que un ciudadano seleccione los conceptos a pagar podrá disparar un nuevo HTTP POST request con la información configurada desde la configuración de peticiones externas de un servicio y consumir la respuesta obtenida (application/json) para mostrarle los ajustes del costo al ciudadano.

Nota: Toma en cuenta que el endpoint de tu aplicación deberá ser REST y aceptar requests por método POST.

Al configurar un nuevo webhook para consulta de adeudo deberás configurar la siguiente información:

Nombre Descripción
URL Es la URL que apunta al endpoint en tu aplicación al que se debe enviar el request. Ej: https://my.api.url/my/endpoint/path
Ajustes del costo Cada ajuste se conforma de Variable en URBEM y Nombre de variable en sistema externo.
Variable en URBEM: Se refiere al nombre que se guardará en URBEM y se le mostrará al ciudadano en el desglose de la tarifa.
Nombre de variable en sistema externo: Se refiere al nombre de la variable que estaría enviando tu endpoint.
Autenticación Es el token que deberá recibir tu endpoint para autenticar que el request viene desde URBEM. El token se enviará como un encabezado (header) del request con el nombre de auth-token

Ejemplo de request:

curl --location --request POST 'https://my.api.url/my/endpoint/path' \
--header 'AUTH-TOKEN: token-123' \
--header 'Content-Type: application/json' \
--data-raw '{
              "concepts": [
                  {
                      "index": "1",
                      "accounting_item": "123",
                      "title": "Concepto 1",
                      "value": "500",
                      "bonificaciones": "150.0",
                      "recargos": "123",
                      "selected": true
                  },
                  {
                      "index": "2",
                      "accounting_item": "111",
                      "title": "Cooncepto 2",
                      "value": "150",
                      "bonificaciones": "150.0",
                      "recargos": "123",
                      "selected": true
                  },
                  {
                      "index": "3",
                      "accounting_item": "1232",
                      "title": "Concepto 3",
                      "value": "10",
                      "bonificaciones": "150.0",
                      "recargos": "123",
                      "selected": false
                  }
              ]
          }'

Nota: La respuesta que se espera para el request deberá ser en formato json con un HTTP status de 200 y en el cuerpo de la respuesta las variables configuradas como externas desde el paso de tarifas de un servicio.


Configuración para costo automático

En el momento que un ciudadano llegue al paso de Realizar pago se podrá disparar un nuevo HTTP GET request con los parámetros seleccionados en la configuración de peticiones externas y consumir la respuesta obtenida (application/json) para generar costos para el ciudadano.

Nota: Toma en cuenta que el endpoint de tu aplicación deberá ser REST y aceptar requests por método GET.

Al configurar un nuevo webhook para costo automático deberás configurar la siguiente información:

Nombre Descripción
URL Es la URL que apunta al endpoint en tu aplicación al que se debe enviar el request. Ej: https://my.api.url/my/endpoint/path
Costos automáticos Los costos automáticos estan conformados por Envío de parámetros , Variables en URBEM y Nombre de variables en sistema externo.
Envío de parámetros: Son los parámetros que se tomarán del caso para enviar al endpoint por medio de la URL. Ej: Fecha de nacimiento, CURP, RFC, etc.
Variable en URBEM: Se refiere al nombre que se guardará en URBEM y se le mostrará al ciudadano en el desglose de la tarifa.
Nombre de variable en sistema externo: Se refiere al nombre de la variable que estaría enviando tu endpoint.
Autenticación Es el token que deberá recibir tu endpoint para autenticar que el request viene desde URBEM. El token se enviará como un encabezado (header) del request con el nombre de auth-token

Ejemplo de request:

curl --location --request GET 'https://my.api.url/my/endpoint/path?fecha-de-nacimiento=01/01/1990&dato-prueba=prueba' \
--header 'AUTH-TOKEN: token-123' \
--header 'Content-Type: application/json' \

Nota: La respuesta que se espera para el request deberá ser en formato json con un HTTP status de 200 y en el cuerpo de la respuesta las variables configuradas como externas desde el paso de tarifas de un servicio.

API Keys

URBEM autentica los requests de tu organización utilizando las API keys. Si no incluyes el API key como parámetro o utilizas un API key obsoleta o incorrecta en cualquier request que realices al URBEM API, ésta responderá con un error 401.

Cada organización cuenta con una API Key default con permisos de lectura y escritura. Si deseas agregar nuevas API keys con diferentes permisos puedes hacerlo desde la sección de Desarrolladores en el panel de configuración.

Ver documentación completa de URBEM API