API de documentación

API tecnológica Bullfrog v1.0.0

Introducción

El siguiente documento detalla la API pública de Bullfrog para interactuar con el sistema de punto de venta y oficina en la nube de Bullfrog. La API es un servicio REST basado en JSON que utiliza autenticación de token.

Versionado

Esta API sigue SemVerpor lo que puede estar seguro de que los cambios serán compatibles con versiones anteriores. Todas las rutas comienzan con el número de versión principal para garantizar una transición clara y sencilla entre las versiones de API.

La API siempre admitirá la versión principal actual y la última.

Autenticación

Authorization: Token token="YOUR API TOKEN"

Alternativamente, si es necesario, puede enviar el token a través de un auth_token parámetro.

Los tokens API son exclusivos de un cliente, por lo que si interactúa con más de un cliente de Bullfrog, es posible que necesite más de un token API. El token API identifica al cliente al que realiza las solicitudes.

Si no incluye un token API válido en su solicitud, recibirá un 401 Unauthorized. Si incluye un token API válido pero no está autorizado a realizar la acción intentada, recibirá un 403 Forbidden.

Manejo de errores

El manejo de errores intenta ser coherente y claro si encuentra errores en la API. Códigos de respuesta HTTP generalmente detalla el éxito o el fracaso de una solicitud y da alguna indicación de lo que salió mal.

En general:

El rango 2xx indica éxito.
El rango 2xx indica éxito.
El rango 5xx indica un error en la API (del que luego se nos notificará).

Códigos de respuesta comunes utilizados por esta API:

200 bien
201 creado,
202 Aceptado
204 Sin contenido
400 Petición Incorrecta
401 no autorizado
403 Prohibido
404 no encontrada
422 Entidad no procesable

Además, cada respuesta de error contendrá un amigable message puede mostrar a sus usuarios finales, un únicocode y un description para que los desarrolladores ayuden a solucionar problemas o escribir un script de lo que salió mal, y cualquier otra información relevante para el contexto.

Por ejemplo:

{
  "code":"401",
  "message":"Please sign in to access that resource.",
  "description":"The authentication header or token could not be found or was incorrect and we could not authenticate you. Ensure you are sending the correct authentication information either by the Authorization header or auth_token parameter.",
  "more_info":"https://bullfrogtech.com/docs/api#authentication"
}

Fechas y Horarios

Todas las fechas y horas devueltas por la API están en formato UTC como ISO 8601. Este es un formato inequívoco que tiene en cuenta la zona horaria y debería ser fácilmente analizable en la mayoría de los idiomas.

Cualquier fecha enviada a la API que no contenga información de zona horaria se interpretará como UTC.

Paginación

Rutas de recolección, como GET /clients, proporciona ayuda de paginación para mostrar vistas paginadas en el cliente. Las ayudantes de paginación vendrán de forma estandarizada. pagination bloque dentro del meta bloquear en la respuesta.

page – Indica la página actual que ha solicitado.
per_page – El número máximo de registros que se devolverán por página.
next_page – El número de la página siguiente en los resultados. Será null si no hay página siguiente.
prev_page – El número de la página anterior en los resultados. Será null si no hay página anterior.
page_count – Número total de páginas en el resultado.
total_count – Número total de registros en el resultado.

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 5,
      "next_page": 2,
      "prev_page": null,
      "page_count": 10,
      "total_count": 50
    }
  }
}

Rutas

Cliente

Las clientes representan un usuario final del sistema. Se espera que estén identificados de forma única mediante un número de identificación (conocido como uid) al otro lado de todas tus ubicaciones and at the punto de venta.

`GET /clients`

Obtenga una lista paginada de clientes.

Parámetros:

name – opcional – Filtre los resultados para clientes con un nombre que coincida con esta cadena.
tags – opcional – Filtre los resultados para clientes con una etiqueta coincidente. Varias etiquetas separadas por comas devuelven el subconjunto de clientes que coinciden con todas las etiquetas.
updated_since – opcional – Solo devuelve clientes que se han actualizado desde la fecha.
page – opcional – Se utiliza para seleccionar la lista paginada de resultados. Por defecto: 1
per_page – opcional – Cuántos resultados por página. Predeterminado: 10. Máxima: 100

Solicitud de ejemplo:

GET https://api.bullfrogtech.com/v1/clients?name=Jeff&per_page=5&tags=example,tags

Ejemplo de respuesta:

{
  "clients": [
    {
      "uid": "00123abcd",
      "name": "Jeff Smith",
      "balance": 12.34,
      "memo": "",
      "pin": "1234",
      "daily_spending_limit": 10.23,
      "tags": ["example", "tags"],
      "created_at": "2015-01-01T14:00:00Z",
      "updated_at": "2015-02-28T14:00:00Z",
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 5,
      "next_page": 2,
      "prev_page": null,
      "page_count": 1,
      "total_count": 1
    }
  }
}

`GET /clients/:uid`

Recuperar los detalles de un cliente en particular.

Solicitud de ejemplo:

GET https://api.bullfrogtech.com/v1/clients/00123abcd

Ejemplo de respuesta:

{
  "uid": "00123abcd",
  "name": "Jeff Smith",
  "balance": 12.34,
  "memo": "",
  "pin": "1234",
  "daily_spending_limit": 10.23,
  "tags": ["example", "tags"],
  "created_at": "2015-01-01T14:00:00Z",
  "updated_at": "2015-02-28T14:00:00Z",
}

`PATCH/PUT /clients/:uid`

Actualizar un registro de cliente. No es necesario crear clientes específicamente antes de la actualización.

Parámetros:

name – opcional – El nombre del cliente.
memo – opcional – Un mensaje que se mostrará en la pantalla del punto de venta, al operador, cuando este cliente realice una compra presencial.
pin – opcional – La clave de acceso del cliente para realizar una compra en el TPV. Puede aplicarse o no en el POS según la configuración de la ubicación.
daily_spending_limit – opcional – El límite de gasto diario permitido. Nota: un valor de null significa que no hay límite de gasto diario, un valor de 0 es un límite de gasto diario de $0.00 y no permitirá al cliente realizar compras.
tags – opcional – Una lista de cadenas con las que etiquetaremos al cliente. Luego puede filtrar clientes por estas etiquetas.

Solicitud de ejemplo:

PATCH https://api.bullfrogtech.com/v1/clients/55443?name=Jill Garcia

Ejemplo de respuesta:

{
  "uid": "55443",
  "name": "Jill Garcia",
  "balance": 0.00,
  "memo": "",
  "pin": "1234",
  "daily_spending_limit": 10.23,
  "tags": ["example", "tags"],
  "created_at": "2015-03-01T14:00:00Z",
  "updated_at": "2015-04-15T14:00:00Z",
}

Silbido

Se pueden utilizar rutas de ping para depurar la conexión y garantizar que haya una conexión activa a la API. Ambos métodos de ping responden a ambos GET y POST rutas.

`GET/PUT /ping`

Hace ping a los servidores API y responde con un Pong!, la hora actual y una lista de los parámetros que recibió en la solicitud de ping.

Parámetros:

Todo lo que se envíe al servidor como parámetro se reflejará en la salida.

Solicitud de ejemplo:

GET https://api.bullfrogtech.com/v1/ping?example=test

Ejemplo de respuesta:

{
  "message": "Pong!",
  "time": "2015-03-01T14:00:00Z",
  "received": {
    "example": "test"
  }
}

`GET/PUT /authenticated_ping`

La misma que la ping método, pero requiere que el usuario esté autenticado; de lo contrario, devolverá una respuesta no autenticada: 401 Unauthorized.

Parámetros:

Todo lo que se envíe al servidor como parámetro se reflejará en la salida.

Solicitud de ejemplo:

GET https://api.bullfrogtech.com/v1/authenticated_ping?auth=example

Ejemplo de respuesta:

{
  "message": "Pong! You are authenticated as YOUR_USER_NAME",
  "time": "2015-03-01T14:00:00Z",
  "received": {
    "auth": "example"
  }
}

Transacción

Las transacciones son entradas que ocurren en el saldo de la billetera. Estos pueden venir en forma de depósitos y retiros a través de terceros o compras y reembolsos a través del punto de venta.

`POST /clients/:uid/deposits`

Crea una transacción de depósito para la cliente.

Parámetros:

amount – requerida – El monto en dólares de la transacción.
memo – opcional – Un campo para ingresar valores o referencias personalizados.

Solicitud de ejemplo:

POST https://api.bullfrogtech.com/v1/clients/55443/deposits?amount=5.50

Ejemplo de respuesta:

{
  "id": 12345,
  "type": "deposit",
  "amount": 5.50,
  "net_amount": 5.50,
  "memo": "",
  "occurred_at": "2015-03-01T14:00:00Z",
  "client": {
    "uid": "12345",
    "name": "Jill Garcia",
    "balance": 5.50,
    "memo": "",
    "pin": "1234",
    "daily_spending_limit": 10.23,
    "tags": ["example", "tags"],
    "created_at": "2015-03-01T14:00:00Z",
    "updated_at": "2015-04-15T14:00:00Z"
  }
}

`POST /clients/:uid/withdrawals`

Crea una transacción de retiro para la cliente.

Parámetros:

amount – requerida – El monto en dólares de la transacción.
memo – opcional – Un campo para ingresar valores o referencias personalizados.

Solicitud de ejemplo:

POST https://api.bullfrogtech.com/v1/clients/55443/withdrawals?amount=1.00

Ejemplo de respuesta:

{
  "id": 23456,
  "type": "withdrawal",
  "amount": 1.00,
  "net_amount": -1.00,
  "memo": "",
  "occurred_at": "2015-03-01T14:00:00Z",
  "client": {
    "uid": "12345",
    "name": "Jill Garcia",
    "balance": 4.50,
    "memo": "",
    "pin": "1234",
    "daily_spending_limit": 10.23,
    "tags": ["example", "tags"],
    "created_at": "2015-03-01T14:00:00Z",
    "updated_at": "2015-04-15T14:00:00Z"
  }
}

`GET /clients/:uid/transactions`

Obtenga una lista paginada de las transacciones de un cliente.

Parámetros:

type – opcional – Filtrar la respuesta solo a los tipos especificados. Separe varios tipos con una coma. Ejemplo: type=deposit,purchase. El valor predeterminado es toda tipos.
occurred_since – opcional – Solo devuelve transacciones que han ocurrido desde la fecha del sello.
page – opcional – Se utiliza para seleccionar la lista paginada de resultados. Por defecto: 1
per_page – opcional – Cuántos resultados por página. Predeterminado: 10. Máxima: 100

Respuesta :

id – El ID único de la transacción.
type – Tipo de transacción tal como ocurrió para la billetera. Los valores permitidos son: deposit, withdrawal, purchase, refund.
total – Monto en dólares de la transacción a través del método de pago Wallet.
net_total – Monto en dólares de la transacción tal como afectó el saldo. Parawithdrawal y purchase tipo de transacciones, este número será el mismo que total Pero negativa. Puede ser útil si desea generar el monto que afectó al saldo sin tener que mirar type.
memo – Campo para valor personalizado. Disponible para deposit y withdrawal Tipos, en blanco para otras.
occurred_at – Hora en que ocurrió la transacción.
client_uid – Un identificador único para todo el inquilino para este cliente.
transaction – Una estructura que detalla la transacción completa en el POS. Sólo aplicable a purchase y refund tipos.
- id – El ID único de la transacción.
- total – Importe total de la transacción.
- reset_id – El ID único del reinicio. Puede ser nula si aún no se ha restablecido.
- lane
  - id – El ID del carril.
  - name – Nombre del carril en el que se produjo la transacción.
- location
  - id – El ID de la ubicación.
  - name – Nombre de la ubicación donde se produjo la transacción.
- items – Una variedad de artículos de línea que fueron comprados o reembolsados.
  - description – Una descripción de texto del artículo.
  - total – El importe total de esta partida.
  - amount – El importe unitario.
  - quantity – Número de unidades compradas.
  - order – El orden de las unidades tal como se compraron.
- taxes – Una variedad de impuestos.
  - name – Nombre del impuesto.
  - amount – Importe del impuesto.
- payments – Una variedad de pagos.
  - by – La forma de pago. Una cadena que indica “Monedero”, “Efectivo”, “Cheque”, “Visa”, etc.
  - amount – Cantidad de pago.

Solicitud de ejemplo:

GET https://api.bullfrogtech.com/v1/clients/55443/transactions?per_page=5

Ejemplo de respuesta:

{
  "transactions": [
    {
      "id": 12345,
      "type": "deposit",
      "total": 45.00,
      "net_total": 45.00,
      "memo": "Custom string.",
      "occurred_at": "2015-02-28T14:00:00Z",
      "client_uid": "1234abcd"
    },
    {
      "id": 23456,
      "type": "withdrawal",
      "total": 45.00,
      "net_total": -45.00,
      "memo": "Custom string.",
      "occurred_at": "2015-02-28T14:00:00Z",
      "client_uid": "1234abcd"
    },
    {
      "id": 34567,
      "type": "purchase",
      "total": 4.67,
      "net_total": -4.67,
      "memo": "",
      "occurred_at": "2015-02-28T14:00:00Z",
      "client_uid": "1234abcd",
      "transaction": {
        "id": 998877,
        "total": 5.67,
        "reset_id": 3242,
        "lane": {
          "id": 1234,
          "name": "Lane Name"
        },
        "location": {
          "id": 4567,
          "name": "Location Name"
        },
        "items": [
          {
            "description": "Small Milk",
            "total": 5.00,
            "amount": 2.50,
            "quantity": 2.0,
            "order": 1
          }
        ],
        "taxes": [
          {
            "name": "GST",
            "amount": 0.67
          }
        ],
        "payments": [
          {
            "by": "Wallet",
            "amount": 4.67,
          },
          {
            "by": "Cash",
            "amount": 1
          }
        ]
      }
    },
    {
      "id": 45678,
      "type": "refund",
      "total": 1.00,
      "net_total": 1.00,
      "occurred_at": "2015-02-28T14:00:00Z",
      "client_uid": "1234abcd",
      "transaction": {
        "id": 665544,
        "total": -1.00,
        "reset_id": 3243,
        "lane": {
          "id": 1234,
          "name": "Lane Name"
        },
        "location": {
          "id": 4567,
          "name": "Location Name"
        },
        "items": [
          {
            "plu": "1234abcd",
            "description": "Pop",
            "total": -0.93,
            "amount": 0.93,
            "quantity": -1.0,
            "order": 1
          }
        ],
        "taxes": [
          {
            "name": "GST",
            "amount": -0.07
          }
        ],
        "payments": [
          {
            "by": "Wallet",
            "amount": -1,
          }
        ]
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 5,
      "next_page": 2,
      "prev_page": null,
      "page_count": 1,
      "total_count": 1
    }
  }
}

Silbido

Un reinicio representa el cierre de un período fiscal de un carril o grupo de carriles.

`GET /resets`

Obtenga una lista paginada de reinicios.

Parámetros:

occurred_since – opcional – Solo devuelve los restablecimientos que se han producido desde la fecha.
page – opcional – Se utiliza para seleccionar la lista paginada de resultados. Por defecto: 1
per_page – opcional – Cuántos resultados por página. Predeterminado: 10. Máxima: 100

Respuesta :

id – Identifica de forma única este reinicio en todos los carriles, ubicaciones e inquilinos. Se utiliza para consultar los detalles del reinicio.
number – Este es el número de reinicio informado por el POS y solo puede ser exclusivo del carril o grupo de carriles. Generalmente es secuencial para los carriles afectados pero no de forma global. Puede usarse para ayudar en la contabilidad y la presentación de informes.
total – La suma total de las transacciones de billetera contenidas en este reinicio.
count – La cantidad de transacciones de billetera incluidas en este reinicio.
lane
- id – El ID del carril.
- name – Nombre del carril en el que se produjo la transacción.
location
- id – El ID de la ubicación.
- name – Nombre de la ubicación donde se produjo la transacción.
occurred_at – La hora a la que se produjo el reinicio.

Solicitud de ejemplo:

GET https://api.bullfrogtech.com/v1/resets?page=2&per_page=5

Ejemplo de respuesta:

{
  "resets": [
    {
      "id": 34234,
      "number": "2342abc",
      "total": 512.34,
      "count": 53,
      "lane": {
        "id": 1234,
        "name": "Lane Name"
      },
      "location": {
        "id": 4567,
        "name": "Location Name"
      },
      "occurred_at": "2015-01-01T14:00:00Z",
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 5,
      "next_page": 2,
      "prev_page": null,
      "page_count": 1,
      "total_count": 1
    }
  }
}

`GET /resets/:uid`

Recupera los detalles de un reinicio en particular.

Respuesta :

id – Identifica de forma única este reinicio en todos los carriles, ubicaciones e inquilinos. Se utiliza para consultar los detalles del reinicio.
number – Este es el número de reinicio informado por el POS y solo puede ser exclusivo del carril o grupo de carriles. Generalmente es secuencial para los carriles afectados pero no de forma global. Puede usarse como ayuda en la contabilidad.
total – La suma total de las transacciones de billetera contenidas en este reinicio.
count – La cantidad de transacciones de billetera incluidas en este reinicio.
lane
- id – El ID del carril.
- name – Nombre del carril en el que se produjo la transacción.
location
- id – El ID de la ubicación.
- name – Nombre de la ubicación donde se produjo la transacción.
occurred_at – La hora a la que se produjo el reinicio.
transactions – Una variedad de transacciones de billetera (purchase y refunds solamente) incluido en el reinicio.
- id – El ID único de la transacción.
- type – Tipo de transacción. Solo purchase o refund Se devolverán los tipos.
- total – Monto en dólares de la transacción.
- client_uid – Un identificador único para todo el inquilino para este cliente.
- occurred_at – Hora en que se produjo la transacción.
- reset_id – El ID único del reinicio. Puede ser nula si aún no se ha restablecido.
- lane
  - id – El ID del carril.
  - name – Nombre del carril en el que se produjo la transacción.
- location
  - id – El ID de la ubicación.
  - name – Nombre de la ubicación donde se produjo la transacción.
- payments – Una variedad de pagos.
  - by – La forma de pago. Solo contendrá transacciones de «Monedero».
  - amount – Cantidad de pago.

Solicitud de ejemplo:

GET https://api.bullfrogtech.com/v1/resets/34234

Ejemplo de respuesta:

{
  "id": 34234,
  "number": "2342abc",
  "total": 4.67,
  "count": 2,
  "lane": {
    "id": 1234,
    "name": "Lane Name"
  },
  "location": {
    "id": 4567,
    "name": "Location Name"
  },
  "occurred_at": "2015-01-01T14:00:00Z",
  "transactions": [
    {
      "id": 34567,
      "type": "purchase",
      "total": 5.67,
      "client_uid": "1234abcd",
      "occurred_at": "2015-02-28T14:00:00Z",
      "reset_id": 34234,
      "lane": {
        "id": 1234,
        "name": "Lane Name"
      },
      "location": {
        "id": 4567,
        "name": "Location Name"
      },
      "payments": [
        {
          "by": "Wallet",
          "amount": 5.67,
        }
      ]
    },
    {
      "id": 45678,
      "type": "refund",
      "total": -1.00,
      "client_uid": "1234abcd",
      "occurred_at": "2015-02-28T14:00:00Z",
      "reset_id": 34234,
      "lane": {
        "id": 1234,
        "name": "Lane Name"
      },
      "location": {
        "id": 4567,
        "name": "Location Name"
      },
      "payments": [
        {
          "by": "Wallet",
          "amount": -1,
        }
      ]
    }
  ]
}

API de documentación

API tecnológica Bullfrog v1.0.0

Introducción

Versionado

Autenticación

Manejo de errores

Fechas y Horarios

Paginación

Rutas

Cliente

GET /clients

GET /clients/:uid

PATCH/PUT /clients/:uid

Silbido

GET/PUT /ping

GET/PUT /authenticated_ping

Transacción

POST /clients/:uid/deposits

POST /clients/:uid/withdrawals

GET /clients/:uid/transactions

Silbido

GET /resets

GET /resets/:uid

¿Lista para mover tu punto de venta al futuro?

`GET /clients`

`GET /clients/:uid`

`PATCH/PUT /clients/:uid`

`GET/PUT /ping`

`GET/PUT /authenticated_ping`

`POST /clients/:uid/deposits`

`POST /clients/:uid/withdrawals`

`GET /clients/:uid/transactions`

`GET /resets`

`GET /resets/:uid`