Documentation de l'API

Bullfrog Tech API v1.0.0

Introduction

Le document suivant détaille l’API publique de Bullfrog pour interagir avec le système Bullfrog Cloud Office et Point of Sale. L’API est un service REST basé sur JSON qui utilise l’authentification par jeton.

Versioning

Cette API suit SemVer, vous pouvez donc être assuré que les changements seront rétrocompatibles dans les versions majeures. Tous les itinéraires commencent par le numéro de la version principale afin d’assurer une transition claire et facile entre les versions de l’API.

L’API prendra toujours en charge la version actuelle et la dernière version majeure.

Authentification

Authorization: Token token="YOUR API TOKEN"

Si vous le souhaitez, vous pouvez également envoyer le jeton par l’intermédiaire d’un paramètre auth_token.

Les jetons d’API sont uniques pour un client, donc si vous interagissez avec plus d’un client Bullfrog, vous pouvez avoir besoin de plus d’un jeton d’API. Le jeton API identifie le client pour lequel vous effectuez les requêtes.

Si vous n’incluez pas un jeton API valide dans votre demande, vous recevrez un message 401 Unauthorized. Si vous incluez un jeton API valide mais que vous n’êtes pas autorisé à effectuer la tentative d’action, vous recevrez un message 403 Forbidden.

Gestion des erreurs

La gestion des erreurs s’efforce d’être cohérente et claire si vous rencontrez des erreurs dans l’API. Les codes de réponse HTTP indiquent généralement le succès ou l’échec d’une demande et donnent des indications sur ce qui n’a pas fonctionné.

En général :

La plage 2xx indique un succès.
La plage 4xx indique une erreur basée sur les informations reçues par l’API (soit un paramètre requis manquait, soit la demande n’a pas abouti).
La plage 5xx indique une erreur dans l’API (qui nous sera alors notifiée).

Codes de réponse courants utilisés par cette API :

200 OK
201 Créé,
202 Accepté
204 Pas de contenu
400 Mauvaise demande
401 Non autorisé
403 Interdit
404 Non trouvé
422 Entité non traitable

En outre, chaque réponse d’erreur contiendra un message amical message que vous pourrez afficher à vos utilisateurs finaux, un message unique code et un message description pour les développeurs afin de les aider à résoudre les problèmes ou à écrire ce qui n’a pas fonctionné, ainsi que toute autre information contextuelle pertinente.

Par exemple :

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

Dates et heures

Toutes les dates et heures renvoyées par l’API sont en UTC et formatées en ISO 8601. Il s’agit d’un format non ambigu qui tient compte du fuseau horaire et qui devrait être facilement analysé par la plupart des langages.

Toutes les dates envoyées à l’API qui ne contiennent pas d’informations sur le fuseau horaire seront interprétées comme étant UTC.

Pagination

Les itinéraires de collecte, tels que GET /clients, fournissent une aide à la pagination pour l’affichage de vues paginées sur le client. Les aides à la pagination seront présentées dans un bloc pagination normalisé à l’intérieur du bloc meta de la réponse.

page – Indique la page actuelle que vous avez demandée.
per_page – Le nombre maximum d’enregistrements qui seront renvoyés par page.
next_page – Le numéro de la page suivante dans les résultats. Sera null s’il n’y a pas de page suivante.
prev_page – Le numéro de la page précédente dans les résultats. L’adresse null sera utilisée s’il n’y a pas de page précédente.
page_count – Nombre total de pages dans le résultat.
total_count – Nombre total d’enregistrements dans le résultat.

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

Itinéraires

Client

Les clients représentent l’utilisateur final du système. Ils doivent être identifiés de manière unique par un numéro d’identification (connu sous le nom de uid) dans tous vos établissements et au point de vente.

`GET /clients`

Obtenir une liste paginée des clients.

Paramètres :

name – optionnel – Filtrer les résultats pour les clients dont le nom correspond à cette chaîne.
tags – optionnel – Filtrer les résultats pour les clients ayant une étiquette correspondante. Les balises multiples, séparées par des virgules, renvoient le sous-ensemble de clients correspondant à toutes les balises.
updated_since – optionnel – Ne renvoie que les clients qui ont été mis à jour depuis l’horodatage.
page – optionnel – Permet de sélectionner la liste paginée des résultats. Par défaut : 1
per_page – optionnel – Nombre de résultats par page. Valeur par défaut : 10. Maximum : 100

Exemple de demande :

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

Exemple de réponse :

{
  "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`

Récupérer les coordonnées d’un client particulier.

Exemple de demande :

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

Exemple de réponse :

{
  "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`

Mise à jour d’un dossier client. Les clients ne doivent pas être créés spécifiquement avant la mise à jour.

Paramètres :

name – optionnel – Le nom du client.
memo – optionnel – Un message à afficher sur l’écran du point de vente, à l’attention de l’opérateur, lorsque ce client effectue un achat en personne.
pin – optionnel – Le code d’accès du client pour effectuer un achat au point de vente. Peut ou non être appliqué au point de vente en fonction des paramètres du site.
daily_spending_limit – optionnel – La limite de dépenses journalières autorisée. Remarque : une valeur de null signifie qu’il n’y a pas de limite de dépenses quotidiennes, une valeur de 0 signifie que la limite de dépenses quotidiennes est de 0,00 $ et que le client ne pourra pas faire d’achats.
tags – optional – Une liste de chaînes de caractères avec lesquelles nous allons étiqueter le client. Vous pouvez ensuite filtrer les clients en fonction de ces étiquettes.

Exemple de demande :

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

Exemple de réponse :

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

Ping

Les routes de ping peuvent être utilisées pour déboguer la connexion et s’assurer qu’il y a une connexion active à l’API. Les deux méthodes de ping répondent aux itinéraires GET et POST.

`GET/PUT /ping`

Effectue un ping des serveurs de l’API et répond avec une adresse Pong!, l’heure actuelle et une liste des paramètres reçus dans la demande de ping.

Paramètres :

Tout ce qui est envoyé au serveur en tant que paramètre sera reflété dans la sortie.

Exemple de demande :

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

Exemple de réponse :

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

`GET/PUT /authenticated_ping`

Identique à la méthode ping, mais exige que l’utilisateur soit authentifié, sinon elle renvoie une réponse non authentifiée : 401 Unauthorized.

Paramètres :

Tout ce qui est envoyé au serveur en tant que paramètre sera reflété dans la sortie.

Exemple de demande :

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

Exemple de réponse :

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

Transaction

Les transactions sont des entrées qui se produisent sur le solde du portefeuille. Il peut s’agir de dépôts et de retraits par l’intermédiaire d’un tiers ou d’achats et de remboursements par l’intermédiaire d’un point de vente.

`POST /clients/:uid/deposits`

Crée une transaction de dépôt pour le client.

Paramètres :

amount – requis – Le montant en dollars de la transaction.
memo – optionnel – Un champ pour saisir des valeurs personnalisées ou des références.

Exemple de demande :

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

Exemple de réponse :

{
  "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`

Crée une transaction de retrait pour le client.

Paramètres :

amount – requis – Le montant en dollars de la transaction.
memo – optionnel – Un champ pour saisir des valeurs personnalisées ou des références.

Exemple de demande :

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

Exemple de réponse :

{
  "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`

Obtenir une liste paginée des transactions d’un client.

Paramètres :

type – optionnel – Filtrer la réponse uniquement sur les types spécifiés. Séparez les types multiples par une virgule. Exemple : type=deposit,purchase. La valeur par défaut est tous les types.
occurred_since – optionnel – Ne renvoie que les transactions qui ont eu lieu depuis l’horodatage.
page – optionnel – Permet de sélectionner la liste paginée des résultats. Par défaut : 1
per_page – optionnel – Nombre de résultats par page. Valeur par défaut : 10. Maximum : 100

Réponse :

id – L’identifiant unique de la transaction.
type – Type de transaction telle qu’elle s’est produite pour le portefeuille. Les valeurs autorisées sont : deposit, withdrawal, purchase, refund.
total – Montant en dollars de la transaction effectuée via la méthode de paiement Wallet.
net_total – Montant en dollars de la transaction telle qu’elle a affecté le solde. Pour les transactions de type withdrawal et purchase, ce numéro sera le même que total mais négatif. Cela peut être utile si vous souhaitez éditer le montant tel qu’il a affecté le solde sans avoir à consulter type.
memo – Champ pour la valeur personnalisée. Disponible pour les types deposit et withdrawal, vierge pour les autres.
occurred_at – Heure à laquelle la transaction a eu lieu.
client_uid – Un identifiant unique à l’échelle du locataire pour ce client.
transaction – Une structure qui détaille l’ensemble de la transaction au point de vente. Uniquement applicable aux types purchase et refund.
- id – L’identifiant unique de la transaction.
- total – Montant total de la transaction.
- reset_id – L’identifiant unique de la réinitialisation. Peut être nul s’il n’a pas encore été réinitialisé.
- lane
  - id – L’identifiant de la voie.
  - name – Nom de la voie sur laquelle la transaction a eu lieu.
- location
  - id – L’identifiant du lieu.
  - name – Nom de l’endroit où la transaction a eu lieu.
- items – Un tableau des postes achetés ou remboursés.
  - description – Une description textuelle de l’élément.
  - total – Le montant total de ce poste.
  - amount – Le montant par unité.
  - quantity – Nombre d’unités achetées.
  - order – L’ordre des unités telles qu’elles ont été achetées.
- taxes – Un éventail de taxes.
  - name – Nom de la taxe.
  - amount – Montant de la taxe.
- payments – Un ensemble de paiements.
  - by – Le mode de paiement. Une chaîne indiquant « Portefeuille », « Espèces », « Chèque », « Visa », etc.
  - amount – Montant du paiement.

Exemple de demande :

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

Exemple de réponse :

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

Ping

Une remise à zéro représente la clôture d’une période fiscale d’une voie ou d’un groupe de voies.

`GET /resets`

Obtenir une liste paginée des réinitialisations.

Paramètres :

occurred_since – optionnel – Ne renvoie que les réinitialisations qui ont eu lieu depuis l’horodatage.
page – optionnel – Permet de sélectionner la liste paginée des résultats. Par défaut : 1
per_page – optionnel – Nombre de résultats par page. Valeur par défaut : 10. Maximum : 100

Réponse :

id – Identifie de manière unique cette réinitialisation dans tous les couloirs, lieux et locataires. Utilisé pour demander les détails de la réinitialisation.
number – Il s’agit du numéro de remise à zéro tel qu’il est indiqué par le TPV et qui ne peut être propre qu’à la piste ou au groupe de pistes. Elle est généralement séquentielle pour les voies concernées, mais pas globalement. Peut être utilisé pour faciliter la comptabilité et l’établissement de rapports.
total – La somme totale des transactions de portefeuille contenues dans cette réinitialisation.
count – Le nombre de transactions du portefeuille incluses dans cette réinitialisation.
lane
- id – L’identifiant de la voie.
- name – Nom de la voie sur laquelle la transaction a eu lieu.
location
- id – L’identifiant du lieu.
- name – Nom de l’endroit où la transaction a eu lieu.
occurred_at – L’heure à laquelle la réinitialisation s’est produite.

Exemple de demande :

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

Exemple de réponse :

{
  "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`

Récupérer les détails d’une réinitialisation particulière.

Réponse :

id – Identifie de manière unique cette réinitialisation dans tous les couloirs, lieux et locataires. Utilisé pour demander les détails de la réinitialisation.
number – Il s’agit du numéro de remise à zéro tel qu’il est indiqué par le TPV et qui ne peut être propre qu’à la piste ou au groupe de pistes. Elle est généralement séquentielle pour les voies concernées, mais pas globalement. Peut être utilisé pour aider à la comptabilité.
total – La somme totale des transactions de portefeuille contenues dans cette réinitialisation.
count – Le nombre de transactions du portefeuille incluses dans cette réinitialisation.
lane
- id – L’identifiant de la voie.
- name – Nom de la voie sur laquelle la transaction a eu lieu.
location
- id – L’identifiant du lieu.
- name – Nom de l’endroit où la transaction a eu lieu.
occurred_at – L’heure à laquelle la réinitialisation s’est produite.
transactions – Un ensemble de transactions de portefeuille (purchase et refunds uniquement) incluses dans la réinitialisation.
- id – L’identifiant unique de la transaction.
- type – Type de transaction. Seuls les types purchase ou refund seront renvoyés.
- total – Montant en dollars de la transaction.
- client_uid – Un identifiant unique à l’échelle du locataire pour ce client.
- occurred_at – Heure à laquelle la transaction a eu lieu.
- reset_id – L’identifiant unique de la réinitialisation. Peut être nul s’il n’a pas encore été réinitialisé.
- lane
  - id – L’identifiant de la voie.
  - name – Nom de la voie sur laquelle la transaction a eu lieu.
- location
  - id – L’identifiant du lieu.
  - name – Nom de l’endroit où la transaction a eu lieu.
- payments – Un ensemble de paiements.
  - by – Le mode de paiement. Ne contiendra que les transactions « Wallet ».
  - amount – Montant du paiement.

Exemple de demande :

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

Exemple de réponse :

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

Documentation de l'API

Bullfrog Tech API v1.0.0

Introduction

Versioning

Authentification

Gestion des erreurs

Dates et heures

Pagination

Itinéraires

Client

GET /clients

GET /clients/:uid

PATCH/PUT /clients/:uid

Ping

GET/PUT /ping

GET/PUT /authenticated_ping

Transaction

POST /clients/:uid/deposits

POST /clients/:uid/withdrawals

GET /clients/:uid/transactions

Ping

GET /resets

GET /resets/:uid

Prêt à faire évoluer votre point de vente vers l'avenir ?

`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`