iopoint
Referência

Colaboradores

Listar, criar, demitir, enviar e baixar a foto facial de colaboradores.

URL Base
https://api.iopoint.com.br/api

Endpoints

Listar colaboradores

GET/customer/v2/collaborator

Retorna os colaboradores da empresa, com o bloco padrão de identificação, o centro de custo e o gênero. Por padrão, só os ativos são retornados; use `include_inactive=1` para incluir também os desligados.

cost_center traz o nome do centro de custo do colaborador; vem vazio quando não há centro de custo.
contract_type é o tipo de contrato (ver GET /contract-type). esocial_id é a matrícula do eSocial e vem null quando não foi informada.
gender é o gênero do colaborador: MASCULINO, FEMININO ou OUTRO; vem null quando não foi informado.
dismissal_date vem null para colaboradores ativos e YYYY-MM-DD para colaboradores desligados.
has_face_photo: true indica que o colaborador tem foto de reconhecimento facial cadastrada — use GET /collaborator/photo para obtê-la.

Query parameters

NomeTipoObrig.Descrição
include_inactivebooleannãoQuando `1`, inclui também colaboradores desligados na resposta, com o campo `dismissal_date` preenchido. Por padrão, só ativos são retornados.
include_branchesbooleannãoQuando `1`, agrega a matriz e todas as filiais do grupo econômico na resposta. Só leitura.
company_national_registrystringnãoCNPJ (apenas dígitos) de uma empresa do grupo para restringir o escopo a ela. Use os CNPJs retornados em `GET /economic-group`. Fora do grupo acessível retorna `company_not_found` (404).

Exemplos

Request
curl -X GET "https://api.iopoint.com.br/api/customer/v2/collaborator" \
  -H "apiIopointToken: SEU_TOKEN_AQUI"
Response200
{
  "data": [
    {
      "national_registry": "12345678900",
      "registration_number": "0042",
      "email": "[email protected]",
      "name": "João da Silva",
      "occupation": "Analista de RH",
      "department": "Recursos Humanos",
      "team": null,
      "business_unit": "Matriz",
      "admission_date": "2022-03-15",
      "pis": "12345678901",
      "company": {
        "name": "Filial São Paulo LTDA",
        "trading_name": "Filial SP",
        "national_registry": "12345678000288"
      },
      "cost_center": "Administrativo",
      "contract_type": 1,
      "esocial_id": "0042",
      "gender": "FEMININO",
      "dismissal_date": null,
      "has_face_photo": true
    }
  ]
}

Respostas

200
{
  "data": [
    {
      "national_registry": "12345678900",
      "registration_number": "0042",
      "email": "[email protected]",
      "name": "João da Silva",
      "occupation": "Analista de RH",
      "department": "Recursos Humanos",
      "team": null,
      "business_unit": "Matriz",
      "admission_date": "2022-03-15",
      "pis": "12345678901",
      "company": {
        "name": "Filial São Paulo LTDA",
        "trading_name": "Filial SP",
        "national_registry": "12345678000288"
      },
      "cost_center": "Administrativo",
      "contract_type": 1,
      "esocial_id": "0042",
      "gender": "FEMININO",
      "dismissal_date": null,
      "has_face_photo": true
    }
  ]
}

Totais de horas por colaborador

GET/customer/v2/collaborator/totalHours

Agrega todos os tipos de horas (banco, faltas, atestados, noturno, horas extras 1/2/3/4, intrajornada, interjornada, DSR, feriados, trabalhada etc.) por colaborador em um período de até 31 dias. Suporta filtro por CPF ou e-mail e formato decimal opcional.

O período máximo é de 31 dias — solicitações maiores retornam date_range_exceeded.
Quando decimal_format=1, valores 00:00:00 viram 0 e horas viram número (ex.: 8.5).

Query parameters

NomeTipoObrig.Descrição
begin_datedatesimData inicial do período (YYYY-MM-DD).
end_datedatesimData final do período (YYYY-MM-DD). Máximo de 31 dias a partir de `begin_date`.
national_registry_list[]array<string>nãoLista de CPFs (somente dígitos) para filtrar. Opcional. Use a sintaxe PHP/HTML padrão repetindo a chave: `national_registry_list[]=12345678900&national_registry_list[]=98765432100`. Mesmo com um único CPF, os colchetes `[]` no nome são obrigatórios.
email_list[]array<string>nãoLista de e-mails para filtrar. Opcional. Mesma sintaxe da `national_registry_list[]`: repita a chave para cada e-mail, ex.: `email_list[][email protected]`.
decimal_formatbooleannãoQuando `1`, devolve as horas em formato decimal (ex.: `8.50`) em vez de `HH:MM:SS`.
include_branchesbooleannãoQuando `1`, agrega a matriz e todas as filiais do grupo econômico na resposta. Só leitura.
company_national_registrystringnãoCNPJ (apenas dígitos) de uma empresa do grupo para restringir o escopo a ela. Use os CNPJs retornados em `GET /economic-group`. Fora do grupo acessível retorna `company_not_found` (404).

Erros possíveis

StatusCódigoQuando ocorre
422date_range_exceededPeríodo maior que 31 dias.
401invalid_iopoint_tokenToken ausente ou inválido.

Exemplos

Request
curl -X GET "https://api.iopoint.com.br/api/customer/v2/collaborator/totalHours?begin_date=2026-05-01&end_date=2026-05-31" \
  -H "apiIopointToken: SEU_TOKEN_AQUI"
Response200
{
  "data": [
    {
      "national_registry": "12345678900",
      "registration_number": "0042",
      "email": "[email protected]",
      "name": "João da Silva",
      "occupation": "Analista de RH",
      "department": "Recursos Humanos",
      "team": null,
      "business_unit": "Matriz",
      "admission_date": "2022-03-15",
      "pis": "12345678901",
      "company": {
        "name": "Filial São Paulo LTDA",
        "trading_name": "Filial SP",
        "national_registry": "12345678000288"
      },
      "total_hours": {
        "worked_time": "176:00:00",
        "worked_actual_time": "170:15:00",
        "bank_time": "04:30:00",
        "bank_time_factored": "06:45:00",
        "fault_full_time": "08:00:00",
        "fault_partial_time": "00:00:00",
        "interjourney": "00:00:00",
        "intrajourney": "00:00:00",
        "justified_time": "00:00:00",
        "justified_not_paid_time": "00:00:00",
        "medical_certificate_time": "00:00:00",
        "night_time": "00:00:00",
        "night_time_reduced": "00:00:00",
        "over_time_1": "10:00:00",
        "over_time_1_day": "08:30:00",
        "over_time_1_night": "01:30:00",
        "over_time_1_night_reduced": "01:42:51",
        "over_time_2": "02:00:00",
        "over_time_2_day": "02:00:00",
        "over_time_2_night": "00:00:00",
        "over_time_2_night_reduced": "00:00:00",
        "over_time_3": "00:00:00",
        "over_time_3_day": "00:00:00",
        "over_time_3_night": "00:00:00",
        "over_time_3_night_reduced": "00:00:00",
        "over_time_4": "00:00:00",
        "over_time_4_day": "00:00:00",
        "over_time_4_night": "00:00:00",
        "over_time_4_night_reduced": "00:00:00",
        "over_time_dsr": "00:00:00",
        "over_time_dsr_day": "00:00:00",
        "over_time_dsr_night": "00:00:00",
        "over_time_dsr_night_reduced": "00:00:00",
        "over_time_holiday": "00:00:00",
        "over_time_holiday_day": "00:00:00",
        "over_time_holiday_night": "00:00:00",
        "over_time_holiday_night_reduced": "00:00:00"
      }
    }
  ],
  "meta": {
    "begin_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}

Respostas

200
{
  "data": [
    {
      "national_registry": "12345678900",
      "registration_number": "0042",
      "email": "[email protected]",
      "name": "João da Silva",
      "occupation": "Analista de RH",
      "department": "Recursos Humanos",
      "team": null,
      "business_unit": "Matriz",
      "admission_date": "2022-03-15",
      "pis": "12345678901",
      "company": {
        "name": "Filial São Paulo LTDA",
        "trading_name": "Filial SP",
        "national_registry": "12345678000288"
      },
      "total_hours": {
        "worked_time": "176:00:00",
        "worked_actual_time": "170:15:00",
        "bank_time": "04:30:00",
        "bank_time_factored": "06:45:00",
        "fault_full_time": "08:00:00",
        "fault_partial_time": "00:00:00",
        "interjourney": "00:00:00",
        "intrajourney": "00:00:00",
        "justified_time": "00:00:00",
        "justified_not_paid_time": "00:00:00",
        "medical_certificate_time": "00:00:00",
        "night_time": "00:00:00",
        "night_time_reduced": "00:00:00",
        "over_time_1": "10:00:00",
        "over_time_1_day": "08:30:00",
        "over_time_1_night": "01:30:00",
        "over_time_1_night_reduced": "01:42:51",
        "over_time_2": "02:00:00",
        "over_time_2_day": "02:00:00",
        "over_time_2_night": "00:00:00",
        "over_time_2_night_reduced": "00:00:00",
        "over_time_3": "00:00:00",
        "over_time_3_day": "00:00:00",
        "over_time_3_night": "00:00:00",
        "over_time_3_night_reduced": "00:00:00",
        "over_time_4": "00:00:00",
        "over_time_4_day": "00:00:00",
        "over_time_4_night": "00:00:00",
        "over_time_4_night_reduced": "00:00:00",
        "over_time_dsr": "00:00:00",
        "over_time_dsr_day": "00:00:00",
        "over_time_dsr_night": "00:00:00",
        "over_time_dsr_night_reduced": "00:00:00",
        "over_time_holiday": "00:00:00",
        "over_time_holiday_day": "00:00:00",
        "over_time_holiday_night": "00:00:00",
        "over_time_holiday_night_reduced": "00:00:00"
      }
    }
  ],
  "meta": {
    "begin_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}

Criar colaborador

POST/customer/v2/collaborator

Cria um novo colaborador vinculado à empresa. Todos os IDs referenciados precisam existir e pertencer à empresa autenticada.

Sem contract_type, o colaborador é cadastrado como mensalista e precisa de esocial_id.
Terceirizado, estagiário e outros podem ser cadastrados sem esocial_id.

Body (application/json)

NomeTipoObrig.Descrição
namestringsimNome completo.
national_registrystringsimCPF (somente dígitos).
emailstring · emailsimE-mail do colaborador.
birth_datedatesimData de nascimento (YYYY-MM-DD).
registration_numberstringnãoMatrícula.
begin_datedatesimData a partir da qual o colaborador passa a registrar ponto na iopoint (YYYY-MM-DD).
admission_datedatenãoData formal de admissão na empresa (YYYY-MM-DD). Opcional.
pisstringnãoNúmero do PIS.
journey_idintegersimID da jornada (ver `GET /journey`).
cost_center_idintegersimID do centro de custo.
department_idintegersimID do departamento.
unit_idintegersimID da unidade.
collaborator_settings_idintegersimID das configurações.
point_rule_idintegersimID da regra de ponto.
occupation_idintegernãoID do cargo.
contract_typeintegernãoTipo de contrato (ver `GET /contract-type`). Opcional; sem ele, o colaborador é cadastrado como mensalista.
Valores: 0123100
esocial_idstringnãoMatrícula do eSocial. Obrigatória para horista e mensalista (`requires_esocial_id: true` em `GET /contract-type`); opcional nos demais contratos.

Erros possíveis

StatusCódigoQuando ocorre
404journey_not_foundjourney_id inexistente ou de outra empresa.
404cost_center_not_foundcost_center_id inválido.
404department_not_founddepartment_id inválido.
404unit_not_foundunit_id inválido.
404collaborator_settings_not_foundcollaborator_settings_id inválido.
404point_rule_not_foundpoint_rule_id inválido.
404contract_type_not_foundcontract_type fora da lista de `GET /contract-type`.
422invalid_request_payloadFalta `esocial_id` para horista ou mensalista (vem em `payload_data_required`).

Exemplos

Request
curl -X POST "https://api.iopoint.com.br/api/customer/v2/collaborator" \
  -H "apiIopointToken: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "João da Silva",
  "national_registry": "12345678900",
  "email": "[email protected]",
  "birth_date": "1990-05-20",
  "registration_number": "0042",
  "begin_date": "2026-05-26",
  "admission_date": "2026-05-26",
  "journey_id": 3,
  "cost_center_id": 5,
  "department_id": 2,
  "unit_id": 1,
  "collaborator_settings_id": 1,
  "point_rule_id": 4,
  "contract_type": 1,
  "esocial_id": "0042"
}'
Response201
{
  "data": {
    "id": 1042
  }
}

Respostas

201
{
  "data": {
    "id": 1042
  }
}

Enviar foto facial

POST/customer/v2/collaborator/photo

Envia a foto facial do colaborador (em base64) para reconhecimento facial. O colaborador é identificado pelo CPF (`national_registry`); se houver mais de um colaborador com o mesmo CPF na empresa, o ponto sobe no ativo (`dismissal_date IS NULL`). A imagem deve ser nítida, frontal e sem acessórios.

Body (application/json)

NomeTipoObrig.Descrição
national_registrystringsimCPF do colaborador (somente dígitos). Zeros à esquerda são preenchidos automaticamente até 11 caracteres.
photo_base64base64simImagem JPEG/PNG codificada em base64 (sem o prefixo `data:image/...`).

Erros possíveis

StatusCódigoQuando ocorre
404cpf_not_foundCPF não cadastrado no sistema.
404collaborator_not_foundCPF existe, mas não há colaborador vinculado na empresa do token.
422collaborator_firedÚnico colaborador encontrado com esse CPF na empresa está demitido (`dismissal_date` preenchida); upload de foto bloqueado.
403invalid_photoImagem rejeitada (sem rosto, baixa qualidade).
403face_recognition_failedFalha ao processar a foto facial.

Exemplos

Request
curl -X POST "https://api.iopoint.com.br/api/customer/v2/collaborator/photo" \
  -H "apiIopointToken: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
  "national_registry": "12345678900",
  "photo_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAg..."
}'
Response200
{
  "data": {
    "success": true
  }
}

Respostas

200
{
  "data": {
    "success": true
  }
}

Baixar foto facial

GET/customer/v2/collaborator/photo

Retorna em base64 a foto de reconhecimento facial cadastrada para o colaborador, a mesma que aparece no cadastro dele no gestor, junto com o nome do arquivo e o `mime_type` da imagem. Informe um identificador: `collaborator_id`, `registration_number` ou `national_registry`. Colaboradores desligados também recebem a foto.

Se mais de um identificador for enviado, vale o primeiro na ordem collaborator_id, registration_number, national_registry.
Se o CPF ou a matrícula tiver mais de um vínculo (por exemplo, numa readmissão), vem a foto do vínculo ativo; sem vínculo ativo, a do de admissão mais recente.
A foto devolvida é a cópia guardada no cadastro, recortada e reduzida para 300x400 pixels. Ela vem em JPEG na maioria dos casos; fotos antigas podem vir em PNG, então use o mime_type da resposta.
O base64 vem sem o prefixo data:image/....
Para saber quem tem foto sem baixar uma por uma, use o campo has_face_photo de GET /collaborator.

Query parameters

NomeTipoObrig.Descrição
collaborator_idintegernãoID do colaborador (use um dos identificadores).
registration_numberstringnãoMatrícula do colaborador.
national_registrystringnãoCPF do colaborador (somente dígitos). Zeros à esquerda são preenchidos automaticamente até 11 caracteres.
include_branchesbooleannãoQuando `1`, agrega a matriz e todas as filiais do grupo econômico na resposta. Só leitura.
company_national_registrystringnãoCNPJ (apenas dígitos) de uma empresa do grupo para restringir o escopo a ela. Use os CNPJs retornados em `GET /economic-group`. Fora do grupo acessível retorna `company_not_found` (404).

Erros possíveis

StatusCódigoQuando ocorre
422invalid_request_payloadNenhum identificador informado.
404collaborator_not_found`collaborator_id` inexistente ou fora do escopo do token.
404collaborator_not_found_by_registrationMatrícula não encontrada no escopo do token.
404collaborator_not_found_by_national_registryCPF não encontrado no escopo do token.
404face_photo_not_foundColaborador encontrado, mas sem foto de reconhecimento facial cadastrada.

Exemplos

Request
curl -X GET "https://api.iopoint.com.br/api/customer/v2/collaborator/photo?national_registry=12345678900" \
  -H "apiIopointToken: SEU_TOKEN_AQUI"
Response200
{
  "data": {
    "collaborator_id": 1042,
    "filename": "photo.jpg",
    "mime_type": "image/jpeg",
    "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAg..."
  },
  "meta": {
    "collaborator_id": 1042
  }
}

Respostas

200
{
  "data": {
    "collaborator_id": 1042,
    "filename": "photo.jpg",
    "mime_type": "image/jpeg",
    "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAg..."
  },
  "meta": {
    "collaborator_id": 1042
  }
}

Demitir colaborador

PUT/customer/v2/collaborator/dismissal

Registra a demissão de um colaborador. Pelo menos um identificador (`collaborator_id`, `registration_number` ou `national_registry`) deve ser informado.

Body (application/json)

NomeTipoObrig.Descrição
dismissal_datedatesimData da demissão (YYYY-MM-DD).
fired_type_idintegersimID do tipo de demissão (ver `GET /fired-type`).
collaborator_idintegernãoID do colaborador (use um dos identificadores).
registration_numberstringnãoMatrícula do colaborador.
national_registrystringnãoCPF do colaborador (somente dígitos).
fired_descriptionstringnãoObservações da demissão.

Erros possíveis

StatusCódigoQuando ocorre
404collaborator_not_foundNenhum identificador resolve para um colaborador da empresa.
404fired_type_not_foundfired_type_id inválido.
422dismissal_date_before_admission_dateData da demissão anterior à admissão.

Exemplos

Request
curl -X PUT "https://api.iopoint.com.br/api/customer/v2/collaborator/dismissal" \
  -H "apiIopointToken: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
  "national_registry": "12345678900",
  "dismissal_date": "2026-05-31",
  "fired_type_id": 2,
  "fired_description": "Demissão sem justa causa."
}'
Response200
{
  "data": {
    "success": true
  }
}

Respostas

200
{
  "data": {
    "success": true
  }
}