PHPackages                             paybook/sync-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. paybook/sync-php

ActivePackage[API Development](/categories/api)

paybook/sync-php
================

A package to consume Syncfy REST for humans without pain

V2.0.1(1y ago)114.0k↓11.1%10[1 PRs](https://github.com/Paybook/sync-php/pulls)MITPHP

Since Aug 22Pushed 8mo ago8 watchersCompare

[ Source](https://github.com/Paybook/sync-php)[ Packagist](https://packagist.org/packages/paybook/sync-php)[ RSS](/packages/paybook-sync-php/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (8)Used By (0)

[![Sync-Paybook-logo](https://raw.githubusercontent.com/Paybook/sync-php/master/images/syncLogo.svg?sanitize=true)](https://raw.githubusercontent.com/Paybook/sync-php/master/images/syncLogo.svg?sanitize=true)

SYNC-PHP
========

[](#sync-php)

**Sync** recupera información de las cuentas y sus transacciones, de instituciones financieras autorizados por el usuario, y lo regresa a soluciones de terceros en un formato organizado, muy fácil de utilizar.

Tabla de contenidos
-------------------

[](#tabla-de-contenidos)

- [Instalación](#instalaci%C3%B3n)
- [Requerimientos](#requerimientos)
- [Modelo de información](#modelo-de-informaci%C3%B3n)
- [Implementación](#implementaci%C3%B3n)
    - [La librería](#la-librer%C3%ADa)
    - [Implementación de un Webhook ](#implementaci%C3%B3n-de-un-Webhook)
    - [Sync Widget](#sync-widget)
- [Autenticación](#autenticaci%C3%B3n)
    - [Obtener un Token de sesión:](#obtener-un-token-de-sesi%C3%B3n)
    - [Flujo de Información](#flujo-de-informaci%C3%B3n)
- [Recursos y Ejemplos](#recursos-y-ejemplos)
    - [Usuarios](#usuarios)
        - [Consultar usuarios](#consultar-usuarios)
        - [Consultar un usuario en especifico](#consultar-un-usuario-en-especifico)
        - [Crear un Usuario](#crear-un-usuario)
        - [Actualizar un Usuario](#actualizar-un-usuario)
        - [Eliminar un usuario](#eliminar-un-usuario)
    - [Catálogos](#cat%C3%A1logos)
        - [Catálogos de Instituciones](#cat%C3%A1logos-de-instituciones)
    - [Credenciales](#credenciales)
        - [Credenciales normales](#credenciales-normales)
        - [Crear credenciales TWOFA](#credenciales-twofa)
        - [Consultar credenciales](#consultar-credenciales)
        - [Eliminar una credencial](#eliminar-una-credencial)
        - [Consultar historial de cambios de la credencial](#consultar-historial-de-cambios-de-la-credencial)
    - [Cuentas](#cuentas)
        - [Consulta las cuentas de un usuario específico](#consulta-las-cuentas-de-un-usuario-espec%C3%ADfico)
    - [Transacciones](#transacciones)
        - [Consulta las transacciones de un usuario específico](#consulta-las-transacciones-de-un-usuario-espec%C3%ADfico)
        - [Consulta el número de transacciones dados algunos parámetros de búsqueda](#consulta-el-n%C3%BAmero-de-transacciones-dados-algunos-par%C3%A1metros-de-b%C3%BAsqueda)
    - [Webhooks](#webhooks)
        - [Crear Webhook](#crear-webhook)
        - [Consultar Webhooks](#consultar-webhooks)
        - [Eliminar Webhook](#eliminar-webhook)
    - [Archivos adjuntos (Attachments)](#archivos-adjuntos-attachments)
        - [Consulta los archivos adjuntos de un usuario específico](#consulta-los-archivos-adjuntos-de-un-usuario-espec%C3%ADfico)
        - [Regresa el archivo adjunto](#regresa-el-archivo-adjunto)
        - [Regresa la información extraída del archivo adjunto](#regresa-la-informaci%C3%B3n-extra%C3%ADda-del-archivo-adjunto)
- [Entorno](#entorno)
- [Enlaces de interes](#enlaces-de-interes)
- [Comentarios y aportes](#comentarios-y-aportes)

Instalación
-----------

[](#instalación)

1. Instalar mediante composer

```
  composer require paybook/sync-php
```

Requerimientos
--------------

[](#requerimientos)

1. **API Key:**

Cuando creamos una cuenta de [Paybook Sync](https://www.paybook.com/sync/es/) se nos proporcionó una API Key, por ejemplo:

```
api_key = 7767a4a04f990e9231bafc949e8ca08a

```

Al crear tu cuenta se te proporcionan dos API Keys: ***Producción*** & ***Sandbox***. Las cuales tienen el mismo proposito, ambas nos permiten implementar **Paybook Sync**, pero ***Sandbox*** nos permite hacerlo sin la necesidad de tener credenciales reales de bancos o el SAT.

Este API key lo podemos visualizar como la contraseña o llave de acceso a los servicios de [Paybook Sync](https://www.paybook.com/sync/es/). Solamente a través de ella podremos empezar a interactuar con las instituciones que sincronicemos.

> ***Nota:*** Pasar de una API key a otra es tan sensillo como escribir la nueva API key correspondiente.

2.**Webhook**

*Opcional* pero altamente recomendable para lograr una integración completa de las funcionalidades de Paybook Sync.

Modelo de información
---------------------

[](#modelo-de-información)

El modelo de información de Paybook Sync es bastante sencillo. Prácticamente podemos visualizar al API key como el elemento raíz del modelo, del cual se desglosan los usuarios, pero entendamos como usuarios a aquellas entidades (personas o empresas) a las cuales se les desea sincronizar las instituciones financieras que el servicio de Paybook Sync facilita, podemos apreciarlo gráficamente en este diagrama:

[![sync-model-image](https://raw.githubusercontent.com/Paybook/sync-php/master/images/resourceModel.svg?sanitize=true)](https://raw.githubusercontent.com/Paybook/sync-php/master/images/resourceModel.svg?sanitize=true)

> Hay que mencionar la diferencia entre un usuario de Paybook Sync (usted, el developer) y un usuario del API key: Por cada usuario de Paybook Sync, hay un API key y cada API key puede tener N usuarios.

### Users ([Usuarios](#usuarios))

[](#users-usuarios)

Los usuarios son segmentaciones lógicas para los usuarios finales. Una mejor práctica es registrar usuarios para tener su información agrupada y control en ambos extremos.

### Catalogs/Sites ([Catálogos](#cat%C3%A1logos))

[](#catalogssites-catálogos)

Los catálogos son colecciones de endpoints que son importantes para la clasificación de otros endpoints. Dentro de estos se encuentran los sitios que nos permite consultar los sitios financieros disponibles para sincronizar a través de Paybook Sync.

### Credentials ([Credenciales](#credenciales))

[](#credentials-credenciales)

Las credenciales se refieren a la información de terceras personas que se necesita para autorizar el acceso a un sitio de terceros. Las credenciales se encriptan al momento de introducirse y no están disponibles en ningún endpoint. La información que se extrae de este endpoint, será sólo complementaria.

> Es necesario tener al menos un usuario registrado para crear credenciales.

### Accounts ([Cuentas](#cuentas))

[](#accounts-cuentas)

Las cuentas son repositorios de transacciones de usuarios finales, que normalmente se clasifican por alguna característica como tipo y/o número de cuenta. La cuenta y la información de las transacciones pueden recuperarse desde sitios de terceros y se actualizan hasta una vez al día.

### Transactions ([Transacciones](#transacciones))

[](#transactions-transacciones)

Las transacciones son los movimientos financieros que están relacionados con una cuenta, y reflejan el ingreso o egreso que el usuario final tiene en determinado sitio. La cantidad de información histórica que Sync puede recuperar, varía dependiendo de la fuente pero, por lo general, estarán disponibles las transacciones de 60 días.

### Attachments ([Archivos Adjuntos](#archivos-adjuntos-attachments))

[](#attachments-archivos-adjuntos)

Los archivos adjuntos son archivos que están relacionados con las cuentas o las transacciones. La disponibilidad y el tipo de archivo adjunto varía de acuerdo a la fuente.

#### En Resumen:

[](#en-resumen)

A partir de los usuarios podemos crear credenciales, las cuales son únicas por cada usuario e institución. Una vez creada una credencial automáticamente se crea una cuenta correspondiente, esto permite manejar fácilmente diferentes cuentas de un mismo usuario de una misma institución.

Por último pero no menos importante, se encuentran las transacciones que dependen de su respectiva cuenta, algunas transacciones vienen con un documento el cual llamaremos Attachments o mejor dicho *“documentos adjuntos”*, los cuales son el último recurso en el modelo de de información de Paybook Sync.

Implementación
--------------

[](#implementación)

### La librería

[](#la-librería)

Incluye la librería y declara tu API Key.

```
require __DIR__.'./vendor/autoload.php';
define('API_KEY', '');
use Paybook\Sync\Sync;
```

> ***¡Importante!:*** No escribas tu API KEY directamente en tu código o en texto plano, ya que es una mala práctica de seguridad.

La librería incluye los métodos:

- `Sync.auth()`

```
// Crear una sesión para un usuario
$token = Sync::auth(
    array("api_key" => API_KEY), // Tu API KEY
    array("id_user"=>$id_user) // ID de usuario
);
```

> ***Nota**: Para realizar la autenticación es necesario tener creado un usuario, de donde se obtiene el **id\_user**, vease este [ejemplo](#crear-un-usuario).*

- `Sync.run()`

```
// Consumir un recurso de Sync
$response = Sync::run(
    $token, // Autenticación
    "/credentials", // Recurso
    null, // Parametros
    'GET' // Método HTTP
);
```

Y hace uso los siguientes métodos de HTTP:

MetodoAcciónGETConsultarPOSTCrearPUTActualizarDELETEEliminarDependiendo del recurso y la acción a realizar, será el método de la librería, el método de HTTP y el elemento de autenticación (se explica en la sección de [autenticación](#autenticaci%C3%B3n)) a usar.

> Puedes ver más acerca de cada uno en [recursos y ejemplos](#recursos-y-ejemplos).

### Implementación de un Webhook

[](#implementación-de-un-webhook)

Un **Webhook** es una devolución de llamada HTTP a un URL especificado. Ellos se activan cada vez que se actualizan los datos de sincronización para ayudarte a mantenerte al día con los últimos cambios en la información.

La ventaja principal es que te permite recibir las últimas actualizaciones de credenciales, transacciones y attachments directamente en tu aplicación sin necesidad de estar preguntando constantemente por ellas.

[![alt](https://camo.githubusercontent.com/c32b3c88077fa06d4567331e191488bf7ebf3b6dbe9696ecd2ec90b53c1c2453/68747470733a2f2f6d656469612e67697068792e636f6d2f6d656469612f6c324a6568506278356549464c71416d732f67697068792e676966)](https://camo.githubusercontent.com/c32b3c88077fa06d4567331e191488bf7ebf3b6dbe9696ecd2ec90b53c1c2453/68747470733a2f2f6d656469612e67697068792e636f6d2f6d656469612f6c324a6568506278356549464c71416d732f67697068792e676966)

Para fines prácticos de desarrollo usaremos el servicio de [ngrok](https://ngrok.com/), el cual nos permite crear URLs públicas para exponer nuestro servidor local a través de internet. Puedes consultar cómo instalarlo en su [página de descargas](https://ngrok.com/download).

Ahora crearemos un servidor sencillo con [PHP](https://www.php.net/) y [Slim](https://www.slimframework.com/).

> Cabe mencionar que se hace uso de estas tecnologías con fines ilustrativos y el desarrollador es libre de implementar las que crea más convenientes.

Creando un archivo al que llamaremos `server.php` e incluiremos el siguiente código:

```