> For the complete documentation index, see [llms.txt](https://integracao.useblu.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integracao.useblu.com.br/varejo-apis/api-movimento-de-vendas.md).

# API Movimento de Vendas

A API de Movimento de Vendas tem como objetivo registrar as vendas que foram realizadas pela máquina de POS da Blu.

Podemos dizer que ela é o primeiro passo para a realização da conciliação uma vez que registrará todas as vendas reconhecidas pela Blu que geraram saldo atual ou agenda na conta Blu. Vale frisar que esta API não registra o pagamento de parcelas, apenas a data em que a operação ocorreu e a previsão de pagamento.

### Orientações

* Os dados devem ser buscados em D-1(O intervalo de datas não pode ser maior que 31 dias). 
* Os dados são carregados todos os dias às 9h, a consulta deve ser feita após esse horário.
* O range de data não deve ser superior a um mês.
* A API registra as vendas feitas no crédito, débito e Link de Pagamento.
* É possível filtrar os resultados pelo *status* da venda.
* É possível filtras vendas canceladas por *range* de data.
* Para ter acesso aos dados, é necessário um `token.` 
* É possível consultar dados de [produção](#movimento-de-vendas-producao) ou [homologação](#movimento-de-vendas-homologacao).
* Para **vendas split** deve ser utilizada a [API Movimento de Vendas Split](/varejo-apis/api-movimento-de-vendas/api-movimento-de-vendas-split.md)

{% hint style="info" %}
Esses parâmetros são disponibilizados pelo time de Integração da Blu quando solicitados pelo executivo de contas.
{% endhint %}

### API

**Fique atento!** para visualizar os exemplos de retornos da API, clique no botão **>** para abrir o campo de leitura

## Movimento de Vendas

<mark style="color:blue;">`GET`</mark> `https://api.blu.com.br/conciliations/sales`

Esta API é responsável por retornar as vendas realizadas na maquininha Blu de acordo com as datas solicitadas a partir de D-1.

**Objetivo**

Possibilitar aos varejistas validar que as vendas realizadas na máquina de POS da Blu foram registrada pelo portal Blu.

<mark style="color:blue;">**Fique atento!**</mark> <mark style="color:blue;">para visualizar os exemplos dos responses abaixo, clique no botão</mark> <mark style="color:blue;"></mark><mark style="color:blue;">**>**</mark> <mark style="color:blue;"></mark><mark style="color:blue;">para abrir o campo de leitura.</mark>

#### Headers

| Name                                                                        | Type   | Description                                                                                                                      |
| --------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| token<mark style="color:red;">\*</mark>                                     | string | Bearer token de identificação do fornecedor                                                                                      |
| begindate                                                                   | string | Data inicial do período no formato AAAA-MM-DD. Não deve ser superior a D-1.                                                      |
| enddate                                                                     | string | Data final do período no formato AAAA-MM-DD. Não deve ser superior a D-1.                                                        |
| nsucode                                                                     | string | Código NSU da Transação (Número Sequencial Único).                                                                               |
| status                                                                      | string | <p>Filtro pelos status da cobrança: confirmed, canceled,                                                                         |
| <br>system\_rejected, pending, antifraud\_analysis, acquirer\_analysis.</p> |        |                                                                                                                                  |
| begindatecancel                                                             | string | **Filtrando pelo status: canceled**. Data inicial do período de cancelamento no formato AAAA-MM-DD. Não deve ser superior a D-1. |
| enddatecancel                                                               | string | **Filtrando pelo status: canceled**. Data final do período de cancelamento no formato AAAA-MM-DD. Não deve ser superior a D-1.   |
| version                                                                     | string | 2                                                                                                                                |

{% hint style="info" %}
O campo `status` é filtrado pelos campos `beginDate` e `endDate` , qualquer um dos status possíveis será filtrado por essa data. Caso nenhum status seja preenchido todos os status possíveis serão retornados.
{% endhint %}

{% hint style="info" %}
Os campos `begindatecancel` e `enddatecancel` devem somente ser utilizados com o campo `status` filtrando cobranças `canceled`. Os campos `beginDate` e `endDate` não devem ser utilizados nesse caso.
{% endhint %}

{% hint style="info" %}
O campo *nsuCode* pode ser utilizado na busca de forma independente a busca por data.
{% endhint %}

**Parâmetros de Query**

| Parâmetro  | Obrigatório | Descrição                                            |
| ---------- | ----------- | ---------------------------------------------------- |
| `page`     | Não         | Página a consultar (ex: 1)                           |
| `per_page` | Não         | Quantidade de registro por página (**máx**: `4000`). |

{% tabs %}
{% tab title="200 Retorno de sucesso" %}
{% tabs %}
{% tab title="OK" %}

```javascript
{
    "page": 1,
    "per_page": 4000,
    "itemsPerPage": 84,
    "total_items": 84,
    "has_more": false,
    "Message": "Quantidade de registros encontrados: 84",
    "Objects": [
        {
            "id_transacao": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "id_venda": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "valor_venda_total_bruto": 2500,
            "valor_venda_total_liquido": 2430.25,
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Token inválido" %}

```json
{
    "Mensage": "Usuário não encontrado para o token informado."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Data inválida" %}

```json
{
    "Mensage": "Não é possível realizar consultas com a data maior ou igual a data de hoje."
}
```

{% endtab %}

{% tab title="200: OK Sem informação para data" %}

```json
{
    "Message": "Nenhuma informação encontrada."
}
```

{% endtab %}

{% tab title="200: OK Sem informação para o NSU" %}

```json
{
    "Message": "Nenhuma informação encontrada."
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
• Os parâmetros *begindate* e *enddate* se referem a data de ocorrência da transação e devem estar ambos preenchidos. Caso nenhum deles seja especificado, a resposta retornará todos os pagamentos realizados antes à data da consulta, ou seja, **D-1**.\
• Se `page` **não** for informado, será considerado **`1`** (primeira página).\
• Se `per_page` **não** for informado, será considerado **`1000`** itens por página.
{% endhint %}

O retorno desta consulta é um arquivo JSON, contendo um conjunto (Array) das transações do período informado. Abaixo vemos todos os campos que serão retornados:

| Campos da transação                   | Descrição                                                            |
| ------------------------------------- | -------------------------------------------------------------------- |
| id\_transacao                         | Identificador da transação dentro da Blu.                            |
| id\_venda                             | Identificador da venda dentro da Blu                                 |
| valor\_venda\_total\_bruto            | Valor bruto da venda.                                                |
| valor\_venda\_total\_liquido          | Valor líquido da venda.                                              |
| valor\_sem\_taxas                     | Valor bruto da parcela.                                              |
| valor\_com\_taxas                     | Valor líquido da parcela.                                            |
| data\_ocorrencia                      | Data de ocorrência da transação no formato AAAA-MM-DD.               |
| data\_liquidacao                      | Data de prevista para liquidação da transação no formato AAAA-MM-DD. |
| data\_criacao                         | Data de criação da transação no portal Blu no formato AAAA-MM-DD.    |
| cod\_autorizacao                      | Código de autorização da transação.                                  |
| tipo\_venda                           | Tipo de venda da transação, sendo débito ou crédito.                 |
| numero\_pos                           | Número do POS que foi efetuada a transação.                          |
| serial\_pos                           | Serial do POS que foi efetuada a transação.                          |
| banco                                 | Banco emissor do cartão que efetuou a transação.                     |
| bandeira                              | Bandeira do cartão que efetuou a transação.                          |
| numero\_cartao                        | Número do cartão que efetuou a transação.                            |
| razao\_social\_cliente\_blu           | Razão social do cliente Blu registrado no POS.                       |
| cnpj\_cliente\_blu                    | CNPJ do cliente Blu registrado no POS.                               |
| cv\_nsu                               | NSU da transação.                                                    |
| status\_transacao\_pos\_ou\_cobranca  | Status da transação.                                                 |
| data\_cancelamento\_pos\_ou\_cobranca | Data do cancelamento da transação no formato AAAA-MM-DD.             |
| parcela                               | Número da parcela da transação.                                      |
| parcelas                              | Número total de parcelas da transação.                               |
| valor\_taxa\_administracao            | Valor da taxa de administração da transação.                         |
| data\_liquidacao\_programada          | Data de prevista para liquidação da transação no formato AAAA-MM-DD. |
| via\_de\_venda                        | Via que a transação foi realizada.                                   |
| data\_atualizacao                     | Data que a transação sofreu atualização no formato AAAA-MM-DD.       |

Abaixo vemos exemplos de retorno da API para uma transações do tipo **crédito** e **débito**:

{% tabs %}
{% tab title="Crédito" %}

<pre class="language-json"><code class="lang-json">{
    "page": 1,
    "per_page": 4000,
    "itemsPerPage": 645,
    "total_items": 645,
    "has_more": false,
    "Message": "Quantidade de registros encontrados: 645",
    "Objects": [
        [
{
                "id_transaction": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "id_venda": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "valor_venda_total_bruto": "0.00",
                "valor_venda_total_liquido": "0.00",
                "valor_sem_taxas": "0.00",
                "valor_com_taxas": "0.00",
                "data_ocorrencia": "aaaa-mm-ddT00:00:00Z",
                "data_liquidacao": "aaaa-mm-ddT00:00:00Z",                
<strong>                "data_criacao": "aaaa-mm-ddT00:00:00Z",
</strong>                "cod_autorizacao": "xxxxxx",
                "tipo_venda": "credit",
                "numero_pos": xxxxxxxxxx,
                "serial_pos": xxxxxxxxxx,
                "banco": "Banco Emissor",
                "bandeira": "Nome da bandeira",
                "numero_cartao": "000000000XXXXXX0000",
                "razao_social_cliente_blu": "Razão Social",
                "cnpj_cliente_blu": "00000000000000",
                "cv_nsu": "000000000000",
                "status_transacao_pos_ou_cobranca": "confirmed",
                "data_cancelamento_pos_ou_cobranca": null,
                "parcela": 0,
                "parcelas": 0,
                "valor_taxa_administracao": "0.00000",
                "data_liquidacao_programada": "aaaa-mm-ddT00:00:00Z",
                "via_de_venda": "via de venda",
                "data_atualizacao": "aaaa-mm-ddT00:00:00Z"     
}
</code></pre>

{% endtab %}

{% tab title="Débito" %}

```json
{
                "id_transaction": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "valor_venda_total_bruto": "0.00",
                "valor_venda_total_liquido": "0.00",
                "valor_sem_taxas": "0.00",
                "valor_com_taxas": "0.00",
                "data_ocorrencia": "aaaa-mm-ddT00:00:00Z",
                "data_liquidacao": "aaaa-mm-ddT00:00:00Z",
                "data_criacao": "aaaa-mm-ddT00:00:00Z",
                "cod_autorizacao": "xxxxxx",
                "tipo_venda": "debit",
                "numero_pos": xxxxxxxxxx,
                "serial_pos": xxxxxxxxxx,
                "banco": "Banco Emissor",
                "bandeira": "Nome da bandeira",
                "numero_cartao": "000000000XXXXXX0000",
                "razao_social_cliente_blu": "Razão Social",
                "cnpj_cliente_blu": "00000000000000",
                "cv_nsu": "000000000000",
                "status_transacao_pos_ou_cobranca": "confirmed",
                "data_cancelamento_pos_ou_cobranca": null,
                "parcela": 0,
                "parcelas": 0,
                "valor_taxa_administracao": "0.00000",
                "data_liquidacao_programada": "aaaa-mm-ddT00:00:00Z",
                "via_de_venda": "via de venda",
                "data_atualizacao": "aaaa-mm-ddT00:00:00Z"
               
}
```

{% endtab %}
{% endtabs %}

O campo *id\_transaction* presente neste retorno será utilizado para relacionar as vendas registradas pela API Movimento de Vendas com a API Débito, Crédito e Antecipações.

O cURL para executar a consulta é o exibido abaixo, bem como a collection com todas as APIs para ser importada no Postman está em anexo na página.

```javascript
curl --location 'https://api.blu.com.br/conciliations/sales' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'begindate: AAAA-MM-DD' \
--header 'enddate: AAAA-MM-DD' \
--header 'nsucode: xxxxxxxxxxxxx' \
--header 'version: 2'
```

## Movimento de Vendas - Homologação

A API Movimento de Vendas pode ser consultada diretamente no [ambiente de produção](#movimento-de-vendas) caso já existam vendas registradas para o CNPJ cadastrado no Portal Blu. Caso ainda não existam vendas é possível realizar a consulta em homologação.

{% hint style="warning" %}
**Atenção!** Os dados retornados na API Movimento de Vendas - Homologação são mockados, anonimizados e sem uso de CNPJs reais. O retorno dessa API só é positivo na data de 01/12/2025, que constará no cURL.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api-hlg.blu.com.br/conciliations/sales`

#### Headers

| Name                                    | Type   | Description                                                                 |
| --------------------------------------- | ------ | --------------------------------------------------------------------------- |
| token<mark style="color:red;">\*</mark> | string | Bearer token de identificação do fornecedor                                 |
| begindate                               | string | Data inicial do período no formato AAAA-MM-DD. Não deve ser superior a D-1. |
| enddate                                 | string | Data final do período no formato AAAA-MM-DD. Não deve ser superior a D-1.   |

{% tabs %}
{% tab title="200 Retorno de sucesso" %}
{% tabs %}
{% tab title="OK" %}

```javascript
{
  "Message": "Quantidade de registros encontrados : 00",
  "Objects": [[{}]]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Token inválido" %}

```json
{
    "Mensage": "Usuário não encontrado para o token informado."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Data inválida" %}

```json
{
    "Mensage": "Não é possível realizar consultas com a data maior ou igual a data de hoje."
}
```

{% endtab %}

{% tab title="200: OK Sem informação para data" %}

```json
{
    "Message": "Nenhuma informação encontrada."
}
```

{% endtab %}

{% tab title="200: OK Sem informação para o NSU" %}

```json
{
    "Message": "Nenhuma informação encontrada."
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Os parâmetros *begindate* e *enddate* se referem a data de ocorrência da transação e devem estar ambos preenchidos. Caso nenhum deles seja especificado, a resposta retornará todos os pagamentos realizados antes à data da consulta, ou seja, **D-1**.
{% endhint %}

O retorno desta consulta é um arquivo JSON, contendo um conjunto (Array) das transações do período informado. Abaixo vemos todos os campos que serão retornados:

| Campos da transação                   | Descrição                                                            |
| ------------------------------------- | -------------------------------------------------------------------- |
| id\_transacao                         | Identificador da transação dentro da Blu.                            |
| id\_venda                             | Identificador da venda dentro da Blu                                 |
| valor\_venda\_total\_bruto            | Valor bruto da venda.                                                |
| valor\_venda\_total\_liquido          | Valor líquido da venda.                                              |
| valor\_sem\_taxas                     | Valor bruto da parcela.                                              |
| valor\_com\_taxas                     | Valor líquido da parcela.                                            |
| data\_ocorrencia                      | Data de ocorrência da transação no formato AAAA-MM-DD.               |
| data\_liquidacao                      | Data de prevista para liquidação da transação no formato AAAA-MM-DD. |
| data\_criacao                         | Data de criação da transação no portal Blu no formato AAAA-MM-DD.    |
| cod\_autorizacao                      | Código de autorização da transação.                                  |
| tipo\_venda                           | Tipo de venda da transação, sendo débito ou crédito.                 |
| numero\_pos                           | Número do POS que foi efetuada a transação.                          |
| serial\_pos                           | Serial do POS que foi efetuada a transação.                          |
| banco                                 | Banco emissor do cartão que efetuou a transação.                     |
| bandeira                              | Bandeira do cartão que efetuou a transação.                          |
| numero\_cartao                        | Número do cartão que efetuou a transação.                            |
| razao\_social\_cliente\_blu           | Razão social do cliente Blu registrado no POS.                       |
| cnpj\_cliente\_blu                    | CNPJ do cliente Blu registrado no POS.                               |
| cv\_nsu                               | NSU da transação.                                                    |
| status\_transacao\_pos\_ou\_cobranca  | Status da transação.                                                 |
| data\_cancelamento\_pos\_ou\_cobranca | Data do cancelamento da transação no formato AAAA-MM-DD.             |
| parcela                               | Número da parcela da transação.                                      |
| parcelas                              | Número total de parcelas da transação.                               |
| valor\_taxa\_administracao            | Valor da taxa de administração da transação.                         |
| data\_liquidacao\_programada          | Data de prevista para liquidação da transação no formato AAAA-MM-DD. |
| via\_de\_venda                        | Via que a transação foi realizada.                                   |
| data\_atualizacao                     | Data que a transação sofreu atualização no formato AAAA-MM-DD.       |

O cURL para executar a consulta já com a data 01/12/2025 é o exibido abaixo, bem como a collection com todas as APIs para ser importada no Postman está em anexo na página com o nome Varejo HLG - Movimento de Vendas ou APIs Varejo HLG.

<pre class="language-javascript"><code class="lang-javascript"><strong>curl --location 'https://api-hlg.blu.com.br/conciliations/sales' \
</strong>--header 'begindate: 2025-12-01' \
--header 'enddate: 2025-12-01' \
--header 'Authorization: XXXXXXXXXXXXXXXXXXXXXXXX' \
</code></pre>

{% file src="/files/SnLaTAK4jK3eQz9NMzWz" %}

{% file src="/files/vWDHYxO1QA08bxaWD267" %}

{% file src="/files/1VO42KThN0lc28dzLVXR" %}

{% file src="/files/B3ARIOs7WpRfCHzWWXbe" %}