API Turron Acesso · Documentação

Seguro por padrãoOAuth 2.0 client credentials, tokens de 15 minutos e escopos por rota.

Dados só da sua empresaA credencial pode ser da instalação inteira ou de uma empresa só. A API nunca devolve dados de outra empresa.

Resumo, sintético e analíticoTotal por refeição, consumo por usuário e cada passagem na catraca, com quantidade e valor.

Limites claros120 requisições por minuto por credencial, período de até 31 dias por consulta.

Início rápido

Em três passos você faz a primeira consulta.

Receba a credencial da sua instalação (client_id e client_secret) com a equipe Turron.
Gere um token em POST /oauth/token. Ele vale 15 minutos.
Consulte GET /v1/refeicoes/resumo enviando o token no header Authorization: Bearer.

cURL · 1. gerar token

curl -X POST https://controledeacesso.turron.com.br/api/oauth/token \
  -u "SEU_CLIENT_ID:SEU_CLIENT_SECRET" \
  -d grant_type=client_credentials

cURL · 2. consultar

curl "https://controledeacesso.turron.com.br/api/v1/refeicoes/resumo?dataInicio=2026-10-01&dataFim=2026-10-31" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

Credenciais e empresas

Uma credencial é formada por:

Campo	Descrição
`client_id`	Identificador público da credencial. Ex.: `tac_10015_002b7960c4d8`.
`client_secret`	Senha da credencial. Use só no back-end, nunca em aplicativo, navegador ou repositório de código.

Uma instalação (refeitório) atende várias empresas. Por isso existem dois tipos de credencial:

Tipo	O que enxerga	Para quem
Geral	Todas as empresas da instalação. Pode filtrar uma com `codigoEmpresa`.	Quem administra o refeitório.
Empresa	Só as passagens dos usuários daquela empresa, em todas as rotas.	Cada empresa cliente do refeitório.

Na credencial de empresa, o filtro é aplicado pela própria API: passar outro codigoEmpresa não traz dados de outra empresa (a resposta vem vazia). As respostas trazem instalacao.empresa com a empresa da credencial.

Vazou o secret? Peça um novo à equipe Turron. O secret antigo para de funcionar na hora e todos os tokens gerados com ele são revogados.

Autenticação

A API usa OAuth 2.0 Client Credentials (RFC 6749 §4.4). Troque a credencial por um token de acesso e envie o token em todas as rotas /v1:

Header

Authorization: Bearer SEU_ACCESS_TOKEN

O token vale 15 minutos (expires_in: 900). Reutilize-o até perto de expirar, em vez de gerar um por chamada.
Ao receber 401, gere um novo token e repita a chamada uma única vez.
5 tentativas com secret errado bloqueiam a credencial por 15 minutos.
Tokens podem ser revogados pela Turron (troca de secret ou desativação da instalação).

Escopos

Escopo	Permite
`refeicoes:leitura`	Consultar refeições (quantidade e valor).
`usuarios:leitura`	Consultar usuários.
`usuarios:escrita`	Cadastrar, alterar e desligar usuários.

Sem o escopo exigido pela rota, a resposta é 403.

Postman

A coleção já vem com as requisições prontas e um script que guarda o token sozinho.

Baixe a coleção e importe no Postman (Ctrl + O).
Na coleção, aba Variables, preencha client_id e client_secret e salve.
Rode Gerar token e depois Refeicoes - resumo por periodo.

POST/oauth/tokenPúblico

Gera um token de acesso

Envie as credenciais por HTTP Basic (recomendado) ou no corpo, como client_id e client_secret. O corpo pode ser application/x-www-form-urlencoded ou JSON.

Corpo

Campo	Tipo	Descrição
`grant_type`obrigatório	string	Sempre `client_credentials`.
`scope`	string	Escopos separados por espaço, para pedir um token com menos permissões. Padrão: todos os da credencial.
`client_id`	string	Só se não usar HTTP Basic.
`client_secret`	string	Só se não usar HTTP Basic.

Requisição

POST /api/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Resposta · 200

{
  "access_token": "9f1c2e…b07a",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "refeicoes:leitura"
}

Erros (formato OAuth)

Status	`error`	Quando
400	`unsupported_grant_type`	`grant_type` ausente ou diferente de `client_credentials`.
400	`invalid_scope`	Escopo pedido não pertence à credencial.
401	`invalid_client`	Credencial inválida, desativada ou bloqueada por tentativas.
429	`slow_down`	Mais de 10 tokens por minuto a partir do mesmo IP.

Resposta · 401

{
  "error": "invalid_client",
  "error_description": "Credenciais invalidas."
}

Refeições

Cada passagem liberada na catraca do refeitório conta como uma refeição consumida. Entram só as refeições ativas e os equipamentos configurados para descontar refeição.

GET/v1/refeicoes/resumorefeicoes:leitura

Resumo de refeições por período

Devolve a quantidade e o valor das refeições da instalação da credencial, no total e por tipo de refeição.

Parâmetros (query)

Parâmetro	Tipo	Descrição
`dataInicio`obrigatório	data	`AAAA-MM-DD` ou `AAAA-MM-DDTHH:MM:SS`. Incluído no período.
`dataFim`obrigatório	data	`AAAA-MM-DD` inclui o dia inteiro; com hora, o instante é excluído. Até 31 dias após `dataInicio`.
`tipoPreco`	string	`integral` (padrão) ou `subsidiado`. Veja como o valor é calculado.
`codigoEmpresa`	int	Código da empresa, para ver só uma. Na credencial de empresa, só restringe ainda mais.

Requisição

GET /api/v1/refeicoes/resumo?dataInicio=2026-10-01&dataFim=2026-10-15
Authorization: Bearer SEU_ACCESS_TOKEN

Resposta · 200

{
  "instalacao": { "id": 10015, "nome": "LLINEA | RBR LOG" },
  "periodo": {
    "dataInicio": "2026-10-01T00:00:00",
    "dataFim": "2026-10-16T00:00:00"
  },
  "tipoPreco": "integral",
  "total": { "quantidade": 3120, "valor": 49920.00 },
  "dados": [
    { "codigoRefeicao": 2, "refeicao": "ALMOÇO", "quantidade": 1450, "valor": 27550.00 },
    { "codigoRefeicao": 3, "refeicao": "DESJEJUM DA TARDE", "quantidade": 853, "valor": 6824.00 }
  ]
}

Campos da resposta

Campo	Tipo	Descrição
`instalacao.id`	int	Código da instalação.
`instalacao.nome`	string	Nome da instalação.
`instalacao.empresa`	objeto	Só na credencial de empresa: `codigo` e `nome` da empresa.
`periodo.dataInicio`	data-hora	Início considerado (incluído).
`periodo.dataFim`	data-hora	Fim considerado (excluído).
`tipoPreco`	string	Tipo de preço usado no cálculo.
`total.quantidade`	int	Total de refeições no período.
`total.valor`	decimal	Valor total em reais, com 2 casas.
`dados[].codigoRefeicao`	int	Código da refeição no WAcesso. Use-o para agrupar e conciliar, porque o nome pode mudar.
`dados[].refeicao`	string	Nome da refeição.
`dados[].quantidade`	int	Quantidade dessa refeição.
`dados[].valor`	decimal	Valor dessa refeição em reais. A lista vem ordenada pela maior quantidade.

Como o valor é calculado

Se a passagem já tem valor gravado no histórico da catraca, esse valor é usado.
Se o valor gravado é zero, usa-se a tabela de preços da refeição vigente no dia da passagem, pelo dia da semana (integral ou subsidiado, conforme tipoPreco).
Sem preço cadastrado, valor vem 0.

GET/v1/refeicoes/por-usuariorefeicoes:leituraPaginado

Sintético por usuário

Uma linha por usuário, com o total do período e o detalhe por refeição. Ordenado por empresa e nome. Se o usuário mudou de empresa no período, aparece uma linha para cada empresa.

Parâmetros (query)

Parâmetro	Tipo	Descrição
`dataInicio`obrigatório	data	Igual ao resumo. Veja datas e períodos.
`dataFim`obrigatório	data	Igual ao resumo. Até 31 dias.
`tipoPreco`	string	`integral` (padrão) ou `subsidiado`.
`codigoEmpresa`	int	Código da empresa.
`pagina`	int	Página, a partir de 1.
`limite`	int	Itens por página. Padrão 50, máximo 100.

Requisição

GET /api/v1/refeicoes/por-usuario?dataInicio=2026-10-01&dataFim=2026-10-15&pagina=1&limite=50
Authorization: Bearer SEU_ACCESS_TOKEN

Resposta · 200

{
  %(inst)s,
  %(periodo)s,
  %(pt)s,
  %(dados)s: [
    {
      %(nome)s: %(vname)s,
      %(reg)s: %(vreg)s,
      %(cracha)s: %(vbadge)s,
      %(empresa)s: %(vcomp)s,
      %(cc)s: %(n8)s,
      %(org)s: %(null)s,
      %(qty)s: %(n17)s,
      %(amt)s: %(n272)s,
      %(refeicoes)s: [
        { %(mid)s: %(n1)s, %(refeicao)s: %(vdes)s, %(qty)s: %(n7)s, %(amt)s: %(n56)s },
        { %(mid)s: %(n2)s, %(refeicao)s: %(valm)s, %(qty)s: %(n10)s, %(amt)s: %(n216)s }
      ]
    }
  ],
%(meta)s
}

Campos de cada item de `dados`

Campo	Tipo	Descrição
`nome`	string	Nome do usuário.
`matricula`	string	Matrícula.
`cracha`	string	Número do crachá.
`empresa`	string	Nome da empresa do usuário.
`codigoEmpresa`	int	Código da empresa. Use-o para agrupar, porque o nome pode mudar.
`organograma`	string	Organograma (setor), quando informado na passagem.
`quantidade`	int	Total de refeições do usuário no período.
`valor`	decimal	Valor total do usuário em reais.
`refeicoes[]`	lista	Por refeição: `codigoRefeicao`, `refeicao`, `quantidade`, `valor`.

GET/v1/refeicoes/passagensrefeicoes:leituraPaginado

Analítico: cada passagem na catraca

Uma linha por refeição consumida, em ordem de data e hora. A soma das linhas bate com o resumo do mesmo período.

Parâmetros (query)

Parâmetro	Tipo	Descrição
`dataInicio`obrigatório	data	Igual ao resumo. Veja datas e períodos.
`dataFim`obrigatório	data	Igual ao resumo. Até 31 dias.
`tipoPreco`	string	`integral` (padrão) ou `subsidiado`.
`codigoEmpresa`	int	Código da empresa.
`pagina`	int	Página, a partir de 1.
`limite`	int	Itens por página. Padrão 50, máximo 100.
`codigoRefeicao`	int	Só uma refeição.
`matricula`	string	Só uma matrícula (até 25 caracteres).
`cracha`	string	Só um crachá (até 25 caracteres).

Requisição

GET /api/v1/refeicoes/passagens?dataInicio=2026-10-01&dataFim=2026-10-15&pagina=1&limite=100
Authorization: Bearer SEU_ACCESS_TOKEN

Resposta · 200

{
  "instalacao": { "id": 10015, "nome": "LLINEA | RBR LOG", "empresa": { "codigo": 8, "nome": "VULCABRAS SP COM LTDA" } },
  "periodo": { "dataInicio": "2026-10-01T00:00:00", "dataFim": "2026-10-16T00:00:00" },
  "tipoPreco": "integral",
  "dados": [
    {
      "id": 287042,
      "data": "2026-10-01",
      "hora": "04:50:53",
      "nome": "VANUZA VIEIRA",
      "matricula": "8400",
      "cracha": "8400",
      "empresa": "VULCABRAS SP COM LTDA",
      "codigoEmpresa": 8,
      "organograma": null,
      "equipamento": "REVOLUTION-2",
      "codigoRefeicao": 1,
      "refeicao": "DESJEJUM",
      "valor": 8.00
    }
  ],
  "meta": { "pagina": 1, "limite": 50, "total": 4177, "totalPaginas": 84 },
  "links": { "atual": "…pagina=1", "proxima": "…pagina=2", "anterior": null }
}

Campos de cada item de `dados`

Campo	Tipo	Descrição
`id`	int	Identificador único da passagem.
`data` / `hora`	texto	Data (`AAAA-MM-DD`) e hora (`HH:MM:SS`) no horário local da instalação.
`nome`, `matricula`, `cracha`	string	Nome, matrícula e crachá do usuário.
`empresa`, `codigoEmpresa`	string / int	Empresa do usuário.
`organograma`	string	Organograma (setor), quando informado.
`equipamento`	string	Catraca onde passou.
`codigoRefeicao`, `refeicao`	int / string	Refeição.
`valor`	decimal	Valor da refeição em reais.

Usuários

Cadastro dos usuários do refeitório: quem tem crachá para passar na catraca. O que é feito pela API chega à catraca da mesma forma que o cadastro feito no sistema, normalmente em poucos segundos.

O usuário é identificado pelo id devolvido no cadastro. A matricula é única dentro de cada empresa.
Na credencial de empresa, a empresa é sempre a da credencial: não é preciso informar codigoEmpresa, e usuários de outras empresas não aparecem (respondem 404).
Usuário novo recebe a permissão de horário padrão da instalação. As refeições seguem a regra de refeições do usuário.
Desligar bloqueia o usuário a partir do momento da chamada e libera o crachá para ser usado por outra pessoa. O histórico de refeições é mantido.
Crachá com outra pessoa: no cadastro, no lote e na sincronização, o crachá é transferido para quem está sendo gravado; a pessoa anterior continua cadastrada, sem crachá. Toda resposta informa isso em crachaRemovidoDe (id, nome, matricula), e fica registrado no histórico dela.

Refeições do usuário

O campo refeicoes diz o que a pessoa pode comer no refeitório. Ele é opcional e funciona igual no cadastro, no lote e na sincronização:

O que você envia	Usuário novo	Usuário que já existe (sincronização)
Sem o campo `refeicoes`	Recebe todas as refeições ativas da instalação, 1 vez por dia cada.	Fica como está (nada muda).
Com a lista	Recebe só as refeições da lista.	Fica só com as da lista; as outras são retiradas.

A lista aceita dois formatos (pode misturar):

[{"codigoRefeicao": 2, "limite": 1}, {"codigoRefeicao": 4, "limite": 2}] — limite = quantas vezes por dia (1 a 99).
[2, 4] — só os códigos; cada uma vale 1 vez por dia.

O crédito é sempre livre (a pessoa não "gasta" créditos); o que controla é o limite por dia. Os códigos estão em GET /v1/refeicoes. Lista vazia, refeição inativa, inexistente ou repetida é recusada.

GET/v1/usuariosusuarios:leituraPaginado

Listar usuários

Parâmetro	Tipo	Descrição
`matricula`	string	Matrícula exata.
`cracha`	string	Número do crachá exato.
`nome`	string	Parte do nome (até 100 caracteres).
`codigoEmpresa`	int	Código da empresa.
`situacao`	string	`ativo` ou `desligado`.
`pagina` / `limite`	int	Paginação (limite padrão 50, máximo 100).

Requisição

GET /api/v1/usuarios?matricula=15000923
Authorization: Bearer SEU_ACCESS_TOKEN

GET/v1/usuarios/{id}usuarios:leitura

Consultar um usuário

Resposta · 200

{
  "id": 45194,
  "nome": "ADERBAL BATISTA BORGES FILHO",
  "matricula": "15000923",
  "cracha": "915",
  "empresa": "VULCABRAS SP COM LTDA",
  "codigoEmpresa": 8,
  "cpf": "12345678901",
  "celular": "11999990000",
  "email": null,
  "situacao": "ativo",
  "bloqueioInicio": null,
  "bloqueioFim": null,
  "atualizadoEm": "2026-10-16T21:10:53"
}

Campo	Descrição
`situacao`	`ativo` ou `desligado` (bloqueado agora).
`cracha`	Número do crachá vinculado. `null` depois de desligado.
`bloqueioInicio` / `bloqueioFim`	Período de bloqueio, se houver. Fim `null` = sem data para acabar.

POST/v1/usuariosusuarios:escrita

Cadastrar usuário

Corpo em JSON (Content-Type: application/json). Campos não documentados são rejeitados.

Campo	Tipo	Descrição
`nome`obrigatório	string	Somente letras e espaços, até 250 caracteres.
`matricula`obrigatório	string	Somente números, até 25 dígitos. Única na empresa.
`cracha`obrigatório	string	Número do crachá, só números. Se já existir e estiver livre, é reaproveitado. Se estiver com outra pessoa, é transferido: ela continua cadastrada, mas fica sem crachá (não passa na catraca até receber outro). A resposta traz `crachaRemovidoDe` com quem perdeu o crachá.
`codigoEmpresa`	int	Obrigatório na credencial geral. Na de empresa, se enviado, tem que ser o da própria empresa.
`cpf`	string	11 dígitos (pontuação é ignorada).
`celular`	string	Até 20 caracteres.
`email`	string	E-mail válido.
`refeicoes`	lista	Opcional. Sem o campo, a pessoa recebe todas as refeições ativas, 1 vez por dia. Com o campo, só as informadas. Veja refeições do usuário.

Requisição

POST /api/v1/usuarios
Authorization: Bearer SEU_ACCESS_TOKEN
Content-Type: application/json

{
  "nome": "Maria da Silva",
  "matricula": "20231",
  "cracha": "884512",
  "codigoEmpresa": 8,
  "cpf": "123.456.789-01"
}

Resposta 201 com o usuário criado (mesmo formato da consulta) e o header Location com o endereço dele.

Status	Quando
400	Campo obrigatório ausente, formato inválido, campo desconhecido, empresa ou refeição inexistente.
403	Credencial de empresa tentando cadastrar em outra empresa.
409	Matrícula já cadastrada na empresa.

PATCH/v1/usuarios/{id}usuarios:escrita

Alterar usuário

Altera só os campos enviados: nome, matricula, cpf, celular, email. Para apagar celular, e-mail ou CPF, envie "". Crachá e empresa não mudam por esta rota.

Se o seu sistema não conseguir enviar PATCH, use POST na mesma rota, com o mesmo corpo.

Requisição

PATCH /api/v1/usuarios/45194
Authorization: Bearer SEU_ACCESS_TOKEN
Content-Type: application/json

{ "celular": "11999990000", "email": "maria@empresa.com.br" }

POST/v1/usuarios/{id}/desligarusuarios:escrita

Desligar usuário

Sem corpo. Bloqueia o usuário a partir de agora, sem data de fim, e libera o crachá. Resposta 200 com o usuário (situacao: "desligado").

Requisição

POST /api/v1/usuarios/45194/desligar
Authorization: Bearer SEU_ACCESS_TOKEN

POST/v1/usuarios/loteusuarios:escritaTudo ou nada

Cadastrar usuários em lote

Até 500 usuários por chamada, com os mesmos campos e regras do cadastro individual. Se qualquer item tiver problema, nenhum é cadastrado e a resposta lista o erro de cada item (itens[3].cracha, por exemplo). Corrija e envie o lote inteiro de novo.

Refeições de cada usuário

Cada item pode ter o seu próprio campo refeicoes, independente dos outros do lote:

Item sem refeicoes: a pessoa recebe todas as refeições ativas da instalação, 1 vez por dia cada.
Item com refeicoes: a pessoa recebe só as refeições listadas, com o limite por dia informado. Ex.: [{"codigoRefeicao": 2, "limite": 1}] ou só [2, 4] (1 vez por dia).
Refeição inativa, inexistente, repetida ou lista vazia faz o item dar erro (e, como é tudo ou nada, o lote não é gravado).

No exemplo abaixo, Maria só almoça (código 2) e Joao recebe todas as refeições. Detalhes em refeições do usuário; códigos em GET /v1/refeicoes.

Requisição

POST /api/v1/usuarios/lote
Authorization: Bearer SEU_ACCESS_TOKEN
Content-Type: application/json

{
  "itens": [
    { "nome": "Maria da Silva", "matricula": "20231", "cracha": "884512", "codigoEmpresa": 8,
      "refeicoes": [ { "codigoRefeicao": 2, "limite": 1 } ] },
    { "nome": "Joao Pereira", "matricula": "20232", "cracha": "884513", "codigoEmpresa": 8 }
  ]
}

Resposta · 201

{
  "criados": 2,
  "usuarios": [
    { "indice": 0, "id": 45199, "matricula": "20231", "cracha": "884512" },
    { "indice": 1, "id": 45200, "matricula": "20232", "cracha": "884513" }
  ]
}

Guarde o id de cada usuário: indice é a posição do item na lista enviada (começa em 0). Se o crachá foi tirado de outra pessoa, o item traz crachaRemovidoDe.

Resposta · 422 (nada foi cadastrado)

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Nenhum usuario foi cadastrado: corrija os itens com erro e envie o lote de novo.",
  "errors": [
    { "field": "itens[1].matricula", "message": "Matricula ja cadastrada para esta empresa." },
    { "field": "itens[4].matricula", "message": "Repetida no lote (igual ao item 2)." }
  ]
}

POST/v1/usuarios/desligar-loteusuarios:escritaTudo ou nada

Desligar usuários em lote

Até 500 usuários por chamada. Cada item identifica o usuário pelo id ou pela matricula (na credencial geral, com codigoEmpresa). Se algum não for encontrado, nenhum é desligado. Quem já estava desligado não é erro: volta como ja_desligado.

Requisição

POST /api/v1/usuarios/desligar-lote
Authorization: Bearer SEU_ACCESS_TOKEN
Content-Type: application/json

{
  "itens": [
    { "id": 45199 },
    { "matricula": "20232", "codigoEmpresa": 8 }
  ]
}

Resposta · 200

{
  "desligados": 1,
  "jaDesligados": 1,
  "usuarios": [
    { "indice": 0, "id": 45199, "resultado": "desligado", "crachaLiberado": "884512" },
    { "indice": 1, "id": 45200, "resultado": "ja_desligado" }
  ]
}

POST/v1/usuarios/sincronizarusuarios:escritaTudo ou nada

Sincronizar usuários (lista completa)

Envie a lista completa de funcionários de cada empresa, como sai do RH. A lista vira a verdade:

Não existe (matrícula na empresa) → é cadastrado.
Já existe → é atualizado (só os campos enviados). Se estava desligado, é reativado.
Não veio na lista → é desligado e o crachá é liberado. Vale só para as empresas que aparecem na lista (na credencial de empresa, a própria).
Quem já está igual não é regravado (sem_alteracao). Pode enviar a mesma lista todo dia.

Comece simulando. Envie "simular": true para ver exatamente quem seria criado, alterado, reativado e desligado, sem gravar nada.

Corpo

Campo	Tipo	Descrição
`itens`obrigatório	lista	Até 5.000 usuários, nos campos abaixo.
`simular`	bool	`true` devolve o resultado sem gravar.
`confirmarDesligamentos`	bool	Necessário quando a sincronização desligaria mais de 20% dos ativos de uma empresa (e pelo menos 10 pessoas). Protege contra lista incompleta enviada por engano.

Campos de cada item (mesmos da planilha de importação)

Campo	Planilha	Descrição
`codigoEmpresa`	CODIGOEMPRESA	Obrigatório na credencial geral.
`matricula`obrigatório	MATRICULA	Identifica a pessoa dentro da empresa. Só números.
`cracha`	CRACHA	Obrigatório para quem é novo, a menos que venha o CPF. Em branco num usuário existente = mantém o atual. Crachá com outra pessoa é transferido (ela fica sem crachá; volta em `crachaRemovidoDe`). Duas pessoas da lista não podem terminar com o mesmo crachá.
`cpf`	CPF	11 dígitos. Com `cracha` em branco, gera o número do crachá a partir do CPF (igual à planilha).
`nome`obrigatório	NOME	Somente letras. Se a matrícula já existir com outro nome, o item é recusado (para trocar o nome, use `PATCH /v1/usuarios/{id}`).
`organogramaPai`	ORGANOGRAMAPAI	Nome do organograma pai (opcional; ajuda quando o filho tem nome repetido).
`organograma`	ORGANOGRAMA	Nome do organograma (setor). `null` limpa.
`categoria`	CATEGORIA	Código da categoria. `null` limpa.
`celular` / `email`	—	Opcionais.
`refeicoes`	LIMITEREFEICAO1…9	Opcional. Lista exata do que a pessoa pode comer, com o limite por dia; as que não vierem são retiradas. Sem o campo: novo recebe todas as refeições ativas (1 vez por dia) e quem já existe fica como está. Veja refeições do usuário.

Campo que não vier no item não é alterado. Campo que vier com null é limpo.

Requisição

POST /api/v1/usuarios/sincronizar
Authorization: Bearer SEU_ACCESS_TOKEN
Content-Type: application/json

{
  "simular": true,
  "itens": [
    {
      "codigoEmpresa": 8, "matricula": "15000647", "cracha": "861",
      "nome": "ABNER OLIVEIRA BONASSA", "organograma": "PRODUCAO", "categoria": 2,
      "refeicoes": [ { "codigoRefeicao": 1, "limite": 1 }, { "codigoRefeicao": 2, "limite": 1 } ]
    },
    { "codigoEmpresa": 8, "matricula": "15000923", "cracha": "", "cpf": "43489218817", "nome": "ADERBAL BATISTA BORGES FILHO" }
  ]
}

Resposta · 200

{
  "simulacao": true,
  "resumo": { "recebidos": 439, "criados": 3, "atualizados": 5, "reativados": 1, "semAlteracao": 430, "desligados": 2 },
  "empresas": [ { "codigoEmpresa": 8, "ativosAntes": 437, "desligados": 2 } ],
  "usuarios": [
    { "indice": 0, "id": 294, "matricula": "15000647", "nome": "ABNER OLIVEIRA BONASSA", "acao": "atualizado", "alteracoes": ["organograma", "refeicoes"], "cracha": "861" }
  ],
  "desligados": [
    { "id": 1180, "matricula": "15000101", "nome": "FULANO DE TAL", "codigoEmpresa": 8, "crachaLiberado": "412" }
  ]
}

usuarios lista só quem foi criado, atualizado ou reativado (acao), com os campos alterados. Com "simular": true, nada é gravado; sem ele, a mesma resposta confirma o que foi feito.

Status	Quando
200	Sincronizado (ou simulado).
403	Credencial de empresa enviando outra empresa.
422	Algum item com erro (todos são listados de uma vez), ou desligamentos acima do limite sem `confirmarDesligamentos`. Nada foi gravado.

GET/v1/refeicoesrefeicoes:leitura

Refeições da instalação

Códigos para usar em refeicoes no cadastro e na sincronização.

Resposta · 200

{
  "dados": [
    { "codigoRefeicao": 1, "numero": 1, "nome": "DESJEJUM", "ativa": true },
    { "codigoRefeicao": 2, "numero": 2, "nome": "ALMOCO", "ativa": true }
  ]
}

GET/healthPúblico

Status da API

Não exige token. Use para monitorar se a API está no ar.

Resposta · 200

{ "status": "ok" }

Paginação

As rotas marcadas como Paginado aceitam pagina (começa em 1) e limite (padrão 50, máximo 100).
A resposta traz dados, meta (pagina, limite, total, totalPaginas) e links (atual, proxima, anterior), que preservam os filtros.
Para percorrer tudo, siga links.proxima até ele vir null.

Datas e períodos

Formatos aceitos: AAAA-MM-DD ou AAAA-MM-DDTHH:MM:SS.
O intervalo inclui o início e exclui o fim. dataFim só com data inclui o dia inteiro.
Período máximo de 31 dias por consulta. Para períodos maiores, faça uma chamada por mês.
Datas e horas no horário local da instalação, sem fuso.
Passagens coletadas com a catraca offline podem chegar depois. Para fechamento, consulte de novo no dia seguinte.

Erros

As rotas /v1 respondem erros no formato Problem Details (RFC 9457). O requestId também vem no header X-Request-Id; informe-o ao suporte.

Resposta · 400

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Parametros invalidos.",
  "instance": "/v1/refeicoes/resumo",
  "requestId": "a588fcb90defbcbb",
  "errors": [
    { "location": "query", "field": "dataFim", "message": "Periodo maximo de 31 dias." }
  ]
}

Status	Significado
200	Sucesso.
400	Parâmetro ausente, formato incorreto, parâmetro desconhecido ou período acima de 31 dias.
401	Token ausente, inválido, expirado ou revogado.
403	Token sem o escopo exigido.
404	Rota não encontrada.
405	Método HTTP não permitido na rota.
409	Conflito: matrícula já cadastrada na empresa.
422	Lote com itens inválidos: nada foi gravado; a lista `errors` diz o item e o motivo.
429	Limite de requisições atingido (veja `Retry-After`).
500	Erro interno. Informe o `requestId` ao suporte.

Limites

Recurso	Limite
Requisições por credencial	120 por minuto
Geração de token (`/oauth/token`)	10 por minuto, por IP
Tentativas com secret errado	5, depois bloqueio de 15 minutos
Validade do token	15 minutos
Período por consulta	31 dias
Itens por lote (cadastro e desligamento)	500
Usuários por sincronização	5.000
Chamadas de lote e sincronização por credencial	10 por minuto

Headers de consumo em cada resposta: X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos). Ao exceder, a resposta é 429 com o header Retry-After.

Boas práticas

Guarde o client_secret só no servidor e nunca o envie para o navegador ou aplicativo.
Reutilize o token até perto de expirar; gere outro ao receber 401.
Envie só os parâmetros documentados: parâmetros desconhecidos são rejeitados com 400.
Use codigoRefeicao, e não o nome, para agrupar e conciliar refeições.
Em 429 ou 5xx, tente de novo com espera crescente (backoff exponencial).
Registre o requestId dos erros. Todas as chamadas são auditadas (credencial, rota, IP e horário).

Consulte as refeições do seu refeitório com o Turron Acesso

Início rápido

Credenciais e empresas

Autenticação

Escopos

Postman

Gera um token de acesso

Corpo

Erros (formato OAuth)

Refeições

Resumo de refeições por período

Parâmetros (query)

Campos da resposta

Como o valor é calculado

Sintético por usuário

Parâmetros (query)

Campos de cada item de dados

Analítico: cada passagem na catraca

Parâmetros (query)

Campos de cada item de dados

Usuários

Refeições do usuário

Listar usuários

Consultar um usuário

Cadastrar usuário

Alterar usuário

Desligar usuário

Cadastrar usuários em lote

Refeições de cada usuário

Desligar usuários em lote

Sincronizar usuários (lista completa)

Corpo

Campos de cada item (mesmos da planilha de importação)

Refeições da instalação

Status da API

Paginação

Datas e períodos

Erros

Limites

Boas práticas

Campos de cada item de `dados`

Campos de cada item de `dados`