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"

Filtros / Parámetros

Parameter Type Default Description
service_id String Devuelve los servicios/trámites asociados al departamento especificado.
page String 1 Si no se envía se devuelven los servicios correspondientes a la primer página.
available Boolean Si no se envía se devuelven los servicios publicados y no publicados.

Ejemplo de respuesta

[
  {
    "id": "un_servicio_123",
    "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,
    "procedure_type": "procedure",
    "available": false,
    "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"
  },
  ...
]

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.
department String Nombre del departamento al que pertenece el servicio.
description String Descripción del servicio.
url String URL del servicio.
procedure_type String Tipo de servicio seleccionado. Valores posibles: beneficence, procedure, report o information.
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

Ejemplo de respuesta

{
  "id": "un_servicio_123",
  "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,
  "procedure_type": "procedure",
  "available": false,
  "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"
}

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",
  "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,
    "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.
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,
  "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,
  "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": [
    {
        "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": ""
}

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 Description
page 1 Si no se envía se devuelven los casos correspondientes a la primer página.
created_after Devuelve los casos creados después de la fecha especificada.
by_procedure Devuelve los casos asociados al servicio especificado.

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,
    "citizen_fb_id": "1234567890",
    "folio": null,
    "amount": null,
    "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": "",
    "attachments": [],
    "done": false,
    "current_step_id": 'paso-123',
    "solved_by": "user@mail.com",
    "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d"
  },
  ...
]

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?auth_token=apitoken123"

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.
citizen_fb_id String Identificador de Facebook 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.
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.
public_token String Token para generar la URL pública del caso ciudadano.

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,
  "citizen_fb_id": "1234567890",
  "folio": null,
  "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": "",
  "attachments": [],
  "done": false,
  "current_step_id": 'paso-123',
  "solved_by": "user@mail.com",
  "amount": null,
  "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d"
}

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,
    "citizen_attributes": {
      "first_name": "Ana",
      "fathers_last_name": "Jiménez",
      "mothers_last_name": "Ruiz",
      "email": "ana@mail.com",
      "fb_id": "12345678",
      "phone": "12345678",
    }
  }
}
'

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",
  "citizen_fb_id": "12345678",
  "folio": "ABCD-111",
  "status": "make_payment",
  "custom_data": {},
  "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,
  "current_step_id": 'paso-123',
  "solved_by": null,
  "amount": 50000,
  "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d"
}

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,
    "citizen_attributes": {
      "name": "Ana Jiménez Ruiz",
      "email": "ana@mail.com",
      "fb_id": "12345678",
      "phone": "1234567890"
    }
  }
}
'

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á resuelto.
amount Float Cantidad en pesos del precio específico para el caso.

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.
fb_id String Identificador de Facebook del ciudadano.
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,
  "citizen_fb_id": "12345678",
  "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,
  "current_step_id": 'paso-123',
  "solved_by": "user@mail.com",
  "amount": 500.00
  "public_token": "772064d3-bcf8-437b-930f-3d159d3f889d"
}

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,
  "citizen_fb_id": "12345678",
  "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"
}

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.

Documentos internos

Devuelve un arreglo con los documentos internos 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",
        "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.
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)

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"
  }
}
'

Filtros / 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",
    "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",
        "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.
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)

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
}

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..."
}
shell