Pular para conteúdo

Visão geral da API Telvora

Base: /api/v1
OpenAPI: packages/openapi/openapi.v1.yaml
Rotas: apps/api/routes/api.php
Atualizado: 2026-09-13

Autenticação

A maior parte dos endpoints exige Bearer Token (Laravel Sanctum).

  1. POST /api/v1/auth/login com credenciais → recebe token.
  2. Envie em todas as chamadas autenticadas:
Authorization: Bearer <token>
Method Path Permissão Descrição
POST /auth/login — (público) Login do painel; retorna token
GET /auth/me autenticado Usuário atual e contexto
GET /auth/accessible-branches organization.company.read Filiais acessíveis
POST /auth/logout autenticado Invalida o token
POST /auth/change-password autenticado Troca de senha
GET /health — (público) Saúde do serviço

Outros logins (fora do escopo principal do painel): POST /portal/auth/login, POST /tv/auth/validate, POST /learning/auth/validate.

Headers de tenant / filial

Após autenticar, a API resolve empresa e filial pelo middleware SetTenantContext. Envie:

Header Obrigatório Descrição
Authorization Sim (rotas autenticadas) Bearer <token>
X-Company-Id Sim (quando multi-empresa) ID da empresa
X-Branch-Id Sim (operações por filial) ID da filial ativa
X-Request-Id Opcional Correlação; a API também pode devolver

Sem X-Branch-Id / X-Company-Id válidos, rotas que isolam por tenant/filial retornam erro de contexto ou 403.

Permissões

  • Cada rota autenticada tipicamente declara EnsurePermission::class.':<chave>'.
  • A chave segue o padrão dominio.recurso.acao (ex.: purchasing.order.release).
  • Usuário precisa ter a permissão no grupo vinculado (IAM).
  • Em algumas rotas, várias chaves separadas por | significam OU (basta uma).

Liste permissões disponíveis via:

Method Path Permissão Descrição
GET /roles/permissions iam.role.read Catálogo de permissões
GET /roles iam.role.read Grupos
PATCH /roles/{id} iam.role.update Atualiza permissões do grupo

Organização (empresa / filial)

Method Path Permissão Descrição
GET /company organization.company.read Dados da empresa
PATCH /company organization.company.update Atualiza empresa
POST /company/logo organization.company.update Upload logo empresa
GET /branches organization.branch.read Lista filiais
POST /branches organization.branch.create Cria filial
GET /branches/{id} organization.branch.read Detalhe
PATCH /branches/{id} organization.branch.update Atualiza
POST /branches/{id}/logo organization.branch.update Logo da filial (relatórios/NF)
POST /branches/{id}/certificate organization.branch.update Certificado A1
GET/POST/PATCH /branches/{branchId}/document-numbers organization.branch.read / update Numeração fiscal

Boas práticas

  • Trate X-Request-Id nos logs do cliente.
  • Operações críticas (liberar pedido, transmitir NFCom, fechar folha) são auditadas — consulte /audit-logs.
  • Para o contrato completo de request/response, use o OpenAPI; esta wiki não substitui o schema.
  • Wiki do operador (telas): 23-WIKI/.

Referências