Integracao

[ESPEC] Cadastrar ou atualizar pessoa

Especificacao — ainda nao implementado. Este endpoint esta publicado para acordo de contrato; chamadas retornam 404 ate a implementacao.

Cria a pessoa quando o documento ainda nao existe no espaco e atualiza quando ja existe — o sistema de origem pode reenviar o mesmo registro sem se preocupar em distinguir os casos.

Deduplicacao: o document.number e a chave. Se a pessoa ja existir em outro espaco, o cadastro nao e duplicado; ela apenas passa a ter acesso a este espaco (action: "linked").

Efeito nos dispositivos: a face so e reenviada aos leitores quando o nome ou a foto mudam. Alteracoes de cracha, e-mail, telefone ou atributos nao geram trafego para o dispositivo.

Situacao: status: "leave" remove a pessoa do grupo de acesso mas mantem a face gravada, de modo que o retorno e imediato e nao exige reenvio de foto. status: "terminated" encerra o acesso.

post/api/v1/integration/persons

Request

Base URL: http://localhost:3000
URL: http://localhost:3000/api/v1/integration/persons
Auth: API key in header X-API-Key

Headers

X-API-Keystring required

Chave de API do espaco, gerada no painel administrativo.

Example:k_9fA3…

X-Tenant-Slugstring required

Identificador do espaco (slug).

Example:matriz-sao-jose

Request body

personType'employee' | 'contractor' | 'partner' | 'visitor'

Vinculo da pessoa com o espaco. employee colaborador proprio, contractor terceiro, partner parceiro, visitor visitante.

namestring required

emailstring email

phonestring

birthDatestring

status'active' | 'leave' | 'terminated'

Situacao no sistema de origem. leave bloqueia o acesso preservando o cadastro e a face no dispositivo; terminated encerra o acesso.

photoBase64string

Foto facial em base64 (JPEG ou PNG), sem o prefixo data:image/.... Quando ausente, a pessoa e criada com cadastro incompleto e a resposta traz photoPending: true e uma URL para o proprio titular concluir o cadastro. Sem foto a pessoa nao e reconhecida no dispositivo e portanto nao gera eventos de acesso.

attributesobject

Campos livres do sistema de origem. E o ponto de extensao do contrato: identificadores e codigos proprietarios de cada ERP/RH ficam aqui, sem alterar o restante do payload.

Example request

{
  "identity": {
    "externalId": "EMP-4521",
    "registration": "4521",
    "badgeCode": "0000004521",
    "companyCode": "1"
  },
  "personType": "employee",
  "name": "Joao da Silva",
  "document": {
    "number": "12345678900"
  },
  "email": "joao.silva@empresa.com.br",
  "phone": "47999998888",
  "birthDate": "1990-05-20",
  "access": {
    "validFrom": "2026-03-01T00:00:00.000Z",
    "allowedHours": {
      "start": "07:00",
      "end": "19:00",
      "days": [
        1,
        2,
        3,
        4,
        5
      ]
    }
  },
  "attributes": {
    "matriculaInterna": "4521",
    "turno": "A"
  }
}

Response

Pessoa atualizada

action'created' | 'updated' | 'linked' required

created pessoa nova, updated cadastro existente atualizado, linked a pessoa ja existia em outro espaco e passou a ter acesso a este, sem duplicar o registro.

Example response

{
  "item": {
    "identity": {
      "externalId": "EMP-4521",
      "registration": "4521",
      "badgeCode": "0000004521",
      "companyCode": "1"
    },
    "personType": "employee",
    "access": {
      "validFrom": "2026-03-01T00:00:00.000Z",
      "allowedHours": {
        "start": "07:00",
        "end": "19:00",
        "days": [
          1,
          2,
          3,
          4,
          5
        ]
      }
    },
    "devices": [
      {
        "deviceName": "Catraca Portaria"
      }
    ],
    "attributes": {
      "matriculaInterna": "4521",
      "turno": "A"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.