VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/PDV e terminal de balcão

Login do caixa

Confere o e-mail e a senha do operador do terminal e devolve o perfil, as formas de pagamento e de envio da loja e um token de acesso.

É a primeira chamada do terminal depois de ligado. O caixa (operador) digita e-mail e senha; o terminal manda os dois para cá. Se estão certos, a resposta traz tudo que o terminal precisa para montar a tela de venda: os dados do operador, as formas de pagamento, as formas de envio, a empresa (seller) do operador e um access_token.

O login aceita os dois jeitos de mandar os dados porque os terminais instalados se dividem: GET com user_login e password na query, ou POST com os mesmos campos em JSON (application/json) ou em formulário. Se a query estiver incompleta, o servidor lê o corpo. Evite o GET em produção: a senha vai na URL e fica em logs.

O login também exige credencial de API

Esta rota não é pública. O servidor autentica a chamada antes de chegar ao login, então o terminal precisa mandar Authorization: Basic e-mail:chave_de_api (ou Bearer <JWT>) mesmo nesta chamada. Sem isso a resposta é 401 Authentication required..., e a senha do caixa nem é lida. O que o pos_login valida é a pessoa que opera o terminal; a credencial do cabeçalho identifica o terminal.

POST/api/v1.0/pos_loginAutenticada

Venddor 1.0: login do caixa (corpo JSON ou formulário)

Mesmas regras de GET, com as credenciais no corpo. Ids em UUID. Nomes alternativos em Nomes alternativos do login.

Cabeçalhos

Authorizationstringobrigatório
Basic base64(e-mail:chave_de_api) ou Bearer <JWT> do terminal.
Content-Typestring
application/json para corpo JSON; qualquer outro valor é lido como formulário (application/x-www-form-urlencoded ou multipart).

Corpo da requisição

user_loginstringobrigatório
E-mail do caixa.
passwordstringobrigatório
Senha do caixa.
GET/api/v1.0/pos_loginAutenticada

Venddor 1.0: login do caixa (parâmetros na URL)

Faz o mesmo que o POST, com user_login e password na query string. Mantido porque os exemplos da documentação antiga usam GET.

Parâmetros de consulta

user_loginstringobrigatório
E-mail do caixa.
passwordstringobrigatório
Senha do caixa. Vai na URL: prefira o POST.
POST/api/pos_loginAutenticada

Login do caixa, forma sem versão (ids decimais)

Igual a POST /api/v1.0/pos_login, mas os ids da resposta (user_id e vendor_id, company_id) saem como números decimais em string. Os payment_id e shipping_id das listas continuam UUID.

Corpo da requisição

user_loginstringobrigatório
E-mail do caixa.
passwordstringobrigatório
Senha do caixa.
GET/api/pos_loginAutenticada

Login do caixa por GET, forma sem versão (ids decimais)

Igual a GET /api/v1.0/pos_login, com ids decimais na resposta.

Parâmetros de consulta

user_loginstringobrigatório
E-mail do caixa.
passwordstringobrigatório
Senha do caixa.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1.0/pos_login" \
  -u "$TERMINAL_EMAIL:$TERMINAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_login":"caixa@minhaloja.com.br","password":"senha-do-caixa"}'

Resposta

200Login aceito
json
{
  "status": 200,
  "data": {
    "success": true,
    "message": "",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "agent_info": {
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "user_info": {
        "email": "caixa@minhaloja.com.br",
        "firstname": "Carla",
        "lastname": "Nunes",
        "phone": "11955550000",
        "manager_id": "",
        "ec_user_level": "",
        "manager_discount_limit": ""
      }
    },
    "balance": "0.00",
    "payment_methods": [
      { "payment_id": "02000000-0000-0000-0000-000000000001", "payment": "PIX", "payment_code": "pix", "processor_type": "online", "position": 1, "status": "A" },
      { "payment_id": "02000000-0000-0000-0000-000000000010", "payment": "Pagamento na Entrega (COD)", "payment_code": "pagamento-na-entrega", "processor_type": "offline", "position": 10, "status": "A" }
    ],
    "shipping_methods": [
      { "shipping_id": "50000000-0000-0000-0000-000000000002", "shipping": "Entrega Expressa", "code": "express", "position": 1, "status": "A" }
    ],
    "usergroups": [],
    "company_details": {
      "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "company": "Loja Centro",
      "company_name": "Loja Centro",
      "email": "centro@minhaloja.com.br",
      "phone": "1133334444",
      "address": "Avenida Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01310-100",
      "country": "BR"
    },
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "allowed_destination_ids": [],
    "notes_length": 0,
    "extra": {
      "primary_currency": "BRL",
      "secondary_currency": "",
      "allowed_currencies": ["BRL"],
      "current_currency_data": { "code": "BRL", "symbol": "R$" },
      "allow_selling_without_limit": "N",
      "company_details": { "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "company": "Loja Centro" }
    }
  }
}
200Senha errada (também é HTTP 200)
json
{ "status": 200, "data": { "success": false, "message": "Incorrect login or password" } }

Campos da resposta

statusinteger
Sempre 200.
data.successboolean
true quando o login foi aceito. Leia este campo, não o HTTP.
data.messagestring
Vazio no sucesso; o motivo da falha (em inglês) no erro.
data.access_tokenstring
JWT do caixa. Use como Authorization: Bearer ... nas chamadas seguintes (vale só para rotas que o perfil do caixa pode acessar).
data.agent_info.user_idstring
Id do usuário caixa (UUID em /api/v1.0, decimal em /api).
data.agent_info.user_infoobject
email, firstname, lastname, phone do operador. manager_id, ec_user_level e manager_discount_limit vêm sempre como string vazia (a plataforma não os preenche).
data.balancestring
Sempre "0.00". Não reflete a conta-corrente do representante.
data.payment_methodsarray
Formas de pagamento cadastradas na loja: payment_id (UUID), payment (nome), payment_code (o código que o fechamento espera em payment_info.payment_type), processor_type (online, offline, invoiced), position e status (A ativa). A lista é a da loja, igual para todos os operadores.
data.shipping_methodsarray
Formas de envio: shipping_id (UUID), shipping (nome), code, position, status.
data.usergroupsarray
Sempre vazia.
data.company_detailsobject
Empresa (seller) à qual o operador está ligado: company_id, company, company_name, email, phone, address, city, state, zipcode, country. Objeto vazio {} se o operador não é de nenhum seller.
data.vendor_idstring
Id do seller do operador, ou string vazia.
data.allowed_destination_idsarray
Sempre vazia.
data.notes_lengthinteger
Sempre 0.
data.extraobject
Moeda (primary_currency BRL, allowed_currencies, current_currency_data com code e symbol), allow_selling_without_limit ("N") e uma cópia de company_details.

Erros

Os problemas do login voltam com HTTP 200 e data.success: false:

data.messageQuando
Required params missing: user_login, passwordUm dos dois campos não veio (nem na query nem no corpo).
Incorrect login or passwordE-mail inexistente ou senha errada.
User not foundA autenticação passou, mas o cadastro do usuário não foi encontrado.
Account is not activeA conta do caixa não está ativa.

Os erros de credencial do terminal usam o formato simples da API 1.0, sem o envelope:

StatusQuandoCorpo
401Sem Authorization{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}
401Chave de API inválida{"message":"Invalid credentials","status":401}
401JWT inválido ou expirado{"message":"Invalid or expired token","status":401}
Guarde a lista de pagamentos

O payment_code de cada forma de pagamento é o texto que o fechamento da venda espera em payment_info.payment_type. Salve a lista no terminal e mostre os nomes (payment) ao caixa.

Veja também

  • Produtos e clientes
  • Fechar a venda
  • Nomes alternativos do login
Anterior
PDV e terminal de balcão
Próxima
Produtos e clientes do PDV
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também