URBEM API

Documentación del URBEM API.

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

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.

Si no envías el parámetro auth_token con un API key válida, URBEM API devolverá una respuesta de error con status 401.

¿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	Default	Description
service_id		Devuelve los servicios/trámites asociados al departamento especificado.
page	1	Si no se envía se devuelven los servicios correspondientes a la primer página.

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

Los únicos atributos modificables son name, description, available, url, external_reference y accounting_id.

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.

Los únicos atributos modificables son folio, status, name, email, address, city, state, zip_code, metadata, receipt_url y xml_receipt_url.

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": {
      "name": "Ana Jiménez 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"
    }
  }
}
'

El hash citizen_attributes modifica directamente los campos del ciudadano asociado al caso.

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.

Los únicos atributos modificables son folio, procedure_step_id, description, done, amount y citizen_attributes.

Los únicos atributos modificables para citizen_attributes son name, email, fb_id y phone.

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

Es importante siempre verificar el status del caso para saber a qué paso se está moviendo y evitar saltar múltiples pasos a la vez.

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.

El arreglo concepts puede contener más llaves con valores adicionales a accounting_item, title, value, selected si así se requiere.

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

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.",
    }]
  }
}
'

El arreglo citizen_attachments_attributes modifica directamente los campos de los documentos asociados a la revisión del caso ciudadano.

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.

Los únicos atributos modificables son approved, completed, comments y citizen_attachments_attributes.

Los únicos atributos modificables para citizen_attachments_attributes son status y rejected_reason.

Los atributos para attachment no son modificables.

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