# Integração API NAPP

# Integração API NAPP

A integração NAPP consulta as vendas registradas no Illimitar em um período. O acesso é feito em duas etapas: primeiro a autenticação, que devolve um token; depois a consulta da lista de vendas, enviando esse token.

<p class="callout info">Os exemplos desta página usam o ambiente de demonstração `https://demonstracao.pdv.moda` e o token de biblioteca `1b8e80a3-b465-44c4-8fb1-67758fd28d15`. No ambiente do cliente, troque os dois pelos valores copiados nas telas abaixo. Toda chamada envia o cabeçalho `X-Requested-With: XMLHttpRequest`.</p>

## Fluxo da integração

<figure id="bkmrk-fluxo-da-integra%C3%A7%C3%A3o-"><figcaption>Fluxo da integração NAPP: autenticar, conferir se o retorno chegou inteiro e só então consultar as vendas.</figcaption><table><thead><tr><th>Etapa</th><th>Chamada</th><th>Retorno que libera a etapa seguinte</th><th>Retorno que não segue adiante</th></tr></thead><tbody><tr><td>1. Autenticar</td><td>`POST /illi/autenticar` com `login`, `senha` e `X-Requested-With: XMLHttpRequest`</td><td>JSON que fecha, `success` `true` e `bearer` com o token inteiro</td><td>Credencial inválida (`success` `false`). Ou JSON cortado, ou `success` `true` sem `bearer`: repetir a autenticação</td></tr><tr><td>2. Consultar vendas</td><td>`GET .../apiNapp/api/getVendas` com as datas, `Authorization: Bearer {bearer}` e `X-Requested-With: XMLHttpRequest`</td><td>JSON que fecha, `success` `true` e `data` como lista. Cada item traz os seis campos da venda</td><td>Período vazio: encerrar sem vendas. Página HTML HTTP 500: voltar à etapa 1. JSON cortado ou item sem um dos seis campos: repetir a consulta e não gravar o pedaço</td></tr></tbody></table>

</figure>## O que copiar antes de chamar a API

<table id="bkmrk-dado-onde-copiar-ond"><thead><tr><th>Dado</th><th>Onde copiar</th><th>Onde entra na chamada</th></tr></thead><tbody><tr><td>Endereço do ambiente</td><td>Barra do navegador, na tela de entrada</td><td>Começo de todas as URLs</td></tr><tr><td>Usuário</td><td>Campo Usuário da tela de entrada</td><td>Campo `login` da autenticação</td></tr><tr><td>Senha</td><td>Senha cadastrada nesse usuário</td><td>Campo `senha` da autenticação</td></tr><tr><td>Token da biblioteca apiNapp</td><td>Sistema, Biblioteca, coluna Token</td><td>Trecho `/bibliotecas/{token}/` da consulta de vendas</td></tr></tbody></table>

## 1. Endereço, usuário e senha

Abra o Illimitar no navegador. O endereço base é o nome do site, antes da primeira barra. Não inclua `/LOGIN` e não deixe barra no final.

No exemplo da coleção, o endereço base é `https://demonstracao.pdv.moda`. No ambiente do cliente, use o endereço que aparecer na barra do navegador.

O usuário e a senha da tela de entrada são os mesmos enviados na autenticação da API. Na grade de usuários, a coluna Usuário é o `login`. A coluna Senha aparece mascarada. A senha da API é a que foi cadastrada nesse usuário.

![](https://kb.illimitar.pro/uploads/images/gallery/2026-10/gemini-generated-image-b0hjhkb0hjhkb0hj.jpg)

Há dois caminhos para abrir a grade de usuários, se precisar conferir o login:

- Campo Acesso Rápido, no canto direito da barra superior: digite `Usuário` e selecione o item.
- Ícone Sistema: no grupo Usuário, clique em Usuário.

## 2. Chave (key) do usuário

A tela abaixo fica no cadastro do usuário de integração. O campo Chave (key), no bloco Acesso API, é a chave desse usuário. O valor que aparece na figura é só um exemplo do ambiente fotografado.

1. Na barra superior, clique no ícone Sistema (engrenagem).
2. Clique em Usuário.
3. Na grade, selecione o usuário da integração. No exemplo, Integração API NAPP.
4. Clique em Configuração.
5. Abra o bloco Acesso API e leia o campo Chave (key).

![](https://kb.illimitar.pro/uploads/images/gallery/2026-10/1-3.png)

<p class="callout warning">A coleção NAPP não envia a Chave (key). Quem libera a lista de vendas é o campo `bearer` devolvido na autenticação. Não cole essa chave no endereço da consulta e não a use no lugar do bearer.</p>

## 3. Token da biblioteca apiNapp

O identificador do caminho `/bibliotecas/{token}/apiNapp/api/getVendas` é o Token da biblioteca apiNapp. Ele muda de um ambiente para outro.

1. No campo Acesso Rápido, digite `Biblioteca` e selecione o item. O outro caminho é o ícone Sistema, grupo Controles do Sistema, botão Biblioteca.
2. Na grade, filtre a coluna Nome por `napp`.
3. Use a linha em que a coluna Arquivo / Classe é `apiNapp` e a coluna Saída é `BIBLIOTECA`.
4. Copie o valor da coluna Token.

Junte as peças neste formato:

```
{endereço base}/bibliotecas/{Token}/apiNapp/api/getVendas
```

Exemplo montado com os dados da coleção de demonstração:

```
https://demonstracao.pdv.moda/bibliotecas/1b8e80a3-b465-44c4-8fb1-67758fd28d15/apiNapp/api/getVendas
```

O período vai no final do endereço, por exemplo `?data_inicio=2024-10-01&data_fim=2024-10-05`.

<p class="callout info">O trecho `1b8e80a3-b465-44c4-8fb1-67758fd28d15` é o Token da biblioteca apiNapp no ambiente da coleção. Em outro ambiente, troque somente esse trecho. O restante do caminho permanece `/bibliotecas/{token}/apiNapp/api/getVendas`.</p>

## Convenções

- Datas no formato `aaaa-mm-dd`. Exemplo: `2024-10-01`.
- A autenticação envia os dados como formulário (`application/x-www-form-urlencoded`), não como JSON.
- Todas as chamadas enviam `X-Requested-With: XMLHttpRequest`.
- A consulta de vendas exige o cabeçalho `Authorization: Bearer {token}`.
- Use o corpo só quando ele chegou inteiro. JSON utilizável abre com `{`, fecha com `}` e um leitor de JSON aceita o texto sem erro.
- As respostas de negócio vêm em JSON. Leia sempre o campo `success` antes de usar `data`.
- A autenticação não usa cookie. O token da resposta é o que libera a consulta seguinte.
- Não há paginação. O período inteiro volta na lista `data`.

## 4. Autenticar

Obtém o token de acesso. Guarde o campo `bearer` da resposta. Ele entra na consulta de vendas.

<table id="bkmrk-%C2%A0-%C2%A0-m%C3%A9todo-post-url-"><thead><tr><th> </th><th> </th></tr></thead><tbody><tr><td>Método</td><td>`POST`</td></tr><tr><td>URL</td><td>`{endereço}/illi/autenticar`</td></tr><tr><td>Corpo</td><td>`application/x-www-form-urlencoded`</td></tr><tr><td>Cabeçalho</td><td>`X-Requested-With: XMLHttpRequest`</td></tr></tbody></table>

### Campos enviados

<table id="bkmrk-campo-obrigat%C3%B3rio-de"><thead><tr><th>Campo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td>`login`</td><td>Sim</td><td>Usuário da tela de entrada, o mesmo da coluna Usuário na grade.</td></tr><tr><td>`senha`</td><td>Sim</td><td>Senha cadastrada nesse usuário.</td></tr></tbody></table>

### Exemplo

Troque `usuario` e `senha` pelos dados da tela de entrada. Troque o endereço se o ambiente não for o de demonstração.

```bash
curl -X POST "https://demonstracao.pdv.moda/illi/autenticar" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Requested-With: XMLHttpRequest" \
  --data "login=usuario&senha=senha"
```

```http
POST /illi/autenticar HTTP/1.1
Host: demonstracao.pdv.moda
Content-Type: application/x-www-form-urlencoded
X-Requested-With: XMLHttpRequest

login=usuario&senha=senha
```

### Sucesso — HTTP 200

Login aceito. O retorno completo traz `success`, `message`, `data` e `bearer`. Copie o `bearer` da aspa de abertura até a aspa de fechamento.

O exemplo gravado na coleção encurtou dois campos: `bearer` aparece como `eyJT` e `xss` como `bWQ.`. Esses pedaços não autenticam. No ambiente real o texto de cada um vem inteiro. `xss` só aparece quando o usuário tem esse dado. `controle` só aparece quando o usuário tem controle. A falta de `xss` ou de `controle` não torna o retorno incompleto. A falta de `bearer`, com `success` `true`, torna: descarte o corpo e autentique de novo.

<details id="bkmrk-json-de-sucesso-%7B-%22s"><summary>JSON de sucesso</summary>

```json
{
    "success": true,
    "message": "Autenticado com sucesso.",
    "data": false,
    "xss": "bWQ.",
    "bearer": "eyJT"
}
```

</details><table id="bkmrk-campo-descri%C3%A7%C3%A3o-succ"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`success`</td><td>`true` quando o login foi aceito.</td></tr><tr><td>`message`</td><td>Texto do resultado. No sucesso: `Autenticado com sucesso.`</td></tr><tr><td>`data`</td><td>Nesta resposta de autenticação o exemplo retorna `false`.</td></tr><tr><td>`bearer`</td><td>Token de acesso. Envie este valor na consulta de vendas.</td></tr><tr><td>`xss`</td><td>Valor devolvido junto com a autenticação. A consulta de vendas usa o campo `bearer`.</td></tr></tbody></table>

<p class="callout success">Guarde o conteúdo de `bearer`. Ele entra no cabeçalho da próxima chamada, no formato `Authorization: Bearer {bearer}`.</p>

### Credencial inválida — HTTP 200

Login ou senha incorretos também respondem HTTP 200. A diferença está no JSON. Não há token nesse retorno. Confira usuário e senha antes de consultar vendas.

<details id="bkmrk-json-de-credencial-i"><summary>JSON de credencial inválida</summary>

```json
{
    "success": false,
    "message": "A credencial informada está incorreta ou é inválida.",
    "data": false,
    "errors": {
        "reason": "A credencial informada está incorreta ou é inválida."
    }
}
```

</details>## 5. Lista de vendas

Retorna as vendas do período informado. Cada item traz filial, identificador da venda, data, valor e os indicadores de troca e cancelamento.

<table id="bkmrk-%C2%A0-%C2%A0-m%C3%A9todo-get-url-%7B"><thead><tr><th> </th><th> </th></tr></thead><tbody><tr><td>Método</td><td>`GET`</td></tr><tr><td>URL</td><td>`{endereço}/bibliotecas/{token}/apiNapp/api/getVendas`</td></tr><tr><td>Autenticação</td><td>`Authorization: Bearer {bearer}`</td></tr><tr><td>Cabeçalho</td><td>`X-Requested-With: XMLHttpRequest`</td></tr></tbody></table>

### Parâmetros de consulta

Os dois parâmetros vão na URL (query string).

<table id="bkmrk-campo-tipo-obrigat%C3%B3r"><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td>`data_inicio`</td><td>texto `aaaa-mm-dd`</td><td>Sim</td><td>Data inicial do período.</td></tr><tr><td>`data_fim`</td><td>texto `aaaa-mm-dd`</td><td>Sim</td><td>Data final do período.</td></tr></tbody></table>

### Exemplo

Substitua `COLE_O_BEARER_AQUI` pelo campo `bearer` da autenticação. Substitua o token da biblioteca e as datas pelo período que você quer consultar.

```bash
curl "https://demonstracao.pdv.moda/bibliotecas/1b8e80a3-b465-44c4-8fb1-67758fd28d15/apiNapp/api/getVendas?data_inicio=2024-10-01&data_fim=2024-10-05" \
  -H "Authorization: Bearer COLE_O_BEARER_AQUI" \
  -H "X-Requested-With: XMLHttpRequest"
```

```http
GET /bibliotecas/1b8e80a3-b465-44c4-8fb1-67758fd28d15/apiNapp/api/getVendas?data_inicio=2024-10-01&data_fim=2024-10-05 HTTP/1.1
Host: demonstracao.pdv.moda
Authorization: Bearer COLE_O_BEARER_AQUI
X-Requested-With: XMLHttpRequest
```

### Sucesso — HTTP 200

`success` fica `true` quando existe ao menos uma venda no período. A mensagem é `Lista de vendas`. Leia o array `data`.

Nesta consulta o cabeçalho `Content-Type` pode vir `text/html; charset=UTF-8` mesmo com o corpo em JSON. Vale o corpo: se ele abre com `{` e fecha com `}`, leia como JSON.

<details id="bkmrk-json-com-vendas-no-p"><summary>JSON com vendas no período</summary>

```json
{
    "success": true,
    "message": "Lista de vendas",
    "data": [
        {
            "CodigoFilial": "3",
            "idVenda": "12122",
            "DataVenda": "2024-10-01",
            "valor": "347",
            "troca": false,
            "cancelado": false
        },
        {
            "CodigoFilial": "3",
            "idVenda": "12125",
            "DataVenda": "2024-10-01",
            "valor": "597",
            "troca": false,
            "cancelado": false
        },
        {
            "CodigoFilial": "3",
            "idVenda": "12131",
            "DataVenda": "2024-10-01",
            "valor": "447",
            "troca": false,
            "cancelado": false
        },
        {
            "CodigoFilial": "3",
            "idVenda": "12132",
            "DataVenda": "2024-10-03",
            "valor": "647",
            "troca": false,
            "cancelado": false
        }
    ]
}
```

</details>### Campos de cada venda

<table id="bkmrk-campo-tipo-no-exempl"><thead><tr><th>Campo</th><th>Tipo no exemplo</th><th>Descrição</th></tr></thead><tbody><tr><td>`CodigoFilial`</td><td>texto</td><td>Código da filial da venda.</td></tr><tr><td>`idVenda`</td><td>texto</td><td>Identificador da venda.</td></tr><tr><td>`DataVenda`</td><td>texto `aaaa-mm-dd`</td><td>Data da venda.</td></tr><tr><td>`valor`</td><td>texto numérico</td><td>Valor da venda. No exemplo vem como texto (`"347"`), não como número JSON.</td></tr><tr><td>`troca`</td><td>booleano</td><td>`true` quando a venda é troca.</td></tr><tr><td>`cancelado`</td><td>booleano</td><td>`true` quando a venda está cancelada.</td></tr></tbody></table>

### Período sem vendas — HTTP 200

Período válido sem movimento também responde HTTP 200, com `success` igual a `false`. Trate esse caso como lista vazia. `data` vem `false`, não como lista vazia (`[]`). O texto de `message` e de `errors.reason` repete o período consultado.

<details id="bkmrk-json-de-per%C3%ADodo-sem-"><summary>JSON de período sem vendas</summary>

```json
{
    "success": false,
    "message": "Nenhum registro encontrado no periodo  2024-10-01 - 2024-10-01",
    "data": false,
    "errors": {
        "reason": "Nenhum registro encontrado no periodo  2024-10-01 - 2024-10-01"
    }
}
```

</details>### Token ausente ou inválido — HTTP 500

Se o token não for enviado, ou se o usuário não estiver autenticado, a chamada devolve uma página HTML inteira, com HTTP 500. Não é um JSON cortado. O título da página é `Ops!`. No corpo visível há o título `SERVIÇO INDISPONÍVEL NO MOMENTO` e o parágrafo `Usuário não autenticado.`

<p class="callout danger">Não interprete esse HTML como lista de vendas. Autentique de novo e repita a consulta com o `bearer` novo. Se o HTTP 500 continuar com token recém-obtido, o serviço está indisponível.</p>

### Corpo que não chegou inteiro

Descarte o corpo e repita a mesma chamada quando acontecer um destes casos:

- O texto parece JSON, mas não fecha com `}`, ou o leitor de JSON recusa o corpo.
- A autenticação traz `success` `true` e o campo `bearer` não veio, veio vazio, ou veio só o pedaço do exemplo (`eyJT`).
- A lista traz `success` `true` e o JSON fechou, mas um item não tem `CodigoFilial`, `idVenda`, `DataVenda`, `valor`, `troca` e `cancelado`. Não grave esse item. Se a lista inteira veio pela metade, repita a consulta do mesmo período.

Uma página que começa com `<!DOCTYPE` ou `<html` é o erro HTTP 500 descrito acima. Trate como falha de autenticação, não como JSON incompleto.

## Ordem de chamada

1. `POST /illi/autenticar` com `login`, `senha` e `X-Requested-With: XMLHttpRequest`.
2. Confirme que o JSON fechou, que `success` é `true` e copie o `bearer` inteiro.
3. `GET .../apiNapp/api/getVendas` com `data_inicio`, `data_fim`, `Authorization: Bearer {bearer}` e `X-Requested-With: XMLHttpRequest`.
4. Se o JSON fechou e `success` for `true`, leia a lista em `data`. Cada item precisa dos seis campos.
5. Se `success` for `false` e a mensagem indicar que não há registro no período, encerre a consulta sem vendas.
6. Se a resposta for a página HTML com HTTP 500 e o parágrafo `Usuário não autenticado.`, renove o token e tente outra vez.
7. Se o JSON não fechar, ou se a autenticação vier sem `bearer`, descarte o corpo e repita a mesma chamada.

## O que fazer em cada retorno

<table id="bkmrk-situa%C3%A7%C3%A3o-http-succes"><thead><tr><th>Situação</th><th>HTTP</th><th>`success`</th><th>O que fazer</th></tr></thead><tbody><tr><td>Login aceito</td><td>200</td><td>`true`</td><td>Usar `bearer` na consulta de vendas.</td></tr><tr><td>Login ou senha inválidos</td><td>200</td><td>`false`</td><td>Corrigir as credenciais. Não há token.</td></tr><tr><td>Vendas encontradas</td><td>200</td><td>`true`</td><td>Ler o array `data`.</td></tr><tr><td>Nenhuma venda no período</td><td>200</td><td>`false`</td><td>Tratar como período vazio. `data` é `false`.</td></tr><tr><td>Token ausente ou inválido</td><td>500</td><td>não há JSON</td><td>Página HTML completa. Título `Ops!`, texto `SERVIÇO INDISPONÍVEL NO MOMENTO` e parágrafo `Usuário não autenticado.` Autenticar de novo.</td></tr><tr><td>Corpo cortado ou `bearer` ausente</td><td>o que chegar</td><td>JSON inválido, ou `true` sem `bearer`</td><td>Descartar e repetir a mesma chamada. Não usar token nem venda pela metade.</td></tr><tr><td>Item de venda sem os seis campos</td><td>200</td><td>`true`</td><td>Não gravar esse item. Se a lista veio pela metade, repetir a consulta do período.</td></tr></tbody></table>