Desenvolvedores

API pública do Kivo RH

Conecte seus sistemas a pessoas, colaboradores, EPI, assinaturas e recrutamento, com acesso restrito ao seu grupo.

Começando

Crie uma chave em Configurações › Integrações › API e webhooks. O endereço base é:

Endereço base

https://app.kivorh.com.br/api/public/v1

Primeira chamada

curl -H "Authorization: Bearer <chave>" https://app.kivorh.com.br/api/public/v1/ping

Autenticação

Envie Authorization: Bearer kv_…. A chave vale para todas as empresas do grupo e age como o administrador responsável.

Escopo	O que libera	Módulo necessário
`empresas:read`	Empresas e filiais do cliente, com códigos e CNPJ.	Nenhum
`pessoas:read`	Pessoas, vínculos e estrutura (cargos, departamentos, locais), sem dados sensíveis.	colaboradores
`pessoas:write`	Admitir, atualizar, movimentar, desligar e reativar	colaboradores
`dados_sensiveis:read`	CPF, RG, PIS, CTPS, nascimento, endereço, raça/cor e deficiência (eSocial) e salário	colaboradores
`dados_bancarios:read`	Banco, agência, conta e Pix	colaboradores
`epi:read`	Itens de EPI e entregas registradas.	epi
`epi:write`	Registrar entregas de EPI para colaboradores.	epi
`assinaturas:read`	Modelos, documentos, situação das assinaturas e arquivos PDF.	assinatura
`assinaturas:write`	Criar e enviar documentos, cancelar, lembrar e gerar links de assinatura.	assinatura
`recrutamento:read`	Vagas e candidaturas.	recrutamento
`eventos:read`	Fila de eventos do cliente (os mesmos enviados por webhook).	Nenhum

Erros

Todas as falhas usam { erro, mensagem, detalhes? }.

Status	erro	Quando acontece
401	nao_autenticado	Chave ausente, inválida, expirada ou revogada
403	sem_permissao	Escopo ausente, módulo inativo ou responsável sem acesso
404	nao_encontrado	Registro não encontrado no grupo
409	conflito	O estado atual impede a ação
422	dados_invalidos	Campos ou formatos inválidos
429	limite_excedido	Mais de 120 chamadas no minuto
500	erro_interno	Falha interna sem detalhes técnicos

Exemplo: segundo vínculo

{
  "erro": "conflito",
  "mensagem": "A pessoa já tem vínculo ativo.",
  "detalhes": {
    "conflito": "segundo_vinculo_nao_confirmado",
    "vinculos_existentes": []
  }
}

Paginação e filtros

Use pagina, por_pagina (até 100) e atualizado_desde para sincronização incremental.

Exemplo

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": []
}

Idempotência

Em POSTs compatíveis, envie Idempotency-Key. Por 24 horas, repetir a chave com o mesmo corpo devolve a resposta original e o header Idempotent-Replayed: true. Outro corpo retorna 422.

Limites

120 chamadas por minuto por chave, com headers x-ratelimit-*.
Ao exceder, HTTP 429 com Retry-After: 60.
Corpo JSON de 256 KB; 7 MB na criação de documento.
PDF de até 5 MB e 30 páginas.
Kivo Assinatura tem franquia mensal de documentos: documentos por funcionário × funcionários contratados + adicionais, somada para todas as empresas do grupo e zerada no dia 1 (horário de Brasília). Consulte o consumo em GET /assinaturas/consumo. Quando a franquia do mês acaba, POST /assinaturas/documentos responde 422 com a mensagem pronta.

Webhooks

O Kivo envia o evento por POST e espera um 2xx em até 10 segundos. As novas tentativas ocorrem em 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h. Depois de 50 falhas seguidas e 3 dias sem sucesso, o webhook é desativado. Eventos podem chegar repetidos ou fora de ordem: deduplique pelo id. Como alternativa, consulte GET /eventos?apos=.

Valide Kivo-Assinatura: t=<unix>,v1=<hex> com o segredo inteiro, incluindo whsec_, sobre t + "." + corpo bruto, usando comparação em tempo constante e tolerância de 5 minutos.

Node.js

const raw = await request.text();
const pares = Object.fromEntries(header.split(',').map(p => p.split('=')));
const t = Number(pares.t);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) throw Error('Expirada');
const esperado = Buffer.from(createHmac('sha256', segredoInteiro)
  .update(t + '.' + raw).digest('hex'), 'hex');
const recebido = Buffer.from(pares.v1 ?? '', 'hex');
if (recebido.length !== esperado.length || !timingSafeEqual(recebido, esperado)) throw Error('Inválida');

PHP

$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_KIVO_ASSINATURA']), $p);
if (!isset($p['t'], $p['v1']) || abs(time() - (int)$p['t']) > 300) { http_response_code(401); exit; }
$expected = hash_hmac('sha256', $p['t'].'.'.$raw, $segredoInteiro);
if (!hash_equals($expected, $p['v1'])) { http_response_code(401); exit; }

Evento	Descrição
`colaborador.admitido` { "id": "evt_1024", "tipo": "colaborador.admitido", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "empresa_id": "00000000-0000-0000-0000-000000000000", "matricula": "1024", "nome": "Maria Souza", "status": "ativo", "data_admissao": "2026-09-01", "origem_cadastro": "api" } }	Novo vínculo cadastrado (admissão), por tela, importação ou API.
`colaborador.atualizado` { "id": "evt_1024", "tipo": "colaborador.atualizado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "empresa_id": "00000000-0000-0000-0000-000000000000", "matricula": "1024", "nome": "Maria Souza", "status": "ativo", "campos": [ "cargo_id", "departamento_id" ] } }	Dados do vínculo alterados. Traz só os nomes dos campos alterados.
`colaborador.movimentado` { "id": "evt_1024", "tipo": "colaborador.movimentado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "movimentacao_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "empresa_id": "00000000-0000-0000-0000-000000000000", "tipo": "promocao", "data_efeito": "2026-10-01", "contrato_id": "00000000-0000-0000-0000-000000000000" } }	Movimentação aplicada: promoção, reajuste, transferência, jornada, afastamento.
`colaborador.desligado` { "id": "evt_1024", "tipo": "colaborador.desligado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "empresa_id": "00000000-0000-0000-0000-000000000000", "matricula": "1024", "nome": "Maria Souza", "status": "desligado", "data_desligamento": "2026-09-30", "categoria": "sem_justa_causa" } }	Vínculo desligado.
`colaborador.reativado` { "id": "evt_1024", "tipo": "colaborador.reativado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "empresa_id": "00000000-0000-0000-0000-000000000000", "matricula": "1024", "nome": "Maria Souza", "status": "ativo" } }	Vínculo desligado voltou a ficar ativo.
`colaborador.excluido` { "id": "evt_1024", "tipo": "colaborador.excluido", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "empresa_id": "00000000-0000-0000-0000-000000000000", "matricula": "1024", "nome": "Maria Souza", "status": "ativo" } }	Vínculo excluído (cadastrado por engano).
`pessoa.criada` { "id": "evt_1024", "tipo": "pessoa.criada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "pessoa_id": "00000000-0000-0000-0000-000000000000", "nome": "Maria Souza", "situacao": "ativa", "origem_cadastro": "api" } }	Pessoa nova no cadastro do grupo.
`pessoa.atualizada` { "id": "evt_1024", "tipo": "pessoa.atualizada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "pessoa_id": "00000000-0000-0000-0000-000000000000", "nome": "Maria Souza", "situacao": "ativa", "campos": [ "telefone", "endereco_cep" ] } }	Dados pessoais alterados. Traz só os nomes dos campos alterados.
`documento.enviado` { "id": "evt_1024", "tipo": "documento.enviado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "documento_id": "00000000-0000-0000-0000-000000000000", "codigo_verificacao": "KV-7F3A-92C1", "titulo": "Contrato de trabalho", "status": "enviado", "status_anterior": "rascunho", "empresa_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "modelo_id": "00000000-0000-0000-0000-000000000000", "origem": "manual", "lote_id": null } }	Documento enviado para assinatura.
`documento.assinado` { "id": "evt_1024", "tipo": "documento.assinado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "documento_id": "00000000-0000-0000-0000-000000000000", "codigo_verificacao": "KV-7F3A-92C1", "titulo": "Contrato de trabalho", "colaborador_id": "00000000-0000-0000-0000-000000000000", "modelo_id": "00000000-0000-0000-0000-000000000000", "signatario": { "id": "00000000-0000-0000-0000-000000000000", "papel": "colaborador", "funcao": null, "nome": "Maria Souza", "assinado_em": "2026-09-28T12:00:00Z" } } }	Um signatário assinou (colaborador, testemunha ou empresa).
`documento.concluido` { "id": "evt_1024", "tipo": "documento.concluido", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "documento_id": "00000000-0000-0000-0000-000000000000", "codigo_verificacao": "KV-7F3A-92C1", "titulo": "Contrato de trabalho", "status": "concluido", "status_anterior": "aguardando_empresa", "empresa_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "modelo_id": "00000000-0000-0000-0000-000000000000", "origem": "manual", "lote_id": null } }	Todos assinaram e o PDF final com selo está disponível.
`documento.recusado` { "id": "evt_1024", "tipo": "documento.recusado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "documento_id": "00000000-0000-0000-0000-000000000000", "codigo_verificacao": "KV-7F3A-92C1", "titulo": "Contrato de trabalho", "status": "recusado", "status_anterior": "enviado", "empresa_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "modelo_id": "00000000-0000-0000-0000-000000000000", "origem": "manual", "lote_id": null } }	Um signatário recusou o documento.
`documento.cancelado` { "id": "evt_1024", "tipo": "documento.cancelado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "documento_id": "00000000-0000-0000-0000-000000000000", "codigo_verificacao": "KV-7F3A-92C1", "titulo": "Contrato de trabalho", "status": "cancelado", "status_anterior": "enviado", "empresa_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "modelo_id": "00000000-0000-0000-0000-000000000000", "origem": "manual", "lote_id": null } }	Documento cancelado pelo RH ou pela API.
`documento.expirado` { "id": "evt_1024", "tipo": "documento.expirado", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "documento_id": "00000000-0000-0000-0000-000000000000", "codigo_verificacao": "KV-7F3A-92C1", "titulo": "Contrato de trabalho", "status": "expirado", "status_anterior": "enviado", "empresa_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "modelo_id": "00000000-0000-0000-0000-000000000000", "origem": "manual", "lote_id": null } }	Prazo de assinatura encerrado sem todas as assinaturas.
`epi.entrega.registrada` { "id": "evt_1024", "tipo": "epi.entrega.registrada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "entrega_id": "00000000-0000-0000-0000-000000000000", "codigo": "EPI-000123", "empresa_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "matricula": "1024", "tipo": "entrega", "data_entrega": "2026-09-28", "status": "registrada", "assinado": false } }	Entrega de EPI registrada.
`epi.entrega.assinada` { "id": "evt_1024", "tipo": "epi.entrega.assinada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "entrega_id": "00000000-0000-0000-0000-000000000000", "codigo": "EPI-000123", "empresa_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "matricula": "1024", "tipo": "entrega", "data_entrega": "2026-09-28", "status": "registrada", "assinado": true } }	Ficha da entrega assinada.
`epi.entrega.cancelada` { "id": "evt_1024", "tipo": "epi.entrega.cancelada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "entrega_id": "00000000-0000-0000-0000-000000000000", "codigo": "EPI-000123", "empresa_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "matricula": "1024", "tipo": "entrega", "data_entrega": "2026-09-28", "status": "cancelada", "assinado": false } }	Entrega de EPI cancelada.
`epi.devolucao.registrada` { "id": "evt_1024", "tipo": "epi.devolucao.registrada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "entrega_id": "00000000-0000-0000-0000-000000000000", "entrega_codigo": "EPI-000123", "entrega_item_id": "00000000-0000-0000-0000-000000000000", "epi_item_id": "00000000-0000-0000-0000-000000000000", "colaborador_id": "00000000-0000-0000-0000-000000000000", "pessoa_id": "00000000-0000-0000-0000-000000000000", "quantidade": 1, "devolvido_em": "2026-09-28T12:00:00Z", "destino": "descarte" } }	Devolução de um item de EPI registrada.
`recrutamento.vaga.criada` { "id": "evt_1024", "tipo": "recrutamento.vaga.criada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "vaga_id": "00000000-0000-0000-0000-000000000000", "numero": 42, "titulo": "Analista de DP", "status": "rascunho", "status_anterior": null, "empresa_id": "00000000-0000-0000-0000-000000000000" } }	Vaga criada.
`recrutamento.vaga.atualizada` { "id": "evt_1024", "tipo": "recrutamento.vaga.atualizada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "vaga_id": "00000000-0000-0000-0000-000000000000", "numero": 42, "titulo": "Analista de DP", "status": "aberta", "status_anterior": "rascunho", "empresa_id": "00000000-0000-0000-0000-000000000000" } }	Situação da vaga mudou (aberta, fechada, rascunho).
`recrutamento.candidatura.criada` { "id": "evt_1024", "tipo": "recrutamento.candidatura.criada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "candidatura_id": "00000000-0000-0000-0000-000000000000", "vaga_id": "00000000-0000-0000-0000-000000000000", "candidato_id": "00000000-0000-0000-0000-000000000000", "etapa_id": "00000000-0000-0000-0000-000000000000", "status": "em_andamento", "status_anterior": null, "etapa_anterior_id": null } }	Nova candidatura em uma vaga.
`recrutamento.candidatura.atualizada` { "id": "evt_1024", "tipo": "recrutamento.candidatura.atualizada", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "candidatura_id": "00000000-0000-0000-0000-000000000000", "vaga_id": "00000000-0000-0000-0000-000000000000", "candidato_id": "00000000-0000-0000-0000-000000000000", "etapa_id": "00000000-0000-0000-0000-000000000000", "status": "em_andamento", "status_anterior": "em_andamento", "etapa_anterior_id": "00000000-0000-0000-0000-000000000000" } }	Candidatura mudou de etapa ou de situação (inclusive contratado).
`webhook.teste` { "id": "evt_1024", "tipo": "webhook.teste", "criado_em": "2026-09-28T12:00:00Z", "cliente": 12, "empresa_id": "00000000-0000-0000-0000-000000000000", "tentativa": 1, "dados": { "mensagem": "Teste de webhook do Kivo RH", "webhook_id": "00000000-0000-0000-0000-000000000000", "webhook_nome": "ERP" } }	Enviado só pelo botão de teste do webhook.

Referência

Diagnóstico

get/openapi.json

Esta especificação

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/openapi.json'

Resposta

{}

get/ping

Valida a chave e mostra cliente, responsável e escopos

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/ping' \
  -H 'Authorization: Bearer <chave>'

Resposta

{}

Empresas

get/empresas

Empresas e filiais do cliente

Escopo exigido: empresas:read

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/empresas' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Estrutura

get/cargos

Lista cargos do grupo

Escopo exigido: pessoas:read

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/cargos' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

get/centros-custo

Lista centros de custo do grupo

Escopo exigido: pessoas:read

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/centros-custo' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

get/departamentos

Lista departamentos do grupo

Escopo exigido: pessoas:read

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/departamentos' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

get/equipes

Lista equipes do grupo

Escopo exigido: pessoas:read

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/equipes' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

get/locais

Lista locais do grupo

Escopo exigido: pessoas:read

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/locais' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Pessoas

get/pessoas

Lista pessoas do grupo

Escopo exigido: pessoas:read

Parâmetros

Nome	Local	Tipo	Descrição
`pagina`	query	integer	—
`por_pagina`	query	integer	—
`situacao`	query	string	—
`busca`	query	string	—
`cpf`	query	string	—
`atualizado_desde`	query	string (date-time)	—
`ordem`	query	string	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/pessoas' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

get/pessoas/{id}

Obtém uma pessoa

Escopo exigido: pessoas:read

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/pessoas/<id>' \
  -H 'Authorization: Bearer <chave>'

Resposta

{}

patch/pessoas/{id}

Atualiza contato e endereço da pessoa

Escopo exigido: pessoas:write

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—

Corpo

Campo	Tipo	Obrigatório	Descrição
`nome_social`	string	Não	—
`email_pessoal`	string	Não	—
`telefone`	string	Não	—
`telefone_alternativo`	string	Não	—
`estado_civil`	string	Não	—
`endereco_cep`	string	Não	—
`endereco_logradouro`	string	Não	—
`endereco_numero`	string	Não	—
`endereco_complemento`	string	Não	—
`endereco_bairro`	string	Não	—
`endereco_cidade`	string	Não	—
`endereco_uf`	string	Não	—

Requisição

curl -X PATCH 'https://app.kivorh.com.br/api/public/v1/pessoas/<id>' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"telefone":"(11) 99999-0000","endereco_cidade":"São Paulo"}'

Resposta

{}

Colaboradores

get/colaboradores

Lista vínculos (colaboradores)

Escopo exigido: pessoas:read

Parâmetros

Nome	Local	Tipo	Descrição
`pagina`	query	integer	—
`por_pagina`	query	integer	—
`empresa_id`	query	string (uuid)	—
`status`	query	string	—
`cargo_id`	query	string (uuid)	—
`departamento_id`	query	string (uuid)	—
`pessoa_id`	query	string (uuid)	—
`matricula`	query	string	—
`cpf`	query	string	—
`busca`	query	string	—
`atualizado_desde`	query	string (date-time)	—
`ordem`	query	string	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/colaboradores' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

post/colaboradores

Admite um colaborador

Escopo exigido: pessoas:write

Parâmetros

Nome	Local	Tipo	Descrição
`Idempotency-Key`	header	string	Repetir a mesma chave com o mesmo corpo devolve a resposta original (header Idempotent-Replayed: true).

Corpo

Campo	Tipo	Obrigatório	Descrição
`empresa_id`	string (uuid)	Sim	—
`nome_completo`	string	Sim	—
`cpf`	string	Sim	—
`data_admissao`	string (date)	Sim	—
`matricula`	string	Não	—
`cargo_id`	string (uuid)	Não	—
`departamento_id`	string (uuid)	Não	—
`regime`	string	Não	—
`salario`	number	Não	—
`carga_horaria_semanal`	number	Não	—
`status`	string	Não	—
`categoria_trabalhador`	string	Não	—
`tipo_duracao_contrato`	string	Não	—
`email_pessoal`	string (email)	Não	—
`telefone`	string	Não	—
`data_nascimento`	string (date)	Não	—
`confirmar_segundo_vinculo`	boolean	Não	Confirme quando a pessoa já tem outro vínculo ativo

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/colaboradores' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"empresa_id":"00000000-0000-0000-0000-000000000000","nome_completo":"Maria Souza","cpf":"12345678909","data_admissao":"2026-10-01"}'

Resposta

{}

get/colaboradores/{id}

Obtém um vínculo

Escopo exigido: pessoas:read

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/colaboradores/<id>' \
  -H 'Authorization: Bearer <chave>'

Resposta

{}

patch/colaboradores/{id}

Atualiza dados do vínculo

Escopo exigido: pessoas:write

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—

Corpo

Campo	Tipo	Obrigatório	Descrição
`email_corporativo`	string	Não	—
`gestor_id`	string (uuid)	Não	—
`numero_folha`	string	Não	—
`codigo_holerite`	string	Não	—
`numero_identificador`	string	Não	—
`observacoes`	string	Não	—

Requisição

curl -X PATCH 'https://app.kivorh.com.br/api/public/v1/colaboradores/<id>' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"email_corporativo":"texto","gestor_id":"00000000-0000-0000-0000-000000000000","numero_folha":"texto","codigo_holerite":"texto","numero_identificador":"texto","observacoes":"texto"}'

Resposta

{}

post/colaboradores/{id}/desligamento

Desliga o colaborador

Escopo exigido: pessoas:write

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—
`Idempotency-Key`	header	string	Repetir a mesma chave com o mesmo corpo devolve a resposta original (header Idempotent-Replayed: true).

Corpo

Campo	Tipo	Obrigatório	Descrição
`data_desligamento`	string (date)	Sim	—
`categoria`	string	Sim	—
`motivo`	string	Sim	—
`causa`	string	Não	—
`aviso_previo_tipo`	string	Não	—
`aviso_previo_dias`	integer	Não	—
`aviso_previo_inicio`	string (date)	Não	—
`ciente_estabilidade`	boolean	Não	—
`justificativa_epi`	string	Não	—

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/colaboradores/<id>/desligamento' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"data_desligamento":"2026-10-01","categoria":"texto","motivo":"texto","causa":"texto","aviso_previo_tipo":"texto","aviso_previo_dias":1,"aviso_previo_inicio":"2026-10-01","ciente_estabilidade":true,"justificativa_epi":"texto"}'

Resposta

{}

post/colaboradores/{id}/movimentacoes

Registra movimentação

Escopo exigido: pessoas:write

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—
`Idempotency-Key`	header	string	Repetir a mesma chave com o mesmo corpo devolve a resposta original (header Idempotent-Replayed: true).

Corpo

Campo	Tipo	Obrigatório	Descrição
`tipo`	string	Sim	promocao, reajuste, transferencia, jornada, afastamento, retorno…
`data_efeito`	string (date)	Sim	—
`cargo_id`	string (uuid)	Não	—
`departamento_id`	string (uuid)	Não	—
`centro_custo_id`	string (uuid)	Não	—
`local_trabalho_id`	string (uuid)	Não	—
`equipe_id`	string (uuid)	Não	—
`novo_salario`	number	Não	—
`regime`	string	Não	—
`carga_horaria_semanal`	number	Não	—
`motivo`	string	Não	—
`motivo_afastamento`	string	Não	—
`previsao_retorno`	string (date)	Não	—

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/colaboradores/<id>/movimentacoes' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"tipo":"texto","data_efeito":"2026-10-01","cargo_id":"00000000-0000-0000-0000-000000000000","departamento_id":"00000000-0000-0000-0000-000000000000","centro_custo_id":"00000000-0000-0000-0000-000000000000","local_trabalho_id":"00000000-0000-0000-0000-000000000000","equipe_id":"00000000-0000-0000-0000-000000000000","novo_salario":1,"regime":"texto","carga_horaria_semanal":1,"motivo":"texto","motivo_afastamento":"texto","previsao_retorno":"2026-10-01"}'

Resposta

{}

post/colaboradores/{id}/reativacao

Reativa um vínculo desligado

Escopo exigido: pessoas:write

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—
`Idempotency-Key`	header	string	Repetir a mesma chave com o mesmo corpo devolve a resposta original (header Idempotent-Replayed: true).

Corpo

Campo	Tipo	Obrigatório	Descrição
`motivo`	string	Sim	—

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/colaboradores/<id>/reativacao' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"motivo":"texto"}'

Resposta

{}

EPI

get/epi/entregas

Entregas de EPI

Escopo exigido: epi:read

Parâmetros

Nome	Local	Tipo	Descrição
`pagina`	query	integer	—
`por_pagina`	query	integer	—
`empresa_id`	query	string (uuid)	—
`colaborador_id`	query	string (uuid)	—
`pessoa_id`	query	string (uuid)	—
`status`	query	string	—
`data_de`	query	string (date)	—
`data_ate`	query	string (date)	—
`atualizado_desde`	query	string (date-time)	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/epi/entregas' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

post/epi/entregas

Registra entrega de EPI

Escopo exigido: epi:write

Parâmetros

Nome	Local	Tipo	Descrição
`Idempotency-Key`	header	string	Repetir a mesma chave com o mesmo corpo devolve a resposta original (header Idempotent-Replayed: true).

Corpo

Campo	Tipo	Obrigatório	Descrição
`colaborador_id`	string (uuid)	Sim	—
`itens`	lista de object	Sim	—
`empresa_id`	string (uuid)	Não	—
`data_entrega`	string (date)	Não	—
`tipo`	string	Não	—
`almoxarifado_id`	string (uuid)	Não	—
`observacoes`	string	Não	—
`orientacoes_fornecidas`	boolean	Não	—
`manual_entregue`	boolean	Não	—
`treinamento_verificado`	boolean	Não	—
`justificativa_sem_treinamento`	string	Não	—
`orientacao_data`	string (date)	Não	—
`orientacao_observacoes`	string	Não	—

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/epi/entregas' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"colaborador_id":"00000000-0000-0000-0000-000000000000","itens":[{"epi_item_id":"00000000-0000-0000-0000-000000000000","quantidade":1,"lote_id":"00000000-0000-0000-0000-000000000000","unidade_serie_id":"00000000-0000-0000-0000-000000000000","motivo":"texto"}],"empresa_id":"00000000-0000-0000-0000-000000000000","data_entrega":"2026-10-01","tipo":"primeira_entrega","almoxarifado_id":"00000000-0000-0000-0000-000000000000","observacoes":"texto","orientacoes_fornecidas":true,"manual_entregue":true,"treinamento_verificado":true,"justificativa_sem_treinamento":"texto","orientacao_data":"2026-10-01","orientacao_observacoes":"texto"}'

Resposta

{}

get/epi/entregas/{id}

Obtém uma entrega

Escopo exigido: epi:read

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/epi/entregas/<id>' \
  -H 'Authorization: Bearer <chave>'

Resposta

{}

get/epi/itens

Itens de EPI

Escopo exigido: epi:read

Parâmetros

Nome	Local	Tipo	Descrição
`busca`	query	string	—
`ativo`	query	string	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/epi/itens' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Assinaturas

get/assinaturas/consumo

Franquia de documentos do mês

Escopo exigido: assinaturas:read

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/assinaturas/consumo' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "mes": "2026-09",
  "inicio": "2026-09-01",
  "reinicia_em": "2026-10-01",
  "ilimitado": false,
  "por_colaborador": 5,
  "base_colaboradores": 40,
  "base_origem": "contratados",
  "adicionais": 0,
  "excedente": "bloquear",
  "franquia": 200,
  "usados": 9,
  "restantes": 191,
  "excedentes": 0,
  "percentual": 4.5,
  "bloqueado": false,
  "origens": {
    "por_colaborador": "padrao",
    "adicionais": "padrao",
    "excedente": "padrao"
  }
}

get/assinaturas/documentos

Documentos de assinatura

Escopo exigido: assinaturas:read

Parâmetros

Nome	Local	Tipo	Descrição
`pagina`	query	integer	—
`por_pagina`	query	integer	—
`status`	query	string	—
`colaborador_id`	query	string (uuid)	—
`pessoa_id`	query	string (uuid)	—
`empresa_id`	query	string (uuid)	—
`modelo_id`	query	string (uuid)	—
`origem`	query	string	—
`criado_de`	query	string (date)	—
`criado_ate`	query	string (date)	—
`atualizado_desde`	query	string (date-time)	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/assinaturas/documentos' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

post/assinaturas/documentos

Cria e envia um documento para assinatura

Escopo exigido: assinaturas:write

Parâmetros

Nome	Local	Tipo	Descrição
`Idempotency-Key`	header	string	Repetir a mesma chave com o mesmo corpo devolve a resposta original (header Idempotent-Replayed: true).

Corpo

Campo	Tipo	Obrigatório	Descrição
`colaborador_id`	string (uuid)	Sim	—
`modelo_id`	string (uuid)	Sim	—
`titulo`	string	Não	Obrigatório quando o modelo não gera o documento
`arquivo_pdf_base64`	string	Não	PDF em base64 (até 5 MB e 30 páginas). Só para modelos sem texto.
`notificar`	boolean	Não	Enviar e-mail ao colaborador (padrão true)
`signatarios_adicionais`	lista de object	Não	—

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/assinaturas/documentos' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"colaborador_id":"00000000-0000-0000-0000-000000000000","modelo_id":"00000000-0000-0000-0000-000000000000","titulo":"texto","arquivo_pdf_base64":"texto","notificar":true,"signatarios_adicionais":[{"nome":"texto","email":"pessoa@empresa.com.br","cpf":"texto","funcao":"texto"}]}'

Resposta

{}

get/assinaturas/documentos/{id}

Obtém um documento

Escopo exigido: assinaturas:read

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/assinaturas/documentos/<id>' \
  -H 'Authorization: Bearer <chave>'

Resposta

{}

get/assinaturas/documentos/{id}/arquivo

Baixa o PDF (final ou original)

Escopo exigido: assinaturas:read

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—
`versao`	query	string	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/assinaturas/documentos/<id>/arquivo' \
  -H 'Authorization: Bearer <chave>'

post/assinaturas/documentos/{id}/cancelamento

Cancela o documento

Escopo exigido: assinaturas:write

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—
`Idempotency-Key`	header	string	Repetir a mesma chave com o mesmo corpo devolve a resposta original (header Idempotent-Replayed: true).

Corpo

Campo	Tipo	Obrigatório	Descrição
`motivo`	string	Sim	—

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/assinaturas/documentos/<id>/cancelamento' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"motivo":"texto"}'

Resposta

{}

post/assinaturas/documentos/{id}/lembretes

Envia lembrete agora

Escopo exigido: assinaturas:write

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—
`Idempotency-Key`	header	string	Repetir a mesma chave com o mesmo corpo devolve a resposta original (header Idempotent-Replayed: true).

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/assinaturas/documentos/<id>/lembretes' \
  -H 'Authorization: Bearer <chave>'

Resposta

{}

post/assinaturas/documentos/{id}/links

Gera link de assinatura

Escopo exigido: assinaturas:write

Parâmetros

Nome	Local	Tipo	Descrição
`id`	path	string (uuid)	—

Corpo

Campo	Tipo	Obrigatório	Descrição
`signatario_id`	string (uuid)	Não	Testemunha na vez (vazio = colaborador)

Requisição

curl -X POST 'https://app.kivorh.com.br/api/public/v1/assinaturas/documentos/<id>/links' \
  -H 'Authorization: Bearer <chave>' \
  -H 'Content-Type: application/json' \
  -d '{"signatario_id":"00000000-0000-0000-0000-000000000000"}'

Resposta

{}

get/assinaturas/modelos

Modelos de documento

Escopo exigido: assinaturas:read

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/assinaturas/modelos' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Recrutamento

get/recrutamento/candidaturas

Candidaturas

Escopo exigido: recrutamento:read

Parâmetros

Nome	Local	Tipo	Descrição
`pagina`	query	integer	—
`por_pagina`	query	integer	—
`vaga_id`	query	string (uuid)	—
`status`	query	string	—
`desde`	query	string (date-time)	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/recrutamento/candidaturas' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

get/recrutamento/vagas

Vagas

Escopo exigido: recrutamento:read

Parâmetros

Nome	Local	Tipo	Descrição
`pagina`	query	integer	—
`por_pagina`	query	integer	—
`status`	query	string	—
`atualizado_desde`	query	string (date-time)	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/recrutamento/vagas' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 12,
  "pagina": 1,
  "por_pagina": 50,
  "total": 1,
  "dados": [
    {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Eventos

get/eventos

Eventos do cliente em ordem (mesmos do webhook)

Escopo exigido: eventos:read

Parâmetros

Nome	Local	Tipo	Descrição
`apos`	query	string	—
`limite`	query	integer	—
`tipos`	query	string	—

Requisição

curl -X GET 'https://app.kivorh.com.br/api/public/v1/eventos' \
  -H 'Authorization: Bearer <chave>'

Resposta

{
  "cliente": 1,
  "dados": [
    {
      "id": "evt_1024",
      "tipo": "colaborador.admitido",
      "criado_em": "2026-09-28T12:00:00Z",
      "cliente": 12,
      "empresa_id": "00000000-0000-0000-0000-000000000000",
      "dados": {
        "colaborador_id": "00000000-0000-0000-0000-000000000000",
        "pessoa_id": "00000000-0000-0000-0000-000000000000",
        "empresa_id": "00000000-0000-0000-0000-000000000000",
        "matricula": "1024",
        "nome": "Maria Souza",
        "status": "ativo",
        "data_admissao": "2026-09-01",
        "origem_cadastro": "api"
      }
    }
  ],
  "proximo_apos": "texto",
  "tem_mais": true
}