> For the complete documentation index, see [llms.txt](https://developer.bemfacil.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.bemfacil.com.br/servicos/conta-bemfacil-r/estabelecimentos.md).

# 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

<mark style="color:green;">`POST`</mark> `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](/servicos/debitos-veiculares/autenticacao-entre-sistemas.md) <- Tipo de autenticação utilizada por este endpoint

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json                                  |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {Token gerado pela autenticação sistemica} |

#### Request Body

| Name                                          | Type   | Description                                                                                                             |
| --------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| document<mark style="color:red;">\*</mark>    | string | Documento do EC ex: 31593345038                                                                                         |
| legalName<mark style="color:red;">\*</mark>   | string | Razão social do EC (Caso seja pessoa física, cadastrar o nome completo)                                                 |
| fantasyName<mark style="color:red;">\*</mark> | string | Nome fantasia do EC (Caso seja pessoa física, cadastrar o nome completo)                                                |
| phone<mark style="color:red;">\*</mark>       | string | Telefone do EC, ex: +5511985140113                                                                                      |
| 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 | <p>Chave pix do cliente Ex: 31593345038 / 77602863000163 /</p><p>+5511985140113 /</p><p><email@bemfacil.com.br> ...</p> |
| email<mark style="color:red;">\*</mark>       | String | email do EC ex: <email@bemfacil.com.br>                                                                                 |
| customerKey<mark style="color:red;">\*</mark> | 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                                                                            |

{% tabs %}
{% tab title="200: OK Estabelecimento criado com sucesso" %}

<pre class="language-json"><code class="lang-json"><strong>[
</strong>    {
        "customerKey": "9999",
        "document": "99999999999",
        "fantasyName": "FULANO NA SILVA",
        "email": "email@bemfacil.com.br",
        "phone": "+5519999999999",
        "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@bemfacil.com.br"
                }
            }
        ]
    }
]
</code></pre>

{% endtab %}

{% tab title="403: Forbidden Operação não permitida" %}

{% endtab %}

{% tab title="200: OK Estabelecimento não criado por falha em uma das etapas " %}

```json
[
    {
        "customerKey": "9999",
        "document": "99999999999",
        "fantasyName": "FULANO NA SILVA",
        "email": "email@bemfacil.com.br",
        "phone": "+5519999999999",
        "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"
                }
            }
        ]
    }
]
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}
{% endtabs %}

#### Exemplo de Request:

```json
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": "+5511985140113",
  "customerKey": "12345",
  "email": "email@bemfacil.com.br",
  "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:

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

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

***

{% hint style="info" %}
**Bom saber:** Os dados do Body, devem ser passados dentro de uma lista \[]
{% endhint %}

***

### Alteração de Estabelecimento

#### **Introdução:**&#x20;

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.

{% hint style="info" %}
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.
{% endhint %}

**Endpoint:** `PUT /customer/{documento}`

## Alteração de estabelecimento da Conta bemfácil

<mark style="color:orange;">`PUT`</mark> `https://stage-api.bemfacil.digital/customer/{documento}`

[Autenticação entre Sistemas](/servicos/debitos-veiculares/autenticacao-entre-sistemas.md) <- Autenticação utilizada para este endpoint

#### Path Parameters

| Name                                       | Type   | Description     |
| ------------------------------------------ | ------ | --------------- |
| document<mark style="color:red;">\*</mark> | String | Documento do EC |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json                                  |
| Authorization<mark style="color:red;">\*</mark> | 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: +5511985140113                                       |
| customerKey | String | ID bemfácil do EC, ex: 12345                                             |

{% tabs %}
{% tab title="200: OK Estabelecimento alterado com sucesso" %}

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

{% endtab %}

{% tab title="500: Internal Server Error Falha ao alterar o estabelecimento" %}

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

{% endtab %}

{% tab title="403: Forbidden Operação não permitida (Autenticação inválida)" %}

{% endtab %}
{% endtabs %}

#### **Exemplo de Request:**

```json
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": "+5511985140222",
  "email": "novoemail@bemfacil.com.br"
}
```

#### Exemplo de Response:

```json
{
  "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:**&#x20;

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

{% hint style="info" %}
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.
{% endhint %}

**Endpoint:** `PUT /enable/{documento}`

## Habilitar estabelecimento da Conta digital bemfácil

<mark style="color:orange;">`PUT`</mark> `https://stage-api.bemfacil.digital/enable/{documento}`

[Autenticação entre Sistemas](/servicos/debitos-veiculares/autenticacao-entre-sistemas.md) <- Autenticação utilizada para este endpoint

#### Path Parameters

| Name                                        | Type   | Description     |
| ------------------------------------------- | ------ | --------------- |
| documento<mark style="color:red;">\*</mark> | String | Documento do EC |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json                                  |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {Token gerado pela autenticação sistemica} |

{% tabs %}
{% tab title="200: OK EC Habilitado com sucesso" %}

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

{% endtab %}

{% tab title="403: Forbidden Operação não permitida (Autenticação inválida))" %}

{% endtab %}

{% tab title="500: Internal Server Error Falha ao habilitar o EC" %}

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

{% endtab %}
{% endtabs %}

**Exemplo de Request:**

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

#### Exemplo de Reponse:

```json
{
  "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:**&#x20;

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.

{% hint style="info" %}
Através do endpoint `PUT /disable/{documento}`, é possível desabilitar um estabelecimento, interrompendo temporariamente ou permanentemente suas atividades na conta digital bemfácil.
{% endhint %}

**Endpoint:** `PUT /disable/{documento}`

## Desabilitar estabelecimento da Conta digital bemfácil

<mark style="color:orange;">`PUT`</mark> `https://stage-api.bemfacil.digital/disable/{documento}`

[Autenticação entre Sistemas](/servicos/debitos-veiculares/autenticacao-entre-sistemas.md) <- Autenticação utilizada para este endpoint

#### Path Parameters

| Name                                        | Type   | Description     |
| ------------------------------------------- | ------ | --------------- |
| documento<mark style="color:red;">\*</mark> | String | Documento do EC |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json                                  |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {Token gerado pela autenticação sistemica} |

{% tabs %}
{% tab title="200: OK EC desabilitado com sucesso" %}

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

{% endtab %}

{% tab title="500: Internal Server Error Falha ao desabilitar o EC" %}

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

{% endtab %}

{% tab title="403: Forbidden Operação não permitida (Autenticação inválida)" %}

{% endtab %}
{% endtabs %}

#### Exemplo de Request:

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

#### Exemplo de Response:

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

<mark style="color:blue;">`GET`</mark> `https://stage-api.bemfacil.digital/customer`

[Autenticação entre Sistemas](/servicos/debitos-veiculares/autenticacao-entre-sistemas.md) <- 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<mark style="color:red;">\*</mark>  | String | application/json                                  |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {Token gerado pela autenticação sistemica} |

{% tabs %}
{% tab title="200: OK Sucesso" %}

```json
{
    "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": "+5519997210705",
            "customer_key": "2302",
            "active": false,
            "email": "financeiro@charlesdespachante.com.br",
            "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": "+5547992783630",
            "customer_key": "2643",
            "active": false,
            "email": "trentini.details@gmail.com",
            "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": "daniel.nascimento@bemfacil.com.br",
            "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"
    }
}
```

{% endtab %}

{% tab title="500: Internal Server Error Erro" %}

{% endtab %}
{% endtabs %}

#### Exemplo de Request:

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

{% hint style="info" %}
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.
{% endhint %}

#### Exemplo de Response:

```json
{
  "status": "200",
  "message": "Sucesso",
  "data": [
    {
      "document": "31593345038",
      "legalName": "Nome da Empresa Ltda",
      "fantasyName": "Nome Fantasia da Empresa",
      "phone": "+5511985140113",
      "customerKey": "12345",
      "email": "email@bemfacil.com.br",
      "status": "Ativo",
      "registrationDate": "2023-01-15"
    },
    {
      "document": "98765432100",
      "legalName": "Outra Empresa Ltda",
      "fantasyName": "Outro Nome Fantasia",
      "phone": "+5511987654321",
      "customerKey": "67890",
      "email": "contato@outraempresa.com.br",
      "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.

{% hint style="warning" %}
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!
{% endhint %}

**Endpoint:** `DELETE /customer/{documento}`

## Operação para resetar o EC da conta digital

<mark style="color:red;">`DELETE`</mark> `https://stage-api.bemfacil.digital/customer/{documento}`

[Autenticação entre Sistemas](/servicos/debitos-veiculares/autenticacao-entre-sistemas.md) <- Autenticação utilizada para este endpoint

#### Headers

| Name                                           | Type   | Description                                       |
| ---------------------------------------------- | ------ | ------------------------------------------------- |
| Content-type<mark style="color:red;">\*</mark> | String | application/json                                  |
| Authorization                                  | String | Bearer {Token gerado pela autenticação sistemica} |

{% tabs %}
{% tab title="200: OK Sucesso na execução" %}

```json
true
```

{% endtab %}

{% tab title="500: Internal Server Error Erro na execução" %}

```json
false
```

{% endtab %}
{% endtabs %}

#### Exemplo de Request

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

#### Exemplo de Response:

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

{% hint style="info" %}
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.
{% endhint %}

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.bemfacil.com.br/servicos/conta-bemfacil-r/estabelecimentos.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.