Integração facial360 ↔ Lanaup

Visão geral

O facial360 é a plataforma que controla os equipamentos de reconhecimento facial instalados no cliente. Quando um funcionário é reconhecido, nós registramos o evento e entregamos a batida para a Lanaup.

A divisão de responsabilidade é deliberada: não recalculamos ponto, não aplicamos tolerância, não fechamos espelho. Isso é da Lanaup.

Como funciona

O endpoint de vocês

Precisamos de uma URL HTTPS que aceite POST com corpo JSON. É o único requisito de infraestrutura da integração.

Cada requisição carrega uma batida. Não agrupamos em lote — isso mantém o reenvio simples e evita que uma batida ruim derrube as outras.

Payload da batida

Este é o corpo que enviamos. Se vocês precisarem de outro formato, nomes de campos diferentes ou campos adicionais, nos mandem o modelo — nós adaptamos do nosso lado.

{
  "employee_external_id": "EMP-042",
  "event_time":           "2026-08-13T08:03:00-03:00",
  "event_type":           "time_clock",
  "direction":            "in",
  "correlation_id":       "7cddd486-469b-405b-9911-5f0229a892c7",
  // identificadores internos, informativos
  "tenant_id":            "<uuid da empresa>",
  "unit_id":              "<uuid da unidade>",
  "device_id":            "<uuid do equipamento>",
  "person_id":            "<uuid da pessoa>"
}

Autenticação

Enviamos a credencial que vocês nos derem. Por padrão, no header Authorization:

POST /ponto HTTP/1.1
Host: api.lanaup.com.br
Content-Type: application/json
Authorization: Bearer <chave que vocês emitirem>

Se preferirem um header próprio — x-api-key, x-token, qualquer nome — é só informar. É configuração do nosso lado, não precisa de alteração de código.

Resposta esperada

O corpo da resposta é opcional para nós — guardamos os primeiros 500 caracteres para suporte. Se vocês devolverem um identificador próprio da batida, podemos armazená-lo; digam qual campo.

Reenvio e duplicidade

Se a Lanaup não aceitar, tentamos de novo com espera crescente. Nenhuma batida é descartada silenciosamente.

Esgotadas as tentativas, a batida fica marcada como falha e um alerta é disparado para a operação — a batida continua guardada e pode ser reenviada manualmente.

Entrada e saída

O primeiro cliente tem um único equipamento registrando entrada e saída. O equipamento informa o sentido de cada leitura, e nós repassamos isso no campo direction.

Precisamos saber como vocês tratam isso: usam o direction que enviamos, ou deduzem pela ordem das batidas do dia? Se for pela ordem, o campo é inofensivo e vocês podem ignorá-lo. Se vocês usam, ele passa a ser a fonte da verdade — e aí vale combinar o que fazer quando vier null (equipamento não informou).

Cadastro de funcionários

O cadastro dos funcionários é de vocês. O facial360 guarda apenas o mínimo para reconhecer a pessoa: nome, a foto de referência e o código dela na Lanaup.

Esse código é o que aparece em employee_external_id em toda batida. Sem ele idêntico dos dois lados, a batida chega sem dono.

Três formas de manter isso alinhado

1. Vocês nos passam a lista. Um endpoint que liste os funcionários ativos com código e nome, e nós importamos. É o caminho mais simples de operar e o que preferimos.
2. Vocês criam direto na nossa API. Quando um funcionário é admitido, a Lanaup chama nosso endpoint de cadastro passando o código. Damos uma chave e a documentação.
3. Manual, no nosso painel. Alguém digita o código ao cadastrar a foto. Funciona para poucos funcionários, mas erro de digitação vira batida órfã.

Consultar em vez de receber

Se vocês preferirem buscar as batidas em vez de recebê-las, nossa API REST expõe o mesmo dado. Autenticação por chave no header x-api-key.

Aceita filtros por person_id e unit_id, além de paginação. Cada registro traz o status de entrega e o mesmo correlation_id do envio. A URL base e a chave são entregues junto com as credenciais.

Também entregamos eventos por webhook assinado (HMAC-SHA256, com reenvio próprio) caso vocês queiram acompanhar mais do que ponto — acesso liberado, acesso negado, equipamento offline. Documentamos à parte se houver interesse.

O que precisamos de vocês

São estes os pontos que travam a integração. Nada aqui depende de desenvolvimento — é definição.

• URL do endpoint que recebe as batidas Produção e homologação, se houver ambiente separado.
• Como autenticar Bearer, header próprio (qual nome) ou outro esquema.
• O formato acima serve? Se não, o modelo de vocês. Adaptamos do nosso lado.
• Vocês usam o campo direction? Ou deduzem entrada/saída pela ordem das batidas.
• O que respondem ao aceitar e ao recusar Status e corpo, para diferenciarmos erro nosso de erro de dado.
• Como tratam batida repetida Confirmando que podemos reenviar sem gerar ponto duplicado.
• Qual código identifica o funcionário — e como obtemos a lista É a chave da integração inteira.