NAV

Introdução

Nossa API é baseada no modelo REST, disponibilizando endpoints para consumo e atualização de dados na nossa plataforma, suportando até cinquenta (50) requisições por minuto. Sua empresa pode tirar proveito integrando-se a nossos sistemas ou mesmo consolidando estes dados em plataformas de análise.

Disponibilizamos também webhooks que podem notificar seu sistema de que um evento aconteceu. Com isso seu sistema não precisa consultar nossa API periodicamente, bastando requisitar a informação nova quando esta for atualizada. Os webhooks estão documentados adiante neste documento.

Cadastre-se em nossa Newsletter para receber novidades sobre nossa API ou veja as últimas alterações no Histórico de Alterações.

Autenticação

Todas as requisições devem ser autenticadas para que os dados referentes a empresa, e somente a ela, sejam disponibilizados. Esta autenticação é realizada a partir de um token, gerado a partir de nossa plataforma. Confira este artigo para saber como gerar o token. O token deve ser enviado no cabeçalho (header) da requisição HTTPS.

Dados do Sistema

Obter dados de etnias

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "1",
      "name": "Indígena"
    }
  ],
  "redirect": null,
  "success": true
}

São retornadas todas as etnias disponíveis na Convenia.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/ethnicities

Obter dados de nacionalidades

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "9",
      "name": "Naturalizado Brasileiro"
    }
  ],
  "redirect": null,
  "success": true
}

São retornadas todas as nacionalidades disponíveis na Convenia.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/nationalities

Obter dados de estados

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "1",
      "name": "Acre"
    }
  ],
  "redirect": null,
  "success": true
}

São retornados todos os estados disponíveis na Convenia.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/states

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter dados de cidades

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "1",
      "name": "Acrelândia"
    }
  ],
  "redirect": null,
  "success": true
}

São retornadas todas as cidades disponíveis na Convenia.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/cities

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Query Params

Name Value Obrigatório Tipo Descrição
state_id id do estado não inteiro Retorna as cidades pertencentes ao estado inserido através de seu identificador. É possível visualizar os ids possíveis para estado no Endpoint de listagem de estados
state_abbreviation uf não texto Retorna as cidades pertencentes ao estado inserido através de sua sigla. É possível visualizar as ufs possíveis para estado no Endpoint de listagem de estados
state_name nome do estado não texto Retorna as cidades pertencentes ao estado inserido através de seu nome. É possível visualizar os nomes possíveis para estado no Endpoint de listagem de estados

Ao utilizar múltiplos query params, o retorno levará em conta apenas um deles seguindo a prioridade: state_id, state_abbreviation e state_name.

Colaboradores

Obter todos os colaboradores

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "2e6c8997-3237-4868-a7f0-ddecf7d79777",
      "name": "Colaborador",
      "last_name": "A",
      "email": "colaboradorA@email.com",
      "document": {
        "pis": "XXX.XXXXX.XX-X",
        "cpf": "XXX.XXX.XXX-XX"
      },
      "hiring_date": "AAAA-MM-DD"
    }
  ],
  "redirect": null,
  "success": true
}

São retornados todos os colaboradores ativos na plataforma.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter todos os colaboradores desligados

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "0c7b9a96-bda9-438b-8b19-16b0bd866706",
      "dismissal": {
        "id": "c5665842-e101-4e2f-bbfe-74eb00961903",
        "date": "AAAA-MM-DD",
        "type": {
          "id": 26,
          "title": "Suspensão de contrato"
        }
      }
    }
  ],
  "redirect": null,
  "success": true
}

É retornada uma lista com todos os colaboradores desligados da plataforma.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/dismissed

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Query Params

Name Value Obrigatório Tipo Descrição
from_date data não AAAA-MM-DD Retorna os colaboradores desligados após a data inserida
to_date data não AAAA-MM-DD Retorna os colaboradores desligados anteriores à data inserida

Obter um colaborador especifico

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": {
      "id": "b33c2606-66be-4f09-a493-2132c524952e",
      "name": "Colaborador",
      "last_name": "A",
      "mother_name": "Mãe de A",
      "father_name": "Pai de A",
      "email": "colaboradorA@email.com",
      "alternative_email": "colaborador.pessoal@email.com",
      "hiring_date": "AAAA-MM-DD",
      "phone": "(XX) XXXX-XXXX",
      "cellphone": "(XX) XXXXX-XXXX",
      "registration": "123",
      "gender": "M/F",
      "birth_date": "AAAA-MM-DD",
      "salary": 1000.00,
      "natural_from_state_uf": "SP",
      "natural_from_city_name": "São Paulo",
      "marital_status_id": "Solteiro",
      "first_job": true,
      "gender_identity_id": 8,
      "gender_identity": {
        "id": 8,
        "name": "Não-binário"
      },
      "relationship_id": 1,
      "relationship": {
        "id": 1,
        "name": "CLT"
      },
      "ethnicity_id": 1,
      "ethnicity": {
        "id": 1,
        "name": "Indígena"
      },
      "document": {
        "cpf": "XXX.XXX.XXX-XX",
        "rg": "XX.XXX.XXX-X",
        "rg_expedition": "AAAA-MM-DD",
        "rg_emission": "SSP",
        "rg_uf": "SP",
        "pis": "XXX.XXXXX.XX-X",
        "ctps": "XXXXXXX",
        "ctps_serial": "XXXX",
        "ctps_emission_date": "AAAA-MM-DD",
        "ctps_uf": "SP",
        "voter_card": "XXXXXXXXXXXXX",
        "voter_card_zone": "XXX",
        "voter_card_section": "XXXX"
      },
      "department": {
        "id": "9d2d3417-0ddf-4aad-bd86-b9c5f1b29e6a",
        "name": "Departamento"
      },
      "job": {
        "id": "903c2e29-41b0-4198-8648-ba60e7a3c9d7",
        "name": "Cargo"
      },
      "dismissal": {
        "id": "82c32ede-2e49-42da-915d-d1803c15d23c",
        "date": "AAAA-MM-DD"
      },
      "supervisor": {
        "id": "fa8f0bb3-e2f7-425e-bfcd-a7cc79427ac0",
        "name": "Gestor",
        "last_name": "C"
      },
      "cost_center": {
        "id": "51756826-3906-4d03-9cb6-b2df59a47a16",
        "name": "Centro de Custo"
      },
      "salary_type": {
        "id": 1,
        "name": "Mensalista"
      },
      "address": {
        "id": "51756826-3906-4d03-9cb6-b2df59a47a16",
        "address": "Rua",
        "number": "123",
        "complement": "APTO",
        "zip_code": "XXXXX-XXX",
        "state": "SP",
        "city": "São Paulo",
        "district": "Bairro"
      },
      "benefits": [
        {
          "id": "58458737-6940-441f-9659-e6ec1290a5b9",
          "benefit_id": "ac82da39-aecd-4ada-9eb2-03de0b01665e",
          "name": "Vale Transporte",
          "operator": "Operador",
          "employee_value": 10.00,
          "company_value": 15.00,
          "type": "Vale Transporte",
          "payment_method": "Fixo mensal"
        }
      ],
      "custom_fields": [
        {
          "id": "ca8fbd5e-215a-4524-a6d7-2ddc1f27b035",
          "custom_field_id": "404806b4-e4c5-4dea-9ef6-01f47236182b",
          "name": "Campo Customizado",
          "value": "Camiseta M"
        }
      ],
      "educations":  [
        {
          "id": "b03852b4-3fab-4df4-8317-7879e7f72ff1",
          "education_type_id": 11,
          "education_type": {
            "id":  11,
            "name": "Doutorado completo"
          },
          "course": "Curso",
          "institution": "Instituição",
          "graduation_year": "2021"
        }
      ],
      "bank_account": {
        "id": "12c3cbc6-8562-4d38-a0fc-12561f06c4c5",
        "bank_id": 1,
        "bank": {
          "id":  1,
          "name": "Nome do banco"
        },
        "account": "Número da conta",
        "agency": "Número da agência",
        "digit": "Dígito da conta",
        "pix": "Pix colaborador A",
        "modality": "PJ",
        "account_type_id": "1",
        "account_type": {
          "id":  1,
          "name": "Conta Corrente"
        }
      },
      "bank_accounts": [
        {
          "id": "12c3cbc6-8562-4d38-a0fc-12561f06c4c5",
          "bank_id": 1,
          "bank": {
            "id":  1,
            "name": "Nome do banco"
          },
          "account": "Número da conta",
          "agency": "Número da agência",
          "digit": "Dígito da conta",
          "pix": "Pix colaborador A",
          "modality": "PJ",
          "account_type_id": "1",
          "account_type": {
            "id":  1,
            "name": "Conta Corrente"
          }
        }
      ],
      "experience_period": {
        "type_id": 1,
        "type": {
          "id": 1,
          "name": "1 x 45 dias"
        },
        "first_end": "AAAA-MM-DD",
        "second_end": "AAAA-MM-DD",
        "total_days": "45"
      },
      "time_tracking": true
  },
  "redirect": null,
  "success": true
}

Esse endpoint retorna o detalhe de um colaborador especifico da plataforma através de seu identificador único.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/<ID do Colaborador>

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter o histórico salarial de um colaborador

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "f10e1989-5f73-4845-9160-7faea8998207",
      "salary": 1000.00,
      "relationship_id": 1,
      "relationship": {
        "id": 1,
        "name": "clt"
      },
      "department_id": "82ab854d-a066-480a-a607-b8d3cd30a2ed",
      "department": {
        "id": "82ab854d-a066-480a-a607-b8d3cd30a2ed",
        "name": "Departamento"
      },
      "job_description_id": "9ca044e0-0ee1-43fb-a3d6-fc51fb728b05",
      "job": {
        "id": "9ca044e0-0ee1-43fb-a3d6-fc51fb728b05",
        "name": "Cargo"
      },
      "cost_center_id": "f985c237-5e81-48e8-b068-e93461c8fa7c",
      "cost_center": {
        "id": "f985c237-5e81-48e8-b068-e93461c8fa7c",
        "name": "Centro de custo"
      },
      "motive_id": 1,
      "motive": {
        "id": 1,
        "name": "Promoção"
      },
      "description": "Descrição",
      "is_active": true,
      "date_from": "AAAA-MM-DD",
      "date_to": "AAAA-MM-DD",
      "created_at": "AAAA-MM-DD",
      "updated_at": "AAAA-MM-DD"
    }
  ],
  "redirect": null,
  "success": true
}

Entradas de alterações salariais de um colaborador através de seu identificado único.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/{ColaboradorID}/salaries-historic

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter dependentes relacionados a um colaborador

Este endpoint retorna um objeto com dependentes de um colaborador e seus benefícios, definidos na seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "f10e1989-5f73-4845-9160-7faea8998207",
      "employee_id": "33fb5be0-5614-43b3-83f6-b36a087f3699",
      "name": "Colaborador",
      "last_name": "B",
      "email": "colaboradorb@gmail.com",
      "birth_date": "AAAA-MM-DD 00:00:00",
      "cpf": "XXX.XXX.XXX-XX",
      "mother_name": "Mãe do Colaborador",
      "dependent_relation": "Filho ou enteado universitário ou escola técnica",
      "dependent_relation_description": "Filho(a) ou enteado(a) universitário(a) ou cursando escola técnica de 2º grau, até 24 (vinte e quatro) anos.",
      "relation_esocial_id": 22,
      "ir": true,
      "foreigner": true,
      "family_salary": true,
      "description": "Descrição",
      "phone": "(XX) XXXX-XXXX",
      "benefits": {
        "benefit_id": "ac82da39-aecd-4ada-9eb2-03de0b01665e",
        "name": "Vale Transporte",
        "operator": "Operador",
        "dependent_value": 10.00,
        "company_value": 15.00,
        "type": "Vale Transporte",
        "payment_method": "Fixo mensal"
      }      
    }
  ],
  "redirect": null,
  "success": true
}

Listagem de detalhes de dependentes relacionados a um colaborador através de seu identificador único.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/{ColaboradorID}/dependents

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Iniciar a admissão de um colaborador

Esta requisição retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "521260c6-3433-49d2-800a-48e614958183",
      "status": 0,
      "employee": {
        "id": "1d93b0b1-6b93-4670-b8ae-7f4df7f3ff86",
        "name": "Colaborador",
        "last_name": "A",
        "job": "Cargo",
        "department": "Departamento",
        "registration": 123,
        "birth_date": "AAAA-MM-DD",
        "gender": "M/F",
        "marital_status_id": "Solteiro",
        "relationship_id": 1,
        "father_name": "Pai do Colaborador",
        "mother_name": "Mãe do Colaborador",
        "hiring_date": "AAAA-MM-DD",
        "salary": 1000.00,
        "personal_email": "colaboradora@gmail.com",
        "phone": "1188887777",
        "cell": "11988887777",
        "natural_from_state_uf": "SP",
        "natural_from_city": "Adamantina",
        "first_job": false,
        "nationality_id": 9,
        "nationality": {
          "id": 9,
          "name": "Naturalizado Brasileiro"
        },
        "ethnicity_id": 1,
        "ethnicity": {
          "id": 1,
          "name": "Indígena"
        },
        "documents": {
          "cpf": "XXXXXXXXXXX",
          "rg": "XXXXXXXXXX",
          "rg_expedition": "YYYY-mm-dd",
          "rg_emission": "SP",
          "voter_card": "XXXXXXXXXXXX",
          "voter_card_zone": "XXX",
          "voter_card_section": "XXXX",
          "ctps": "XXXXXX",
          "ctps_serie": "XXXXX-XX",
          "ctps_emission": "YYYY-mm-dd",
          "cnh": "XXXXXXXXXXX",
          "pis": "XXXXXXXXXXXXX"
        },
        "address": {
          "zip_code": "XXXXXXXX",
          "address": "Rua",
          "complement": "Apto",
          "number": 123,
          "district": "Bairro",
          "city": "Adamantina",
          "state": "SP"
        },
        "education": {
          "course": "Curso",
          "institution": "Instituição",
          "graduation_year": 2021,
          "education_type_id": 8,
          "educationType": {
            "name": "Educação Superior incompleta"
          }
        },
        "bankAccount": {
          "account": 123,
          "agency": 456,
          "digit": 9,
          "accountant_type_id": 2,
          "bank_id": 1,
          "bank": {
            "name": "ABC Brasil S.A.",
            "code": 246
          }
        }
      }
    }
  ],
  "redirect": null,
  "success": true
}

Esse endpoint é responsável por criar o colaborador na plataforma e iniciar uma nova admissão para ele.

HTTP Request

POST https://public-api.convenia.com.br/api/v3/employees/admission

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Payload

Campo Obrigatório Tipo Formato Descrição
name sim texto texto Nome do colaborador
last_name sim texto texto Sobrenome do colaborador
job não texto texto Nome do cargo (Caso o nome exista na plataforma o valor será vinculado)
department não texto texto Nome do departamento (Caso o nome exista na plataforma o valor será vinculado)
registration não texto texto Matrícula
birth_date não texto AAAA-MM-DD Matrícula
gender não texto texto Sexo do colaborador (M ou F)
relationship_id não inteiro id Identificador do vínculo
marital_status_id não inteiro id Identificador do estado civil
father_name não texto texto Nome do pai
mother_name não texto texto Nome da mãe
salary não ponto flutuante 1000.00 Salário
personal_email não texto email Email pessoal do colaborador
phone não texto texto Telefone
cell não texto texto Celular
natural_from_state_uf não (exceto quando há valor para inclusão de cidade e o campo natural_from_state_id não está presente) texto UF UF do estado natal do colaborador. É possível visualizar os possíveis estados no endpoint de listagem de estados
natural_from_state_id não (exceto quando há valor para inclusão de cidade e o campo natural_from_state_uf não está presente) inteiro id Id do estado natal do colaborador. É possível visualizar os possíveis estados no Endpoint de listagem de estados
natural_from_city não texto texto Cidade natal do colaborador. É possível visualizar as possíveis cidades no Endpoint de listagem de cidades
natural_from_city_id não inteiro id Id da cidade natal do colaborador. É possível visualizar as possíveis cidades no Endpoint de listagem de cidades
ethnicity_id não inteiro id Identificador da etnia
nationality_id não inteiro id Identificador da nacionalidade
first_job não boleano boleano Indicador se esse é ou não o primeiro emprego desse colaborador
documents[cpf] não texto texto CPF
documents[rg] não texto texto RG
documents[rg_expedition] não texto AAAA-MM-DD Data de expedição do RG
documents[rg_emission] não texto AAAA-MM-DD Orgão emissor do RG
documents[voter_card] não texto texto Título de eleitor
documents[voter_card_section] não texto texto Seção do título de eleitor
documents[ctps] não texto texto Carteira de trabalho
documents[ctps_serie] não texto texto Número de série da carteira de trabalho
documents[ctps_emission] não texto AAAA-MM-DD Data de emissão da CTPS
documents[cnh] não texto texto CNH
documents[pis] não texto texto PIS
address[zip_code] não texto texto CEP
address[address] não texto texto Endereço
address[complement] não texto texto Complemento
address[number] não texto texto Número
address[district] não texto texto Bairro
address[city] não texto texto Nome da cidade. É possível visualizar os nomes possíveis para cidade no Endpoint de listagem de cidades
address[city_id] não inteiro id Id da cidade. É possível visualizar os ids possíveis para cidade no Endpoint de listagem de cidades
address[state] não (exceto quando há valor para inclusão de cidade e o campo address[state_id] não está presente) texto texto UF do estado. É possível visualizar os possíveis estados no endpoint de listagem de estados
address[state_id] não (exceto quando há valor para inclusão de cidade e o campo address[state_id] não está presente) inteiro id Id do estado. É possível visualizar os possíveis estados no endpoint de listagem de estados
education[course] não texto texto Nome do curso
education[institution] não texto texto Nome da instituição
education[graduation_year] não texto texto Ano de conclusão do curso
education[education_type_id] não inteiro id Identificador do tipo de escolaridade do colaborador
bankAccount[account] não texto texto Número da conta bancária
bankAccount[agency] não texto texto Agência da conta bancária
bankAccount[digit] não texto texto Dígito da conta bancária
bankAccount[accountant_type_id] não inteiro id Identificador do tipo da conta bancária
bankAccount[bank_id] não inteiro id Identificador do banco

Faltas e Afastamentos

Obter todos os motivos de Faltas e Afastamentos para um colaborador

Este endpoint retorna os motivos disponíveis para Faltas e Afastamentos.

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": {
    "id": 1,
    "name": "Falta"
  },
  "redirect": null,
  "success": true
}

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/absences/motives

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter todos os tipos de Faltas e Afastamentos para um colaborador

Este endpoint retorna os tipos disponíveis de Faltas e Afastamentos

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": {
    "id": 1,
    "name": "Justificada",
    "motive_id": 1,
    "motive": {
      "id": 1,
      "name": "Falta"
    }
  },
  "redirect": null,
  "success": true
}

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/absences/motives

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter todas as Faltas e Afastamentos de um colaborador

Este endpoint retorna um objeto com as faltas e afastamentos de um colaborador

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": {
    "employee_id": "33fb5be0-5614-43b3-83f6-b36a087f3699",
    "absences": [
      {
        "id": "4c3decd1-402d-412f-9024-ade3166be417",
        "motive_id": 6,
        "motive": {
          "id": 6,
          "name": "Outros"
        },
        "type_id": 2,
        "type": {
          "id": 2,
          "name": "Não justificada"
        },
        "date_from": "YYYY-mm-dd",
        "date_to": "YYYY-mm-dd",
        "total": "Número total de dias",
        "cid": "cid",
        "justification": "Justificação da falta",
        "created_at": "YYYY-mm-dd",
        "updated_at": "YYYY-mm-dd"
      }
    ]
  },
  "redirect": null,
  "success": true
}

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/{ColaboradorID}/absences

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter uma Falta/Afastamento de um colaborador

Este endpoint retorna uma Falta/Absence específica de um colaborador.

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": {
    "employee_id": "33fb5be0-5614-43b3-83f6-b36a087f3699",
    "id": "",
    "motive_id": 6,
    "motive": {
      "id": 6,
      "name": "Outros"
    },
    "type_id": 2,
    "type": {
      "id": 2,
      "name": "Não justificada"
    },
    "date_from": "YYYY-mm-dd",
    "date_to": "YYYY-mm-dd",
    "total": "Número total de dias",
    "cid": "cid",
    "justification": "Justificação da falta",
    "created_at": "YYYY-mm-dd",
    "updated_at": "YYYY-mm-dd"
    },
  "redirect": null,
  "success": true
}

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/{ColaboradorID}/absences/{Falta/AfastamentoID}

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Criar uma Falta/Afastamento para um colaborador

Endpoint responsável por criar uma falta/afastamento para um colaborador.

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": {
    "id": "4c3decd1-402d-412f-9024-ade3166be417",
    "employee_id": "33fb5be0-5614-43b3-83f6-b36a087f3699",
    "absence_motive_id": 6,
    "absence_type_id": 1,
    "date_from": "YYYY-mm-dd",
    "date_to": "YYYY-mm-dd",
    "total": "Número total de dias",
    "cid": "cid",
    "justification": "Justificação da falta"
  },
  "redirect": null,
  "success": true
}

HTTP Request

POST https://public-api.convenia.com.br/api/v3/employees/{ColaboradorID}/absences

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Payload

Campo Obrigatório Tipo Formato Descrição
date_to sim texto AAAA-MM-DD Data que inicia a Falta/Afastamento
date_from sim texto AAAA-MM-DD Data que termina a Falta/Afastamento
justification não texto texto Justificação da Falta/Afastamento
absence_motive_id não inteiro inteiro Identificador do motivo da Falta/Afastamento (Caso exista na plataforma o valor será vinculado)
absence_type_id não inteiro inteiro Identificador do tipo de Falta/Afastamento (Caso exista na plataforma o valor será vinculado)
cid não texto texto Matrícula

Atualizar uma Falta/Afastamento para um colaborador

Endpoint responsável por atualizar uma falta/afastamento específica de um colaborador.

Este endpoint não retorna um objeto, apenas o status 204

HTTP Request

PUT https://public-api.convenia.com.br/api/v3/employees/{ColaboradorID}/absences/{Falta/AfastamentoID}

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Payload

Campo Obrigatório Tipo Formato Descrição
date_to não (exceto quando houver campo "date_from") texto AAAA-MM-DD Data que inicia a Falta/Afastamento
date_from não (exceto quando houver campo "date_to") texto AAAA-MM-DD Data que termina a Falta/Afastamento
justification não texto texto Justificação da Falta/Afastamento
absence_motive_id não inteiro inteiro Identificador do motivo da Falta/Afastamento (Caso exista na plataforma o valor será vinculado)
absence_type_id não inteiro inteiro Identificador do tipo de Falta/Afastamento (Caso exista na plataforma o valor será vinculado)
cid não texto texto Matrícula

Deletar uma Falta/Afastamento de um colaborador

Endpoint responsável por deletar uma falta/afastamento específica de um colaborador.

Este endpoint não retorna um objeto, apenas o status 204

HTTP Request

DELETE https://public-api.convenia.com.br/api/v3/employees/{ColaboradorID}/absences/{Falta/AfastamentoID}

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Empresa

Obter todos os centros de custo

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "138589a9-a3e6-4393-8c39-a348406f107c",
      "name": "Centro de custo"
    }
  ],
  "redirect": null,
  "success": true
}

São retornados todos os centros de custo da plataforma.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/companies/cost-centers

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter todos os departamentos

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "0d379d76-a07e-4a6a-a0ac-24ca96ebc89b",
      "name": "Departamentos"
    }
  ],
  "redirect": null,
  "success": true
}

Sào retornados todos os departamentos da plataforma.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/companies/departments

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter todos os cargos

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "cb8e3a0f-5e16-41c1-b758-cdaed46147ea",
      "name": "Cargo",
      "description": "",
      "cbo_code": "212405",
      "cbo": {
        "name": "Tecnólogo em sistemas para internet"
      }
    }
  ],
  "redirect": null,
  "success": true
}

São retornados todos os cargos da plataforma.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/companies/jobs

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Obter todos os campos customizados

Este endpoint retorna um objeto com a seguinte estrutura:

{
  "message": "",
  "data": [
    {
      "id": "2c7f0e5d-0f20-478b-9c6d-992bc28c80e5",
      "name": "Campo customizado",
      "type": "Tipo do campo"
    }
  ],
  "redirect": null,
  "success": true
}

Esse endpoint retorna todos os campos customizados da plataforma.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/companies/custom-fields

Headers

Header Obrigatório Descrição
token sim Token de integração gerado na plataforma Convenia

Erros

Caso se depare com algum erro durante a configuração ou uso de nossa API, confira aqui os principais motivos para cada código de status retornado:

Código do Erro Motivo
400 Dados da requisição inválidos
401 Token de integração inválido
403 Empresa bloqueada
404 Recurso não encontrado
502 Erro na comunicação interna dos servidores

Webhooks

Para que seu sistema seja notificado via requisição HTTPS ele deve ser configurado para observar nossos webhooks. Ao realizar uma admissão, desligamento, pedido de férias ou alteração cadastral, o Convenia enviara uma requisição para a URL configurada na plataforma.

Esta requisição é realizada através de HTTPS, utilizando o método POST. Recomendamos que esta URL não tenha limitação de requisições, afim de evitar que uma notificação não seja recebida.

Nossa implementação de webhooks foi feita através da biblioteca spatie/laravel-webhook-client, e com essa implementação é possível garantir a confiabilidade dos dados enviados pela Convenia através do header Signature, nesta parte da documentação você encontra mais detalhes de como decodificar esse cabeçalho e autenticar o hook recebido.

Disponibilizamos um tutorial para a configuração de webhooks.

A seguir descrevemos nossos Webhooks com quais eventos os disparam, além de um exemplo de como é enviado o payload da nossa requisição e os headers que o acompanham.

Admissão

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "admission.finished",
  "employee": {
    "id": "55fe5c64-84c5-426d-9903-0768fcc8732d"
  },
  "status_name": "finished"
}

Quando

Sempre que um processo de admissão é finalizado na Convenia.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Demissão

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "dismissal.finished",
  "employee": {
    "id": "55fe5c64-84c5-426d-9903-0768fcc8732d"
  },
  "status_name": "finished",
  "termination_notice": {
    "id": 1,
    "name": "Trabalhado"
  },
  "dismissal_type": {
    "id": 8,
    "name": "Término de Contrato de Estágio"
  },
  "comments": "Comentários da demissão",
  "dismissal_date": "AAAA-MM-DD",
  "termination_notice_date": "AAAA-MM-DD",
  "dismissal_examination": true,
  "discount_breaking_contract": false,
  "dismissal_exam_date": "AAAA-MM-DD"
}

Quando

Sempre que um processo de demissão é finalizado na Convenia.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Criação de Férias

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "vacation.created",
  "employee": {
    "id": "ff8bf3ed-5faa-43a3-a68a-0da56b061b62"
  },
  "status_name": "approved",
  "start_date": "AAAA-MM-DD",
  "end_date": "AAAA-MM-DD",
  "days": 16,
  "reason": "Descrição do pedido",
  "anticipate_thirteenth": false,
  "allowance_days": 10
}

Quando

Sempre que um processo de férias é criado com data de início posterior à data atual (desconsidera histórico).

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Aprovação de Férias

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "vacation.approved",
  "employee": {
    "id": "ff8bf3ed-5faa-43a3-a68a-0da56b061b62"
  },
  "status_name": "approved",
  "start_date": "AAAA-MM-DD",
  "end_date": "AAAA-MM-DD",
  "days": 16,
  "reason": "Descrição do pedido ",
  "anticipate_thirteenth": false,
  "allowance_days": 10
}

Quando

Sempre que um processo de férias é finalizado na Convenia ou durante a criação de um histórico de férias.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Alteração no perfil de Colaboradores

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "employee.edited",
  "employee": {
    "id": "55fe5c64-84c5-426d-9903-0768fcc8732d"
  },
  "section": "Colaborador"
}

Quando

Sempre que ocorre uma mudança nas informações de um colaborador.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Alteração de Dados Salariais

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "salary.historic.changed",
  "employee": {
    "id": "40ed29b4-b815-41d8-b801-fe267c68bede"
  }
}

Quando

Sempre que ocorre uma mudança nas informações salariais de um colaborador.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Criação de Faltas e Afastamentos

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "absence.created",
  "employee": {
    "id": "40ed29b4-b815-41d8-b801-fe267c68bede"
  },
  "absence": {
    "id": "c30a3ec3-ce7e-46da-8be8-e66668cb20a7"
  }
}

Quando

Sempre que ocorre uma criação falta/afastamento para um colaborador.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Atualização de Faltas e Afastamentos

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "absence.updated",
  "employee": {
    "id": "40ed29b4-b815-41d8-b801-fe267c68bede"
  },
  "absence": {
    "id": "c30a3ec3-ce7e-46da-8be8-e66668cb20a7"
  }
}

Quando

Sempre que ocorre uma atualização nas informações de faltas e afastamentos de um colaborador.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Deleção de Faltas e Afastamentos

O Webhook ao lado é enviado com o seguinte payload:

{
  "type": "absence.deleted",
  "employee": {
    "id": "40ed29b4-b815-41d8-b801-fe267c68bede"
  },
  "absence": {
    "id": "c30a3ec3-ce7e-46da-8be8-e66668cb20a7"
  }
}

Quando

Sempre que ocorre uma deleção de faltas e afastamentos de um colaborador.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Aniversariantes do Dia

O Webhook ao lado é enviado com o seguinte payload:

{
  "employee_ids": {
    "40ed29b4-b815-41d8-b801-fe267c68bede",
    "695e83b3-97a3-474c-b529-8b6314358eed"
  }
}

Quando

Sempre que tem um ou mais colaboradores estiverem fazendo aniversário hoje.

Headers

Header Valor
content-type application/json
signature segredo + payload criptografados

Exemplos

Para auxiliar na configuração das requisições, preparamos um workspace público para referências de uso da nossa API na ferramenta Postman. Você pode também fazer o download do aquivo JSON para importação no Insomnia se preferir.