NAV Navbar

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

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.

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

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.

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

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

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.
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).
description String Descripción del pago realizado.
created_at String/timestamp Momento en el que se realizó el pago.

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

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",
    "metadata": { "key": "value", ... }
  }
}
'

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 o pending.
metadata Object/Hash Objeto que contiene un hash con metadatos relacionados al pago.

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

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_status Devuelve los casos que tienen el status especificado.
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,
    "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": [],
    "labels": []
  },
  ...
]

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.
labels Array de objects Lista de etiquetas del caso.

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.

Campos para labels

Parámetro Tipo Descripción
name String Nombre de la etiqueta.

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": [],
  "labels": []
}

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",
    "status": "done",
    "description": "Descripción del caso ciudadano...",
    "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.
status String Estado del caso. Depende de los pasos agregados a un servicio. Valores posibles: send_documents, make_payment, get_result, evaluate_service, active o done.
description String Descripción del 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": [],
  "labels": []
}

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