URBEM

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".
`Casos ciudadanos cerrados`	Se dispara cada vez que un caso ciudadano es marcado como cerrado en cualquiera de los estatus (resuelto, vencido y no procedente).
`Tarifa creada`	Se dispara cada vez que se establece una tarifa (manual o costo automático) para un caso ciudadano dentro de tu organización.
`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.
`Documento de resultado firmado`	Se dispara cada vez que una persona de tu organización firma un documento de resultado para un caso ciudadano.
`Usuario registrado`	Se dispara cada vez que un ciudadano se registra dentro de una organización. * Sólo aplica para organizaciones que tienen Cuenta ciudadana activa.
`Citas creadas por ciudadano`	Se dispara cada vez que un ciudadano agenda una cita en un caso ciudadano.
`Citas creadas por colaborador`	Se dispara cada vez que un colaborador agenda una cita para el ciudadano y un colaborador en 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,
  "folio": null,
  "status": "make_payment",
  "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": "",
  "attachments": [],
  "done": false,
  "archived": false,
  "archived_at": null,
  "current_step_id": "paso-123",
  "solved_by": "user@mail.com",
  "amount": null,
  "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d",
  "external_payment_url": "https://payment.url",
  "payment_redirect_url": "https://payment.redirection.url/",
  "citizen_opt_in": true,
  "closed_as": "solved",
  "closed_reason": "",
  "street": "Calle",
  "exterior_number": 1515,
  "interior_number": null,
  "neighborhood": "Colonia centro",
  "state_text": "Nuevo León",
  "city_text": "Monterrey",
  "zip_code": "66666",
  "custom_data": {
    "Alfanumérico": "a1b2c3",
    "Numérico": "123456",
    "Fecha": "01/02/2002",
    "Dirección": {
      "zip_code": "08000",
      "state": "Ciudad de México",
      "city": "Iztacalco",
      "neighborhood": "Gabriel Ramos Millán Sección Bramadero",
      "street": "calle",
      "exterior_number": "12",
      "interior_number": "2a"
    },
    "Opción múltiple": "Opción 1",
    "Opciones anidadas 1er nivel": "Opción A",
    "Segundo nivel": "Opción A.2",
    "Tercer nivel": "Opción A.2.1",
    "Sumatoria número": {
      "10": "10",
      "15": "15",
      "25": "25"
    },
    "Sumatoria porcentaje": {
      "25": "25%",
      "30": "30%",
      "35": "35%",
      "10": "10%"
    },
    "Dato reservación": {
      "type": "reservation",
      "total": "600.00",
      "items": [
        {
          "qty": "3",
          "concept": "Concepto 1",
          "amount": "100",
          "cost": "300.00"
        },
        {
          "qty": "2",
          "concept": "Concepto 2",
          "amount": "150",
          "cost": "300.00"
        }
      ]
    },
    "Género": "Masculino",
    "Fecha de nacimiento": "1/2/2002",
    "Teléfono / Celular": "1234567890",
    "CURP": "abcd990823hdfltd02",
    "RFC": "qwre9908125t0"
  },
  "center": {
    "name": "Oficinas de Secretaría de Salud",
    "city_name": "Ciudad",
    "address": "Calle #123, colonia X",
    "url": "",
    "phone": "",
    "rfc": null,
    "license_number": null,
    "appointments_count": 1
  }
}

Para el evento: Tarifa creada, el payload corresponde a un objeto custom_fee. Ejemplo:

{
  "id": 3,
  "concepts":[
    {
      "accounting_item": "pago123",
      "title": "Concepto de pago",
      "value": 150.0
    }
  ],
  "adjustments":{},
  "calculated_total": 150.0,
  "discount": false,
  "description": "Pago por el servicio",
  "discount_unit": "percentage",
  "discount_value": 0.0,
  "citizen_case_id": 2,
  "citizen_name": "Ana Márquez",
  "citizen_email": "ana@mail.com",
  "created_at": "2022-10-26T10:00:30.580-05:00"
}

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,
  "decimal_amount": 709.66,
  "citizen_case_id": 123,
  "citizen_name": "Luis Espinoza Ruiz",
  "citizen_phone": "8080808080",
  "custom_fields": {
    "codigo_descuento": "XHF20"
  },
  "status": "failed",
  "description": "Pago para Licencia de Conducir",
  "procedure": "Licencia de conducir",
  "procedure_id": "licencia-111",
  "external_receipt_url": null,
  "external_receipt_xml_url": null,
  "created_at": "2019-01-24T15:06:50.575-06:00",
  "created_at_formatted": "24, 01, 2019 15:06",
  "updated_at": "2019-02-26T20:59:07.900-06:00",
  "updated_at_formatted": "26, 02, 2019 20:59",
  "paid_at": null,
  "paid_at_formatted": null,
  "payment_method": "debit_credit_card",
  "fee_type": "free",
  "concepts": [
    {
      "title": "Servicio",
      "value": 200.0
    },
    {
      "title": "Otro",
      "value": 230.5
    }
  ],
  "public_url": "urbem.digital/public/citizen_cases/42?token=772064d3-bcf8-437b-930f-3d159d3f889d",
  "receipt_url": ""
}

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",
  "folio": "xv35h",
  "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"
}

Para los eventos: Citas creadas por ciudadano y Citas creadas por colaborador, el payload corresponde a un objeto appointment. Ejemplo:

{
  "center_name": "Punto de contacto 1",
  "status": "pending",
  "scheduled_at": "2023-04-12T10:15:06.000-06:00",
  "attended_by": null,
  "date": "2023-04-14 09:30",
  "citizen_case_id": 1,
  "citizen_phone": 1234567890
}

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' \

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