🏢Estabelecimentos

Introdução:

Para integrar um novo estabelecimento à plataforma bemfácil®, utilize o endpoint de criação de estabelecimento. Este processo é essencial para começar a usufruir dos serviços financeiros digitais oferecidos pela bemfácil®.

Criação de Novo Estabelecimento

POST https://stage-api.bemfacil.digital/customer

O endpoint POST /customer permite o credenciamento de um ou mais estabelecimentos, habilitando-os a utilizar a conta digital bemfácil. É necessário fornecer detalhes como documento do estabelecimento, razão social, nome fantasia, telefone, chave do cliente, e-mail, entre outros. https://plataforma.bemfacil.digital/

Autenticação entre Sistemas <- Tipo de autenticação utilizada por este endpoint

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer {Token gerado pela autenticação sistemica}

Request Body

Name	Type	Description
document*	string	Documento do EC ex: 31593345038
legalName*	string	Razão social do EC (Caso seja pessoa física, cadastrar o nome completo)
fantasyName*	string	Nome fantasia do EC (Caso seja pessoa física, cadastrar o nome completo)
phone*	string	Telefone do EC, ex: [phone]
responsibleDocument	String	Documento do responsável pelos dados bancários Ex: 31593345038 ou 77602863000163
pixKeyType	Number	Tipo da chave pix: 1 - Documento 2 - email 3 - telefone 4 - chave aleatória 5 - dados bancários
pixKey	String	Chave pix do cliente Ex: 31593345038 / 77602863000163 / [phone] / [email protected] ...
email*	String	email do EC ex: [email protected]
customerKey*	String	ID bemfácil do EC, ex: 12345
ispb	String	Número do banco perante o Bacem ex: 60872504
bankName	String	Nome do banco Ex 341 - ITAÚ
bankCode	String	Código do banco Ex: 341
agency	String	Agência da conta Ex: 1234
accountDigit	String	Digito da conta Ex: 1
account	String	Conta bancária Ex: 12334
nickname	String	Apelido para a conta pix Ex: Fulano da Silva

200: OK Estabelecimento criado com sucesso

[
    {
        "customerKey": "9999",
        "document": "99999999999",
        "fantasyName": "FULANO NA SILVA",
        "email": "[email protected]",
        "phone": "[phone]",
        "success": true,
        "steps": [
            {
                "stepName": "addCustomer",
                "stepStatus": {
                    "errorName": "Success",
                    "errorMessage": "Customer was created with this document: 99999999999"
                }
            },
            {
                "stepName": "addUser",
                "stepStatus": {
                    "errorName": "Success",
                    "errorMessage": "User was created on Cognito with username: 99999999999"
                }
            },
            {
                "stepName": "sendMail",
                "stepStatus": {
                    "errorName": "Success",
                    "errorMessage": "Success to send this email to: [email protected]"
                }
            }
        ]
    }
]

403: Forbidden Operação não permitida

200: OK Estabelecimento não criado por falha em uma das etapas

[
    {
        "customerKey": "9999",
        "document": "99999999999",
        "fantasyName": "FULANO NA SILVA",
        "email": "[email protected]",
        "phone": "[phone]",
        "success": true,
        "steps": [
            {
                "stepName": "addCustomer",
                "stepStatus": {
                    "errorName": "Error",
                    "errorMessage": "Error description"
                }
            },
            {
                "stepName": "addUser",
                "stepStatus": {
                    "errorName": "Error",
                    "errorMessage": "Error description"
                }
            },
            {
                "stepName": "sendMail",
                "stepStatus": {
                    "errorName": "Error",
                    "errorMessage": "Error description"
                }
            }
        ]
    }
]

500: Internal Server Error

Exemplo de Request:

POST /customer
Headers:
  Content-Type: application/json
  Authorization: Bearer {Token gerado pela autenticação sistemica}

Body:
{
  "document": "31593345038",
  "legalName": "Nome da Empresa Ltda",
  "fantasyName": "Nome Fantasia da Empresa",
  "phone": "[phone]",
  "customerKey": "12345",
  "email": "[email protected]",
  "pixKey": "31593345038",
  "pixKeyType": 1,
  "responsibleDocument": "31593345038",
  "nickname": "Fulano da Silva",
  "account": "12334",
  "accountDigit": "1",
  "agency": "1234",
  "bankCode": "341",
  "bankName": "ITAÚ",
  "ispb": "60872504"
}

Exemplo de Response:

{
  "status": "200",
  "message": "Estabelecimento criado com sucesso"
}

Este response indica que o estabelecimento foi criado e credenciado com sucesso na plataforma.

---

Bom saber: Os dados do Body, devem ser passados dentro de uma lista []

---

Alteração de Estabelecimento

Introdução:

Alterações nos dados cadastrais do estabelecimento podem ser realizadas através do endpoint específico para este fim. Isso permite atualizar informações importantes para a manutenção da conta.

Utilize o endpoint PUT /customer/{documento} para atualizar os dados de um estabelecimento já existente. As informações que podem ser atualizadas incluem razão social, nome fantasia, telefone, entre outras.

Endpoint: PUT /customer/{documento}

Alteração de estabelecimento da Conta bemfácil

PUT https://stage-api.bemfacil.digital/customer/{documento}

Autenticação entre Sistemas <- Autenticação utilizada para este endpoint

Path Parameters

Name	Type	Description
document*	String	Documento do EC

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer {Token gerado pela autenticação sistemica}

Request Body

Name	Type	Description
document	String	Documento do EC ex: 31593345038
legalName	String	Razão social do EC (Caso seja pessoa física, cadastrar o nome completo)
fantasyName	String	Nome fantasia do EC (Caso seja pessoa física, cadastrar o nome completo)
phone	String	Telefone do EC, ex: [phone]
customerKey	String	ID bemfácil do EC, ex: 12345

200: OK Estabelecimento alterado com sucesso

{
    "document": "09104373430",
    "success": true
}

500: Internal Server Error Falha ao alterar o estabelecimento

{
    "document": "09104373431",
    "success": false
}

403: Forbidden Operação não permitida (Autenticação inválida)

Exemplo de Request:

PUT /customer/31593345038
Headers:
  Content-Type: application/json
  Authorization: Bearer {Token gerado pela autenticação}

Body:
{
  "legalName": "Novo Nome da Empresa Ltda",
  "fantasyName": "Novo Nome Fantasia da Empresa",
  "phone": "[phone]",
  "email": "[email protected]"
}

Exemplo de Response:

{
  "status": "200",
  "message": "Estabelecimento alterado com sucesso"
}

Este response confirma que as informações do estabelecimento foram atualizadas corretamente.

---

Habilitação de Estabelecimento

Introdução:

Para habilitar um estabelecimento previamente cadastrado e permitir que ele inicie suas operações na plataforma, é necessário utilizar o endpoint de habilitação.

O endpoint PUT /enable/{documento} é destinado à habilitação de estabelecimentos, garantindo que estejam aptos a realizar transações e acessar os serviços da conta digital bemfácil.

Endpoint: PUT /enable/{documento}

Habilitar estabelecimento da Conta digital bemfácil

PUT https://stage-api.bemfacil.digital/enable/{documento}

Autenticação entre Sistemas <- Autenticação utilizada para este endpoint

Path Parameters

Name	Type	Description
documento*	String	Documento do EC

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer {Token gerado pela autenticação sistemica}

200: OK EC Habilitado com sucesso

{
    "document": "99999999999",
    "success": true
}

403: Forbidden Operação não permitida (Autenticação inválida))

500: Internal Server Error Falha ao habilitar o EC

{
    "document": "99999999999",
    "success": false
}

Exemplo de Request:

PUT /enable/31593345038
Headers:
  Content-Type: application/json
  Authorization: Bearer {Token gerado pela autenticação sistemica}

Exemplo de Reponse:

{
  "status": "200",
  "message": "EC Habilitado com sucesso"
}

Este response indica que o estabelecimento foi habilitado com sucesso e está pronto para operar na plataforma.

---

Desabilitação de Estabelecimento

Introdução:

Caso seja necessário pausar ou encerrar as operações de um estabelecimento na plataforma bemfácil®, o endpoint de desabilitação permite realizar essa ação de forma controlada.

Através do endpoint PUT /disable/{documento}, é possível desabilitar um estabelecimento, interrompendo temporariamente ou permanentemente suas atividades na conta digital bemfácil.

Endpoint: PUT /disable/{documento}

Desabilitar estabelecimento da Conta digital bemfácil

PUT https://stage-api.bemfacil.digital/disable/{documento}

Autenticação entre Sistemas <- Autenticação utilizada para este endpoint

Path Parameters

Name	Type	Description
documento*	String	Documento do EC

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer {Token gerado pela autenticação sistemica}

200: OK EC desabilitado com sucesso

{
    "document": "99999999999",
    "success": true
}

500: Internal Server Error Falha ao desabilitar o EC

{
    "document": "99999999999",
    "success": false
}

403: Forbidden Operação não permitida (Autenticação inválida)

Exemplo de Request:

PUT /disable/31593345038
Headers:
  Content-Type: application/json
  Authorization: Bearer {Token gerado pela autenticação sistemica}

Exemplo de Response:

{
  "status": "200",
  "message": "EC desabilitado com sucesso"
}

Este response confirma que o estabelecimento foi desabilitado conforme solicitado.

---

Consultar Estabelecimentos Cadastrados

A consulta de estabelecimentos permite listar qualquer estabelecimento cadastrado ou filtrar por critérios específicos, como documento, razão social ou nome fantasia.

Endpoint: GET /customer

Listagem de EC da Conta digital bemfácil

GET https://stage-api.bemfacil.digital/customer

Autenticação entre Sistemas <- Autenticação utilizada para este endpoint

Query Parameters

Name	Type	Description
page	Number	Número da página
limit	Number	Limite de registros por página
document	String	Documento do EC
legalName	String	Razão social do EC
fantasyName	String	Nome fantasia do EC

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer {Token gerado pela autenticação sistemica}

200: OK Sucesso

{
    "data": [
        {
            "id": 1,
            "createdAt": "2023-07-17T21:24:43.742Z",
            "updatedAt": "2023-07-17T21:24:43.742Z",
            "document": "59015339000104",
            "legal_name": "CHARLES DESPACHANTE LTDA.",
            "fantasy_name": "CHARLES DESPACHANTE",
            "phone": "[phone]",
            "customer_key": "2302",
            "active": false,
            "email": "[email protected]",
            "responsibleDocument": "59015339000104"
        },
        {
            "id": 2,
            "createdAt": "2023-07-17T21:24:43.742Z",
            "updatedAt": "2023-07-17T21:24:43.742Z",
            "document": "02970067978",
            "legal_name": "ALLAN RICHARD TRENTINI",
            "fantasy_name": "ALLAN RICHARD TRENTINI",
            "phone": "[phone]",
            "customer_key": "2643",
            "active": false,
            "email": "[email protected]",
            "responsibleDocument": "2970067978"
        },
        {
            "id": 6,
            "createdAt": "2023-07-18T15:08:33.804Z",
            "updatedAt": "2023-07-18T17:40:28.889Z",
            "document": "09104373430",
            "legal_name": "DANIEL LIMA DO NASCIMENTO",
            "fantasy_name": "DAN",
            "phone": "12333441255555",
            "customer_key": "9999",
            "active": false,
            "email": "[email protected]",
            "responsibleDocument": "09104373430"
        }
    ],
    "success": true,
    "pagination": {
        "total": 3,
        "pageCount": 1,
        "currentPage": 1,
        "from": 1,
        "to": 3,
        "nextPage": "/customer?page=2&limit=10",
        "previousPage": "/customer?page=1&limit=10"
    }
}

500: Internal Server Error Erro

Exemplo de Request:

GET /customer?page=1&limit=10&document=31593345038
Headers:
  Content-Type: application/json
  Authorization: Bearer {Token gerado pela autenticação sistemica}

Neste exemplo, a requisição busca estabelecimentos utilizando parâmetros de consulta para paginação (page e limit) e filtragem por documento (document). A resposta incluirá uma lista de estabelecimentos que correspondem aos critérios de busca, dentro dos limites de paginação especificados.

Exemplo de Response:

{
  "status": "200",
  "message": "Sucesso",
  "data": [
    {
      "document": "31593345038",
      "legalName": "Nome da Empresa Ltda",
      "fantasyName": "Nome Fantasia da Empresa",
      "phone": "[phone]",
      "customerKey": "12345",
      "email": "[email protected]",
      "status": "Ativo",
      "registrationDate": "2023-01-15"
    },
    {
      "document": "98765432100",
      "legalName": "Outra Empresa Ltda",
      "fantasyName": "Outro Nome Fantasia",
      "phone": "[phone]",
      "customerKey": "67890",
      "email": "[email protected]",
      "status": "Ativo",
      "registrationDate": "2023-02-20"
    }
  ]
}

Este exemplo mostra uma resposta bem-sucedida da API, indicando que a operação de consulta foi realizada com sucesso ("status": "200", "message": "Sucesso"). A resposta inclui um array data contendo os detalhes de cada estabelecimento que corresponde aos critérios de busca.

---

Exclusão de Estabelecimento

A exclusão de um estabelecimento é uma operação sensível que remove permanentemente o estabelecimento e seus dados associados da plataforma, exceto seu extrato. Deve ser usada com cautela.

Cuidado! Este método irá executar duas ações. Apagar o EC do Cognito e remover os dados do Estabelecimento da Conta digital, exceto seu extrato!

Endpoint: DELETE /customer/{documento}

Operação para resetar o EC da conta digital

DELETE https://stage-api.bemfacil.digital/customer/{documento}

Autenticação entre Sistemas <- Autenticação utilizada para este endpoint

Headers

Name	Type	Description
Content-type*	String	application/json
Authorization	String	Bearer {Token gerado pela autenticação sistemica}

200: OK Sucesso na execução

true

500: Internal Server Error Erro na execução

false

Exemplo de Request

DELETE /customer/31593345038
Headers:
  Content-Type: application/json
  Authorization: Bearer {Token gerado pela autenticação sistemica}

Exemplo de Response:

{
  "status": "200",
  "message": "Estabelecimento excluído com sucesso"
}

Este exemplo de response indica que o estabelecimento especificado foi excluído com sucesso da plataforma. A resposta confirma a ação realizada e não inclui dados adicionais, uma vez que se trata de uma operação de exclusão.

---