shell

URBEM API

Documentación del URBEM API.

URL: https://api.urbem.digital/v1/

Versionamiento

Versionamiento

La versión actual de URBEM API es v1.

Autenticación

Cada request dirigido al URBEM API debe contener el parámetro auth_token con el valor del api key.

¿No tienes un API key? Genera una desde el panel de configuración.

Paginación

Todos los resultados se regresan paginados. Por cada request se devuelve el header X-Pagination que contiene:

 {
  "total": 50,
  "total_pages": 2,
  "current_page": 1,
  "first_page": true,
  "last_page": false,
  "next_page": 2,
  "limit_value": 25,
  "previous_page": null
}
Parámetro Descripción
total El total de resultados correspondiente al request.
total_pages Número total de páginas de resultados correspondiente al request.
current_page Página actual de resultados.
first_page Indica si la página actual es la primer página de resultados.
last_page Indica si la página actual es la última página de resultados.
next_page Número de página que le sigue a la actual.
limit_value Límite de resultados por página (default: 25).
previous_page Número de página anterior a la actual.

Para obtener los resultados correspondientes a un número de página específico se deberá enviar el parámetro page con el número de página que se requiere.

?page=2

Servicios/Trámites

Listado de servicios

Devuelve un arreglo con lo servicios dados de alta dentro de tu organización.

HTTP Request

GET /v1/procedures

curl "https://api.urbem.digital/v1/procedures?auth_token=apitoken123"

curl "https://api.urbem.digital/v1/procedures?test_mode=true&auth_token=apitoken123"

Filtros / Parámetros

Parameter Type Default Description
procedure_type String Devuelve los servicios/trámites que coincidan con el tipo de servicio enviado. Posibles valores: procedure (Trámite), modalities (Trámite con modalidades), beneficence (Programa para beneficiarios) o report (Solicitud de Servicio).
service_id Integer Devuelve los servicios/trámites asociados al departamento especificado.
available Boolean Si no se envía se devuelven los servicios publicados y no publicados.
test_mode Boolean false Filtra por el atributo modo prueba. Por default devuelve todos aquellos que NO se encuentran en modo prueba.
page Integer 1 Si no se envía se devuelven los servicios correspondientes a la primer página.
per_page Integer 25 Especifica el número de objetos que conforman 1 página. Máximo valor: 50.

Ejemplo de respuesta

[
  {
  "id": "un_servicio_123",
  "service_id": 111,
  "department": "Departamento del servicio",
  "name": "Mi servicio",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla varius nisl sit amet elit maximus, feugiat tristique urna finibus. Morbi sapien nisi, congue id est non, vehicula pellentesque tortor. ",
  "url": null,
  "homoclave": "SERVICIO123",
  "legal_basis": "Fundamento jurídico que...",
  "modality_type": "online",
  "user_type": "citizen",
  "procedure_type": "procedure",
  "available": false,
  "additional_details": "Detalles adicionales del servicio...",
  "public_target_description": "Descripción...",
  "created_at": "2018-05-28T12:22:12.303-05:00",
  "updated_at": "2018-06-28T12:33:42.484-05:00",
  "author": "user@org.com",
  "fee_type": "free",
  "updated_by": "user@org.com",
  "external_reference": "custom-id-123",
  "accounting_id": "acct-123"
  },
  {...}
]

Ver servicio

Obtener un servicio específico.

HTTP Request

GET /v1/procedures/:id

curl "https://api.urbem.digital/v1/procedures/un_servicio_123?auth_token=apitoken123"

Descripción de campos en respuesta

Parámetro Tipo Descripción
id String Identificador/Slug del servicio.
name String Nombre del servicio.
service_id Integer Identificador/Slug del departamento al que que pertenece el servicio.
department String Nombre del departamento al que pertenece el servicio.
description String Descripción del servicio.
url String URL del servicio.
homoclave String Homoclave del servicio.
legal_basis String Fundamento jurídico del servicio.
modality_type String Modalidad del servicio. Valores posibles: online (en línea), onsite (presencial) o hybrid (híbrido).
user_type String Sector al que va dirigido el servicio. Valores posibles: citizen (Ciudadano), enterprise (Empresarial), enterprise_citizen (Ciudadano / Empresarial), scholar (Escolar) o notary (Notarios).
categories Array Categorías y subcategorías a las que pertenece el trámite.
procedure_type String Tipo de servicio seleccionado. Valores posibles: beneficence, procedure, report, modalities o information.
additional_details String Detalles adicionales del servicio.
public_target_description String Descripción sobre a quién va dirigido el trámite.
available Boolean Bandera que identifica si el servicio está disponible para realizarse en URBEM web.
created_at String/timestamp Momento en el que se creó el servicio.
updated_at String/timestamp Momento en el que se actualizó el servicio por última vez.
author String Correo electrónico del usuario que creó el servicio.
updated_by String Correo electrónico del usuario que actualizó por última vez un trámite.
external_reference String Id externo para el uso de la organización
accounting_id String Partida contable del servicio
requirements Array Requisitos configurados del trámite
fee_type String Tipo de tarifa configurada en el trámite. Posibles valores: free (Gratuito), fixed (Fija) o variable (Variable).
fees Array Tarifas configuradas para el trámite
data_inputs Array Datos a recabar configurados en el trámite
procedure_contact Object Datos de contacto principal del trámite
procedure_inspectors Array Datos de los inspectores de un trámite
modalities Array Modalidades de trámite

Ejemplo de respuesta

{
  "id": "un_servicio_123",
  "service_id": 111,
  "department": "Departamento del servicio",
  "name": "Mi servicio",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla varius nisl sit amet elit maximus, feugiat tristique urna finibus. Morbi sapien nisi, congue id est non, vehicula pellentesque tortor. ",
  "url": null,
  "homoclave": "SERVICIO123",
  "legal_basis": "Fundamento jurídico que...",
  "modality_type": "online",
  "user_type": "citizen",
  "procedure_type": "procedure",
  "available": false,
  "additional_details": "Detalles adicionales del servicio...",
  "public_target_description": "Descripción...",
  "created_at": "2018-05-28T12:22:12.303-05:00",
  "updated_at": "2018-06-28T12:33:42.484-05:00",
  "author": "user@org.com",
  "fee_type": "free",
  "updated_by": "user@org.com",
  "external_reference": "custom-id-123",
  "accounting_id": "acct-123",
  "modalities": []
}

Actualizar un servicio

Actualiza el servicio especificado asignando los valores del hash de procedure. Los valores que no contenga el hash no serán modificados.

HTTP Request

PUT /v1/procedures/:id

curl "https://api.urbem.digital/v1/procedures/servicio-123?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "procedure": {
    "name": "Servicio actualizado",
    "description": "Una descripción acerca del trámite...",
    "available": true,
    "url": "http://mywebsite.url/mi-servicio"
  }
}
'

Parámetros

Parámetro Descripción
id El identificador del servicio.
procedure Objeto del servicio con los nuevos atributos.

Parámetros de procedure

Parámetro Tipo Descripción
name String Nombre del servicio.
description String Descripción del servicio.
available Boolean Bandera que identifica si el servicio está disponible para realizarse en URBEM web.
url String URL al servicio.
external_reference String Id externo para el uso de la organización
accounting_id String Partida contable del servicio

Ejemplo de respuesta

{
  "id": "un_servicio_123",
  "service_id": 111,
  "department": "Departamento del servicio",
  "name": "Servicio actualizado",
  "description":  "Una descripción acerca del trámite...",
  "url": "http://mywebsite.url/mi-servicio",
  "procedure_type": "procedure",
  "available": true,
  "created_at": "2018-05-28T12:22:12.303-05:00",
  "updated_at": "2018-06-28T12:33:42.484-05:00",
  "author": "user@org.com",
  "updated_by": "user@org.com",
  "external_reference": "custom-id-123",
  "accounting_id": "acct-123"
}

Pasos de un servicio/trámite

Listado de pasos

Devuelve un arreglo con los pasos dados de alta dentro de un servicio.

HTTP Request

GET /v1/steps

curl "https://api.urbem.digital/v1/steps?procedure_id=procedure123&auth_token=apitoken123"

Filtros / Parámetros

Parameter Default Description
procedure_id Devuelve los pasos asociados al servicio especificado.
page 1 Si no se envía se devuelven los pasos correspondientes a la primer página.

Ejemplo de respuesta

[
  {
    "id": "un_paso_123",
    "index": 1,
    "procedure_id": "servicio123",
    "title": "Paso actualizado",
    "description":  "Una descripción acerca del paso para el ciudadano...",
    "action": "send_documents",
    "revision_required": "true",
    "action_to_perform": null,
    "responsible_email": "user@mail.com",
    "step_type": "citizen",
    "signature_issuers" : [],
    "signature_step": false,
    "revision_by_center": false,
    "created_at": "2018-05-28T12:22:12.303-05:00",
    "updated_at": "2018-06-28T12:33:42.484-05:00"
  },
  ...
]

Descripción de campos en respuesta

Parámetro Tipo Descripción
id String Identificador/Slug del paso.
index Integer Índice del paso. Indica el orden dentro del servicio/trámite.
title String Nombre del paso.
description String Descripción del paso para el ciudadano.
action String Acción a realizar en el paso. Puede ser send_documents, make_payment, make_appointment, get_result, other
revision_required Boolean Bandera que identifica si el paso requiere revisión de un colaborador.
action_to_perform String Acción a realizar del colaborador.
responsible_email String Correo del colaborador responsable del paso.
step_type String Tipo de paso, define si la acción la realiza el ciudadano o el colaborador. Puede ser citizen o collaborator
signature_days Integer Número de días que tiene un colaborador para firmar.
signature_step Boolean Bandera que identifica si el paso requiere firma de un colaborador.
signature_issuers String Array Arreglo que contenga el correo de las personas que deben firmar.
revision_by_center Boolean Bandera que identifica si el paso requiere revisión de un colaborador asignado a un centro.
created_at String/timestamp Momento en el que se creó el paso.
updated_at String/timestamp Momento en el que se actualizó el paso por última vez.

Actualizar un paso de un servicio

Actualiza el paso especificado del servicio asignando los valores del hash de procedure_step. Los valores que no contenga el hash no serán modificados.

HTTP Request

PUT /v1/steps/:id

curl "https://api.urbem.digital/v1/steps/paso-123?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "procedure_step": {
    "title": "Nuevo paso",
    "description": "Una descripción acerca del paso para el ciudadano...",
    "action": "send_documents",
    "revision_required": "true",
    "action_to_perform": null,
    "responsible_email": "user@mail.com",
    "step_type": "citizen"
  }
}
'

Parámetros

Parámetro Descripción
id El identificador del paso.
procedure_step Objeto del paso con los nuevos atributos.

Parámetros de procedure step

Parámetro Tipo Descripción
title String Nombre del paso.
description String Descripción del paso para el ciudadano.
action String Acción a realizar en el paso. Puede ser send_documents, make_payment, make_appointment, get_result, other
revision_required Boolean Bandera que identifica si el paso requiere revisión de un colaborador.
action_to_perform String Acción a realizar del colaborador.
responsible_email String Correo del colaborador responsable del paso.
step_type String Tipo de paso, define si la acción la realiza el ciudadano o el colaborador. Puede ser citizen o collaborator
signature_days Integer Número de días que tiene un colaborador para firmar.
signature_step Boolean Bandera que identifica si el paso requiere firma de un colaborador.
signature_issuers String Array Arreglo que contenga el correo de las personas que deben firmar.
revision_by_center Boolean Bandera que identifica si el paso requiere revisión de un colaborador asignado a un centro.

Ejemplo de respuesta

{
  "id": "un_paso_123",
  "index": 1,
  "procedure_id": "servicio123",
  "title": "Paso actualizado",
  "description":  "Una descripción acerca del paso para el ciudadano...",
  "action": "send_documents",
  "revision_required": "true",
  "action_to_perform": null,
  "responsible_email": "user@mail.com",
  "step_type": "citizen",
  "signature_issuers" : [],
  "signature_step": false,
  "revision_by_center": false,
  "created_at": "2018-05-28T12:22:12.303-05:00",
  "updated_at": "2018-06-28T12:33:42.484-05:00"
}

Pagos

Listado de pagos

Devuelve un arreglo con los pagos realizados a cualquier servicio dentro de tu organización.

HTTP Request

GET /v1/payments

curl "https://api.urbem.digital/v1/payments?auth_token=apitoken123"

Filtros / Parámetros

Parameter Default Description
citizen_case_id Devuelve los pagos realizados al caso ciudadano especificado.
page 1 Si no se envía se devuelven los pagos correspondientes a la primer página.
by_date Devuelve los pagos realizados después de la fecha especificada.

Ejemplo de respuesta

[
  {
    "folio": "ABCD-111",
    "name": "Ana Ruiz",
    "email": "ana@mail.com",
    "address": "Calle 1515, Colonia Independencia",
    "city": "Monterrey",
    "state": "Nuevo León",
    "zip_code": "66600",
    "amount": 51800,
    "decimal_amount": 518.00,
    "citizen_case_id": 42,
    "metadata": {
      "key": "value"
    },
    "status": "pending",
    "description": "Pago para Acta de nacimiento",
    "procedure": "Acta de nacimiento",
    "procedure_id": "acta_de_nacimiento_6ccff29a-1625-477f-9d11-9b6a791d0ffa",
    "created_at": "2019-02-14T20:59:07.900-06:00",
    "payment_method": "debit_credit_card",
    "concepts": [],
    "fee_type": "free",
    "external_receipt_url": null,
    "public_url": ""
  },
  ...
]

Ver pago

Obtener un pago específico.

HTTP Request

GET /v1/payments/:folio

curl "https://api.urbem.digital/v1/payments/ABCD-123?auth_token=apitoken123"

Descripción de campos en respuesta

Parámetro Tipo Descripción
folio String Folio generado en base al identificador de un servicio (procedure) y una cadena hexadecimal de 6 dígitos.
name String Nombre de la persona que realizó el pago.
email String Correo electrónico de la persona que realizó el pago.
address String Dirección de la persona que realizó el pago.
city String Ciudad o municipio de la persona que realizó el pago.
state String Estado de la persona que realizó el pago.
zip_code String Código postal de la persona que realizó el pago.
amount Integer Cantidad pagada por la persona en centavos.
decimal_amount Float Cantidad pagada por la persona en pesos con notación decimal.
citizen_case_id Integer Identificador del Caso ciudadano al que pertenece el pago realizado.
procedure_id String Identificador del servicio.
procedure String Nombre del servicio.
metadata object/hash Objeto que contiene un hash con metadatos relacionados al pago.
status String Status actual del pago (succeeded, failed, pending, expired).
description String Descripción del pago realizado.
created_at String/timestamp Momento en el que se realizó el pago.
payment_method String Método de pago (debit_credit_card, bank_transfer, cash)
concepts Array Arreglo de objetos que contienen los conceptos de pago establecidos en la tarifa.
fee_type String Tipo de tarifa configurada para el servicio al que pertenece el caso ciudadano en el que se realizó el pago (free, fixed, variable).
external_receipt_url String URL al recibo en pdf generado a partir de receipt_url
external_receipt_xml_url String URL al recibo en xml generado a partir de xml_receipt_url
public_url String URL pública al resumen del pago en URBEM, sólo se envía si el pago tiene un status de succeeded.

Ejemplo de respuesta

{
  "folio": "folio1234456",
  "name": "Ana Ruiz",
  "email": "ana@mail.com",
  "address": "Calle 1515, Colonia Independencia",
  "city": "Monterrey",
  "state": "Nuevo León",
  "zip_code": "66600",
  "amount": 51800,
  "decimal_amount": 518.00,
  "citizen_case_id": 42,
  "metadata": {
    "dato_metadata": "valor metadata"
  },
  "status": "succeeded",
  "description": "Pago para Acta de nacimiento",
  "procedure": "Acta de nacimiento",
  "procedure_id": "acta_de_nacimiento_6ccff29a-1625-477f-9d11-9b6a791d0ffa",
  "created_at": "2019-02-14T20:59:07.900-06:00",
  "payment_method": "debit_credit_card",
  "concepts": [
    {
        "accounting_item": "ingresos-001",
        "title": "Servicio",
        "value": 200.0,
        "bonificaiones": 50.0,
        "recargos": 0.0,
        ...
        "selected": true
    },
    {
        "accounting_item": "ingresos-002",
        "title": "Otro",
        "value": 230.5,
        "bonificaiones": 10.0,
        "recargos": 0.0,
        ...
        "selected": true
    }
  ],
  "fee_type": "variable",
  "external_receipt_url": null,
  "external_receipt_xml_url": null,
  "public_url": "https://app.urbem.digital/public_url/123?token=123"
}

Actualizar un pago

Actualiza el pago especificado asignando los valores del hash de payment. Los valores que no contenga el hash no serán modificados.

HTTP Request

PUT /v1/payments/:folio

curl "https://api.urbem.digital/v1/payments/ABCD-123?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "payment": {
    "folio": "ABCD-111",
    "status": "pending",
    "name": "Juan López",
    "email": "juan@mail.com",
    "address": "Calle 1516, Colonia Independencia",
    "city": "Monterrey",
    "state": "Nuevo León",
    "zip_code": "66600",
    "metadata": { "key": "value", ... },
    "receipt_url": "https://recibo.url/recibo.pdf",
    "xml_receipt_url": "https://recibo.url/recibo.xml"
  }
}
'

Parámetros

Parámetro Descripción
folio El folio identificador del pago.
payment Objeto del pago con los nuevos atributos.

Parámetros de payment

Parámetro Tipo Descripción
folio String El folio identificador del pago.
status String Estado del pago succeeded, failed, expired o pending.
metadata Object/Hash Objeto que contiene un hash con metadatos relacionados al pago.
receipt_url String URL del recibo de pago externo. Sólo se permiten archivos .pdf
xml_receipt_url String URL del recibo de pago externo en formato XML. Sólo se permiten archivos .xml
name String Nombre de la persona que realizó el pago.
email String Correo electrónico de la persona que realizó el pago.
address String Dirección de la persona que realizó el pago.
city String Ciudad o municipio de la persona que realizó el pago.
state String Estado de la persona que realizó el pago.
zip_code String Código postal de la persona que realizó el pago.

Ejemplo de respuesta

{
  "folio": "ABCD-111",
  "name": "Ana Ruiz",
  "email": "ana@mail.com",
  "address": "Calle 1516, Colonia Independencia",
  "city": "Monterrey",
  "state": "Nuevo León",
  "zip_code": "66600",
  "amount": 51800,
  "decimal_amount": 518.00,
  "citizen_case_id": 42,
  "citizen_name": "Ana Ruiz",
  "citizen_phone": "8080808080",
  "custom_fields": {
    "key": "value"
  },
  "status": "pending",
  "description": "Pago para Acta de nacimiento",
  "procedure": "Acta de nacimiento",
  "procedure_id": "acta_de_nacimiento_6ccff29a-1625-477f-9d11-9b6a791d0ffa",
  "external_receipt_url": null,
  "external_receipt_xml_url": null,
  "created_at": "2019-02-14T20:59:07.900-06:00",
  "created_at_formatted": "14, 02, 2019 20:59",
  "updated_at": "2019-02-14T20:59:07.900-06:00",
  "updated_at_formatted": "14, 02, 2019 20:59",
  "paid_at": null,
  "paid_at_formatted": null,
  "payment_method": "debit_credit_card",
  "fee_type": "free",
  "concepts": [
    {
      "key": "value"
    }
  ],
  "public_url": "urbem.digital/public/citizen_cases/42?token=772064d3-bcf8-437b-930f-3d159d3f889d",
  "receipt_url": ""
}

Actualizar un pago Pendiente a través de un caso ciudadano

Actualiza el pago Pendiente especificado asignando los valores del hash de payment. Los valores que no contenga el hash no serán modificados.

HTTP Request

PUT /v1/payments/update_status

curl "https://api.urbem.digital/v1/payments/update_status?citizen_case_id=42&auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "payment": {
    "folio": "ABCD-111",
    "status": "failed",
    "name": "Juan López",
    "email": "juan@mail.com",
    "address": "Calle 1516, Colonia Independencia",
    "city": "Monterrey",
    "state": "Nuevo León",
    "zip_code": "66600",
    "metadata": { "key": "value", ... },
    "receipt_url": "https://recibo.url/recibo.pdf",
    "xml_receipt_url": "https://recibo.url/recibo.xml"
  }
}
'

Parámetros

Parámetro Descripción
citizen_case_id El identificador del caso ciudadano.
payment Objeto del pago con los nuevos atributos.

Parámetros de payment

Parámetro Tipo Descripción
folio String El folio identificador del pago.
status String Estado del pago succeeded, failed, expired o pending.
metadata Object/Hash Objeto que contiene un hash con metadatos relacionados al pago.
receipt_url String URL del recibo de pago externo. Sólo se permiten archivos .pdf
xml_receipt_url String URL del recibo de pago externo en formato XML. Sólo se permiten archivos .xml
name String Nombre de la persona que realizó el pago.
email String Correo electrónico de la persona que realizó el pago.
address String Dirección de la persona que realizó el pago.
city String Ciudad o municipio de la persona que realizó el pago.
state String Estado de la persona que realizó el pago.
zip_code String Código postal de la persona que realizó el pago.

Ejemplo de respuesta

{
  "folio": "ABCD-111",
  "name": "Ana Ruiz",
  "email": "ana@mail.com",
  "address": "Calle 1516, Colonia Independencia",
  "city": "Monterrey",
  "state": "Nuevo León",
  "zip_code": "66600",
  "amount": 51800,
  "decimal_amount": 518.00,
  "citizen_case_id": 42,
  "metadata": {
    "key": "value"
  },
  "status": "failed",
  "description": "Pago para Acta de nacimiento",
  "procedure": "Acta de nacimiento",
  "procedure_id": "acta_de_nacimiento_6ccff29a-1625-477f-9d11-9b6a791d0ffa",
  "created_at": "2019-02-14T20:59:07.900-06:00",
  "created_at_formatted": "14, 02, 2019 20:59",
  "updated_at": "2019-02-14T20:59:07.900-06:00",
  "updated_at_formatted": "14, 02, 2019 20:59",
  "paid_at": null,
  "paid_at_formatted": null,
  "payment_method": "debit_credit_card",
  "fee_type": "variable",
  "concepts": [
    {
        "accounting_item": "ingresos-001",
        "title": "Servicio",
        "value": 200.0,
        "bonificaiones": 50.0,
        "recargos": 0.0,
        ...
        "selected": true
    },
    {
        "accounting_item": "ingresos-002",
        "title": "Otro",
        "value": 230.5,
        "bonificaiones": 10.0,
        "recargos": 0.0,
        ...
        "selected": true
    }
  ],
  "fee_type": "variable",
  "external_receipt_url": "https://reciboexterno.url/recibo.pdf",
  "external_receipt_xml_url": "https://reciboexterno.url/recibo.xml",
  "public_url": "urbem.digital/public/citizen_cases/42?token=772064d3-bcf8-437b-930f-3d159d3f889d",
  "receipt_url": ""
}

Casos ciudadanos

Listado de casos

Devuelve un arreglo con los casos ciudadanos creados para cualquier servicio dentro de tu organización.

HTTP Request

GET /v1/citizen_cases

curl "https://api.urbem.digital/v1/citizen_cases?auth_token=apitoken123"

Filtros / Parámetros

Parameter Default Tipo Description
page 1 Integer Si no se envía se devuelven los casos correspondientes a la primer página.
date String Devuelve los casos creados después de la fecha especificada. Ej: 11-04-2021
procedure_id Integer Devuelve los casos asociados al servicio especificado.
done Booleano Filtra a los casos cerrados(true) o los casos abiertos(false).
procedure_step_id Integer Filtra los casos asociados al paso del trámite especificado.
step_index Integer Filtra los casos que se encuentren en la posición del orden especificado en el trámite.
custom_data String Filtra los casos que coinciden con el valor ingresado en el dato a recabar especificado. Solo se puede uno a la vez. Ej. Numérico,123456.
sort_by_creation false Booleano Ordena los casos por fecha de creación en forma descendente.

Ejemplo de respuesta

[
  {
    "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,
    "amount": null,
    "status": "make_payment",
    "custom_data": {
      "Alfanumérico": "a1b2c3",
      "Numérico": "123456",
      "Opción múltiple": "Opción 1",
    },
    "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",
    "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d",
    "external_payment_url": "https://payment.url",
    "payment_redirect_url": "https://payment.redirection.url/",
    "citizen_opt_in": false,
    "closed_as": "expired",
    "closed_reason": "",
    "street": "Calle",
    "exterior_number": 1515,
    "interior_number": null,
    "neighborhood": "Colonia centro",
    "state_text": "Nuevo León",
    "city_text": "Monterrey",
    "zip_code": "66666"
  },
  ...
]

Ver caso ciudadano

Obtener un caso ciudadano específico.

HTTP Request

GET /v1/citizen_cases/:id

curl "https://api.urbem.digital/v1/citizen_cases/id?date_format=aaaa-mm-dd&auth_token=apitoken123"

Parámetros

Parámetro Tipo Descripción
date_format String Formato en el que se transformarán las fechas del caso.

Descripción de campos en respuesta

Parámetro Tipo Descripción
id Integer Identificador del caso ciudadano.
procedure String Nombre del servicio al que pertenece el caso.
procedure_id String Identificador del servicio al que pertenece el caso.
subject String Asunto asignado al caso.
citizen_name String Nombre del ciudadano que inició el caso.
citizen_email String Correo electrónico del ciudadano que inició el caso.
citizen_phone String Número telefónico del ciudadano que inició el caso.
folio String Identificador modificable del caso.
status String Estado actual del caso ciudadano.*
custom_data Object/Hash Objeto que contiene los datos recabados para el caso.
address String Dirección con la que fue dado de alta el caso.
assigned_to String Correo electrónico del administrador al que fue asignado el caso.
created_by String Idenfiticador del medio por el que fue dado de alta el caso (URBEM web / URBEM bot / Correo electrónico del administrador)
created_at String Timestamp de la fecha de creación del caso.
updated_at String Timestamp de la última actualización del caso.
description String Descripción del caso.
attachments Array de objects Lista de archivos adjuntos en el caso.
done Boolean Bandera que identifica si el caso está resuelto.
archived Boolean Bandera que identifica si el caso está archivado.
archived_at String Timestamp de la fecha en la que fue archivado el caso.
solved_by String Correo electrónico del colaborador que marcó el caso como "Resuelto".
amount Float Cantidad en pesos del precio específico para el caso.
closed_as String Descripción de como fue cerrado el caso: solved(resuelto), expired(vencido) o denied(no procedente).
closed_reason String Descripción de por qué un caso fue cerrado cuando es denied(no procedente).
street String Dirección por campos - Calle
exterior_number Number Dirección por campos - Número exterior
interior_number String Dirección por campos - Número interior
neighborhood String Dirección por campos - Colonia
city_text String Dirección por campos - Municipio/Ciudad
state_text String Dirección por campos - Estado
zip_code String Dirección por campos - Código postal
external_payment_url String URL externa para redirigir al ciudadano en el paso de Realizar pago.
external_payment_refresh_status_url String URL externa para consultar el status de un pago.
payment_redirect_url String URL a la cual se debe redirigir una vez que se está procesando un pago por medio de un motor de pagos externo.
public_token String Token para generar la URL pública del caso ciudadano.
citizen_opt_in Boolean Bandera que identifica si un ciudadano seleccionó la opción de Opt-in para recibir notificaciones por Whatsapp.

Campos para attachments

Parámetro Tipo Descripción
id Integer Identificador del archivo adjunto.
url String Url del archivo adjunto.
filename String Nombre del archivo adjunto.

Ejemplo de respuesta

{
  "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",
  "custom_data": { "RFC": "XXXX880611" },
  "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": false,
  "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"
}

// Ejemplo de respuesta cuando el trámite incluye distintos tipos de dato a recabar
{
  "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",
  "external_payment_refresh_status_url": "https://paymentstatus.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
  }
}

Crear caso ciudadano

Crear nuevo caso ciudadano.

HTTP Request

POST /v1/citizen_cases/

curl "https://api.urbem.digital/v1/citizen_cases?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "citizen_case": {
    "folio": "ABCD-111",
    "procedure_id": "servicio-123",
    "service_id": "departamento-123",
    "done": false,
    "procedure_step_id": "step-123",
    "description": "Descripción del caso ciudadano...",
    "amount": 50000,
    "external_payment_refresh_status_url": "https://paymentstatus.url",
    "citizen_attributes": {
      "first_name": "Ana",
      "fathers_last_name": "Jiménez",
      "mothers_last_name": "Ruiz",
      "email": "ana@mail.com",
      "phone": "12345678",
    },
    "custom_data": {
      "RFC": "XXXX880611",
      "Curso": "Repostería"
    }
  }
}
'

Ejemplo de respuesta

{
  "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": "12345678",
  "folio": "ABCD-111",
  "status": "make_payment",
  "custom_data":{
    "RFC": "XXXX880611",
    "Curso": "Repostería"
  },
  "address": "Calle #1515, colonia Centro",
  "assigned_to": null,
  "created_by": "Organización API",
  "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": null,
  "amount": 50000,
  "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d",
  "external_payment_url": null,
  "external_payment_refresh_status_url": "https://paymentstatus.url",
  "payment_redirect_url": "https://payment.redirection.url/",
  "citizen_opt_in": true,
  "closed_as": "",
  "closed_reason": "",
  "street": "Calle",
  "exterior_number": 1515,
  "interior_number": null,
  "neighborhood": "Colonia centro",
  "state_text": "Nuevo León",
  "city_text": "Monterrey",
  "zip_code": "66666",
  "metadata": {}
}

Actualizar un caso ciudadano

Actualiza el caso ciudadano especificado asignando los valores del hash citizen_case. Los valores que no contenga el hash no serán modificados.

HTTP Request

PUT /v1/citizen_case/:id

curl "https://api.urbem.digital/v1/citizen_cases/2?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "citizen_case": {
    "folio": "ABCD-111",
    "description": "Descripción del caso ciudadano...",
    "amount": 50000,
    "external_payment_url": "https://payment.url",
    "external_payment_refresh_status_url": "https://paymentstatus.url",
    "citizen_attributes": {
      "name": "Ana Jiménez Ruiz",
      "email": "ana@mail.com",
      "phone": "1234567890"
    },
    "custom_data": {
      "Curso": "Dibujo"
    },
    "metadata": {
      "dato": "valor"
    }
  }
}
'

Parámetros

Parámetro Descripción
id Identificador del caso.
citizen_case Objeto del caso ciudadano con los nuevos atributos.

Parámetros de citizen_case

Parámetro Tipo Descripción
folio String El folio identificador del caso.
procedure_step_id String Identificador del paso del servicio.
description String Descripción del caso.
procedure_id String Identificador del servicio al que pertenece el caso.
done Boolean Bandera que identifica si el caso está cerrado.
archived Boolean Bandera que identifica si el caso está archivado.
amount Float Cantidad en pesos del precio específico para el caso.
external_payment_url String URL externa para redirigir al ciudadano en el paso de Realizar pago.
external_payment_refresh_status_url String URL externa para consultar el status de un pago.
custom_data Objeto/Hash Objeto que contiene los datos a recabar del caso.
closed_as String Descriptor de cómo se cierra el caso: solved(resuelto), expired(vencido) o denied(no procedente).
closed_reason String Descripción de porqué un caso fue cerrado cuando es denied(no procedente).
metadata Objeto/Hash Objeto que contiene metadatos del objeto.

Descripción de campos del ciudadano (citizen)

Parámetro Tipo Descripción
name String Nombre completo del ciudadano que inició el caso.
email String Correo electrónico del ciudadano que inició el caso.
phone String 10 dígitos, Teléfono del ciudadano que inició el caso.

Ejemplo de respuesta

{
  "id": 41,
  "procedure": "Acta de nacimiento",
  "procedure_id": "acta_de_nacimiento_6ccff29a-1625-477f-9d11-9b6a791d0ffa",
  "subject": null,
  "citizen_name": "Ana Jiménez Ruiz",
  "citizen_email": "ana@mail.com",
  "citizen_phone": 1234567890,
  "folio": "ABCD-111",
  "status": "done",
  "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 ciudadano...",
  "attachments": [],
  "done": false,
  "archived": true,
  "archived_at": "2019-02-14T20:49:07.357-06:00",
  "current_step_id": "paso-123",
  "solved_by": "user@mail.com",
  "amount": 500.00,
  "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d",
  "external_payment_url": "https://payment.url",
  "external_payment_refresh_status_url": "https://paymentstatus.url",
  "payment_redirect_url": "https://payment.redirection.url/",
  "citizen_opt_in": true,
  "closed_as": "expired",
  "closed_reason": "No cumplió con los requisitos necesarios",
  "metadata": {
    "dato": "valor"
  }
}

Mover un caso ciudadano al siguiente paso

Actualiza el caso ciudadano especificado al siguiente paso que le corresponde en el servicio.

HTTP Request

PUT /v1/citizen_case/:id/move_to_next_step

curl "https://api.urbem.digital/v1/citizen_cases/2/move_to_next_step?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT

Parámetros

Parámetro Descripción
id Identificador del caso.

Ejemplo de respuesta

{
  "id": 41,
  "procedure": "Acta de nacimiento",
  "procedure_id": "acta_de_nacimiento_6ccff29a-1625-477f-9d11-9b6a791d0ffa",
  "subject": null,
  "citizen_name": "Ana Jiménez Ruiz",
  "citizen_email": "ana@mail.com",
  "citizen_phone": 1234567890,
  "folio": "ABCD-111",
  "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 ciudadano...",
  "attachments": [],
  "done": false,
  "current_step_id": "paso-124",
  "solved_by": "user@mail.com",
  "amount": 500.00,
  "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d",
  "payment_redirect_url": "https://payment.redirection.url/",
  "citizen_opt_in": true,
  "closed_as": "solved",
  "closed_reason": "",
  "metadata": {}
}

Crear una tarifa para un caso ciudadano.

Crear una tarifa para un caso ciudadano. Ésta se mostrará al ciudadano una vez se encuentre en el paso de "Realizar pago".

HTTP Request

POST /v1/citizen_cases/:id/custom_fees

curl "https://api.urbem.digital/v1/citizen_cases/123/custom_fees?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "custom_fee": {
    "discount": true,
    "discount_value": 10,
    "discount_unit": "percentage",
    "description": "Pagos y multas",
    "concepts": [
      {
          "accounting_item": "ingresos-001",
          "title": "Servicio",
          "value": 200.0,
          "columna_adicional": "valor"
      },
      {
          "accounting_item": "ingresos-002",
          "title": "Otro",
          "value": 230.5,
          "columna_adicional": "valor"
      }
    ]
  }
}
'

Ejemplo de respuesta

{
  "id": 22,
  "set_by": "Mi Organización",
  "discount": true,
  "discount_value": 10,
  "discount_unit": "percentage",
  "description": "Pagos y multas",
  "concepts": [
    {
        "accounting_item": "ingresos-001",
        "title": "Servicio",
        "value": 200.0,
        "columna_adicional": "valor",
        "selected": true
    },
    {
        "accounting_item": "ingresos-002",
        "title": "Otro",
        "value": 230.5,
        "columna_adicional": "valor",
        "selected": false
    }
  ],
  "citizen_case_id": 123,
  "created_at": "2020-11-27T13:25:30.970-06:00"
}

Descripción de campos en respuesta

Parámetro Tipo Descripción
id String Identificador de la tarifa variable creada.
set_by String Correo o nombre del usuario/organización que creó la tarifa variable. Cuando la creación se lleva a cabo vía URBEM API, el campo contendrá el nombre de la Organización.
discount Boolean Bandera que define si la tarifa variable contiene descuento del total. Default: false
discount_value Float Valor de descuento que se aplicará al total de la tarifa.
discount_unit String Unidad para aplicar descuento al total de la tarifa. Valores disponibles: percentage o pesos
description String Descripción de la tarifa para el usuario ciudadano.
concepts Array Arreglo de objetos que contienen los conceptos de pago establecidos en la tarifa.
citizen_case_id Integer Identificador del caso ciudadano.
created_at String Timestamp de la fecha de creación de la tarifa.

Descripción de campos de cada concepto (concept)

Parámetro Tipo Descripción
accounting_item String Partida contable correspondiente al concepto.
title String Título o nombre del concepto.
value Float Valor total a pagar por el concepto.
selected Boolean Bandera que describe si el concepto fue seleccionado por el usuario ciudadano para pagarlo.

Citas

Devuelve un arreglo con las citas agendadas por un ciudadano dentro de un caso ciudadano.

HTTP Request

GET /v1/citizen_case/:id/appointments

curl "https://api.urbem.digital/v1/citizen_cases/2/appointments?auth_token=apitoken123"

Parámetros

Parámetro Descripción
id Identificador del caso.

Ejemplo de respuesta

[
    {
      "citizen_case_id": 2,
      "status": "attended",
      "date": "2022-04-25 08:00",
      "scheduled_at": "2021-06-29 17:12:14 -0500",
      "attended_by": "colaborador@mail.com",
      "center_name": "Secretaría de transporte"
    }
]

Descripción de campos en respuesta

Parámetro Tipo Descripción
citizen_case_id Integer Identificador del caso ciudadano.
status String Estado de la cita: attended(atendida), not_attended(no atendida), cancelled(cancelada) o pending(pendiente)
date String Fecha y hora programada para la cita
scheduled_at String Timestamp que indica la fecha y hora en la que se agendó la cita por el ciudadano.
attended_by String Correo electrónico de la persona que marcó la cita como atendida o no atendida.
center_name String Nombre del centro en el que se agendó la cita.

Pre caso ciudadano

Crear pre caso ciudadano

Crear un pre caso ciudadano para un trámite.

HTTP Request

POST /v1/prior_citizen_cases/

curl "https://api.urbem.digital/v1/prior_citizen_cases?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '

{
  "prior_citizen_case": {
    "procedure_id": "un_tramite_123",
    "disable_edit": "true",
    "citizen_data": {
      "email": "ana@correo.com",
      "first_name": "Ana",
      "last_name": "Flores",
      "second_last_name": "Ramírez",
      "phone": "8080808080",
      "curp": "CURPXXXXXXXXXX09",
      "birthdate": "20/10/1999",
      "gender": "Femenino",
      "birthplace": "Baja California"
    }
  }
}
'

Parámetros

Parámetro Tipo Descripción
procedure_id String Id del trámite que el ciudadano realizará
disable_edit Boolean Bandera que impide que se editen los datos en el formulario de creación de caso
citizen_data JSON Información del ciudadano

Descripción de campos de cada dato ciudadano (citizen_data)

Parámetro Tipo Descripción
email String Dirección de correo electrónico usada por el usuario
first_name String Nombre del ciudadano
last_name String Primer apellido del ciudadano
second_last_name String Segundo apellido del ciudadano
phone String Teléfono del ciudadano
curp String CURP del ciudadano
birthdate String Fecha de nacimiento del ciudadano
gender String Género del ciudadano
birthplace String Estado de nacimiento del ciudadano 
{
  "id": "2ab682be-xxxx-yyyy-zzzz-7e7a008f7660",
  "public_url": "urbem.digital/public/prior_citizen_case/2ab682be-xxxx-yyyy-zzzz-7e7a008f7660"
}

Descripción de campos en respuesta

Parámetro Tipo Descripción
id String Identificador único del ciudadano
public_url String URL de Urbem para redirigir al ciudadano donde encontrará su información

Documentos

Crear documento

Crear un documento interno o para el ciudadano en un caso ciudadano.

HTTP Request

POST /v1/citizen_cases/:citizen_case_id/documents

Existen 2 formas de crear un documento. La primera es enviando el nombre del documento(attachment_data_filename) y el contenido del documento en base64(attachment_data_uri). La segunda es enviando una url(attachment_url) que apunte directamente al archivo.

curl "https://api.urbem.digital/v1/citizen_cases/1/documents?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "document": {
    "attachment_data_filename": "licencia.pdf",
    "attachment_data_uri": "data:application/pdf;base64,a099encodedfile000"
  }
}
'

curl "https://api.urbem.digital/v1/citizen_cases/1/document?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "document": {
    "attachment_url": "https://www.application.url/licencia.pdf",
    "signature_limit_date": "2021-06-22"
  }
}
'

Parámetros

Parámetro Descripción
attachment_data_filename Nombre del documento
attachment_data_uri Contenido del archivo en base64
attachment_url URL que apunta directamente al archivo
signature_limit_date Permite asignar una fecha límite de firma al documento si el paso requiere algún tipo de firma

Ejemplo de respuesta

{
  "id": "95e7135a-a72b-4523-8dc0-27e5ed311be4",
  "folio": "po2sy",
  "citizen_case_id": 2,
  "procedure_id": "mi-servicio-729ad83a-6e11-48c2-83bb-d6f986d032f3",
  "signed": true,
  "signed_at": "2020-11-08T14:06:22.801-06:00",
  "signed_by": ["usuario@firmante.com"],
  "signed_document_url": "https://midocumentofirmado.com/firmado.pdf",
  "signed_document_filename": "firmado.pdf",
  "document": {
    "id": 109,
    "url": "https://midocumentooriginal.com/original.pdf",
    "filename": "original.pdf",
    "format": "file"
  },
  "digest_hex": "87120ac3549c11b9c2f74510a984d328cb88c960a4d5876ce6f497210d137d7a",
  "created_at": "2020-09-10T13:37:03.264-05:00",
  "uploaded_by": "usuario@mail.com",
  "signature": "bcebaaa68beb2d03c73d35e679c2482724d89b3042ba90532975b946d6fd4ce733b39066e5bc6e3fe8b3df5ed589c2f7eb2082cf4f117a3aa7220865bd619c1e6bfda62d318954594397391d102d5058877d48f3bef66bf768a34419f1bf651ca10f6b13c63b2d5...",
  "conservation_document_url": "https://miconstanciadeconservacion.com/constancia.pdf",
  "xades_document_url": "https://xml_advanced_e_signature.url/signature.xml",
  "document_type": "collaborator"
}

Ver documentos de un caso

Devuelve un arreglo con los documentos internos y del ciudadano adjuntos a un caso ciudadano.

HTTP Request

GET /v1/citizen_case/:id/documents

curl "https://api.urbem.digital/v1/citizen_cases/2/documents?auth_token=apitoken123"

Parámetros

Parámetro Descripción
id Identificador del caso.

Ejemplo de respuesta

[
    {
        "id": "95e7135a-a72b-4523-8dc0-27e5ed311be4",
        "folio": "po2sy",
        "citizen_case_id": 2,
        "procedure_id": "mi-servicio-729ad83a-6e11-48c2-83bb-d6f986d032f3",
        "signed": true,
        "signed_at": "2020-11-08T14:06:22.801-06:00",
        "signed_by": [
            "usuario@firmante.com"
        ],
        "signed_document_url": "https://midocumentofirmado.com/firmado.pdf",
        "signed_document_filename": "firmado.pdf",
        "document": {
            "id": 109,
            "url": "https://midocumentooriginal.com/original.pdf",
            "filename": "original.pdf",
            "format": "file"
        },
        "digest_hex": "87120ac3549c11b9c2f74510a984d328cb88c960a4d5876ce6f497210d137d7a",
        "created_at": "2020-09-10T13:37:03.264-05:00",
        "uploaded_by": "usuario@mail.com",
        "signature": "bcebaaa68beb2d03c73d35e679c2482724d89b3042ba90532975b946d6fd4ce733b39066e5bc6e3fe8b3df5ed589c2f7eb2082cf4f117a3aa7220865bd619c1e6bfda62d318954594397391d102d5058877d48f3bef66bf768a34419f1bf651ca10f6b13c63b2d5...",
        "conservation_document_url": "https://miconstanciadeconservacion.com/constancia.pdf",
        "xades_document_url": "https://xml_advanced_e_signature.url/signature.xml"
    }
]

Descripción de campos en respuesta

Parámetro Tipo Descripción
id String Identificador del documento.
folio String Folio único para verificar el documento una vez firmado.
citizen_case_id Integer Identificador del caso ciudadano.
procedure_id String Identificador del servicio al que pertenece el caso ciudadano.
signed Boolean Bandera que indica si el documento fue firmado.
signed_at String Timestamp que indica la fecha de firma del caso en caso de haberse firmado.
signed_by Array de Strings Arreglo que contiene el correo de los usuarios que firmaron el documento.
signed_document_url String URL del documento que incluye la hoja de firma.
signed_document_filename String Nombre del archivo que incluye la hoja de firma.
document Object Objeto que contiene los atributos del archivo original.
digest_hex String Cadena de digestión SHA256 del contenido del archivo original.
created_at String Timestamp de la fecha de creación del documento.
uploaded_by String Correo del usuario responsable de subir el documento.
signature String Cadena de firma.
conservation_document_url String URL del documento que contiene la constancia de conservación del evento de firma.
xades_document_url String URL del documento que cumple con el estándar de firma electrónica avanzada (XAdES)
document_type String Tipo de documento. Si fue subido por/para colaborador collaborator y si fue subido por/para ciudadano citizen

Resultados

Crear resultado

Crear un documento de resultado para un caso ciudadano.

HTTP Request

POST /v1/citizen_cases/:citizen_case_id/results

Existen 2 formas de crear un documento de resultado. La primera es enviando el nombre del documento(attachment_data_filename) y el contenido del documento en base64(attachment_data_uri). La segunda es enviando una url(attachment_url) que apunte directamente al archivo.

curl "https://api.urbem.digital/v1/citizen_cases/1/results?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "result": {
    "attachment_data_filename": "licencia.pdf",
    "attachment_data_uri": "data:application/pdf;base64,a099encodedfile000",
    "send": "true"
  }
}
'

curl "https://api.urbem.digital/v1/citizen_cases/1/results?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "result": {
    "attachment_url": "https://www.application.url/licencia.pdf",
    "send": "false",
    "signature_limit_date": "2021-06-22"
  }
}
'

Parámetros

Parámetro Descripción
attachment_data_filename Nombre del documento
attachment_data_uri Contenido del archivo en base64
attachment_url Url que apunte directamente al archivo
send Indica si el documento de resultado debe ser enviado vía correo electrónico al ciudadano que creó el caso
signature_limit_date Permite asignar una fecha límite de firma al resultado si el paso lo requiere

Ejemplo de respuesta

{
    "id": "95e7135a-a72b-4523-8dc0-27e5ed311be4",
    "folio": "qy3tr",
    "citizen_case_id": 1,
    "procedure_id": "mi-servicio-729ad83a-6e11-48c2-83bb-d6f986d032f3",
    "signed": false,
    "signed_at": null,
    "signed_by": [],
    "signed_document_url": null,
    "signed_document_filename": null,
    "document": {
        "id": 109,
        "url": "https://midocumentooriginal.com/licencia.pdf",
        "filename": "licencia.pdf",
        "format": "file"
    },
    "digest_hex": "87120ac3549c11b9c2f74510a984d328cb88c960a4d5876ce6f497210d137d7a",
    "created_at": "2020-09-10T13:37:03.264-05:00",
    "uploaded_by": "Nombre organización",
    "signature": null,
    "conservation_document_url": null,
    "xades_document_url": null
    }

Ver resultado

Devuelve un arreglo con los resultados ciudadanos adjuntos a un caso ciudadano.

HTTP Request

GET /v1/citizen_case/:id/results

curl "https://api.urbem.digital/v1/citizen_cases/2/results?auth_token=apitoken123"

Parámetros

Parámetro Descripción
id Identificador del caso.

Ejemplo de respuesta

[
    {
        "id": "95e7135a-a72b-4523-8dc0-27e5ed311be4",
        "folio": "qy3tr",
        "citizen_case_id": 2,
        "procedure_id": "mi-servicio-729ad83a-6e11-48c2-83bb-d6f986d032f3",
        "signed": true,
        "signed_at": "2020-11-08T14:06:22.801-06:00",
        "signed_by": [
            "usuario@firmante.com"
        ],
        "signed_document_url": "https://midocumentofirmado.com/firmado.pdf",
        "signed_document_filename": "firmado.pdf",
        "document": {
            "id": 109,
            "url": "https://midocumentooriginal.com/original.pdf",
            "filename": "original.pdf",
            "format": "file"
        },
        "digest_hex": "87120ac3549c11b9c2f74510a984d328cb88c960a4d5876ce6f497210d137d7a",
        "created_at": "2020-09-10T13:37:03.264-05:00",
        "uploaded_by": "usuario@mail.com",
        "signature": "bcebaaa68beb2d03c73d35e679c2482724d89b3042ba90532975b946d6fd4ce733b39066e5bc6e3fe8b3df5ed589c2f7eb2082cf4f117a3aa7220865bd619c1e6bfda62d318954594397391d102d5058877d48f3bef66bf768a34419f1bf651ca10f6b13c63b2d5...",
        "conservation_document_url": "https://miconstanciadeconservacion.com/constancia.pdf",
        "xades_document_url": "https://xml_advanced_e_signature.url/signature.xml"
    }
]

Descripción de campos en respuesta

Parámetro Tipo Descripción
id String Identificador del resultado.
folio String Folio único para verificar una vez que el documento fue firmado.
citizen_case_id Integer Identificador del caso ciudadano.
procedure_id String Identificador del servicio al que pertenece el caso ciudadano.
signed Boolean Bandera que indica si el resultado fue firmado.
signed_at String Timestamp que indica la fecha de firma del caso en caso de haberse firmado.
signed_by Array de Strings Arreglo que contiene el correo de los usuarios que firmaron el resultado.
signed_document_url String URL del documento que incluye la hoja de firma.
signed_document_filename String Nombre del archivo que incluye la hoja de firma.
document Object Objeto que contiene los atributos del archivo original.
digest_hex String Cadena de digestión SHA256 del contenido del archivo original.
created_at String Timestamp de la fecha de creación del resultado.
uploaded_by String Correo del usuario responsable de subir el documento de resultado.
signature String Cadena de firma.
conservation_document_url String URL del documento que contiene la constancia de conservación del evento de firma.
xades_document_url String URL del documento que cumple con el estándar de firma electrónica avanzada (XAdES)

Evaluaciones

Crear evaluación de un caso

Crear una evaluación de un caso ciudadano resuelto.

HTTP Request

POST /v1/citizen_cases/:id/ratings

curl "https://api.urbem.digital/v1/citizen_cases/1/ratings?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "rating":{
    "nps_option": "very_likely",
    "value": 5,
    "comments": "Todo muy bien!"
  }
}
'

Ejemplo de respuesta

{
  "id": 1,
  "value": 5,
  "created_at": "2024-03-05T17:33:21.589Z",
  "updated_at": "2024-03-05T17:33:21.589Z",
  "comments": "Todo muy bien!",
  "center_id": null,
  "procedure_id": "tramite_con_documento_ciudadano_0f5d55bb-d8c4-4476-b553-f8c4c34086c3",
  "citizen_case_id": 123,
  "nps_option": "very_likely",
  "other_reason": null
}

Descripción de campos en respuesta

Parámetro Tipo Descripción
id Integer Identificador de la evaluación.
value Integer Valor de calificación asignado del 1 al 5.
created_at String Timestamp de la fecha de creación de la evaluación.
updated_at String Timestamp de la fecha de actualización de la evaluación.
comments String Comentarios generales de la evaluación.
citizen_case_id Integer Identificador del caso ciudadano.
procedure_id String Identificador del servicio al que pertenece el caso ciudadano.
nps_option String Valor del NPS, valores permitidos: Muy probable: very_likely, Probable: likely, Ninguno: neither, Poco probable: unlikely, Nada probable: very_unlikely
other_reason String Razón por la que no se otorgó calificación 5.

Actualizar evaluación

Actualizar una evaluación de un caso ciudadano resuelto.

HTTP Request

PUT /v1/citizen_cases/:id/ratings/1

curl "https://api.urbem.digital/v1/citizen_cases/1/ratings?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "rating":{
    "nps_option": "likely",
    "value": 4,
    "comments": "Todo muy bien!"
  }
}
'

Parámetros

Parámetro Descripción
citizen_case_id El identificador del caso.
rating Objeto de la evaluación con los nuevos atributos.

Parámetros de rating

Parámetro Tipo Descripción
value Integer Valor de calificación asignado del 1 al 5.
comments String Comentarios generales de la evaluación.
citizen_case_id Integer Identificador del caso ciudadano.
nps_option String Valor del NPS, valores permitidos: Muy probable: very_likely, Probable: likely, Ninguno: neither, Poco probable: unlikely, Nada probable: very_unlikely
other_reason String Razón por la que no se otorgó calificación 5.

Ejemplo de respuesta

{
  "id": 1,
  "value": 4,
  "created_at": "2024-03-05T17:33:21.589Z",
  "updated_at": "2024-03-05T17:46:40.821Z",
  "comments": "Todo muy bien!",
  "center_id": null,
  "procedure_id": "tramite_con_documento_ciudadano_0f5d55bb-d8c4-4476-b553-f8c4c34086c3",
  "citizen_case_id": 123,
  "nps_option": "likely",
  "other_reason": null
}

Revisiones

Listado de revisiones

Devuelve un arreglo con las revisiones de los casos ciudadanos dentro de tu organización.

HTTP Request

GET /v1/revisions

curl "https://api.urbem.digital/v1/revisions?auth_token=apitoken123"

Filtros / Parámetros

Parameter Default Description
page 1 Si no se envía se devuelven los casos correspondientes a la primer página.
citizen_case_id Devuelve las revisiones asociadas al caso ciudadano especificado.

Ejemplo de respuesta

[
  {
    "id": 123,
    "created_at": "2019-01-25T16:26:30.560-06:00",
    "updated_at": "2019-01-25T16:26:30.560-06:00",
    "completed": false,
    "approved": false,
    "attachments_count": 1,
    "citizen_attachments": [
      {
        "id": 1,
        "status": "pending",
        "rejected_reason": null,
        "citizen_id": 3,
        "requirement_name": "Pasaporte mexicano",
        "created_at": "2019-01-25T16:26:30.562-06:00",
        "attachment": {
          "id": 36,
          "url": "https://archivos.url/archivo.png",
          "filename": "archivo.png"
        }
      }
    ],
    "citizen_case_id": 2,
    "action": "send_documents",
    "assigned_to": "anaruiz@mail.com",
    "comments": null
  },
  ...
]

Ver revisión

Obtener una revisión específica.

HTTP Request

GET /v1/revisions/:id

curl "https://api.urbem.digital/v1/revisions/id?auth_token=apitoken123"

Descripción de campos en respuesta

Parámetro Tipo Descripción
id Integer Identificador de la revisión.
created_at String Timestamp de la fecha de creación de la revisión.
updated_at String Timestamp de la fecha de la última actualización de la revisión.
completed boolean Bandera que identifica si la revisión fue completada o no.
approved boolean Bandera que identifica si la revisión fue revisada o no.
attachments_count int Número de documentos adjuntos en la revisión.
citizen_case_id int Identificador del caso al que pertenece la revisión.
action String send_documents
assigned_to String Correo electrónico de la persona asignada para revisar los documentos adjuntos.
comments String Comenterios sobre la revisión.
citizen_attachments Array Arreglo de documentos adjuntos a la revisión.

Campos para cada uno de los objetos en citizen_attachments

Parámetro Tipo Descripción
id Integer Identificador del documento adjunto.
citizen_id Integer Identificador del ciudadano que subió el documento.
status String Estado del documento adjunto.
rejected_reason String Razón de rechazo del documento.
requirement_name String Nombre del requisito asociado al documento adjunto.
created_at String Timestamp de la fecha de subida del documento.

Campos para attachment

Parámetro Tipo Descripción
id Integer Identificador del archivo.
url String Url del archivo adjunto.
filename String Nombre del archivo adjunto.

Ejemplo de respuesta

{
  "id": 123,
  "created_at": "2019-01-25T16:26:30.560-06:00",
  "updated_at": "2019-01-25T16:26:30.560-06:00",
  "completed": false,
  "approved": false,
  "attachments_count": 1,
  "citizen_attachments": [
    {
      "id": 1,
      "status": "pending",
      "rejected_reason": null,
      "citizen_id": 3,
      "requirement_name": "Pasaporte mexicano",
      "created_at": "2019-01-25T16:26:30.562-06:00",
      "attachment": {
        "id": 36,
        "url": "https://archivos.url/archivo.png",
        "filename": "archivo.png"
      }
    }
  ],
  "citizen_case_id": 2,
  "action": "send_documents",
  "assigned_to": "anaruiz@mail.com",
  "comments": null
}

Crear una revisión

Crear una nueva revisión de un caso ciudadano. A través de las revisiones se pueden adjuntar documentos que envía un ciudadano.

HTTP Request

POST /v1/revisions/

curl "https://api.urbem.digital/v1/revisions?citizen_case_id=1&auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '
{
  "revision": { 
    "citizen_case_id": 1,
    "approved": false,
    "comments": "Comentarios",
    "citizen_attachments_attributes":[
      {
        "status":"approved",
        "rejected_reason": null,
        "requirement_id": 2,
        "attachment_attributes": {
          "attachment_data_filename": "INE.pdf",
          "attachment_data_uri": "base64;1123o90840..."
        }
      },
      {
        "status":"approved",
        "rejected_reason": "",
        "requirement_id":3,
        "attachment_attributes": {
          "remote_attachment_url": "https://url-documento-remoto.pdf"
        }
      }
    ]
  }
}
'

Ejemplo de respuesta

{
  "id": 71,
  "created_at": "2022-11-17T16:47:20.243-06:00",
  "updated_at": "2022-11-17T16:47:20.243-06:00",
  "completed": true,
  "approved":true,
  "attachments_count": 2,
  "citizen_attachments":[
    {
      "id": 2,
      "attachment_url": "https://urbem-api.document/123",
      "requirement_id": 2,
      "requirement_name": "INE",
      "created_at": "2022-11-17T16:47:20.246-06:00",
      "updated_at": "2022-11-17T16:47:20.246-06:00",
      "status": "approved",
      "rejected_reason": null
    },
    {
      "id": 3,
      "attachment_url":"https://urbem-api.document/124",
      "requirement_id": 3,
      "requirement_name": "Acta de nacimiento",
      "created_at": "2022-11-17T16:47:20.249-06:00",
      "updated_at": "2022-11-17T16:47:20.249-06:00",
      "status":"approved",
      "rejected_reason":""
    }
  ],
  "citizen_case_id": 1,
  "citizen_phone": "044 72 3183 7964",
  "action": "send_documents",
  "assigned_to": "responsible@gmail.com",
  "comments": "Comentarios"
}

Actualizar una revisión

Actualiza la revisión especificada asignando los valores del hash revision. Los valores que no contenga el hash no serán modificados.

HTTP Request

PUT /v1/revisions/:id

curl "https://api.urbem.digital/v1/revisions/2?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
{
  "revision": {
    "approved": "false",
    "completed": "true",
    "comments": "Comentarios acerca de una revisión...",
    "citizen_attachments_attributes": [{
      "id": 1,
      "status": "rejected",
      "rejected_reason": "No se puede abrir el archivo.",
    }]
  }
}
'

Parámetros

Parámetro Descripción
id Identificador de la revisión.
revision Objeto de la revisión con los nuevos atributos.

Parámetros de revision

Parámetro Tipo Descripción
approved boolean Determina si la revisión fue aprobada o no.
completed boolean Determina si la revisión está completa o no.
comments string Comentarios relacionados a la revisión.

Descripción de campos de los archivos (citizen_attachments_attributes)

Parámetro Tipo Descripción
id int Identificador del archivo.
status String Estado de revisión del archivo. Valores posibles: pending, approved o rejected.
rejected_reason String Razón de rechazo de un documento.

Ejemplo de respuesta

{
  "id": 123,
  "created_at": "2019-01-25T16:26:30.560-06:00",
  "updated_at": "2019-01-25T16:26:30.560-06:00",
  "completed": true,
  "approved": false,
  "attachments_count": 1,
  "citizen_attachments": [
    {
      "id": 1,
      "status": "rejected",
      "rejected_reason": "No se puede abrir el archivo.",
      "citizen_id": 3,
      "requirement_name": "Pasaporte mexicano",
      "created_at": "2019-01-25T16:26:30.562-06:00",
      "attachment": {
        "id": 36,
        "url": "https://archivos.url/archivo.png",
        "filename": "archivo.png"
      }
    }
  ],
  "citizen_case_id": 2,
  "action": "send_documents",
  "assigned_to": "anaruiz@mail.com",
  "comments": "Comentarios acerca de una revisión..."
}

Cuenta ciudadana

Ver ciudadano

Obtener la información de un ciudadano registrado.

Parámetros requeridos en el request

Para obtener la información del ciudadano registrado es necesario incluir en el cuerpo del request los parámetros: email y phone.

HTTP Request

GET /v1/citizens/:curp

curl "https://api.urbem.digital/v1/citizens/ABCD880611XXXXXX11?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
  {
    "email": "citizen@mail.com",
    "phone": "1234567890"
  }
'

Descripción de campos en respuesta

Parámetro Tipo Descripción
first_name String Nombre del ciudadano.
last_name String Apellido paterno del ciudadano.
second_last_name String Segundo apellido o apellido materno del ciudadano.
birthdate String Fecha de nacimiento en formato: DD/MM/YYYY
curp String CURP del ciudadano.
rfc String RFC del ciudadano.
email String Correo electrónico del ciudadano.
phone String Teléfono del ciudadano.
gender String Género del ciudadano.
state String Dirección: Estado de la república.
city String Dirección: Ciudad.
number String Dirección: Número interior.
street String Dirección: Calle.
postal_code String Dirección: Código postal.
ext_number String Dirección: Número exterior.
town String Dirección: Colonia.
created_at Timestamp Fecha de registro del ciudadano en la organización.
updated_at Timestamp Fecha de actualización del ciudadano.

Ejemplo de respuesta

{
  "ext_number": "123",
  "email": "citizen@mail.com",
  "rfc": "XXXX880611",
  "curp": "ABCD880611XXXXXX11",
  "gender": "Femenino",
  "state": "Estado",
  "postal_code": "11111",
  "created_at": "2022-02-02 17:57:24 UTC",
  "updated_at": "2022-02-24 15:52:29 UTC",
  "city": "Ciudad",
  "birthdate": "11-06-1988",
  "last_name": "Ruiz",
  "second_last_name": "López",
  "number": "",
  "first_name": "Ana",
  "town": "Colonia",
  "phone": "1234567890",
  "street": "Calle"
}

Actualizar ciudadano

Actualizar la información de un ciudadano registrado.

Parámetros requeridos en el request

Para actualizar la información del ciudadano registrado es necesario incluir en el cuerpo del request los parámetros: email y phone para identifica al ciudadano que se requiere actualizar.

HTTP Request

PUT /v1/citizens/:curp

curl "https://api.urbem.digital/v1/citizens/ABCD880611XXXXXX11?auth_token=apitoken123" \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '
  {
    "email": "citizen@mail.com",
    "phone": "1234567890",
    "citizen": {
      "first_name": "Nombre actualizado",
      "curp": "CURP-ACTUALIZADO"
    }
  }
'

Parámetros

Parámetro Descripción
curp Identificador único de ciudadano.
email Correo electrónico para identificar al ciudadano.
phone Teléfono para identificar al ciudadano.
citizen Objeto del ciudadano con los nuevos atributos.

Parámetros de citizen

Parámetro Tipo Descripción
first_name String Nombre del ciudadano.
last_name String Apellido paterno del ciudadano.
second_last_name String Segundo apellido o apellido materno del ciudadano.
birthdate String Fecha de nacimiento en formato: DD/MM/YYYY
curp String CURP del ciudadano.
rfc String RFC del ciudadano.
gender String Género del ciudadano.
state String Dirección: Estado de la república.
city String Dirección: Ciudad.
number String Dirección: Número interior.
street String Dirección: Calle.
postal_code String Dirección: Código postal.
ext_number String Dirección: Número exterior.
town String Dirección: Colonia.

Ejemplo de respuesta

{
  "ext_number": "123",
  "email": "citizen@mail.com",
  "rfc": "XXXX880611",
  "curp": "CURP-ACTUALIZADO",
  "gender": "Femenino",
  "state": "Estado",
  "postal_code": "11111",
  "created_at": "2022-02-02 17:57:24 UTC",
  "updated_at": "2022-02-24 15:52:29 UTC",
  "city": "Ciudad",
  "birthdate": "11-06-1988",
  "last_name": "Ruiz",
  "second_last_name": "López",
  "number": "",
  "first_name": "Nombre actualizado",
  "town": "Colonia",
  "phone": "1234567890",
  "street": "Calle"
}
shell