Autenticação

A API v1 usa tokens pessoais do Laravel Sanctum. Toda requisição pública desta referência deve enviar o token no header Authorization com o prefixo Bearer.

Perigo

Um token permite agir com as permissões da conta que o criou. Trate-o como uma senha: não o inclua em código-fonte, URLs, capturas de tela, logs ou mensagens de suporte.

Criar um token

Os tokens são criados no painel Paylog, não por chamada de API — não existe endpoint público que emita, renove ou liste tokens.

Acesse Tokens de Acesso API, selecione Criar Token, informe um nome que identifique a integração — como ERP produção, entre 3 e 255 caracteres — e confirme em Criar Token.

O valor completo é exibido uma única vez após a criação. Copie-o antes de fechar a janela.

Observação

A tela Tokens de Acesso API exige a permissão gerenciar_token_api na conta. Sem ela o acesso a /ferramentas/api é negado com 403; peça a habilitação ao titular da conta ou ao suporte.

Importante

Copie o token antes de fechar a janela. A Paylog armazena somente o hash e não consegue exibir novamente o valor original. Se ele for perdido, exclua-o e crie outro.

Enviar o token

bash

curl --request GET \
  --url 'https://ev.paylog.cash/api/v1/clientes' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

http

GET /api/v1/clientes HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN

php

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.paylog.token'))
    ->acceptJson()
    ->get('https://ev.paylog.cash/api/v1/clientes');

javascript

const response = await fetch('https://ev.paylog.cash/api/v1/clientes', {
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${process.env.PAYLOG_API_TOKEN}`,
  },
});

Headers

Header	Presença	Enviado em	Descrição
`Authorization`	Obrigatório	Sempre	`Bearer`, um espaço e o token completo.
`Accept`	Obrigatório	Sempre	Use `application/json`.
`Content-Type`	Condicional	Requisições com corpo	Use `application/json`.

jsonc

{
  "Authorization": "Bearer SEU_TOKEN", // Obrigatório e enviado em todas as chamadas.
  "Accept": "application/json",         // Obrigatório para respostas JSON consistentes.
  "Content-Type": "application/json"   // Condicional: somente quando há corpo JSON.
}

Permissões da conta

O token não amplia o acesso do usuário. Tokens criados no painel não têm escopo próprio — o que delimita o acesso são as permissões da conta que o criou. Além de autenticar, os endpoints de clientes, produtos, pacotes e pedidos verificam essas permissões a cada chamada.

Recurso	Permissões possíveis	Quando necessárias
Clientes	`listar_cliente_api`, `criar_cliente_api`, `editar_cliente_api`	Conforme a operação documentada em Clientes.
Produtos	`listar_produtos_api`	Listagem e consulta individual.
Pacotes	`listar_pacote_api`	Listagem e consulta individual.
Pedidos	`listar_pedido_api`, `criar_pedido_api`, `editar_pedido_api`	Conforme a operação documentada em Pedidos.
Frete	Nenhuma permissão adicional	Qualquer token válido pode usar `/frete/calcular`.

Observação

Funcionários vinculados a um produtor acessam somente os dados permitidos pela conta do produtor. Os endpoints não aceitam um user_id para trocar o contexto da requisição.

Respostas de autenticação

Token ausente ou inválido

401

json

{
  "message": "Unauthenticated."
}

jsonc

{
  "message": "Unauthenticated." // Sempre presente nesta resposta: o token não autenticou a chamada.
}

Usuário sem permissão

403

O corpo pode variar conforme a permissão negada. Trate o status HTTP 403 como contrato: o token é válido, mas a conta não pode executar aquela operação.

Situação	HTTP	Ação recomendada
Header `Authorization` ausente	`401`	Enviar `Bearer SEU_TOKEN`.
Token incorreto, revogado ou expirado	`401`	Substituir por um token ativo.
Conta sem a permissão da rota	`403`	Solicitar a habilitação da permissão.
Registro pertencente a outra conta	Depende do recurso	Conferir o ID no contexto do produtor autenticado. Cada recurso responde exatamente como responderia a um ID inexistente, sem revelar dados de outra conta: clientes e pedidos retornam `401`, pacotes retorna `404` e produtos retorna `204`.

Validade, rotação e revogação

Os tokens criados atualmente não têm expiração automática. Eles permanecem válidos até serem excluídos, a conta perder acesso ou uma política futura definir uma expiração explícita.

Crie um novo token com nome identificável.
Atualize sua integração e confirme uma chamada com sucesso.
Exclua o token antigo em Tokens de Acesso API.

Dica

Use um token por sistema ou ambiente. Isso permite revogar uma integração sem interromper as demais e facilita identificar a última utilização no painel.

#Criar um token

#Enviar o token

#Headers

#Permissões da conta

#Respostas de autenticação

#Token ausente ou inválido

#Usuário sem permissão

#Validade, rotação e revogação