A lo largo de este tutorial explicaremos como está estructurada una cuenta Paybook Sync. A su vez se explicará, haciendo uso de ejemplos, cómo podemos configurar una cuenta, organizar la información de las instituciones que sincronicemos a través de Paybook Sync además de como consultar esta información. Todo esto lo realizaremos consumiendo el API REST de Paybook Sync de manera directa.
- Requerimientos
- Configuración de Postman
- API Key
- Usuarios
- Sesiones
- Catálogos de Instituciones
- Cuentas y Credenciales
- Estatus de Sincronización
- Transacciones
- Facturación
- Contribuyentes
- Facturas
- Catalogo de proveedores
- Borrar Usuario
- Recomendado: Aplicación Postman
- Recomendado: Conocimiento y manejo de REST.
- Un API key de Paybook Sync
Como se mencionó previamente a lo largo de este tutorial se mostrarán ejemplos acerca de como implementar el API REST de Sync. Para esto haremos uso de Postman un cliente HTTP que nos permitirá hacer las peticiones al API así como analizar las respuestas de manera fácil y sencilla. Usted puede descargar el archivo quickstart.json e importarlo a la aplicación de Postman. Con unos cuantos clics podrá acompañarnos a lo largo del tutorial.
Importante: Si bien el tutorial está basado en Postman y es recomendado que usted cuente con la aplicación, usted puede implementar el API con la herramienta que más esté familiarizado y seguir el tutorial sin ningún problema. De ser este su escenario puede brincarse al punto API Key.
Configurando quickstart.json en Postman:
- Descarga el archivo quickstart.json
- Abrir aplicación Postman en tu computadora
- En la parte superior izquierda dar clic en "Import" y posteriormente en la pestaña "Import File"
- Dar clic en "Choose Files" y seleccionar el archivo quickstart.json que hemos descargado en el punto 1.
- La colección se imporatará a la aplicación y la podremos visualizar del lado izquierdo con el nombre de "Sync Quickstart".
Este archivo contiene 9 peticiones preconfiguradas para ti. Estas peticiones las iremos ejecutando a lo largo del tutorial.
Lo único que tenemos que hacer para que la colección de Postman funcione es configurar nuestra API key de Paybook Sync como una variable global en Postman. Para esto:
En la parte superior derecha dar clic en un icono con forma de ojo y posteriormente en el botón "edit" justo a lado de Globals.
Introduce el valor de tu API key de la siguiente manera: - En el campo de "key" introduce el valor "sync_api_key" - En el campo "value" introduce el valor de tu API key e.g. 7167a4a04f660f9131bafc949e8caode
Tu pantalla se debería de ver algo así:
Hecho esto hay que dar clic en "Save" y posteriormente cerrar la ventana.
Para verificar que nuestra API key se haya agregado correctamente podemos ir nuevamente al icono con forma de ojo y dar clic. Debemos ver que el valor de nuestra API key ya se encuentra cargado como variable global de Postman como se muestra a continuación:
Importante: en el punto de Consulta de Usuarios se hace una breve descripción de la interfaz y el manejo de Postman es recomendable consultarlo en su momento.
Importante: en Postman encontrarás que en algunas secciones habrá valores como este:
Estos valores son preconfiguraciones que hemos hecho por ti. Estos valores se pueden traducir a una URL, por ejemplo, https://sync.paybook.com/v1/users, o bien, algo como esto {{sync_api_key}} se traduce al API key que has configurado. De esta forma hemos configurado la mayoría de las llamadas y los parámetros que éstas requieren de tal manera que nos podamos enfocar en la implementación de Paybook Sync. Sin embargo, no pierdas de vista que al final del camino estamos consumiendo los endpoints del API y mandando los valores de acuerdo a los parámetros que nos solicita cada endpoint respectivamente.
Para mayor información puedes consultar la Documentación de Postman directamente.
Para entender como está estructurada nuestra cuenta de Paybook Sync y con ello poder hacer consultas, actualizaciones o modificaciones sobre tu información, es necesario conocer ciertos conceptos de la estructura de la información en Sync. El primer concepto importante es tu API key.
Cuando creamos una cuenta de Paybook Sync se nos proporcionó una API key, por ejemplo:
api_key = 7767a4a04f990e9231bafc949e8ca08a
Este API key lo podemos visualizar como la contraseña o llave de acceso a los servicios de Paybook Sync. Únicamente a través de ella podremos consultar la información de las instituciones que sincronicemos así como hacer las configuraciones necesarias para que esto último pueda ser posible.
Si Mateo es un desarrallodor que está haciendo uso de Paybook Sync su API Key será la llave de acceso (como desarrollador) a toda la información que Paybook Sync le proporciona.
##4. Usuarios
Mateo puede ligar a su API key usuarios. Un usuario lo podemos visualizar como una manera de organizar o clasificar las instituciones que sincronicemos. Supongamos que Mateo tiene 3 clientes:
- Una persona física: José Ochoa
- Una empresa: WalMart Querétaro
- Otra empresa: Starbucks Juriquilla
A estos clientes Mateo les está desarrollando una aplicación y para esa aplicación él requiere conocer la información bancaria de sus clientes (es por eso que Mateo está haciendo uso de Paybook Sync). Para poder hacer uso de Paybook Sync, además de su API key, Mateo necesitará un usuario y, por medio de ese usuario, el podrá sincronizar las cuentas bancarias de sus clientes,
Pero una mejor práctica es hacer una clasificación correcta de la información. La información de esas cuentas bancarias, si bien Mateo la está usando para las aplicaciones que está desarrollando, no le pertenece a él. Entonces lo correcto sería que Mateo creará un usuario por cada uno de sus clientes (esos usuarios desde luego estarían ligados al API Key de Mateo y con ello a su cuenta de Paybook Sync) pero la información de las instituciones que se sincronicen, además de estar ligada a la cuenta de Mateo, estaría clasificada por usuario, es decir, sabríamos quién es el dueño de esa información,
Importante: estos usuarios que Mateo ha creado no tienen una cuenta de Paybook, ni tampoco una cuenta de Paybook Sync, el único que tiene una cuenta en Paybook es Mateo. Él únicamente ha creado estos usuarios para clasificar la información de su cuenta de Sync de tal manera que él pueda hacer consultas y gestionar esa información fácilmente. Por lo tanto no debe confundir estos usuarios con su usuario de Paybook o de Sync, a este último normalmente nos referiremos más como tu Cuenta de Paybook o tu Cuenta de Sync.
Una vez que hallamos entendido la diferencia entre nuestro API Key y nuestros usuarios podemos crear usuarios así como consultar los usuarios que están ligados a nuestra API key.
En nuestra colección de Postman podemos seleccionar la primer petición "Get users linked to an API key":
Una vez que hallamos seleccionado está petición podemos observar la estructura de ésta:
A continuación se describen brevemente los componentes básicos que estaremos analizando a lo largo del tutorial:
- Aquí se selcciona el método/verbo de HTTP de la consulta.
- Aquí se selecciona la URL del API (en este caso siempre será la de Paybook Sync i.e. https://sync.paybook.com/v1/)
- Este botón "Params" es para abrir la interfaz para introducir los parámetros que queramos enviar en query string (ver punto 5)
- Este botón "Send" lo oprimiremos cada vez que queramos realizar la consulta
- En esta sección introducimos cada uno de los parámetros a enviar en query string.
- Body, en esta sección introducimos cada uno de los parámetros a enviar en el body (únicamente habilitado en peticiones con método/verbo POST).
Entonces una vez que hemos entendido la estructura básica de Postman, veremos que para la consulta de usuarios la petición se configura de la siguiente manera:
Esto indica que estamos:
- Usando el método/verbo GET (ya que estamos consultando)
- Consultando el endpoint de Paybook Sync /users (https://sync.paybook.com/v1/users)
- Mandando como parámetro en query string nuestro api_key.
Importante: si usted no está haciendo uso de Postman es importante identificar estos valores para que pueda hacer las peticiones con la herramienta de su elección.
Al momento de dar clic en "Send" se hace la petición al API. Y en la parte inferior de la pantalla (recuadro azul en la imagen) observaremos la respuesta del API, es decir, la lista de usuarios ligados a nuestra API Key:
Es importante mencionar que para ver está respuesta tendremos que estar situados en la pestaña "Body" (recuadro verde). Ojo, si en un principio no has creado usuarios la respuesta te debe regresar un arreglo vacio, puesto que todavía no hay usuarios ligados a tu API key, es decir,
{
"code": 200,
"status": true,
"message": null,
"response": []
}
El API cuenta con un manejador de errores que te regresará en caso de encontrar algún detalle con la petición que estás realizando, por ejemplo:
- Si nuestra API key es inválida
- Si no hemos enviado el API key en los parámetros
- Si el API key que hemos enviado ya no está vigente
En resumen, si la autenticación del desarrollador con el API es incorrecta, entonces no obtendremos, por ejemplo, la lista de usuarios que estábamos consultando y obtendremos una respuesta de error como la siguiente:
Cualquier petición que hagamos al API de Sync (en cualquier endpoint, con cualquier método o verbo, etc) si la autenticación es incorrecta enviará un error como éste.
Para crear un usuario podemos seleccionar en la colección de Postman la segunda petición Creates a new user:
Aquí, a diferencia de la consulta de usuarios, estamos enviando los parámetros en Body, sin embargo las demás especificaciones son iguales.
Esto indica que estamos:
- Usando el método/verbo POST (ya que estamos creando)
- Consultando el endpoint de Paybook Sync /users (https://sync.paybook.com/v1/users)
- Estamos mandando como parámetro en el body nuestro api_key así como el nombre del usuario que vamos a crear.
Y podremos ver una respuesta como la siguiente:
Entonces, sabiendo esto, lo que Mateo tendría que hacer es crear 3 usuarios, uno para José Ochoa, otro para WalMart y otro para Starbucks (como se hizo en el procedimiento previo) y el conseguiría tener la siguiente estructura:
Una vez hecho esto si él consulta los usuarios ligados a su API key (como también se hizo anteriormente) obtendría un arreglo con sus tres usuarios.
¿Por qué no intentas tu crear algunos usarios con tu API key así como consultar la lista de usuarios ligados a ésta? Una vez que domines esto podremos continuar con los siguientes puntos del tutorial.
Otro de los conceptos que es importante que entendamos es el manejo de sesiones. Una forma de autenticarte con el API de Paybook es por medio de tu API key, haciendo uso de ella podrás hacer cualquier consulta o modificación de información de tu cuenta de Sync. Esto implica poder actualizar o consultar la información de cualquier institución de cualquier usuario que esté ligado a tu API key. Aunque esto tenga ciertos beneficios o bondades dependiendo de la lógica de tu aplicación puede ser inseguro en cierta medida.
Otro modo de autenticarte con el API es por medio de una sesión. La diferencia particular es que una sesión va ligada directamente a un usuario y únicamente puede consultar o actualizar la información de éste (a diferencia del API key con la que puedes consultar todo). Para iniciar una sesión puedes seleccionar en Postman la petición Inits Session:
Y obtendremos una respuesta como la siguiente:
Dentro de los parámetros de la sesión está el token,
token = 4cacd8126db956631cde03f234544bf5
El valor de este token es el que podemos usar para autenticarnos con el API en vez de usar nuestro API key.
Importante: a partir de aquí la autenticación que haremos en el tutorial será por medio del token. Recuerda que éste únicamente podrá modificar o consultar la información del usuario con el que hayas creado la sesión.
Importante: algunos métodos únicamente pueden autenticarse por medio del API key. Para más detalles consulta la documentación general de Paybook Sync
Importante: Técnicamente la autenticación por medio del token es análoga a autenticarte por medio del API key y pasando como parámetro el id_user (token <--> api_key + id_user). La lógica es la misma, salvo que en la primera no se expone el valor de tu API key.
Importante: No confundir este token con el "token bancario" que es el que se utiliza al momento de sincronizar una institución cuya autenticación requiere token. El token que aquí manejamos únicamente es para autenticarse con el API.
Continuando la situación de Mateo. Quedamos que Mateo tenía 3 clientes:
- Una persona física: José Ochoa
- Una empresa: WalMart
- Otra empresa: Starbucks Juriquilla
Él ya creo un usuario para cada uno de sus clientes. Él sabe que, por ejemplo, respecto a José Ochoa necesita tener acceso a su información en el SAT (sus facturas tanto de ingresos como egresos), pero también necesita acceso partícularmente a las dos cuentas bancarias que maneja José Ochoa, Santander y Banamex. Así como el cliente José Ochoa, WalMart y Starbucks tienen sus propias cuentas bancarias y registro fiscal, entonces la cuenta de Paybook Sync de Mateo podría tener la siguiente estructura:
Aquí podemos ver que cada usuario tendría sus propias instituciones (entiéndase instituciones como una forma de referirse a los bancos o el SAT), es decir, José Ochoa tendría registrado al SAT así como su cuenta de Santander y Banamex. Walmart tendría registradas sus propias cuentas de Banamex y American Express y lo mismo para Starbucks Juriquilla con Banamex, BBVA y Banorte, pero ¿Cómo quedaría todo esto estructurado en nuestra cuenta de Paybook Sync, o bien, en la cuenta de Mateo?.
Bien, lo primero que hay que entender es que Paybook Sync nos dará un catálogo de las instituciones que podemos sincronizar para nuestros usuarios,
Entonces las instituciones que Mateo tendría que sincronizar para sus clientes tendrían que ser seleccionadas de este catálogo,
Entonces, como se ve en el diagrama anterior, las instituciones que Mateo quiera sincronizar para sus usuarios las tiene que obtener del conjunto de catálogo de instituciones de Paybook Sync (catálogo predefinido). Para esto podemos hacer el siguiente llamado al API. Selecciona en Postman Get testing sites (institutions):
Es importante mencionar que en este caso se están consultando el conjunto de catálogos de prueba que Paybook Sync pone a nuestra disposición, es por eso que se está mandando el parámetro "is_test" en true. Si se quiere consultar el conjunto de catálogos de producción únicamente hay que omitir enviar el parámetro "is_test". También note como en este caso la autenticación la estamos haciendo por medio del token.
La respuesta nos regresará un arreglo donde cada elemento es como el siguiente:
{
"id_site": "56cf5728784806f72b8b4568",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"name": "Normal",
"credentials": [
{
"name": "username",
"type": "text",
"label": "Username",
"required": true,
"username": true,
"validation": null
},
{
"name": "password",
"type": "password",
"label": "Password",
"required": true,
"username": false,
"validation": null
}
]
}
Usted puede analizar la respuesta con más detalle en Postman o en la interfaz de su agrado.
A continuación se explicará brevemente los catálogos de prueba de Paybook Sync y cómo estos nos pueden ayudar a levantar nuestra aplicación sin la necesidad de tener credenciales reales de bancos o el SAT. Esto puede ayudar a optimizar los tiempos de desarrollo. Leer este apartado es opcional, usted lo puede omitir e ir directamente a la siguiente sección.
Importante: no se preocupe a pesar de que usted haga uso de los catálogos de desarrollo el cambio a producción es sencillo por lo que esto no atrasará su desarrollo.
Para realizar pruebas es preferible usar los catálogos de prueba de Paybook Sync. Entre estos se encuentran:
- Normal. Esta institución sirve para simular la sincronización de una institución "normal", es decir, aquella que solo requiere usuario y contraseña.
- Token. Esta institución sirve para simular la sincronización de una institución que utiliza "token" como via de autenticación además de un usuario y contraseña. i.e. token bancario.
- Error. Esta institución sirve para simular un error al sincronizar cualquier institución.
- Token & captcha. Esta institución sirve para simular la sincronización de una institución que utiliza "token" y "captcha" como via de autenticación además de un usuario y contraseña.
- Multiple Image. Esta institución sirve para simular la sincronización de una institución que utiliza "multiple image" como via de autenticación además de un usuario y contraseña.
Por lo que Mateo, con el objetivo de realizar pruebas o levantar el desarrollo de sus aplicaciones, podría tener algo así:
Mediante este catálogo de prueba Mateo o tu podrán, por ejemplo, simular la sincronización del SAT, recordemos que esta sincronización exige un RFC -- un usuario -- y CIEC -- una contraseña -- por lo que sincronizando una institución de prueba Normal -- que solo pide usuario y contraseña -- se puede simular la sincronziación del SAT. Del mismo modo se puede hacer para simular la sincronización de Santander, Banamex, BBVA y Banorte -- o cualquier institución -- solo haciendo uso de la institición de prueba que se le parezca considerando únicamente la manera de autenticarse con ésta. Entonces Mateo podría tener algo así:
Para su cliente José Ochoa, Mateo puede
- simular el SAT con una institución de prueba Normal
- simular Santander con una institución de prueba Normal
- simular Banamex (este pide token bancario) con una institución de prueba Token.
El mismo análisis Mateo lo tiene que hacer para las demás instituciones y usted para cada institución que quiera sincronizar. Recuerde: esto solo si desea usar el ambiente de pruebas de Paybook Sync.
Además de entender que Paybook nos proporciona un catálogo de las instituciones que podemos sincronizar por cada uno de nuestros usuarios. Hay algunos conceptos que hay que entender acerca de como sincronizar, o bien, gestionar las instituciones que queremos sincronizar.
Supongamos que el cliente José Ochoa le dijo a Mateo que tenía cuentas bancarias en Santander y Mateo dijo -- claro, está perfecto -- pero el cliente nunca le dijo cuantas cuentas, o bien, el cliente omitió decirle a Mateo que cuenta con 2 razones sociales (2 RFCs). Pero bueno Mateo es un excelente desarrollador y le dijo a su cliente que no había problema y que lo iba agregar a los requerimientos de la aplicación que le está desarrollando.
Aquí hay cuestiones importantes que Mateo o tu podrían enfrentarse. Pueden sincronizar todas las cuentas de un banco o todas las facturas del SAT de un usuario (aquí el clasificador sería la institución) y Mateo podría saber, por ejemplo, las transacciones que tiene José Ochoa en Santander o en el SAT. Pero que tal si se requiere saber los movimientos que tiene en Santander pero en una cuenta especifica o en el SAT pero en determinada razón social.
Para resolver esta clase de cosas existe el elemento Cuentas (accounts). En realidad Mateo no está sincronizando instituciones como tal, en el fondo está sincronizando cuentas específicas (cuentas bancarias o RFCs) que pertenecen, por supuesto, a determinadas instituciones. Entonces por ejemplo en el caso de su cliente José Ochoa, Mateo tendría algo así:
La forma en que Paybook Sync logra esto es por medio de las cuentas. Cada RFC, o bien, cada cuenta bancaria sería una cuenta (account) y éstas al final tendrían una relación con una institución (sitios). En resumen, toda cuenta (account) estaría relacionada con una institución o sitio (site) . Más adelante veremos que las cuentas nos ayudan principalmente para la clasificación de la información y con ello hacer consultas más especificas como en el caso que hemos presentado anteriormente con Mateo.
Por otro lado se encuentran las credenciales. Las credenciales están relacionadas con las cuentas en el sentido de que cada cuenta debe tener unas credenciales y estas últimas almacenan la información necesaria para realizar la sincronización de esa cuenta especifica. La información que tienen las credenciales consiste en:
- Contraseña y password del usuario para esa institución.
- Información acerca de la consulta del estado de la sincronización. Vía web socket o consultando un endpoint de status (esto se verá más adelante).
Veremos que, a pesar que existen cuentas y credenciales, esto no implica que Mateo tenga que crear primero una cuenta y posteriormente una credencial para cada cuenta de cada usuario que quiera sincronizar. Únicamente se tienen que crear las credenciales. Sin embargo, era importante conocer la existencia de las cuentas para efectos de consulta de información y conocer como está estructurada ésta en Paybook Sync.
Importante: cada vez que creamos unas credenciales Paybook Sync se encargará de crear el objeto cuenta de manera automática y lo asociará con estas credenciales.
Una vez que ya vimos que Paybook Sync nos otorga un catálogo de instituciones para sincronizar y aprendimos a consultarlo. Independientemente de si es el catálogo de instituciones reales o instituciones de prueba, cada elemento (institución) es como el siguiente:
{
"id_site": "56cf5728784806f72b8b4568",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"name": "Normal",
"credentials": [
{
"name": "username",
"type": "text",
"label": "Username",
"required": true,
"username": true,
"validation": null
},
{
"name": "password",
"type": "password",
"label": "Password",
"required": true,
"username": false,
"validation": null
}
]
}
Los datos contenidos en este elemento los requeriremos cada que querramos sincronizar un cuenta de esa institución. Para sincronizar una institución es necesario tener:
- Un token de sesión (o bien un API key) dependiendo de como se quiera hacer la autenticación con el API.
- El id del sitio o institución que quieres sincronizar. Este viene como id_site en cada institución al momento de consultar el catálogo.
- El valor de las credenciales (usuario y contraseña) para esa institución que quieras sincronizar.
Es importante que, con respecto al punto 3, el valor de estas credenciales se debe enviar como se especifica en la propiedad credentials del elemento correspondiente en el catálogo de la institución que queremos sincronizar, para el caso de la institución Normal (el ejemplo que tenemos arriba) en el elemento del catálogo se especifica lo siguiente en la propiedad credentials:
[
{
"name": "username",
"type": "text",
"label": "Username",
"required": true,
"username": true,
"validation": null
},
{
"name": "password",
"type": "password",
"label": "Password",
"required": true,
"username": false,
"validation": null
}
]
Esto quiere decir que al crear unas credenciales de la institución Normal, el valor de estas lo tendríamos que enviar como:
{
"username" : "username_value",
"password" : "password_value"
}
Pero por ejemplo en el caso del SAT, el elemento del catálogo nos indica:
[
{
"name": "rfc",
"type": "text",
"label": "RFC",
"required": true,
"username": true,
"validation": null
},
{
"name": "password",
"type": "password",
"label": "Clave CIEC",
"required": true,
"username": false,
"validation": null
}
]
Esto quiere decir que al crear unas credenciales de la institución SAT, el valor de estas lo tendríamos que enviar como:
{
"rfc" : "rfc_value",
"password" : "password_value"
}
Importante: Note que para el nombre de cada propiedad tomamos el valor que especifica el objeto credentials en la propiedad "name".
La misma lógica se tiene que realizar para sincronizar cualquier institución. En resumen el obtener la institución que queremos sincronizar del catálogo de instituciones es necesario para:
- Obtener el id_site de esa institución
- Obtener la estructura del objeto que usaremos para enviar los valores de las credenciales.
Importante: La misma lógica aplica independientemente si es un catálogo real o de prueba, ambos tienen la misma estructura.
Importante: Al usar un catálogo de prueba siempre se tienen que enviar el valor "test" tanto en "username_value" como en "password_value" (en "bank_token_value" igual en caso de requerirse). Este valor es constante independientemente de la institución de prueba que se esté manejando.
Importante: Lo único que distingue si estamos sincronizando una institución de prueba o no, es de donde obtuvimos el valor id_site, si fue del catálogo de instituciones de prueba o del catálogo de instituciones reales, además de esto no hay ninguna diferencia.
Entonces una vez que sabemos todo esto para crear unas credenciales podemos hacer lo siguiente (en Postman Create a new credentials):
La creación de credenciales nos dará una respuesta como la siguiente:
Los distintos valores que vemos en la respuesta y como estos se utilizan los analizaremos en las siguientes secciones.
Siguiendo con el escenario de Mateo. Él ya tiene sus usuarios creados, ahora el tendrá que crear unas CREDENECIALES por cada CUENTA de cada INSTITUCIÓN O SITIO de cada USUARIO que quiera sincronizar. Con los requerimientos nuevos que agregó su cliente José Ochoa, y suponiendo que Walmart únicamente tiene una cuenta en Banamex y una American Express y que Starbucks Juriquilla únicamente tiene una cuenta en Banamex, BBVA y Banorte el escenario de la cuenta de Paybook Sync de Mateo sería el siguiente:
En resumen todo quedará ligado al API key de Mateo pero de una manera organizada. En resumen Mateo tendrá:
- Su API key (recuadro verde).
- Un usuario por cada cliente que el tiene y estos a su vez están ligados a su API key (recuadro rosa).
- Cada usuario tiene sus propias cuentas que a su vez están relacionadas con alguna institución o sitio. (recuadros azul, amarillo).
- Cada cuenta tiene unas credenciales asociadas (recuadros amarillo y morado).
Nótese como en esta estructura no están contenidos los catálogos que vimos anteriormente. Esto es por que los catálogos de instituciones no le pertenecen al usuario, estos catálogos son globales y son catálogos que ofrece Paybook Sync y no están ligados a ninguna cuenta de Paybook Sync en específico, a diferencia de los usuarios, cuentas y credenciales que si están ligados a un API key y por lo tanto a una cuenta de Paybook Sync, en este caso, la de Mateo.
Más adelante veremos que las transacciones sincronizadas de alguna institución las podrás filtrar por usuario, por sitio o institución, por cuenta o credencial y por cualquier combinación de éstas, además de poder agregar filtros de temporalidad.
En resumen, el simple hecho de crear unas credenciales implica que vamos a sincronizar una cuenta (bancaria o del SAT) de una institución específica (un banco o el SAT) para un usuario específico (algún cliente por ejemplo) y todo esto estará ligado a tu API key (tu cuenta de Paybook Sync).
Pero una vez que hemos creado unas credenciales tenemos que esperar a que Paybook valide éstas y, en caso de ser validas, realice el proceso de sincronización (traer las transacciones de esa cuenta). En este proceso puede haber distintos estados, por ejemplo:
- Las credenciales introducidas pueden ser inválidas
- Las credenciales introducidas son válidas pero se requiere de un token bancario, captcha, etc. por lo que éste se le debe solicitar al usuario.
- Las credenciales, el token bancario, y demás fueron válidos y la cuenta se está sincronizando.
- La cuenta ha terminado de sincronizarse.
Toda esta información la podemos obtener a través de los datos que el API nos regresó al momento de crear las credenciales. En el ejemplo anterior vimos que el resultado de esto era, por ejemplo:
{
"code": 200,
"status": true,
"message": null,
"response": {
"id_credential": "57acf8520b212aa25b8b456a",
"username": "t**t",
"ws": "wss://sync.paybook.com/v1/status/57acf8520b212a835a8b4596",
"status": "https://sync.paybook.com/v1/jobs/57acf8520b212a835a8b4596/status",
"twofa": "https://sync.paybook.com/v1/jobs/57acf8520b212a835a8b4596/twofa"
}
}
En este caso únicamente explicaremos la propiedad "status". Las demás están fuera del alcance de este tutorial, sin embargo, puedes consultar la documentación del API o bien otros tutoriales para checar su funcionamiento.
La propiedad "status" es una URL específica que Paybook Sync nos crea para qué, a través de ella, podamos consultar precisamente eso, el estatus de la sincronización de las credenciales que hemos creado. En Postman podemos seleccionar la petición Check credentials sync status
Cuya respuesta es una serie de códigos (códigos de estatus de sincronización):
Los diferentes estatus y su significado se pueden consultar en la documentación general de Paybook Sync y es trabajo del desarrollador programar su propia rutina dependiendo el tipo de estatus que obtenga, es decir, si el estatus es 401 que significa que las credenciales introducidas son iválidas, es trabajo del desarrollador programar una rutina que vuelva a pedir las credenciales y volver a consumir el endpoint de crear credenciales esta vez con los valores adecuados.
Partícularmente si hemos sincronizado una institución de prueba Normal, podemos esperar por el estatus 200 que significa que la sincronización ha terminado, por tanto, ya hay transacciones de esa cuenta en específico que podemos consultar. Esto lo analizaremos en el siguiente apartado.
Una vez que hemos creado credenciales, monitoreado su estatus y verficado que la sincronización haya terminado exitósamente (código 200 en status), podemos consultar las transacciones de esa cuenta en específico. En Postman podemos seleccionar la petición Get transactions y ejecutarla.
Nótese como estamos consultando las transacciones filtrando por id_credential esto quiere decir que únicamente queremos consultar las transacciones que se han sincronizado para la cuenta cuyas credenciales son aquellas cuyo id es id_credential. De esta misma manera podríamos filtrar por id_site para alguna institución, id_account para alguna cuenta, etc. Igual es importante mencionar que como la autenticación se está haciendo por token de sesión y éste está relacionado con un usuario específico (aquel que se utilizó al crear la sesión) automáticamente esta consulta regresa transacciones pertenecientes a ese usuario.
En la respuesta de esta consulta veremos un arreglo de elementos (transacciones) con la siguiente estructura:
{
"id_transaction": "574755f0234283db178b4569",
"id_source": null,
"id_user": "57acdaa90b212af35b8b4567",
"id_external": null,
"id_site": "56cf5728784806f72b8b4568",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"id_account": "57317925234283f1078b6843",
"id_account_type": "520d3aa93b8e778e0d000000",
"id_currency": "523a25953b8e77910e8b456c",
"is_disable": 0,
"description": "ACME Checking Transaction 1",
"amount": 10,
"currency": "MXN",
"attachments": [
{
"id_attachment": "574755f0234283db178b4575",
"id_attachment_type": "56bcdfca784806d1378b4567",
"is_valid": 0,
"file": "5ee8bf88b42b9b933734a229e631d3e5d716e442b8f830aac737679254c2d59e.xml",
"mime": "text/html",
"url": "/attachments/574755f0234283db178b4575"
},
{
"id_attachment": "574755f0234283db178b4577",
"id_attachment_type": "56bcdfca784806d1378b4568",
"is_valid": 1,
"file": "5ee8bf88b42b9b933734a229e631d3e5d716e442b8f830aac737679254c2d59e.pdf",
"mime": "application/pdf",
"url": "/attachments/574755f0234283db178b4577"
}
],
"dt_transaction": 1412485200,
"dt_refresh": 1470956640
}
Que contiene información de la transacción, ya sea bancaria o fiscal. Para terminar, es importante entender la estructura final de una cuenta. En el caso del escenario de Mateo, una vez que haya creado las credenciales y monitoreado el estado de la sincronización de cada una de las credenciales que creó, entonces el ya tendrá acceso a las transacciones de sus clientes. Con esto el diagrama final que describe la estructura de la infromación en su cuenta de Paybook Sync sería el siguiente:
No hay diferencia con el diagrama que expusimos previamente. Salvo que en éste ya se muestran las transacciones de cada una de las cuentas que Mateo ha sincronizado para cada uno de sus usuarios (recuadro rojo). Al final estas transacciones también estarán ligadas a tu API key.
A través del servicio REST Sync es poible realizar el timbrado de CFDI's. Este servicio permite:
- Simplificar el proceso de timbrado de facturas
- Toda factura expedida a través de Sync será validada
- Cancelación de facturas timbradas
- Consulta de facturas timbradas
- El usuario podrá elegir con qué proveedor quiere timbrar facturas.
El primer paso para generar un CFDI es agregar un contribuyente al sistema, cada usuario de Sync puede tener ligados múltiples contribuyentes. Para agregar un nuevo contribuyente se requiere:
- RFC del contribuyente.
- Credenciales CSD. Estos son 2 archivos en formato cer y key los cuales deben ser codificados en base64 al ser enviados en la petición.
- Contraseña de los CSDs.
- API key de Sync.
- Usuario de Sync -- id_user. Este sería el id del usuario al cual se asociará el contribuyente.
POST invoicing/mx/taxpayers
Para este tutorial de postman, se incluyen credenciales que el SAT publica para poder realizar pruebas.
Una vez que se ha agregado un contribuyente y en caso de que sus credenciales expiren o cambien, se pueden actualizar a través del siguiente endpoint con los mismos parámetros que al agregarlo.
PUT invoicing/mx/taxpayers
También es posible obtener el listado de contribuyentes que se han agregado:
GET invoicing/mx/taxpayers
La respuesta es un arreglo de objetos. Cada uno de estos contiene el RFC del contribuyente, además del rango de fechas en UNIX timestamp que indican el periodo de vigencia de su certificado.
Para timbrar una factura a través del servico de Paybook, se ha generado un esquema basado en una estructura JSON con el fin de simplificar el proceso de timbrado, como usuario usted solo tiene que llenar los datos requeridos en el JSON y el sistema se encargará de:
- Construir el XML
- Generar los sellos de timbrado
- Validar el XML
- Enviarlos al SAT a través de los proveedores disponibles (PACs)
Esto se realiza consumiendo el siguinte endpoint.
POST invoicing/mx/invoices
En el ejemplo de postman se incluye una factura timbrada con el proveedor de sandbox "acme". Como se observa en la siguiente imagen en la respuesta de la llamada, se obtiene el XML de la factura ya timbrada, el UUID de ésta, además de un campo llamado 'warnings', este último es un arreglo que muestra advertencias sobre posibles datos erróneos al generar la factura.
Para realizar la conversión de los archivos a base64, se puede hacer uso de algún conversor en línea por ejemplo este.
También se puede hacer desde la consola de comandos
certutil -encode archivo_entrada.cer archivo_salida_base64.txt
Nota: El string que se envia,no debe incluir esta entre "-----BEGIN CERTIFICATE-----" y "-----END CERTIFICATE-----", además se deben eliminar los retornos y tabs del string.
openssl base64 -in 'archivo_entrada.cer' -out 'archivo_salida_base64.txt'
Nota: se deben eliminar los retornos y y tabs del archivo.
base64 archivo_entrada.cer >archivo_salida_base64.txt
Para traer las facturas que fueron timbradas previamente se usa el siguiente endpoint:
GET invoicing/mx/invoices
Algunos parámetros que se pueden enviar para realizar el filtrado de las facturas que se traerán son los siguientes:
{
api_key: la api key de paybook,
id_user: el id del usuario,
uuid: el uuid de la factura (opcional),
issuer: RFC del emisor de la factura (opcional),
recipient: RFC del receptor (opcional),
dt_create_from: fecha de inicio la creación UNIX_timestamp (opcional),
dt_create_to: fecha final de la creación UNIX_timestamp(opcional),
dt_register_from: fecha inicial del registro UNIX_timestamp(opcional),
dt_register_to: fecha final de registro UNIX_timestamp(opcional),
}
Para realizar la cancelación de una factura lo único que se require es el UUID. El proceso se realiza usando el endpoint:
PUT invoicing/mx/invoices/{{uuid}}/cancel
La factura cancelada seguirá almacenada en el sistema pero con el estado de cancelación. En la sigueinte imagen se observa que en la respuesta exitosa de cancelación contiene el parámetro 'success' igual a 'true', además del acuse de cancelación en formato XML, el cual proporcionan los proveedores de servicio de timbrado.
Como se mencionó anteriormente, Paybook puede realizar el proceso de timbrado a través de múltiples proveedores. Usando el siguiente endpoint se obtiene una lista de los proveedores dados de alta en el sistema, si se desea timbrar con un proveedor en especifico, se debe agregar el parámetro "id_provider" en la petición POST de invoices, el valor de éste puede ser el nombre o el id proporcionados al consultar la lista de proveedores:
GET invoicing/mx/providers?api_key={{sync_api_key}}&id_user={{sync_id_user}}
Por último, a manera opcional, puedes borrar el usuario que hemos creado para efectos de seguir este tutorial. Para borrar el usuario selecciona en Postman la última petición Deletes user:
Esta acción borrará toda la información relacionada con este usuario dejando tu cuenta limpia, es decir, borrar un usuario de tu cuenta de Paybook Sync borrará todas sus credenciales, cuentas, transacciones y demás información relacionada con éste.
A través de este tutorial esperamos que hayas podido implementar el API de Paybook Sync a través de los ejemplos que te hemos proporcionado y partiendo del entendimiento de como está constituida cada cuenta de Paybook Sync.
Una vez que hayas terminado este tutorial puedes consultar todos los recursos que tenemos para ti. Paybook Sync cuenta con:
- Librerías en una gran variedad de tecnologías que te permitirán conectar tu aplicación con Paybook de una manera rápida y sencilla.
- Aplicaciones totalmente integras de código abierto que puedes descargar para iniciar tu aplicación tomando como base éstas (estos proyectos los encontrarás como lites).
- Documentación del API Rest
- Tutoriales y documentación para ayudarte en la integración de Paybook Sync a tu aplicación.
Todo esto lo puedes encontrar aquí mismo en Paybook GitHub
:)