Manual de Uso de API REST de Carpeta Ciudadana

Manual de uso de API REST de
Carpeta Ciudadana
1
Contenido
1. Introducción 4
2. Conceptos 5
3. Servicios web RESTful 7

a. Obtener token de autorización 7
b. Servicios de áreas 9
i. Crear una o más áreas 9
ii. Consultar aŕeas 10
iii. Consultar área 12
iv. Modificar área 13
v. Eliminar área 14
c. Consultar tipos de número de seguimiento 15
d. Crear notificación o comunicación 17
2
Tabla de versiones
Versión Fecha Descripción Elaborado por
v1 10/10/2022 Elaboración del documento Equipo de desarrollo
v1.0.1 08/11/2022 Se agregó servicios Equipo de desarrollo
v1.1 04/01/2023 Se agregó servicios para área Equipo de desarrollo
3
1. Introducción
a. Objetivo
El presente documento tiene como objetivo servir de manual de uso de

las interfaces de programación de aplicaciones (API) expuestas por el
sistema de Carpeta Ciudadana.
Con esta API se busca llegar a la interoperabilidad entre los sistemas

de trámite de la entidad y la Carpeta Ciudadana, que muestra las
notificaciones reportadas de la entidad a la ciudadanía.
b. Consideraciones previas
La entidad deberá proporcionar un correo institucional al equipo de

desarrollo de Carpeta Ciudadana para crear credenciales que se les
enviará por correo para el acceso y consulta vía API.
La entidad deberá cargar todas las áreas en el sistema de Carpeta

Ciudadana.
Las credenciales de acceso que se le entregarán son:
❖ client_id: Cliente ID
❖ client_secret: Cliente Secret
Los ambientes de los servicios son los siguientes:
Ambientes Rutas
Staging https://staging.carpetaciudadana.servicios.g
ob.pe/
QA https://qa.carpetaciudadana.servicios.gob.pe
/
Production https://carpetaciudadana.servicios.gob.pe/
4
2. Conceptos
a. API REST
Una API REST (también conocida como API RESTful), es una interfaz
de programación de aplicaciones que se ajusta al estilo arquitectónico
REST y permite la interacción con los servicios web RESTful.
Fuente: https://www.redhat.com/en/topics/api/what-is-a-rest-api
Un servicio web RESTful expone un conjunto de recursos que

identifican los objetivos de la interacción con sus clientes.
Fuente: http://www.jtech.ua.es/j2ee/restringido/cw/sesion11-apuntes.pdf
Fuente:
https://medium.com/beltranc/diferencia-entre-api-y-servicio-web-5f204af3aedb
5
b. OAuth2
OAuth(Open Authorization) es un estándar abierto que permite flujos

simples de autorización para sitios web o aplicaciones informáticas.
El marco de autorización de OAuth 2.0 permite que un tercero de

aplicación obtenga acceso limitado a un servicio HTTP.
OAuth 2.0 se centra en la simplicidad del desarrollador

cliente/consumidor del servicio, ya que se proporciona flujos de
autorización específicos para aplicaciones web, aplicaciones de
escritorio, teléfonos móviles y dispositivos.
Fuente: https://datatracker.ietf.org/doc/html/rfc6749
c. cURL
cURL es una herramienta para trabajar con URLs, y permite consultar

una URL desde la línea de comandos, también permite enviar datos de
formulario a un servidor soportando muchos protocolos incluyendo
HTTP, FTP, TELNET, etc.
Con cURL se puede hacer una petición HTTP a un determinado
servidor e imprimir su respuesta en la consola.
cURL es compatible con todos los métodos de peticiones de HTTP,

incluyendo POST, GET, PUT, DELETE. cURL puede usar Flags como:
Flags Descripción Sintaxis
-X Especifica el método HTTP que curl -X [method]

[URL]
se utilizará al enviar la solicitud
-H Agrega los parámetros de curl -X [method]

[URL] -H "X-Header:
cabecera a la solicitud HTTP value"
-d Especifica los datos a enviar al curl -X [method]

[URL] -d
servidor "key1=value1&key2=v
alue2" [URL]
6
3. Servicios web RESTful
a. Obtener token de autorización
Este servicio sirve para obtener el token de acceso, la entidad
obtendrá un token de acceso a los otros servicios web disponibles
para consultar sus áreas y crear una notificación y/o comunicación.
De preferencia la entidad deberá consultar este servicio porque los

tokens de acceso tienen un tiempo de expiración y la actualización del
token será automática a través de este servicio.
La entidad también podrá consultar en cuánto tiempo en segundos

expira el token de acceso a través del campo expires in o en el
access token JWT.
A continuación un ejemplo de como usar el servicio con cURL.
Ejemplo
*Credenciales de prueba, se deberían usar las que se proporcionaron a

la entidad
curl -X POST \
https://staging.carpetaciudadana.servicios.gob.pe/oauth2/token
\
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"grant_type": "client_credentials",
"client_id":
"MXsYHjR2yBUaDnveu_S5hsCvYRL5ihAKv-kAssDs4bc",
"client_secret":
"SBHXsXWkwfXsnRytYe9LN4I7l-WK10RrzBPTxwn2rQ0"
}'
Resultado:
{
"access_token":
"eyJraWQiOiJadi1RSEJyemtMRFVoUGdBLXlZUUFxMGxNVGZGZExjSGszT1BFY3R
Ob0xBIiwiYWxnIjoiSFM1MTIifQ.eyJpc3MiOiJDYXJwZXRhIENpdWRhZGFuYSIs
ImlhdCI6MTY2NjM3MTMxOSwiZXhwIjoxNjY2MzczMTE5LCJqdGkiOiI4MjhiOGQ1
My1kZGRiLTRhMjEtYjc3OS0wN2VlZTJhMjZkZWIiLCJ1c2VyIjp7ImlkIjoiMTIx
YTQ3NDktMmEyNS00MTcyLTlhMmYtMGZlYjdmNDYxMjJmIiwiZW1haWwiOiJtZGVs
7
Z2Fkby5wY21AZ21haWwuY29tIn19.hjtCRwF6SegLJRycSoZlp0geamZlIsoBVrb
hFcJuS__cBlX8eyFAenpf9iN3swRO84GiLna2sya8v0ZBqMID6w",
"token_type": "Bearer",
"expires_in": 7200,
"refresh_token":
"HlWAZQTLXrCWlBSaX-CbCw5AYQrq_VfEe6u3MwAPBwo",
"created_at": 1662649293
}
Descripción del API
Campos Descripción Tipo de dato Valor(es)

Permitido(s)
Entrada
grant_type tipo de cadena de “client_creden

consulta texto tials”
client_id identificador cadena de “credenciales

de cliente texto de la entidad”
client_secret clave secreta cadena de “credenciales

de cliente texto de la entidad”
Salida
access_token token de cadena de “nuevo

acceso (JWT) texto generado por
el API”
token_type tipo de token cadena de “Bearer” por

texto defecto
expires_in tiempo de numérico 7200 tiempo en

expiración segundos
refresh_token token de cadena de “nuevo

actualización texto generado por
el API”
created_at tiempo de fecha numérica “generado por

expiración el API”
8
b. Servicios de áreas
i. Crear una o más áreas
Este servicio sirve para crear áreas de manera individual o múltiple en

la entidad que desea enviar la notificación o comunicación.
La creación del área es necesaria antes del servicio de crear

notificación o comunicación, ya que se requiere el identificador del
área como dato de entrada.
Ejemplos
*Las entidades deberán usar las credenciales que se proporcionaron
curl --location --request POST

'https://staging.carpetaciudadana.servicios.gob.pe/api/v1/servic
es/areas' \
--header 'Authorization: Bearer
eyJraWQiOiJDZFZNZFlaNjNEVjhzLTBJZ25YcHpoOWZZOXFQM3NZbS1EN2hpUUM2
MG5nIiwiYWxnIjoiSFM1MTIifQ.eyJpc3MiOiJDYXJwZXRhIENpdWRhZGFuYSIsI
mlhdCI6MTY3Mjg0NTg2NiwiZXhwIjoxNjcyODQ5NDY2LCJqdGkiOiJkOTRkYzM0Y
i1jMDhiLTQ1ZmMtOTFlYS0xN2RhYjQwNzBiNjUiLCJ1c2VyIjp7ImlkIjoiZTg2N
DU0NDgtOGRmOC00NDk2LTgxY2QtM2VmZTRhZmQ4NzVmIiwiZW1haWwiOiJtZGVsZ
2Fkby5wY20zQGdtYWlsLmNvbSJ9fQ.BymqONrMbY8GQjSqZdUbT06KYdTtbPB21G
9DMFBhUO6dSGECLGTPOCsw8-77XIAIWHq1xfcpwtKchHC-m47CGQ' \
--header 'Content-Type: application/json' \
--data-raw '{
"areas": [
{"name": "area de prueba 1"},
{"name": "area de prueba 2"}
]
}'
Resultado:
[
{
"id": 27,
"name": "area de prueba 1",
"institution_id": 1180,
"created_at": "2023-01-04T10:43:02.747-05:00",
"updated_at": "2023-01-04T10:43:02.747-05:00"
},
{
"id": 28,
9
"name": "area de prueba 2",
"created_at": "2023-01-04T10:43:02.752-05:00",
"updated_at": "2023-01-04T10:43:02.752-05:00"
}
]
Descripción

Permitido(s)
Header
authorization token de cadena de “authorization

autorización texto : <token_type>
<access_token>
”
Entrada
areas lista de áreas array de “areas: [

objetos {name:“text”},
{name:“text”}
]”
Salida
id <area id> identificador numérico -

del área de la
entidad
name nombre del cadena de -

área texto
institution id identificador numérico -

de la
institutición
ii. Consultar áreas
Este servicio sirve para encontrar el identificador del área de la entidad

que envía la notificación o comunicación. Esta consulta es necesaria
antes del servicio de crear notificación o comunicación, ya que
requiere el identificador del área como dato de entrada.
Para el servicio de consultar áreas se necesita previamente que la

entidad haya registrado sus áreas en la Carpeta Ciudadana.
10
Ejemplo
curl -X GET \
es/areas?search=General' \
-H 'authorization: bearer
eyJraWQiOiJadi1RSEJyemtMRFVoUGdBLXlZUUFxMGxNVGZGZExjSGszT1BFY3RO
b0xBIiwiYWxnIjoiSFM1MTIifQ.eyJpc3MiOiJDYXJwZXRhIENpdWRhZGFuYSIsI
mlhdCI6MTY2NjM3MTMxOSwiZXhwIjoxNjY2MzczMTE5LCJqdGkiOiI4MjhiOGQ1M
y1kZGRiLTRhMjEtYjc3OS0wN2VlZTJhMjZkZWIiLCJ1c2VyIjp7ImlkIjoiMTIxY
TQ3NDktMmEyNS00MTcyLTlhMmYtMGZlYjdmNDYxMjJmIiwiZW1haWwiOiJtZGVsZ
2Fkby5wY21AZ21haWwuY29tIn19.hjtCRwF6SegLJRycSoZlp0geamZlIsoBVrbh
FcJuS__cBlX8eyFAenpf9iN3swRO84GiLna2sya8v0ZBqMID6w' \
Resultado:
{
"data": [
{
"id": 4,
"name": "Dirección General de Pesquería",
"created_at": "2022-07-06T18:06:49.787-05:00",
"updated_at": "2022-07-06T18:06:49.787-05:00"
},
...
"total_count": 5,
"total_pages": 1
}
Descripción

Permitido(s)
Header

<access_token>
”
Entrada
11
Salida
id <area id> identificador numérico -

del área
name nombre del cadena de -

área texto
institution id identificador numérico -

de la
institución
created_at fecha de cadena de -

creación texto
updated_at fecha de la cadena de -

última texto
actualización
total_count total de numérico -

resultados de
búsqueda de la
página actual
total_pages cantidad de numérico -

páginas
Consideraciones:
El servicio soporta búsquedas con el parámetro search y paginación

con un máximo de 10 resultados por página, esto a través del
parámetro page. Si no recibe el parámetro de página por defecto toma
el valor de 1.
Por ejemplo:
es/areas?search=Secretaria&page=2'
iii. Consultar área
Este servicio sirve para mostrar el detalle de una área en específico a

través del identificador de área de la entidad.
Para el servicio de consulta área se necesita previamente que la

entidad haya registrado el área en el sistema de Carpeta Ciudadana.
12
Ejemplo
curl --location --request GET

es/areas/26' \
mlhdCI6MTY3Mjg0OTUwMSwiZXhwIjoxNjcyODUzMTAxLCJqdGkiOiI0YjliM2NkY
i0xYjQ1LTQ3M2UtYWNiNS01NTJiMDU1ZmU4NzgiLCJ1c2VyIjp7ImlkIjoiZTg2N
2Fkby5wY20zQGdtYWlsLmNvbSJ9fQ.1YNzLkzLzflkS-_XwkANznDvrHZaAX-JJV
Vz6zt175Fd-UkubxerT6ZHSoQdVnI6d7CYSIndA3VfioOWq5AVDQ' \
--data-raw ''
Resultado:
{
"id": 26,
"name": "area de prueba",
"created_at": "2023-01-04T10:35:00.040-05:00",
"updated_at": "2023-01-04T10:35:00.040-05:00"
}
iv. Modificar área
Este servicio sirve para modificar el nombre de una área en específico

a través del identificador de área de la entidad.
Para el servicio de modificar área se necesita previamente que la

13
Ejemplo
curl --location --request PUT

es/areas/26' \
mlhdCI6MTY3Mjg2NjI3MywiZXhwIjoxNjcyODY5ODczLCJqdGkiOiJhN2VkNDU5O
C1hYTg3LTQzZWYtYTQ5NS1kMDExMTE2MzU2NjYiLCJ1c2VyIjp7ImlkIjoiZTg2N
2Fkby5wY20zQGdtYWlsLmNvbSJ9fQ.UCZ2VTkRP4faE1_-cI5QRQci2t2SNCDOzc
1Ra_pb1lBU-dBg_2e8LmAyhboyhnu6yAyqgKNTYr43o3vTWL9NUQ' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "area de prueba modificada"
}'
Resultado:
{
"name": "area de prueba modificada",
"id": 26,
"created_at": "2023-01-04T10:35:00.040-05:00",
"updated_at": "2023-01-04T16:59:16.207-05:00"
}
v. Eliminar área
Este servicio sirve para eliminar un área en específico a través del

identificador de área de la entidad.
Para el servicio de eliminar área se necesita previamente que la

14
Ejemplo
curl --location --request DELETE

es/areas/26' \
mlhdCI6MTY3Mjg2OTk5OCwiZXhwIjoxNjcyODczNTk4LCJqdGkiOiI3MDBhYjE0M
S01ODcyLTQ0NTAtYWY0Yy1iNDA4Y2JiMmEyNDAiLCJ1c2VyIjp7ImlkIjoiZTg2N
2Fkby5wY20zQGdtYWlsLmNvbSJ9fQ.P_PfrTR9OHQ4hzR3zo7AslXi_IfeQpJuJs
R0OSpJ0jM0CiQr10jWShQmpu91U322c7bySMWpi0fDVF00W-vdPg' \
--data-raw ''
Resultado:
c. Consultar tipos de número de seguimiento

Este servicio sirve para encontrar el identificador del tipo de número de
seguimiento de la entidad que envía la notificación o comunicación,
esta consulta es necesaria antes del servicio de crear notificación o
comunicación, ya que requiere el identificador del tipo de número de
seguimiento como dato de entrada.
15
Ejemplo
curl -X GET \
es/track_code_types?page=1' \
eyJraWQiOiJweVJBd2ItSlFPd1YyX0RoVGlfbEZ2SzdORTZKOVZVcEd2VnVOZlRsNWQwIiwiYWx
nIjoiSFM1MTIifQ.eyJpc3MiOiJDYXJwZXRhIENpdWRhZGFuYSIsImlhdCI6MTY2NzgzNjY2MCwi
ZXhwIjoxNjY3OTIzMDYwLCJqdGkiOiI1MzIwMGFjNC0yMDIxLTRlYjgtYTNhMi0wNjdlYTZkYWRi
MGIiLCJ1c2VyIjp7ImlkIjoiMzQ5MTIyMDYtN2M0ZS00NGQyLWE5NzYtY2VkMzIwNzU4M2E5Iiwi
ZW1haWwiOiJtZGVsZ2Fkby5wY20ucGFzYWRvQGdtYWlsLmNvbSJ9fQ.ilQ2YcVEj1bVo69Y-gihL
IojIoWNoHBSe8NizunxrXr0AacXKklSbmRDy09Z0CSCZnn0BtWpKRcC91X7RofA1g' \
Resultado:
{
"data": [
{
"id": 1,
"name": "Número de expediente"
},
...
],
"total_count": 5,
"total_pages": 1
}
Descripción

Permitido(s)
Header

<access_token>
”
Entrada
Salida
16
id <track code identificador numérico -
type id> del tipo de
número de
seguimiento
name cadena de -
texto
total_count total de numérico -

resultados de
búsqueda
total_pages cantidad de numérico -

páginas
d. Crear notificación o comunicación

Este servicio sirve para que la entidad pueda crear su notificación o
comunicación al ciudadano a través de la Carpeta Ciudadana. Cabe precisar
que es necesario que el ciudadano se encuentre registrado previamente para
hacer el envío exitoso de la notificación o comunicación.
El campo message content podrá contener etiquetas html para que el

ciudadano vea el contenido de la notificación o comunicación de manera
estilizada.
Las etiquetas html que se consideran son: "b", "i", "ul", "ol". Cualquier contenido
en otra etiqueta no será considerado. La cantidad de caracteres para el campo
message content es como máximo de 1000 caracteres.
El campo message type admitirá dos valores notification para las

notificaciones y communication para las comunicaciones
El campo file zip es opcional y sigue un formato URL
El campo name dentro de file_infos_attributes sigue un formato URL
El campo raw contendrá los campos adicionales de las notificaciones y/o

comunicaciones de la entidad
17
Ejemplo
curl -X POST \
https://staging.carpetaciudadana.servicios.gob.pe/api/v1/service
s/messages \
eyJraWQiOiJweVJBd2ItSlFPd1YyX0RoVGlfbEZ2SzdORTZKOVZVcEd2VnVOZlRsNWQwIiwiYWx
nIjoiSFM1MTIifQ.eyJpc3MiOiJDYXJwZXRhIENpdWRhZGFuYSIsImlhdCI6MTY2NzgzNjY2MCwi
ZXhwIjoxNjY3OTIzMDYwLCJqdGkiOiI1MzIwMGFjNC0yMDIxLTRlYjgtYTNhMi0wNjdlYTZkYWRi
MGIiLCJ1c2VyIjp7ImlkIjoiMzQ5MTIyMDYtN2M0ZS00NGQyLWE5NzYtY2VkMzIwNzU4M2E5Iiwi
ZW1haWwiOiJtZGVsZ2Fkby5wY20ucGFzYWRvQGdtYWlsLmNvbSJ9fQ.ilQ2YcVEj1bVo69Y-gihL
IojIoWNoHBSe8NizunxrXr0AacXKklSbmRDy09Z0CSCZnn0BtWpKRcC91X7RofA1g' \
-d '{
"citizen_id_code": "dni",
"citizen_id_number": "78109118",
"areas_id": 4,
"track_code_type_id": 1,
"track_code": "09200000223",
"message_type": "notification",
"subject": "Asunto prueba",
"content": "Contenido prueba",
"file_infos_attributes": [
{"name": "archivo1.pdf", "route":
"http://www.africau.edu/images/default/sample.pdf" },
{"name": "archivo2.doc", "route":
"https://filesamples.com/samples/document/doc/sample1.doc"}
],
"file_zip": "https://path.misarchivoscomprimidos.zip",
"raw": {
"data": [{
"campo": "tip_documento",
"descripcion": "tipo de documento",
"tipo": "text",
"valor": "01",
"valor_descriptivo": "oficio"
},
{
"campo": "fec_envio_casilla",
"descripción": "fecha de envio a la casilla de la
entidad",
"tipo": "date",
"valor": "15/2/2022"
}]
}
}'
18
Resultado:
{
"id": "1d258639-8480-48a7-b6e4-9a30e3b887c8",
"entity_register_number": "0920000053",
"citizen_id_code": "dni",
"citizen_id_number": "78109118",
"message_type": "notification",
"procedure": null,
"entity_ruc": null,
"subject": "Asunto prueba",
"content": "Contenido prueba",
"raw": null,
"highlight": false,
"file_zip": "https://path.misarchivoscomprimidos.zip",
"receipt_document": null,
"state": [
"new"
],
"read": false,
"read_date": null,
"created_at": "2022-09-08T09:58:10.902-05:00",
"updated_at": "2022-09-08T09:58:10.902-05:00",
"areas_id": 4,
"user_id": 41,
"gob_user_id": null,
"label_id": null,
"entity_user_id": "c5b2d104-45fd-4922-b643-ad7dd310b19a",
"created_by_type": "EntityUser",
"created_by_id": "c5b2d104-45fd-4922-b643-ad7dd310b19a"
}
Descripción del API

Permitido(s)
Header

<access_token>
”
Entrada
citizen_id_cod identificador cadena de “dni”

e del documento texto
de
identificación
del ciudadano
19
citizen_id_num número del cadena de “xxxxxxxx”
ber documento de texto
identificación
del ciudadano
areas_id identificador numérico <area id>

del área
track_code_typ identificador numérico <track code

e_id del tipo de type id>
número de
seguimiento
track_code Número de cadena de “xxxxxxxxxxxxx

seguimiento texto xxxxxxxxxx”
message_type tipo de cadena de “notification”

mensaje texto o
”communication
”
subject asunto del cadena de “Solicitud de

mensaje texto información”
content contenido del texto Contenido

mensaje prueba
file_infos_att Documentos a Array [{“name”:””,”r

ributes enviar oute”:””},{“na
me”:””,”route”
:””}]
file_zip Ruta del cadena de "https://path.

archivo texto con misarchivoscom
comprimido con formato de URL primidos.zip"
todos los
documentos
raw Otro tipo de jsonb {}

dato
Salida
id identificador cadena de -
<message_id> o CUO(código texto con
único de formato de
operación) UUID
entity_registe Número de cadena de -

r_number expediente / texto
Hoja de
trámite / Hoja
de ruta
citizen_id_cod identificador cadena de -

e del documento texto
de
identificación
20
del ciudadano
citizen_id_num número del cadena de -

ber documento de texto
identificación
del ciudadano
message_type tipo de cadena de -

mensaje texto
procedure trámite cadena de -

texto
entity_ruc ruc de la cadena de -

entidad texto
subject asunto del cadena de -

mensaje texto
content contenido del cadena de -

mensaje texto
raw Otro tipo de jsonb -

dato
highlight Si el mensaje booleano -

fue destacado
por el
ciudadano
file_zip Ruta del cadena de -

archivo texto
comprimido con
todos los
documentos
receipt_docume ruta de cadena de -

nt documento de texto con
recepción formato de URL
state estado del Array -

mensaje
read Si el mensaje Booleano -

ha sido leído
por el
ciudadano
read_date fecha de cadena de -

mensaje leído texto
por el
ciudadano
created_at fecha de cadena de -

creación texto
updated_at fecha de cadena de -

última texto
actualización
21
areas_id identificador Numérico -
del área
user_id identificador Numérico -

del ciudadano
gob_user_id identificador Numérico -

del
funcionario
que envió el
mensaje
label_id identificador Numérico -

de la etiqueta
que asignó el
ciudadano al
mensaje
entity_user_id identificador cadena de -

del usuario texto con
que tiene las formato de
credenciales UUID
para usar el
API y que
envió el
mensaje
created_by_typ clase del cadena de -

e usuario que texto
tiene las
credenciales
para usar el
API y que
envió el
mensaje
created_by_id identificador cadena de -

del usuario texto con
que tiene las formato de
credenciales UUID
para usar el
API y que
envió el
mensaje
22
4. Limitaciones
Los límites de uso son los siguientes:
● Se limita a 15 solicitudes por segundo según la IP de la entidad donde

se consume el servicio.
● Contacte el equipo de desarrollo de la Carpeta ciudadana si necesita
un límite superior.
23

Manual de Uso de API REST de Carpeta Ciudadana

Cargado por

Copyright:

Formatos disponibles

Manual de Uso de API REST de Carpeta Ciudadana

Cargado por

Información del documento

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

Manual de Uso de API REST de Carpeta Ciudadana

Cargado por

Copyright:

Formatos disponibles

Manual de uso de API REST de

3. Servicios web RESTful 7

c. Consultar tipos de número de seguimiento 15

d. Crear notificación o comunicación 17

Versión Fecha Descripción Elaborado por

v1 10/10/2022 Elaboración del documento Equipo de desarrollo

v1.0.1 08/11/2022 Se agregó servicios Equipo de desarrollo

v1.1 04/01/2023 Se agregó servicios para área Equipo de desarrollo

El presente documento tiene como objetivo servir de manual de uso de

Con esta API se busca llegar a la interoperabilidad entre los sistemas

La entidad deberá proporcionar un correo institucional al equipo de

La entidad deberá cargar todas las áreas en el sistema de Carpeta

Las credenciales de acceso que se le entregarán son:

Los ambientes de los servicios son los siguientes:

Un servicio web RESTful expone un conjunto de recursos que

OAuth(Open Authorization) es un estándar abierto que permite flujos

El marco de autorización de OAuth 2.0 permite que un tercero de

OAuth 2.0 se centra en la simplicidad del desarrollador

cURL es una herramienta para trabajar con URLs, y permite consultar

cURL es compatible con todos los métodos de peticiones de HTTP,

Flags Descripción Sintaxis

-X Especifica el método HTTP que curl -X [method]

-H Agrega los parámetros de curl -X [method]

-d Especifica los datos a enviar al curl -X [method]

De preferencia la entidad deberá consultar este servicio porque los

La entidad también podrá consultar en cuánto tiempo en segundos

A continuación un ejemplo de como usar el servicio con cURL.

*Credenciales de prueba, se deberían usar las que se proporcionaron a

Descripción del API

Campos Descripción Tipo de dato Valor(es)

grant_type tipo de cadena de “client_creden

client_id identificador cadena de “credenciales

client_secret clave secreta cadena de “credenciales

access_token token de cadena de “nuevo

token_type tipo de token cadena de “Bearer” por

expires_in tiempo de numérico 7200 tiempo en

refresh_token token de cadena de “nuevo

created_at tiempo de fecha numérica “generado por

Este servicio sirve para crear áreas de manera individual o múltiple en

La creación del área es necesaria antes del servicio de crear

*Las entidades deberán usar las credenciales que se proporcionaron

curl --location --request POST

Campos Descripción Tipo de dato Valor(es)

authorization token de cadena de “authorization

areas lista de áreas array de “areas: [

id <area id> identificador numérico -

name nombre del cadena de -

institution id identificador numérico -

ii. Consultar áreas

Este servicio sirve para encontrar el identificador del área de la entidad

Para el servicio de consultar áreas se necesita previamente que la

*Las entidades deberán usar las credenciales que se proporcionaron

Campos Descripción Tipo de dato Valor(es)

authorization token de cadena de “authorization

id <area id> identificador numérico -

name nombre del cadena de -

institution id identificador numérico -

created_at fecha de cadena de -

updated_at fecha de la cadena de -

total_count total de numérico -