Antes de iniciar a integração, você precisa ser administrador de uma loja oficial no ByPantry. Se você ainda não possui, siga os seguintes passos:
Primeiro, acesse o App e na tela inicial entre na área de Pesquisar. Pesquise por lojas e digite o nome da sua loja, ela será listada nos resultados da pesquisa.
Se sua loja ainda não é oficial, a aba Promoções apresentará o aspecto abaixo, clique no botão existente no meio da tela e na sequência clique em GERENCIAR AGORA.
Preencha as informações com atenção, verifique inclusive a importância de estar em posse do contrato social do CNPJ referente a loja e ter um documento com foto, conforme instruções que constam na tela. Essas informações bem respondidas agilizam e muito o processo de liberação da loja para você, pois torna o processo decisório da ByPantry muito mais rápido.
Caso sua loja já seja oficial, você deve solicitar ao administrador atual lhe incluir como membro da equipe, para que possa acessar os passos seguintes na área do desenvolvedor.
Por fim acesse o ByPantry For Business para validar se o seu acesso está corretamente liberado na plataforma.
https://business.bypantry.com
Agora que você já tem acesso ao ByPantry For Business, no menu lateral acesse Desenvolvedores → API Tokens.
Atribua um nome ao seu token, escolha as permissões que melhor se aplicam e pressione o botão Gerar Token, que o seu token será gerado e exibido para você.
NOTA: Por razões de segurança este token nunca mais será exibido, portanto é sua responsabilidade copiá-lo e mantê-lo em local seguro que evite perdas. Podem ser tantos tokens quanto você tenha necessidade.
Pronto! Agora você já tem um token e está pronto para chamar a API do ByPantry.
Para criar um webhook basta se autenticar no ByPantry For Business e navegar em Desenvolvedores → Webhooks.
Preencha os três campos solicitados na tela seguinte, dentro da área “Adicionar novo webhook” e clique em “Adicionar endpoint”.
Você será redirecionado para a tela de webhooks onde serão exibidas em lista as informações básicas dos endpoints que você tenha criado.
Para descobrir qual é a chave de assinatura do webhook criado que será usada para assinar as requisições que virão, basta clicar em Alterar em alterar e na tela de detalhes, clicar em Revelar, para exibir a chave de assinatura.
Descrição: Realizar movimentações de estoque, como entrada e saída.
| Ambiente | Ação | URL |
|---|---|---|
| Homologação | POST | - |
| Produção | POST | https://developers.bypantry.com/api/v1/manager/goods-movement |
| Protocolo | JSON |
|---|---|
|
REST – Para realizar o consumo pelo protocolo de comunicação REST você precisará enviar as seguintes informações no Body da requisição em formato JSON.
Caso você não queira fornecer a informação do estoque, recomenda-se fortemente enviar o campo out_of_stock como true quando o estoque atingir a margem de segurança no seu sistema, ou ainda quando o estoque em nºs absolutos for igual ou inferior a 10 unidades. Qualquer cenário de estoque acima disto, deve ser enviado como out_of_stock false. |
{ "product_external_id": "01234", "product_name": "FOSAJFDOA JOIDJ OFAS", "barcode": "78919837181401", "out_of_stock": null, "direction": "out", "qty": "100" } |
| Campo | Tipo | Obrigatório | Pré-requisitos | Descrição |
|---|---|---|---|---|
| product_external_id | string:255 | Sim | N/A | Código do produto no seu sistema. Deve ser o mesmo código que é enviado para a SEFAZ no momento da emissão da NFC-e. |
| product_name | string:255 | Sim | N/A | Nome do produto dentro do seu sistema. |
| barcode | string:255 | Sim | N/A | Código de barras do produto, quando não houver deve vir preenchido com “SEM GTIN”. |
| out_of_stock | boolean | Não | Valores possíveis: true | false | Campo que indica se o produto está fora de estoque. Recomenda-se enviá-lo como true quando o estoque atingir a margem de segurança no seu sistema, ou ainda quando o estoque em nºs absolutos for igual ou inferior a 10 unidades. |
| direction | Enum: ‘in’ | ‘out |
Não | Somente aceita ‘in’ ou ‘out’. | Indica a direção do movimento, onde quando preenchido como ‘in’ indicada que o movimento é de entrada no seu estoque, e quando preenchido com ‘out’ indicará que o movimento é de saída do seu estoque. |
| qty | Float:8,3 | Não | Somente aceita valores numéricos, mesmo que contenham ponto flutuante. | Quantidade movimentada, pode ser um número inteiro ou com casas decimais para os casos de produtos que são pesados em balança. |
| Status HTTP | Motivo | O que fazer | JSON |
|---|---|---|---|
| 201 | Registro criado com sucesso | Sem ação adicional, operação concluída. |
{ "event_id": "e57b9c7b-bb9e-4e5d-ad8d-0f041aac3dc7", "event_type": "stock.goods_movement", "status": "pending" } |
| 401 | Token inválido | Verificar se o token está correto, e até mesmo criar um para a continuidade da comunicação. |
{ "message": "Unauthenticated." } |
| 403 | Permissão incorreta | Ajustar a permissão do token ou alterar o token para outro que contenha a permissão necessária. Importante notar que o token deve ter a permissão ‘create’ para executar este evento. |
{ "message": "Não encontrada permissão para essa ação [create]" } |
| 422 | Pré-requisito não atendido | Avaliar mensagem tabela de pré-requisitos acima e atuar de acordo com a mensagem explicativa que será retornada. |
{ "message": "The given data was invalid.", "errors": { "product_external_id": [ "O campo product external id é obrigatório." ], "barcode": [ "O campo barcode é obrigatório." ], "product_name": [ "O campo product name é obrigatório." ], "out_of_stock": [ "The out of stock field must be true or false." ], "direction": [ "O valor selecionado para direction é inválido." ], "qty": [ "O qty precisa ser um valor numérico." ] } } |
| 500 | Erro interno desconhecido. Esperamos que você nunca passe por isso | Entrar em contato com o suporte através do e-mail support@bypantry.com |
{ "message": "Server Error" } |
Descrição: Atualizar preços de produtos individuais. Recomendamos preparar o seu sistema para realizar as chamadas deste grupo em real-time, ou seja, quando a atualização ocorrer na origem.
| Ambiente | Ação | URL |
|---|---|---|
| Homologação | POST | - |
| Produção | POST | https://developers.bypantry.com/api/v1/manager/price |
| Protocolo | JSON |
|---|---|
| REST – Para realizar o consumo pelo protocolo de comunicação REST você precisará enviar as seguintes informações no Body da requisição em formato JSON: |
{ "product_external_id": "1234", "product_name": "oasfdaojdfnja ojsdfnnjasfdaosf naposdfnpsnf", "barcode": "7891234567890", "price": "12.45", "is_on_sale": true, "price_on_sale": "10.45", "on_sale_starts_at": "2022-05-13 22:55:55", "on_sale_finishs_at": "2022-05-20 22:55:55", "price_after_on_sale": "13.55", "out_of_stock": true } |
| Campo | Tipo | Obrigatório | Pré-requisitos | Descrição |
|---|---|---|---|---|
| product_external_id | String:255 | Sim | N/A | Código do produto no seu sistema. Deve ser o mesmo código que é enviado para a SEFAZ no momento da emissão da NFC-e. |
| barcode | String:255 | Sim | N/A | Código de barras do produto, quando não houver deve vir preenchido com “SEM GTIN”. |
| product_name | String:255 | Sim | N/A | Nome do produto dentro do seu sistema. |
| price | Float:8,2 | Sim | N/A | Preço do produto de acordo com o que está sendo apresentado na gôndola física da loja. |
| is_on_sale | Boolean | Sim | Preenchimento do campo price_on_sale. true | false |
Campo que indica se o produto está em promoção, sim ou não. Caso o produto esteja em promoção, torna-se obrigatório preencher o campo price_on_sale descrito a seguir. |
| price_on_sale | Float:8,2 | Não | N/A | Preço promocional do produto. Deve ser um numérico e torna-se obrigatório caso o campo is_on_sale seja enviado como true. |
| on_sale_starts_at | DateTime | Não | Formato: “Y-m-d H:i:s Obrigatório caso seja preenchido o price_after_on_sale” |
Data de início da validade da promoção. O ByPantry pode controlar automaticamente o período promocional do seu produto, e aqui você define a data/hora a partir de quando o preço promocional deve ser exibido para os seus consumidores. Caso preencha este campo, torna-se obrigatório preencher o campo on_sale_finishs_at descrito a seguir. Este campo torna-se obrigatório caso você preencha o campo price_after_on_sale descrito mais abaixo. |
| on_sale_finishs_at | DateTime | Não | Formato: “Y-m-d H:i:s” Obrigatório caso seja preenchido o on_sale_starts_at |
Data final da validade da promoção. O ByPantry pode controlar automaticamente o período promocional do seu produto, e aqui você define a data/hora final de quando o preço promocional deve ser ocultado de seus consumidores. Torna-se obrigatório caso você preencha o campo on_sale_starts_at. |
| price_after_on_sale | Float:8,2 | Não | N/A | Define o novo preço do produto após o período promocional. Caso você defina um período para a promoção e não preencha este campo, concluído o período promocional o sistema voltará com o preço de acordo com o conteúdo do campo ‘price’. |
| out_of_stock | Boolean | Não | true | false | Campo que indica se o produto está fora de estoque. Recomenda-se enviá-lo como true quando o estoque atingir a margem de segurança no seu sistema, ou ainda quando o estoque em nºs absolutos for igual ou inferior a 10 unidades. |
| Status HTTP | Motivo | O que fazer | JSON |
|---|---|---|---|
| 201 | Registro criado com sucesso | Sem ação adicional, operação concluída. |
{ "event_id": "90ac3388-c75a-4cca-85ec-3f5cf032bf55", "event_type": "price.updated", "status": "pending" } |
| 401 | Token inválido | Verificar se o token está correto, e até mesmo criar um para a continuidade da comunicação. |
{ "message": "Unauthenticated." } |
| 403 | Permissão incorreta | Ajustar a permissão do token ou alterar o token para outro que contenha a permissão necessária. Importante notar que o token deve ter a permissão ‘create’ para executar este evento. |
{ "message": "Não encontrada permissão para essa ação [create]" } |
| 422 | Pré-requisito não atendido | Avaliar mensagem tabela de pré-requisitos acima e atuar de acordo com a mensagem explicativa que será retornada. |
{ "message": "The given data was invalid.", "errors": { "product_external_id": [ "The product external id must not be greater than 255 characters." ], "barcode": [ "O campo barcode é obrigatório." ], "product_name": [ "The product name must be a string." ], "price": [ "O price precisa ser um valor numérico." ], "is_on_sale": [ "O campo is on sale é obrigatório." ], "price_on_sale": [ "The price on sale field is required when is on sale is true." ], "price_after_on_sale": [ "O price after on sale precisa ser um valor numérico." ], "out_of_stock": [ "The out of stock field must be true or false." ], "on_sale_starts_at": [ "The on sale starts at field is required when price after on sale is present." ], "on_sale_finishs_at": [ "The on sale finishs at field is required when on sale starts at is present." ] } } |
| 500 | Erro interno desconhecido. Esperamos que você nunca passe por isso | Entrar em contato com o suporte através do e-mail support@bypantry.com |
{ "message": "Server Error" } |