Referência

Colaboradores

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

URL Base

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

Endpoints

GET/customer/v2/collaboratorListar colaboradores ativos
GET/customer/v2/collaborator/totalHoursTotais de horas por colaborador
POST/customer/v2/collaboratorCriar colaborador
POST/customer/v2/collaborator/photoEnviar foto facial
PUT/customer/v2/collaborator/dismissalDemitir colaborador

Listar colaboradores ativos

GET/customer/v2/collaborator

Retorna todos os colaboradores ativos da empresa, com o bloco padrão de identificação.

Query parameters

Nome	Tipo	Obrig.	Descrição
include_branches	boolean	não	Quando `1`, agrega a matriz e todas as filiais do grupo econômico na resposta. Só leitura.
company_national_registry	string	não	CNPJ (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"
      }
    }
  ]
}

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"
      }
    }
  ]
}

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"
      }
    }
  ]
}

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

Nome	Tipo	Obrig.	Descrição
begin_date	date	sim	Data inicial do período (YYYY-MM-DD).
end_date	date	sim	Data final do período (YYYY-MM-DD). Máximo de 31 dias a partir de `begin_date`.
national_registry_list[]	array<string>	não	Lista 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ão	Lista 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_format	boolean	não	Quando `1`, devolve as horas em formato decimal (ex.: `8.50`) em vez de `HH:MM:SS`.
include_branches	boolean	não	Quando `1`, agrega a matriz e todas as filiais do grupo econômico na resposta. Só leitura.
company_national_registry	string	não	CNPJ (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

Status	Código	Quando ocorre
422	date_range_exceeded	Período maior que 31 dias.
401	invalid_iopoint_token	Token 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"
  }
}

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"
  }
}

Criar colaborador

POST/customer/v2/collaborator

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

Body (application/json)

Nome	Tipo	Obrig.	Descrição
name	string	sim	Nome completo.
national_registry	string	sim	CPF (somente dígitos).
email	string · email	sim	E-mail do colaborador.
birth_date	date	sim	Data de nascimento (YYYY-MM-DD).
registration_number	string	não	Matrícula.
begin_date	date	sim	Data a partir da qual o colaborador passa a registrar ponto na iopoint (YYYY-MM-DD).
admission_date	date	não	Data formal de admissão na empresa (YYYY-MM-DD). Opcional.
pis	string	não	Número do PIS.
journey_id	integer	sim	ID da jornada (ver `GET /journey`).
cost_center_id	integer	sim	ID do centro de custo.
department_id	integer	sim	ID do departamento.
unit_id	integer	sim	ID da unidade.
collaborator_settings_id	integer	sim	ID das configurações.
point_rule_id	integer	sim	ID da regra de ponto.
occupation_id	integer	não	ID do cargo.

Erros possíveis

Status	Código	Quando ocorre
404	journey_not_found	journey_id inexistente ou de outra empresa.
404	cost_center_not_found	cost_center_id inválido.
404	department_not_found	department_id inválido.
404	unit_not_found	unit_id inválido.
404	collaborator_settings_not_found	collaborator_settings_id inválido.
404	point_rule_not_found	point_rule_id inválido.

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
}'

Response201

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

Respostas

201

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

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
}'

Response201

{
  "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)

Nome	Tipo	Obrig.	Descrição
national_registry	string	sim	CPF do colaborador (somente dígitos). Zeros à esquerda são preenchidos automaticamente até 11 caracteres.
photo_base64	base64	sim	Imagem JPEG/PNG codificada em base64 (sem o prefixo `data:image/...`).

Erros possíveis

Status	Código	Quando ocorre
404	cpf_not_found	CPF não cadastrado no sistema.
404	collaborator_not_found	CPF existe, mas não há colaborador vinculado na empresa do token.
422	collaborator_fired	Único colaborador encontrado com esse CPF na empresa está demitido (`dismissal_date` preenchida); upload de foto bloqueado.
403	invalid_photo	Imagem rejeitada (sem rosto, baixa qualidade).
403	face_recognition_failed	Falha 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
  }
}

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
  }
}

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)

Nome	Tipo	Obrig.	Descrição
dismissal_date	date	sim	Data da demissão (YYYY-MM-DD).
fired_type_id	integer	sim	ID do tipo de demissão (ver `GET /fired-type`).
collaborator_id	integer	não	ID do colaborador (use um dos identificadores).
registration_number	string	não	Matrícula do colaborador.
national_registry	string	não	CPF do colaborador (somente dígitos).
fired_description	string	não	Observações da demissão.

Erros possíveis

Status	Código	Quando ocorre
404	collaborator_not_found	Nenhum identificador resolve para um colaborador da empresa.
404	fired_type_not_found	fired_type_id inválido.
422	dismissal_date_before_admission_date	Data 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
  }
}

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
  }
}