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

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

{
  "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 vínculos empregatícios

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

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

HTTP Request

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

Obter dados de estado civil

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

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

HTTP Request

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

Obter dados de tipo de escolaridade

{
  "message": "",
  "data": [
    {
      "id": "1",
      "name": "Analfabeto, inclusive o que, embora tenha recebido instrução, não se alfabetizou"
    }
  ],
  "redirect": null,
  "success": true
}

São retornados todos os tipos de escolaridade disponíveis na Convenia.

HTTP Request

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

Obter dados de tipo da conta bancária

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

São retornados todos os tipos de conta bancária disponíveis na Convenia.

HTTP Request

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

Obter listagem de Bancos

{
  "message": "",
  "data": [
    {
      "id": "1",
      "name": "ABC Brasil S.A."
    }
  ],
  "redirect": null,
  "success": true
}

São retornados todos os bancos aceitos na Convenia.

HTTP Request

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

Obter dados de estados

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

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

Obter listagem de tipos de desligamento

{
  "message": "",
  "data": [
    {
      "id": "1",
      "name": "Demissão SEM justa causa fora do contrato de experiência - Pedido da Empresa"
    }
  ],
  "redirect": null,
  "success": true
}

São retornados todos os tipos de desligamento disponíveis na Convenia.

HTTP Request

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

Headers

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

Obter listagem de tipos de aviso prévio

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

São retornados todos os tipos de aviso prévio disponíveis na Convenia.

HTTP Request

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

Headers

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

Obter listagem de identidade de gênero

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

São retornadas todas as identidades de gênero disponíveis na Convenia.

HTTP Request

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

Obter listagem dos relacionamentos de contatos de emergência

{
  "message": "",
  "data": [
    {
      "id": 4,
      "name": "Mãe"
    }
  ],
  "redirect": null,
  "success": true
}

São retornados todos os relacionamentos de contatos de emergência.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/relation-emergency-contacts

Colaboradores

Obter todos os colaboradores

{
  "message": "",
  "current_page": 1,
  "data": [
    {
      "id": "2e6c8997-3237-4868-a7f0-ddecf7d79777",
      "name": "Colaborador",
      "last_name": "A",
      "email": "colaboradorA@email.com",
      "status": "Ativo",
      "document": {
        "pis": "XXX.XXXXX.XX-X",
        "cpf": "XXX.XXX.XXX-XX"
      },
      "hiring_date": "AAAA-MM-DD",
      "salary": 4500.00,
      "birth_date": "AAAA-MM-DD",
      "social_name": "Nome Social Colab A",
      "registration": "Número da matrícula",
      "address": {
        "id": "074d0711-07d9-492e-93c8-07bcf9314aaa",
        "zip_code": "XXXXX-XXX",
        "address": "Avenida",
        "number": "1",
        "complement": "A",
        "district": "bairro x",
        "state": "SP",
        "city": "Sao Paulo"
      },
      "intern": {
        "id": "74c8b5a8-e43a-4373-bd78-19724cdc984e",
        "initial_at": "AAAA-MM-DD",
        "finish_at": "AAAA-MM-DD",
        "internship_category": "Nome da categoria do estágio",
        "is_mandatory": "Natureza do estágio",
        "occupation_area": "Nome da área de ocupação do estágio",
        "college": "Colégio do estágio",
        "cnpj": "##############",
        "zip_code": "########",
        "address": "Endereço da instituição",
        "number": "Número da instituição",
        "complement": "Complemento da instituição",
        "district": "Bairro da instituição",
        "state": "UF da instituição",
        "city": "Cidadae da instituição",
        "internship_supervisor": {
          "id": "5a5e3635-acf4-4806-832c-fef8dc4cbd69",
          "name": "Nome do gestor do estagiário",
          "last_name": "Sobrenome do gestor do estagiário"
        }
      },
      "department": {
        "id": "56871489-b980-2432-ab0d-d8a67cb413b8",
        "name": "Geral"
      },
      "cost_center": {
        "id": "309203bd-c98e-4612-a342-ac683c80444c",
        "name": "Geral"
      },
      "supervisor": {
        "id": "92144248-b6a4-47b7-addf-0b86dce3375a",
        "name": "Nome do gestor",
        "last_name": "Sobrenome do gestor"
      },
      "job": {
        "id": "f18e530a-1f88-4f83-9f2c-772313f1fbdd",
        "name": "Desenvolvedor Júnior"
      },
      "annotations": [
        {
          "id": 1,
          "title": "Título da anotação",
          "notes": "Conteúdo da anotação",
          "date": "AAAA-MM-DD"
        }
      ],
      "aso": [
        {
          "id": "90e53357-0bfb-4e88-9ffe-afe337812c72",
          "status": false,
          "exam_date": "AAAA-MM-DD",
          "observation": "Observações ASO",
          "aso_motive": "Admissional"
        }
      ],
      "bank_accounts": [
        {
          "id": "12c3cbc6-8562-4d38-a0fc-12561f06c4c5",
          "bank": "Nome do banco",
          "account_type": "Conta Corrente",
          "account": "Número da conta",
          "agency": "Número da agência",
          "digit": "Dígito da conta",
          "pix": "Pix colaborador A",
          "modality": "PJ"
        }
      ],
      "contact_information": {
        "id": 1,
        "residential_phone": "Telefone residencial",
        "personal_phone": "Telefone pessoal",
        "personal_email": "email pessoal"
      },
      "disability": {
        "id": 86,
        "observations": "Observações",
        "disability_type": "Física"
      },
      "foreign": {
        "id": 1,
        "arrival_date": "AAAA-MM-DD",
        "naturalization_date": "AAAA-MM-DD",
        "married_to_brazilian": false,
        "has_brazilian_offspring": false,
        "visa": "B-1",
        "country": "Japão"
      },
      "educations": [
        {
          "id": "34ce66b9-aa9f-40da-9b8c-ac41466e1440",
          "course": "Curso",
          "institution": "Instituição",
          "graduation_year": 2021,
          "education_type": "Analfabeto, inclusive o que, embora tenha recebido instrução, não se alfabetizou"
        }
      ],
      "nationalities": [
        {
          "id": 1,
          "nationality": "Brasil"
        }
      ],
      "experience_period": {
        "id": 1,
        "first_end": "AAAA-MM-DD",
        "second_end": "AAAA-MM-DD",
        "total_days": "45",
        "experience_period_type": "1 x 45 dias"
      },
      "emergency_contacts": [
        {
          "id":"d18655dc-221a-4acd-b8e2-6165e0a1f81d",
          "name": "Nome contato emergencia",
          "phone": "(XX) XXXX-XXXX",
          "email": "email@email.com",
          "cellphone": "(XX) XXXX-XXXX",
          "work_phone": "(XX) XXXX-XXXX",
          "emergency_contact_relation": "Amigo"
        }
      ],
      "cpf": {
        "id":"d2d79608-ffae-436a-b629-a7d1b1a1411d",
        "cpf": "XXXXXXXXXXX"
      },
      "ctps": {
        "id":"bc452167-95e1-4b1e-95c1-0245b0b8a1e8",
        "serial_number": "XXXX",
        "number": "XXXXXXX",
        "emission_date": "AAAA-MM-DD",
        "pis": "XXXXXXXXXXX",
        "issuing_state_id": 1
      },
      "reservist": {
        "id":"3737e19c-875d-45c7-9127-4fd93cf13112",
        "reservist": "XXXXXXXXX",
        "ra_number": "XXXXXXX",
        "series": "X"
      },
      "rg": {
        "id":"9b51b887-9102-4afd-aae3-30dd631014ab",
        "number": "XXXXXXXXXX",
        "emission_date": "AAAA-MM-DD",
        "issuing_agency": "SSP",
        "issuing_state_id": 26
      },
      "driver_license": {
        "id":"fe54ae9d-f6c1-4ca3-a4d1-b62974941e9a",
        "number": "XXXXXXXXXXX",
        "emission_date": "AAAA-MM-DD",
        "validate_date": "AAAA-MM-DD",
        "category": "AB"
      },
      "electoral_card": {
        "id":"dc67b574-6e98-4877-96de-77c3125e2281",
        "number": "XXXXXXXXXXXX",
        "section": "XXXX",
        "electoral_ward": "XXX",
        "state_id": 1,
        "city_id": 1
      }
    }
  ],
  "first_page_url": "\/?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "\/?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "\/?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "\/",
  "per_page": 1,
  "prev_page_url": null,
  "to": 1,
  "total": 1,
  "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

Query Params

Header	Obrigatório	Descrição	Exemplo de uso
match	não	Busca dados iguais ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?match[hiring_date]=2020-09-09,2020-09-10 / ?match[hiring_date]=%00 para nulo
different	não	Busca dados diferentes ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?different[hiring_date]=2020-09-09,2020-09-10 / ?different[hiring_date]=%00 para nulo
like	não	Busca dados que contenham o valor inserido.	?like[hiring_date]=2020-09
paginate	não	Pagina o resultado segundo o valor inserido.	?paginate=200
page	não	Seleciona a página dentre as listadas como disponíveis (utilizado em conjunto com o query param paginate	?paginate=200&page=2.

Obter todos os colaboradores desligados

{
  "message": "",
  "current_page": 1,
  "data": [
    {
      "id": "0c7b9a96-bda9-438b-8b19-16b0bd866706",
      "corporate_email": "colaboradorA@email.com",
      "dismissal": {
        "id": "c5665842-e101-4e2f-bbfe-74eb00961903",
        "date": "AAAA-MM-DD",
        "type": {
          "id": 26,
          "title": "Suspensão de contrato"
        },
        "termination_notice": {
          "id": "37d2073d-68af-4941-b42f-0c5ab9e82c7f",
          "date": "AAAA-MM-DD",
          "termination_notice_type_id": 1,
          "termination_notice_type": {
            "id": 1,
            "name": "Trabalhado"
          }
        },
        "dismissal_step_id": 4,
        "dismissal_step": {
          "id": 4,
          "name": "Concluído"
        },
        "breaking_contract": "Quebra de contrato",
        "remove_acess_date": "AAAA-MM-DD",
        "accountancy_date": "AAAA-MM-DD",
        "remove_benefit": true,
        "motive": null,
        "comments": null,
        "finished_at": "AAAA-MM-DD",
        "newSupervisorId": "ce12ea3a-6ed1-440d-bd2e-8ecfbb2c36ec",
        "supervisor": {
          "id": "ce12ea3a-6ed1-440d-bd2e-8ecfbb2c36ec",
          "name": "Nome do gestor"
        }
      }
    }
  ],
  "first_page_url": "\/?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "\/?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "\/?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "\/",
  "per_page": 1,
  "prev_page_url": null,
  "to": 1,
  "total": 1,
  "redirect": null,
  "success": true
}

É retornada uma lista com todos os colaboradores desligados da plataforma. Observação: caso a listagem ultrapasse 1000 registros, utilize o query param page para que seja possível listar o número excedente (máximo de 1000 registros por página).

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
paginate	não	Pagina o resultado segundo o valor inserido.	?paginate=200
page	não	Seleciona a página dentre as listadas como disponíveis (utilizado em conjunto com o query param paginate	?paginate=200&page=2.

Obter um colaborador especifico

{
  "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,
      "social_name": "Nome social do colaborador",
      "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"
      },
      "disability": {
        "id": 86,
        "disability_type_id": 1,
        "disability_type": {
          "id": 1,
          "name": "Física"
        },
        "observations": "Observações"
      },
      "annotations": [
        {
          "id": 1,
          "title": "Título da anotação",
          "date": "AAAA-MM-DD",
          "notes": "Conteúdo de anotação"
        }
      ],
      "emergency_contacts": [
        {
          "id":"d18655dc-221a-4acd-b8e2-6165e0a1f81d",
          "relation_id":2,
          "relation": {
            "id": 2,
            "name": "Amigo"
          },
          "name": "Nome contato emergencia",
          "phone": "(XX) XXXX-XXXX",
          "cellphone": "(XX) XXXX-XXXX",
          "work_phone": "(XX) XXXX-XXXX",
          "email": "email@email.com"
        }
      ],
      "work_period": {
        "journey": {
          "monthly_hours": "160:00"
        }
      },
      "intern": {
        "id": "74c8b5a8-e43a-4373-bd78-19724cdc984e",
        "initial_at": "AAAA-MM-DD",
        "finish_at": "AAAA-MM-DD",
        "internship_category": "Nome da categoria do estágio",
        "is_mandatory": "Natureza do estágio",
        "occupation_area": "Nome da área de ocupação do estágio",
        "college": "Colégio do estágio",
        "cnpj": "##############",
        "zip_code": "########",
        "address": "Endereço da instituição",
        "number": "Número da instituição",
        "complement": "Complemento da instituição",
        "district": "Bairro da instituição",
        "state": "UF da instituição",
        "city": "Cidadae da instituição",
        "internship_supervisor": {
          "id": "5a5e3635-acf4-4806-832c-fef8dc4cbd69",
          "name": "Nome do gestor do estagiário",
          "last_name": "Sobrenome do gestor do estagiário"
        },
      "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

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

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

Obter solicitações de férias relacionadas a um colaborador

{
  "message": "",
  "current_page": 1,
  "data": [
    {
      "id": "3228b4e2-3402-4df0-8d9b-96639424dda3",
      "employee_id": "257fbee4-71a2-4aca-8658-4a311fafd9e1",
      "allowance": 18,
      "thirteenth": true,
      "period_id": "b14fb6c6-5e10-44e9-a02d-733c21d8e066",
      "collective_id": "b57f6356-aa47-48aa-9454-ba743b67fa75",
      "justification": "Justificativa para solicitação",
      "requested_days": 15,
      "sent_to_accountant": true,
      "spent_balance": 25,
      "starts_at": "AAAA-MM-DD",
      "finishes_at": "AAAA-MM-DD",
      "status": "approved",
      "paid_leave": 1,
      "accounting_started_at": "AAAA-MM-DD HH:ii:ss",
      "hr_approvals_started_at": "AAAA-MM-DD HH:ii:ss",
      "supervisor_approvals_started_at": "AAAA-MM-DD HH:ii:ss",
      "signature_started_at": "AAAA-MM-DD HH:ii:ss",
      "supervisor_approvals": [
        {
          "id": "0a165537-0dec-4aff-a16a-03ae82be8d97",
          "status": "approved",
          "supervisor_id": "42a198c5-2e39-4302-afda-8e4098d83589",
          "action_date": "AAAA-MM-DD",
          "updated_at": "AAAA-MM-DD HH:ii:ss",
          "created_at": "AAAA-MM-DD HH:ii:ss"
        }
      ],
      "hr_approvals": [
        {
          "id": "7e3d5d55-621b-49a8-acaf-bc600c64b5ba",
          "status": "approved",
          "employee_id": "3339802f-f219-4b0c-b7dd-d8e8197479f6",
          "action_date": "AAAA-MM-DD HH:ii:ss",
          "updated_at": "AAAA-MM-DD HH:ii:ss",
          "created_at": "AAAA-MM-DD HH:ii:ss"
        }
      ],
      "files": [
        {
          "id": "bf24b8be-283f-4bb4-bc5d-1461c29d381d",
          "name": "file-name.jpg",
          "signable": true,
          "status": "waiting",
          "updated_at": "AAAA-MM-DD HH:ii:ss",
          "created_at": "AAAA-MM-DD HH:ii:ss"
        }
      ],
      "available_steps": {
        "supervisor_approval": true,
        "hr_approval": true,
        "accounting": true,
        "signature": true
      },
      "canceled": {
        "employee_id": "128e21ee-7705-4b17-9025-0cc4b1a64f8d",
        "created_at": "AAAA-MM-DD HH:ii:ss",
        "updated_at": "AAAA-MM-DD HH:ii:ss"
      },
      "created_at": "AAAA-MM-DD\T00:00:00",
      "updated_at": "AAAA-MM-DD\T00:00:00"
    }
  ],
  "first_page_url": "\/?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "\/?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "\/?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "\/",
  "per_page": 1,
  "prev_page_url": null,
  "to": 1,
  "total": 1,
  "redirect": null,
  "success": true
}

Listagem de solicitações de férias (sejam elas canceladas ou não) relacionadas a um colaborador através de seu identificador único. Observação: caso a listagem ultrapasse 1000 registros, utilize o query param page para que seja possível listar o número excedente (máximo de 1000 registros por página).

HTTP Request

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

Headers

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

Query Params

Header	Obrigatório	Descrição	Exemplo de uso
match	não	Busca dados iguais ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?match[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?match[accounting_started_at]=%00 para nulo
different	não	Busca dados diferentes ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?different[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?different[accounting_started_at]=%00 para nulo
like	não	Busca dados que contenham o valor inserido.	?like[created_at]=2020-09
paginate	não	Pagina o resultado segundo o valor inserido.	?paginate=200
page	não	Seleciona a página dentre as listadas como disponíveis (utilizado em conjunto com o query param paginate	?paginate=200&page=2.

Obter solicitação de férias específica relacionada a um colaborador

{
  "message": "",
  "data": {
    "id": "3228b4e2-3402-4df0-8d9b-96639424dda3",
    "employee_id": "257fbee4-71a2-4aca-8658-4a311fafd9e1",
    "allowance": 18,
    "thirteenth": true,
    "period_id": "b14fb6c6-5e10-44e9-a02d-733c21d8e066",
    "collective_id": "b57f6356-aa47-48aa-9454-ba743b67fa75",
    "justification": "Justificativa para solicitação",
    "requested_days": 15,
    "sent_to_accountant": true,
    "spent_balance": 25,
    "starts_at": "AAAA-MM-DD",
    "finishes_at": "AAAA-MM-DD",
    "status": "approved",
    "paid_leave": 1,
    "accounting_started_at": "AAAA-MM-DD HH:ii:ss",
    "hr_approvals_started_at": "AAAA-MM-DD HH:ii:ss",
    "supervisor_approvals_started_at": "AAAA-MM-DD HH:ii:ss",
    "signature_started_at": "AAAA-MM-DD HH:ii:ss",
    "supervisor_approvals": [
      {
        "id": "0a165537-0dec-4aff-a16a-03ae82be8d97",
        "status": "approved",
        "supervisor_id": "42a198c5-2e39-4302-afda-8e4098d83589",
        "action_date": "AAAA-MM-DD",
        "updated_at": "AAAA-MM-DD HH:ii:ss",
        "created_at": "AAAA-MM-DD HH:ii:ss"
      }
    ],
    "hr_approvals": [
      {
        "id": "7e3d5d55-621b-49a8-acaf-bc600c64b5ba",
        "status": "approved",
        "employee_id": "3339802f-f219-4b0c-b7dd-d8e8197479f6",
        "action_date": "AAAA-MM-DD HH:ii:ss",
        "updated_at": "AAAA-MM-DD HH:ii:ss",
        "created_at": "AAAA-MM-DD HH:ii:ss"
      }
    ],
    "files": [
      {
        "id": "bf24b8be-283f-4bb4-bc5d-1461c29d381d",
        "name": "file-name.jpg",
        "signable": true,
        "status": "waiting",
        "updated_at": "AAAA-MM-DD HH:ii:ss",
        "created_at": "AAAA-MM-DD HH:ii:ss"
      }
    ],
    "available_steps": {
      "supervisor_approval": true,
      "hr_approval": true,
      "accounting": true,
      "signature": true
    },
    "canceled": {
      "employee_id": "128e21ee-7705-4b17-9025-0cc4b1a64f8d",
      "created_at": "AAAA-MM-DD HH:ii:ss",
      "updated_at": "AAAA-MM-DD HH:ii:ss"
    },
    "created_at": "AAAA-MM-DD\T00:00:00",
    "updated_at": "AAAA-MM-DD\T00:00:00"
  },
  "redirect": null,
  "success": true
}

Detalhe de solicitação de férias relacionada a um colaborador através de seu identificador único.

HTTP Request

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

Headers

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

Obter arquivo de solicitação de férias específica relacionada a um colaborador

{}

Detalhe de arquivo de solicitação de férias relacionada a um colaborador e de uma solicitação de férias através de seus identificadores únicos.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/employees/{ColaboradorID}/vacations/solicitations/{SolicitacaoID}/files/{ArquivoID}

Headers

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

Obter períodos aquisitivos de férias relacionados a um colaborador

{
  "message": "",
  "current_page": 1,
  "data": [
    {
      "id": "978959ab-4078-4990-857e-4d6c8cbf7c18",
      "employee_id": "8458da55-5ee2-42c3-a770-ef387d52b982",
      "balance": 0,
      "initial_balance": 30,
      "purchasing_started_at": "AAAA-MM-DD",
      "purchasing_finished_at": "AAAA-MM-DD",
      "concessive_started_at": "AAAA-MM-DD",
      "concessive_finished_at": "AAAA-MM-DD",
      "expiring_started_at": "AAAA-MM-DD",
      "expiring_finished_at": "AAAA-MM-DD",
      "created_at": "AAAA-MM-DD\THH:ii:ss",
      "updated_at": "AAAA-MM-DD\THH:ii:ss"
    }
  ],
  "first_page_url": "\/?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "\/?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "\/?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "\/",
  "per_page": 1,
  "prev_page_url": null,
  "to": 1,
  "total": 1,
  "redirect": null,
  "success": true
}

Listagem de períodos aquisitivos relacionadas a um colaborador através de seu identificador único. Observação: caso a listagem ultrapasse 1000 registros, utilize o query param page para que seja possível listar o número excedente (máximo de 1000 registros por página).

HTTP Request

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

Headers

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

Query Params

Header	Obrigatório	Descrição	Exemplo de uso
match	não	Busca dados iguais ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?match[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?match[purchasing_started_at]=%00 para nulo
different	não	Busca dados diferentes ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?different[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?different[purchasing_started_at]=%00 para nulo
like	não	Busca dados que contenham o valor inserido.	?like[created_at]=2020-09
paginate	não	Pagina o resultado segundo o valor inserido.	?paginate=200
page	não	Seleciona a página dentre as listadas como disponíveis (utilizado em conjunto com o query param paginate	?paginate=200&page=2.

Obter período aquisitivo de férias específico relacionado a um colaborador

{
  "message": "",
  "data": {
    "id": "978959ab-4078-4990-857e-4d6c8cbf7c18",
    "employee_id": "8458da55-5ee2-42c3-a770-ef387d52b982",
    "balance": 0,
    "initial_balance": 30,
    "purchasing_started_at": "AAAA-MM-DD",
    "purchasing_finished_at": "AAAA-MM-DD",
    "concessive_started_at": "AAAA-MM-DD",
    "concessive_finished_at": "AAAA-MM-DD",
    "expiring_started_at": "AAAA-MM-DD",
    "expiring_finished_at": "AAAA-MM-DD",
    "created_at": "AAAA-MM-DD\THH:ii:ss",
    "updated_at": "AAAA-MM-DD\THH:ii:ss"
  },
  "redirect": null,
  "success": true
}

Detalhe de período aquisitivo de férias relacionado a um colaborador através de seu identificador único.

HTTP Request

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

Headers

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

Obter alterações relacionadas a um colaborador

{
  "message": "",
  "current_page": 1,
  "data": [
    {
      "id": "f10e1989-5f73-4845-9160-7faea8998207",
      "employee_id": "33fb5be0-5614-43b3-83f6-b36a087f3699",
      "action": "created",
      "section": "accountancy",
      "owner_name": "Pessoa A",
      "changes": {
        "process_number": {
          "new_value": 100,
          "old_value": null
        },
        "social_security_type_id": {
          "new_id": 1,
          "old_id": null,
          "new_value": "Regime Geral de Previdência Social - RGPS",
          "old_value": null
        }
      },
      "created_at": "AAAA-MM-DD\THH:ii:ss",
      "updated_at": "AAAA-MM-DD\THH:ii:ss"
    }
  ],
  "first_page_url": "\/?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "\/?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "\/?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "\/",
  "per_page": 1,
  "prev_page_url": null,
  "to": 1,
  "total": 1,
  "redirect": null,
  "success": true
}

Listagem de alterações relacionadas a um colaborador através de seu identificador único. Quando houver alteração de dado selecionável no sistema, os campos "old_id" e "new_id" estarão presentes. Observação: caso a listagem ultrapasse 1000 registros, utilize o query param page para que seja possível listar o número excedente (máximo de 1000 registros por página).

HTTP Request

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

Headers

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

Query Params

Header	Obrigatório	Descrição	Exemplo de uso
match	não	Busca dados iguais ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?match[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?match[action]=%00 para nulo
different	não	Busca dados diferentes ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?different[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?different[action]=%00 para nulo
like	não	Busca dados que contenham o valor inserido.	?like[created_at]=2020-09
paginate	não	Pagina o resultado segundo o valor inserido.	?paginate=200
page	não	Seleciona a página dentre as listadas como disponíveis (utilizado em conjunto com o query param paginate	?paginate=200&page=2.

Obter alteração específica relacionadas a um colaborador

{
  "message": "",
  "data": {
    "id": "f10e1989-5f73-4845-9160-7faea8998207",
    "employee_id": "33fb5be0-5614-43b3-83f6-b36a087f3699",
    "action": "created",
    "section": "accountancy",
    "owner_name": "Pessoa A",
    "changes": {
      "process_number": {
        "new_value": 100,
        "old_value": null
      },
      "social_security_type_id": {
        "new_id": 1,
        "old_id": null,
        "new_value": "Regime Geral de Previdência Social - RGPS",
        "old_value": null
      }
    },
    "created_at": "AAAA-MM-DD\THH:ii:ss",
    "updated_at": "AAAA-MM-DD\THH:ii:ss"
  },
  "redirect": null,
  "success": true
}

HTTP Request

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

Headers

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

Iniciar a admissão de um colaborador

{
  "message": "",
  "data": [
    {
      "id": "521260c6-3433-49d2-800a-48e614958183",
      "status": 0,
      "employee_fill_form":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",
        "natural_from_city_id": 1,
        "natural_from_state_id": 1,
        "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",
          "city_id": 1,
          "state_id": 1,
        },
        "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
hiring_date	não	texto	AAAA-MM-DD	Data de contratação
birth_date	não	texto	AAAA-MM-DD	Data de nascimento
gender	não	texto	texto	Sexo do colaborador (M ou F)
relationship_id	sim	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
employee_fill_form	não	boleano	boleano	Indicador se deve ou não ser enviado o email de preenchimento da admissão para o colaborador
personal_email	não (exceto quando o campo employee_fill_form for igual a true)	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	UF	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. (Inserir no máximo 8 caracteres e sem hífen).
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

Iniciar o desligamento de um colaborador

{
  "message": "",
  "data": {
    "employee_id": "8518879f-c2b0-49ae-825b-b331723e668d",
    "id": "8132a73b-11dc-4fea-a962-640e05e40656",
    "dismissal_date": "YYYY-mm-dd",
    "dismissal_step_id": 1,
    "dismissal_type_id": 1,
    "remove_access_date": "YYYY-mm-dd",
    "motive": "Motivo do desligamento",
    "comments": "Observações do desligamento",
    "remove_benefit": true,
    "breaking_contract": true,
    "termination": {
      "id": "7aa2f0cc-a20c-4ffb-a553-2faeed7cb5dc",
      "termination_notice_type_id": 2,
      "termination_notice_date": "YYYY-mm-dd"
    }
  },
  "redirect": null,
  "success": true
}

Esse endpoint é responsável por iniciar o desligamento do colaborador na plataforma.

HTTP Request

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

Headers

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

Payload

Campo	Obrigatório	Tipo	Formato	Descrição
dismissal_date	sim	data	YYYY-mm-dd	Data final do desligamento
dismissal_type_id	sim	inteiro	id	Identificador do tipo de desligamento. É possível visualizar os tipos possíveis para desligamento na Listagem de tipos de desligamento
remove_access_date	sim	data	YYYY-mm-dd	Data de remoção de acesso da plataforma
termination_notice_type_id	sim	inteiro	id	Identificador do tipo de aviso prévio. É possível visualizar os tipos possíveis para aviso prévio na Listagem de tipos de aviso prévio
motive	não	texto	texto	Motivo do desligamento
comments	não	texto	texto	Comentários
remove_benefit	não	boleano	boleano	Indicador se serão removidos os beneficios no início do processo
breaking_contract	não	boleano	boleano	Indicador se haverá desconto por quebra de contrato
termination_notice_date	não	data	YYYY-mm-dd	Data do aviso prévio

Atribuir valor à campos customizados

{
  "message": "",
  "data": {
        "employee_id": "cd90d556-e84d-4276-833b-2ded201f8b10",
        "custom_fields": [
            {
                "custom_field_id": "5f2baae5-ccf5-401a-a355-a6e47bec92e5",
                "value": "valor do campo",
                "id": "a11a2d6a-bc5b-40f5-a3eb-5ed45d26cfd7"
            }
        ]
    },
  "redirect": null,
  "success": true
}

Esse endpoint é responsável por atribuir valores para campos customizados pertencentes à seção Outras Informações. É possível visualizar os campos disponíveis e suas seções no Endpoint de listagem de campos customizados

Vale se atentar ao tipo do campo customizado:

Campos do tipo texto: recebem valores de texto.
Campos do tipo pergunta: podem receber "Sim" ou "Não".
Campos do tipo data: recebem um texto no formato: DD/MM/AAAA.
Campos do tipo lista: devem receber o texto de um dos itens da lista.

HTTP Request

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

Headers

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

Payload

Campo	Obrigatório	Tipo	Formato	Descrição
custom_fields[][custom_field_id]	sim	texto	uuid	Id do campo customizado
custom_fields[][value]	sim	texto	texto	Valor para o campo customizado

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.

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

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

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

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

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

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.

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 campos customizados

{
  "message": "",
  "data": [
    {
      "id": "2c7f0e5d-0f20-478b-9c6d-992bc28c80e5",
      "name": "Campo customizado",
      "type": "Tipo do campo",
      "section": "Outras Informações",
    }
  ],
  "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

Obter solicitações de férias coletivas da empresa

{
  "message": "",
  "current_page": 1,
  "data": [
    {
      "id": "0d858ac6-b644-4e3b-b25e-b55d3167642a",
      "title": "Título da solicitação",
      "starts_at": "AAAA-MM-DD",
      "finishes_at": "AAAA-MM-DD",
      "requested_days": 10,
      "discount_holidays": true,
      "justification": "Justificativa para solicitação",
      "emails": [
        {
          "email": "email@email.com"
        }
      ],
      "departments": [
        {
          "id": "5327e64a-0200-4a23-8263-b684aa0d14d1",
          "name": "Nome do departamento selecionado"
        }
      ],
      "owner": {
        "id": "1032be04-c344-481a-a6dc-877144843e00",
        "employee_id": "f4b5148b-491d-4edc-8068-1c9798ccd80d"
      },
      "created_at": "AAAA-MM-DD\T00:00:00",
      "updated_at": "AAAA-MM-DD\T00:00:00"
    }
  ],
  "first_page_url": "\/?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "\/?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "\/?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "\/",
  "per_page": 1,
  "prev_page_url": null,
  "to": 1,
  "total": 1,
  "redirect": null,
  "success": true
}

Listagem de solicitações de férias coletivas da empresa. Observação: caso a listagem ultrapasse 1000 registros, utilize o query param page para que seja possível listar o número excedente (máximo de 1000 registros por página).

HTTP Request

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

Headers

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

Query Params

Header	Obrigatório	Descrição	Exemplo de uso
match	não	Busca dados iguais ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?match[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?match[justification]=%00 para nulo
different	não	Busca dados diferentes ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?different[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?different[justification]=%00 para nulo
like	não	Busca dados que contenham o valor inserido.	?like[created_at]=2020-09
paginate	não	Pagina o resultado segundo o valor inserido.	?paginate=200
page	não	Seleciona a página dentre as listadas como disponíveis (utilizado em conjunto com o query param paginate	?paginate=200&page=2.

Obter solicitação de férias específica relacionada a um colaborador

{
  "message": "",
  "data": {
    "id": "0d858ac6-b644-4e3b-b25e-b55d3167642a",
    "title": "Título da solicitação",
    "starts_at": "AAAA-MM-DD",
    "finishes_at": "AAAA-MM-DD",
    "requested_days": 10,
    "discount_holidays": true,
    "justification": "Justificativa para solicitação",
    "emails": [
      {
        "email": "email@email.com"
      }
    ],
    "departments": [
      {
        "id": "5327e64a-0200-4a23-8263-b684aa0d14d1",
        "name": "Nome do departamento selecionado"
      }
    ],
    "owner": {
      "id": "1032be04-c344-481a-a6dc-877144843e00",
      "employee_id": "f4b5148b-491d-4edc-8068-1c9798ccd80d"
    },
    "created_at": "AAAA-MM-DD\T00:00:00",
    "updated_at": "AAAA-MM-DD\T00:00:00"
  },
  "redirect": null,
  "success": true
}

Detalhe de solicitação de férias férias coletivas através de seu identificador único.

HTTP Request

GET https://public-api.convenia.com.br/api/v3/companies/collective-vacations/{ColetivaID}

Headers

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

Departamentos

Obter todos os departamentos

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

Criar um Departamento

Endpoint responsável por criar um departamento

{
  "message": "",
  "data": {
    "id": "4c3decd1-402d-412f-9024-ade3166be417",
    "name": "Nome do departamento",
    "company_id": "51eeeddf-25cb-4da1-88bb-82e8060080e6"
  },
  "redirect": null,
  "success": true
}

HTTP Request

POST 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

Payload

Campo	Obrigatório	Tipo	Formato	Descrição
name	sim	texto	texto	Nome do departamento

Atualizar um departamento

Endpoint responsável por atualizar um departamento

HTTP Request

PUT https://public-api.convenia.com.br/api/v3/companies/departments/{DepartmentoID}

Headers

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

Payload

Campo	Obrigatório	Tipo	Formato	Descrição
name	sim	texto	texto	Novo nome do departamento

Deletar um departamento

Endpoint responsável por deletar um departamento e transferir o colaborador para um novo departamento.

HTTP Request

DELETE https://public-api.convenia.com.br/api/v3/companies/departments/{DepartmentoID}

Headers

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

Payload

Campo	Obrigatório	Tipo	Formato	Descrição
transfer_to	sim	texto	uuid	Id do departamento que o substituirá

Centros de Custo

Obter todos os centros de custo

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

Criar um Centro de Custo

Endpoint responsável por criar um centro de custo

{
  "message": "",
  "data": {
    "id": "106754de-45ad-11ed-b878-0242ac120002",
    "name": "Nome do centro de custo"
  },
  "redirect": null,
  "success": true
}

HTTP Request

POST https://public-api.convenia.com.br/api/v3/companies/cost-center

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 centro de custo

Atualizar um centro de custo

Endpoint responsável por atualizar um centro de custo

HTTP Request

PUT https://public-api.convenia.com.br/api/v3/companies/cost-centers/{CentroDeCustoID}

Headers

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

Payload

Campo	Obrigatório	Tipo	Formato	Descrição
name	sim	texto	texto	Novo nome do centro de custo

Deletar um centro de custo

Endpoint responsável por deletar um centro de custo e transferir o colaborador para um novo centro de custo.

HTTP Request

DELETE https://public-api.convenia.com.br/api/v3/companies/cost-centers/{CentroDeCustoID}

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	uuid	Uuid do centro de custo a ser transferido

Cargos

Obter todos os cargos

{
  "message": "",
  "data": [
    {
      "id": "cb8e3a0f-5e16-41c1-b758-cdaed46147ea",
      "name": "Cargo",
      "description": "",
      "cbo_code": "212405",
      "cbo": {
        "name": "Tecnólogo em sistemas para internet"
      },
      "apprentice_quota":  false
    }
  ],
  "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

Criar um Cargo

Endpoint responsável por criar um cargo.

{
  "message": "",
  "data": {
    "id": "05b5fde9-8ed5-42bc-8863-850c02d75a98",
    "cbo_code": "843012",
    "name": "Nome do cargo",
    "description": "Criando um cargo",
    "apprentice_quota": false
  },
  "redirect": null,
  "success": true
}

HTTP Request

POST 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

Payload

Campo	Obrigatório	Tipo	Formato	Descrição
name	sim	texto	texto	Nome do cargo
description	não	texto	texto	Descrição do cargo
cbo_code	sim	texto	texto	Código cbo válido
apprentice_quota	não	boleano	boleano	Indicador se o cargo deve ou não ser contabilizado para cálculo do relatório de riscos de menor aprendiz

Atualizar um cargo

Endpoint responsável por atualizar um cargo.

HTTP Request

PUT https://public-api.convenia.com.br/api/v3/companies/jobs/{CargoID}

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	Novo nome do cargo
description	não	texto	texto	Nova descrição do cargo
cbo_code	sim	texto	texto	Código cbo válido
apprentice_quota	não	boleano	boleano	Indicador se o cargo deve ou não ser contabilizado para cálculo do relatório de riscos de menor aprendiz

Deletar um cargo

Endpoint responsável por deletar um cargo e transferir o colaborador para um novo cargo.

HTTP Request

DELETE https://public-api.convenia.com.br/api/v3/companies/jobs/{CargoID}

Headers

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

Payload

Campo	Obrigatório	Tipo	Formato	Descrição
transfer_to	sim	texto	uuid	Uuid do cargo a ser transferido

Folha

Obter todas as folhas da empresa

{
  "message": "",
  "current_page": 1,
  "data": [
    {
      "id": "aa35e356-2e0e-4e68-b9b5-c5006a552b76",
      "type": {
        "id": 1,
        "name": "Folha Mensal"
      },
      "step": {
        "id": 1,
        "name": "Iniciada"
      },
      "name": "Folha iniciada",
      "year": 2023,
      "month": 3,
      "rh_refusal_motive": "Motive for refusal",
      "accountancy_refusal_motive": "Motive for refusal",
      "files": [
        {
          "id": "ca4d4d56-5d1d-4ddb-b634-26c8c501d916",
          "name": "file-name.jpg",
          "due_date": "AAAA-MM-DD",
          "is_accounting": true
        }
      ],
      "created_at": "AAAA-MM-DD\T00:00:00",
      "updated_at": "AAAA-MM-DD\T00:00:00"
    }
  ],
  "first_page_url": "\/?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "\/?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "\/?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "\/",
  "per_page": 1,
  "prev_page_url": null,
  "to": 1,
  "total": 1,
  "redirect": null,
  "success": true
}

Listagem de folhas da empresa (apenas para clientes que fecham folha de pagamento com nossa contabilidade). Observação: caso a listagem ultrapasse 1000 registros, utilize o query param page para que seja possível listar o número excedente (máximo de 1000 registros por página).

HTTP Request

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

Headers

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

Query Params

Header	Obrigatório	Descrição	Exemplo de uso
match	não	Busca dados iguais ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?match[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?match[rh_refusal_motive]=%00 para nulo
different	não	Busca dados diferentes ao(s) valor(es) inserido(s), separados por vírgula. Pode também buscar por dados nulos	?different[created_at]=2020-09-09T23:00:00,2020-09-10T23:00:00 / ?different[rh_refusal_motive]=%00 para nulo
like	não	Busca dados que contenham o valor inserido.	?like[created_at]=2020-09
paginate	não	Pagina o resultado segundo o valor inserido.	?paginate=200
page	não	Seleciona a página dentre as listadas como disponíveis (utilizado em conjunto com o query param paginate	?paginate=200&page=2.

Obter folha específica de uma empresa

{
  "message": "",
  "data": {
    "id": "aa35e356-2e0e-4e68-b9b5-c5006a552b76",
    "type": {
      "id": 1,
      "name": "Folha Mensal"
    },
    "step": {
      "id": 1,
      "name": "Iniciada"
    },
    "name": "Folha iniciada",
    "year": 2023,
    "month": 3,
    "rh_refusal_motive": "Motive for refusal",
    "accountancy_refusal_motive": "Motive for refusal",
    "files": [
      {
        "id": "ca4d4d56-5d1d-4ddb-b634-26c8c501d916",
        "name": "file-name.jpg",
        "due_date": "AAAA-MM-DD",
        "is_accounting": true
      }
    ],
    "created_at": "AAAA-MM-DD\T00:00:00",
    "updated_at": "AAAA-MM-DD\T00:00:00"
  },
  "redirect": null,
  "success": true
}

Detalhe de folha específica da empresa (apenas para clientes que fecham folha de pagamento com nossa contabilidade).

HTTP Request

GET https://public-api.convenia.com.br/api/v3/payrolls/{FolhaID}

Headers

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

Obter arquivo de folha específica da empresa

{}

Detalhe de arquivo de folha específica da empresa (apenas para clientes que fecham folha de pagamento com nossa contabilidade).

HTTP Request

GET https://public-api.convenia.com.br/api/v3/payrolls/{FolhaID}/files/{ArquivoID}

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
504	Excedeu o tempo máximo de requisição 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

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

Desligamento

{
  "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"
  },
  "new_supervisor_id": "d0cc63ab-aeb4-4d96-9595-918e02b07cdb",
  "accountancy_sent_date": "AAAA-MM-DD",
  "access_removal_date": "AAAA-MM-DD",
  "remove_benefit": true,
  "motive": "Motivo detalhado da demissão",
  "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

Desligamento (Aguardando contabilidade)

{
  "type": "dismissal.awaiting.accounting",
  "employee": {
    "id": "55fe5c64-84c5-426d-9903-0768fcc8732d"
  },
  "status_name": "awaiting accounting",
  "termination_notice": {
    "id": 1,
    "name": "Trabalhado"
  },
  "dismissal_type": {
    "id": 8,
    "name": "Término de Contrato de Estágio"
  },
  "new_supervisor_id": "d0cc63ab-aeb4-4d96-9595-918e02b07cdb",
  "accountancy_sent_date": "AAAA-MM-DD",
  "access_removal_date": "AAAA-MM-DD",
  "remove_benefit": true,
  "motive": "Motivo detalhado da demissão",
  "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

Um processo de desligamento for para a etapa aguardando contabilidade.

Headers

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

Criação de Férias

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

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

Atualização de Férias

{
  "type": "vacation.solicitation.updated",
  "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",
  "anticipate_thirteenth": false,
  "allowance_days": 10
}

Quando

Sempre que um processo de férias é atualizado na Convenia.

Headers

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

Alteração no perfil de Colaboradores

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

Quando

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

Headers

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

Sections possíveis

Sections
absences
addresses
aso
bank_accounts
contact_information
cpf
ctps
custom_field_values
dependents
document_files
driver_licenses
electoral_cards
emergency_contacts
employees
employee_educations
employee_nationalities
experience_periods
foreign_employees
handicapped
interns
other_documents
personal_information
professional_information
real_estates
reservists
residence_proof
rg
salaries_historic
union_contributions

Alteração de Dados Salariais

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

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

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

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

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

Precisa de ajuda?

Introdução

Autenticação

Dados do Sistema

Obter dados de etnias

HTTP Request

Obter dados de nacionalidades

HTTP Request

Obter dados de vínculos empregatícios

HTTP Request

Obter dados de estado civil

HTTP Request

Obter dados de tipo de escolaridade

HTTP Request

Obter dados de tipo da conta bancária

HTTP Request

Obter listagem de Bancos

HTTP Request

Obter dados de estados

HTTP Request

Headers

Obter dados de cidades

HTTP Request

Headers

Query Params

Obter listagem de tipos de desligamento

HTTP Request

Headers

Obter listagem de tipos de aviso prévio

HTTP Request

Headers

Obter listagem de identidade de gênero

HTTP Request

Obter listagem dos relacionamentos de contatos de emergência

HTTP Request

Colaboradores

Obter todos os colaboradores

HTTP Request

Headers

Query Params

Obter todos os colaboradores desligados

HTTP Request

Headers

Query Params

Obter um colaborador especifico

HTTP Request

Headers

Obter o histórico salarial de um colaborador

HTTP Request

Headers

Obter dependentes relacionados a um colaborador

HTTP Request

Headers

Obter solicitações de férias relacionadas a um colaborador

HTTP Request

Headers

Query Params

Obter solicitação de férias específica relacionada a um colaborador

HTTP Request

Headers

Obter arquivo de solicitação de férias específica relacionada a um colaborador

HTTP Request

Headers

Obter períodos aquisitivos de férias relacionados a um colaborador

HTTP Request

Headers

Query Params

Obter período aquisitivo de férias específico relacionado a um colaborador

HTTP Request

Headers

Obter alterações relacionadas a um colaborador

HTTP Request

Headers

Query Params

Obter alteração específica relacionadas a um colaborador

HTTP Request

Headers

Iniciar a admissão de um colaborador

HTTP Request

Headers