API: quem o token é quando entra (usuário, loja e permissões)

Esta fonte responde uma pergunta só, e é a que está por trás das duas queixas mais caras de quem integra: "a API funciona, mas não vem tudo" e "deu 403 sem motivo". As duas têm a mesma origem. A API não é um usuário à parte. Quando ela entra, ela vira um usuário do seu ERP, em uma loja do seu ERP, e passa a obedecer exatamente às regras daquele usuário.

O QUE É O APLICATIVO API
No catálogo de aplicativos do ERP este item aparece como API, com o resumo "Integração com seu app via API, acessível de qualquer lugar" (há uma linha para a modalidade ERP e outra para FIS). É onde ficam as chaves de API da empresa, cada uma com o seu Access Token e Secret Access Token, para você ligar o seu sistema ao ERP. Tudo o que esta fonte diz sobre "o token" vale para cada chave separadamente: cada chave é um token.

COMO A CHAMADA SE IDENTIFICA
Toda chamada envia dois códigos em cabeçalhos: access-token e secret-access-token. A API procura o token pelo par exato dos dois. Falta um, ela responde 401 dizendo qual faltou. O par não existe, ela responde 401 "Access Token e/ou Secret Access Token incorreto(s)!". Esses dois códigos valem como senha: não cole em chamado, e-mail ou conversa de suporte.

QUEM É O USUÁRIO DA API
O token pode ter um usuário gravado nele. Se tiver, é esse o usuário da chamada. Se não tiver, a API entra como o usuário MASTER da empresa. Não há meio termo: ou é o usuário do token, ou é o master.
Daí em diante a requisição inteira roda como esse usuário. Tudo que vem a seguir (IP, horário, loja, permissão, filtro de registros) é lido do cadastro dele no ERP.

QUAL LOJA A API ENXERGA
Mesma lógica. Se o token tem uma loja gravada, é aquela. Se não tem e você também não informou nada, a API escolhe sozinha, e a ordem de escolha começa pela MATRIZ. Por isso uma integração que "só traz dados de uma loja" quase sempre está entrando na matriz sem saber.
Em qualquer caso, a loja precisa estar vinculada ao usuário da chamada. Se não estiver, a resposta é 401 "Loja inválida!" — mesmo que a loja exista e esteja ativa.
Para ver o que o usuário do token enxerga, chame GET /api/lojas. Ele devolve as lojas vinculadas a esse usuário, com id e nome. Detalhe importante: essa própria listagem depende da permissão de listar lojas do usuário — sem ela, em vez da lista vem 403.

OS PARÂMETROS ?usuario_id= E ?loja_id=
Você pode mandar ?usuario_id= e ?loja_id= para trocar quem entra e onde entra. Mas existe uma regra de precedência que explica muito chamado: o que estiver gravado no token vence. Se o token já tem usuário, o ?usuario_id= é ignorado. Se o token já tem loja, o ?loja_id= é ignorado. Os parâmetros só têm efeito quando o token não tem aquilo gravado.

A ORDEM DA ENTRADA
A API valida nesta ordem: token (inclusive a validade da chave, quando ela tem uma), usuário, IP, horário e dia, loja, plano. A permissão do método é checada depois, já dentro do recurso que você chamou. Por isso "Loja inválida!" aparece antes de qualquer 403 de permissão — se você recebeu 401 de loja, a permissão nem chegou a ser avaliada.

AS TRÊS TRAVAS QUE VÊM DO CADASTRO DO USUÁRIO
Depois de identificar o usuário, a API aplica as mesmas travas que o ERP aplica na tela. A mensagem literal diz qual foi:
1. "Este usuário não está habilitado ao acesso por este IP!" — o usuário tem lista de IPs liberados no ERP e o IP de onde a chamada saiu não está nela. Se o usuário não tem nenhum IP cadastrado, essa trava não se aplica.
2. "Este usuário não está habilitado ao acesso neste horário!" — a chamada caiu fora do horário de entrada e saída do usuário, dentro do intervalo de almoço dele, ou em um dia da semana que não está nos dias de acesso.
3. "Este usuário não possui permissão para acessar este método!" — o usuário não tem permissão naquele módulo para aquela ação. A verificação é por ação: listar, visualizar, adicionar, editar e deletar são checadas separadamente (ler pode estar liberado e gravar não), e alguns recursos checam ainda ações próprias — nota fiscal, por exemplo, checa permissão para enviar e para cancelar.
O caso clássico é o segundo: a integração roda de madrugada e o usuário tem horário até as 18h. A API não abre exceção para robô.

CUIDADO: NEM TODO 403 É PERMISSÃO DE USUÁRIO
Estas três não são as únicas respostas 403 da API. Vários recursos respondem 403 com "ID não encontrado." quando o id enviado não existe ou não está visível para aquele usuário, e há endpoints com mensagem própria (o dashboard, por exemplo, responde 403 "Sem acesso aos gráficos"). Regra prática: leia a mensagem, não o número. E existem bloqueios que nem são 403 — passar do limite de requisições do seu token devolve 429 com os limites escritos na própria mensagem, e plano vencido devolve 401.

O ERRO QUE NÃO É ERRO: 200 COM MENOS DADOS
Este é o mais silencioso e o que mais gera retrabalho. Duas permissões do ERP não bloqueiam a chamada, elas filtram os registros:
liberado_usuario — sem ela, o usuário só vê os registros ligados a ele. Em clientes, aqueles em que ele é o vendedor. Em pedidos, vendas, orçamentos e ordens de serviço, aqueles em que ele é o usuário ou o vendedor; nas ordens de serviço, também aquelas em que ele é o técnico ou participa como técnico auxiliar.
liberado_loja — sem ela, e quando a empresa tem mais de uma loja ativa, o usuário só vê os registros das lojas vinculadas a ele.
Nas listagens a resposta vem com código 200 e status de sucesso. Não há mensagem de erro, não há aviso. Só vêm menos registros. Se a listagem ficar sem nada, a resposta ainda é 200, com uma mensagem do tipo "Nenhum cliente foi encontrado!". Já quando você busca um registro específico pelo id e ele está fora desse filtro, a resposta muda: em clientes vem 400 com "Você não possui permissão para acessar este cliente!". É por isso que "a API não traz tudo" costuma ser permissão, e não falha de integração.

ORDEM PARA DIAGNOSTICAR
1. Descubra qual usuário o token representa. Se o token não tem usuário gravado, é o master.
2. Chame GET /api/lojas e veja quais lojas esse usuário enxerga.
3. Compare com o ERP: entre com esse mesmo usuário na tela e faça a mesma consulta. Se na tela também falta, o problema é permissão, não é a API.
4. Confira no grupo desse usuário as permissões do módulo, inclusive liberado_usuario e liberado_loja.
5. Só depois disso investigue filtros, período e paginação da sua consulta.

O QUE COSTUMA DAR ERRADO
Mandar ?loja_id= e nada mudar. Causa: o token tem loja gravada, e ela vence o parâmetro.
Integração trazendo só a matriz. Causa: nenhuma loja informada e nenhuma gravada no token, então a escolha automática começa pela matriz.
401 "Loja inválida!" com uma loja que existe. Causa: o usuário da chamada não está vinculado àquela loja.
403 só de madrugada, ou só aos domingos, ou sempre no mesmo intervalo do dia. Causa: horário e dias de acesso do usuário.
403 que aparece depois de uma mudança no ERP. Causa: alguém mexeu no grupo de permissões do usuário. A API sente na hora.
403 "ID não encontrado." em um registro que você sabe que existe. Causa: quase sempre o registro não está visível para o usuário da chamada — veja liberado_usuario e liberado_loja antes de suspeitar do id.
Faltando registros antigos ou de outros vendedores. Causa: liberado_usuario.
Faltando registros de outras lojas. Causa: liberado_loja.
Desativou o usuário no ERP e a integração continuou respondendo. A checagem de usuário ativo não acontece na entrada da API. Para cortar acesso, trate as permissões do usuário e o token.

ONDE ISSO SE RESOLVE
Nada disso se resolve dentro do aplicativo API. Usuário, grupo de usuários, permissões, lista de IPs, horário e dias de acesso, e o vínculo do usuário com as lojas são cadastros do ERP, e é lá que se ajustam. Vale notar: mesmo quando você abre essas telas a partir do aplicativo API, elas não são telas próprias dele — usuários, grupos de usuários, permissões e lojas caem nas telas do próprio ERP. Consulte as fontes do ERP sobre cadastro de usuário e permissões para o passo a passo; esta fonte só explica o efeito de cada uma delas na API.