API de integração de atestados

Esta documentação apresenta o contrato HTTP dos endpoints disponibilizados para a integração de atestados, incluindo as operações de consulta, inclusão, alteração e exclusão de registros.

Informações gerais

Item	Valor
Contexto da aplicação	`/rh/dados`
Recurso	`/api/atestados`
Content-Type para POST/PUT	`application/json`
Formato das datas	`yyyy-MM-dd`
Formato de data e hora	`yyyy-MM-dd'T'HH:mm:ss`
Codificação	UTF-8

Exemplo de URL de testes:

https://rh.suite.betha.cloud/dados/v1/atestados

O endereço e o mecanismo de obtenção do token devem ser confirmados para o ambiente disponibilizado ao parceiro.

Resumo dos endpoints

Método	Caminho	Descrição	Sucesso
GET	`/atestados`	Consulta paginada de atestados	`200 OK`
POST	`/atestados/integracao`	Cria um atestado	`200 OK`
PUT	`/atestados/integracao/{id}`	Atualiza um atestado	`200 OK`
DELETE	`/atestados/integracao/{id}`	Exclui um atestado	`204 No Content`

Campos do corpo de integração

Os campos abaixo são utilizados pelo POST e pelo PUT.

Campo	Tipo	Obrigatório	Regras
`id`	integer (int64)	Somente no PUT	Deve identificar o mesmo atestado informado em `{id}`. Não enviar no POST.
`matricula`	object	Sim	Informar uma matrícula existente por meio de `matricula.id`. A matrícula deve ser de funcionário ou estagiário.
`matricula.id`	integer (int64)	Sim	Identificador da matrícula.
`numeroAtestado`	string	Não	Número externo ou número do documento de atestado.
`inicioAtestado`	string (date)	Sim	Formato `yyyy-MM-dd`.
`fimAtestado`	string (date)	Sim	Formato `yyyy-MM-dd`.
`retornoTrabalho`	string (date)	Sim	Formato `yyyy-MM-dd`.
`unidade`	string (enum)	Sim	Consulte a seção de enums.
`duracao`	number	Sim	Valor entre `0` e `999`. Quando `unidade` for `DIAS`, não pode ser fracionário.
`localAtendimento`	string (enum)	Sim	Consulte a seção de enums.
`observacao`	string	Não	Observação do atestado, com no máximo 5.000 caracteres.
`dataPericia`	string (date)	Não	Data da perícia no formato `yyyy-MM-dd`.
`dataEntrega`	string (date-time)	Não	Data e hora da entrega no formato `yyyy-MM-dd'T'HH:mm:ss`.
`deferido`	boolean	Não	Indica se o atestado foi deferido.
`encaminharMedico`	boolean	Não	Indica se o atestado deve ser encaminhado para junta médica.
`acompanhamento`	boolean	Não	Indica se o atestado decorre do acompanhamento de outra pessoa.
`tipo`	object	Não	Referência a um tipo de atestado existente.
`tipo.id`	integer (int64)	Condicional	Obrigatório quando `tipo` for enviado.
`motivoConsultaMedica`	object	Não	Referência a um motivo de consulta médica existente.
`motivoConsultaMedica.id`	integer (int64)	Condicional	Obrigatório quando `motivoConsultaMedica` for enviado.
`pessoaTerceiro`	object	Não	Pessoa acompanhada pelo titular do atestado.
`pessoaTerceiro.id`	integer (int64)	Condicional	Obrigatório quando `pessoaTerceiro` for enviado.
`estabelecimento`	object	Não	Estabelecimento de saúde relacionado ao atendimento.
`estabelecimento.id`	integer (int64)	Condicional	Obrigatório quando `estabelecimento` for enviado.
`profissional`	object	Não	Profissional responsável pelo atestado.
`profissional.id`	integer (int64)	Condicional	Obrigatório quando `profissional` for enviado.
`codigosCids`	array de string	Condicional	Códigos de CID já cadastrados no RH. Obrigatório quando `codigoCidPrincipal` for informado.
`codigoCidPrincipal`	string	Condicional	Deve existir em `codigosCids`. Obrigatório quando `codigosCids` possuir valores.
`tipoAfastamento`	object	Não	Referência a um tipo de afastamento existente.
`tipoAfastamento.id`	integer (int64)	Condicional	Obrigatório quando `tipoAfastamento` for enviado.
`afastamentoOrigem`	object	Não	Referência ao afastamento que originou o atestado.
`afastamentoOrigem.id`	integer (int64)	Condicional	Obrigatório quando `afastamentoOrigem` for enviado.
`anexos`	array	Não	Documentos relacionados ao atestado.
`anexos[].id`	integer (int64)	Somente na alteração	Identificador de um anexo existente. Omitir para um anexo novo.
`anexos[].data`	string (date)	Sim	Data do anexo no formato `yyyy-MM-dd`.
`anexos[].motivo`	string	Não	Máximo de 1.000 caracteres.
`anexos[].tipoDocumento`	object	Sim	Referência a um tipo de documento existente.
`anexos[].tipoDocumento.id`	integer (int64)	Sim	Identificador do tipo de documento.
`anexos[].arquivos`	array	Sim	Deve possuir ao menos um arquivo. O mesmo arquivo não pode ser repetido no mesmo anexo nem em anexos diferentes.
`anexos[].arquivos[].id`	integer (int64)	Sim	Identificador de arquivo previamente enviado ao storage da plataforma.

Os campos abaixo são retornados pela fonte, mas são somente para leitura e devem ser omitidos no POST e no PUT:

Campo	Tipo	Descrição
`dependentes`	array	Dependentes vinculados ao atestado.
`dependentes[].id`	integer (int64)	Identificador do vínculo do dependente com o atestado.
`dependentes[].dependente`	object	Dados da pessoa dependente.
`camposAdicionais`	object	Valores dos campos adicionais configurados para atestados. As propriedades variam conforme a configuração da entidade.
`idCargo`	integer (int64)	Identificador do cargo da matrícula, calculado pela API.
`descricaoCargo`	string	Descrição do cargo da matrícula, calculada pela API.

Propriedades transitórias de controle de processamento e estruturas internas de persistência da classe Atestado não fazem parte do contrato de integração.

Regra do CID principal

As combinações aceitas são:

`codigoCidPrincipal`	`codigosCids`	Resultado
ausente	ausente ou vazio	Válido
ausente	preenchido	Inválido
preenchido	ausente ou vazio	Inválido
preenchido	preenchido, mas sem o principal	Inválido
preenchido	preenchido e contendo o principal	Válido

No corpo de escrita, utilize codigosCids e codigoCidPrincipal. Os campos cids e cidPrincipal são retornados pela API já resolvidos e não precisam ser enviados pelo integrador.

Enums aceitos na escrita

`unidade`

HORAS
DIAS

`localAtendimento`

AMBULATORIO
CLINICA
DOMICILIAR
HOSPITAL
POSTO_MEDICO
OUTRO

GET `/atestados`

Retorna uma página de atestados.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`offset`	integer	Não	`0`	Posição inicial da página.
`limit`	integer	Não	`20`	Quantidade máxima de registros.
`filter`	string	Não	—	Filtro no padrão de fontes de dados Betha.
`sort`	string	Não	—	Ordenação no padrão de fontes de dados Betha.

Exemplo de requisição

GET
Host: rh.suite.betha.cloud/dados/v1/atestados
Accept: application/json
Authorization: Bearer <token>

O GET não possui corpo JSON.

Exemplo de resposta `200 OK`

{
  "offset": 0,
  "limit": 20,
  "total": 1,
  "hasNext": false,
  "content": [
    {
      "id": 84521,
      "matricula": {
        "id": 12345,
        "tipo": "FUNCIONARIO",
        "codigoMatriculaFormatado": "12345/1"
      },
      "profissional": null,
      "tipo": null,
      "duracao": 3,
      "unidade": "DIAS",
      "inicioAtestado": "2026-07-20",
      "fimAtestado": "2026-07-22",
      "retornoTrabalho": "2026-07-23",
      "localAtendimento": "HOSPITAL",
      "encaminharJuntaMedica": false,
      "motivoConsultaMedica": null,
      "numeroAtestado": "EXT-2026-0001",
      "tipoAfastamento": {
        "id": 321,
        "descricao": "Auxílio-doença",
        "classificacao": "AUXILIO_DOENCA_EMPREGADOR"
      },
      "afastamentoOrigem": null,
      "deferido": null,
      "acompanhamento": null,
      "pessoaTerceiro": null,
      "estabelecimento": null,
      "idCargo": 44,
      "descricaoCargo": "Analista administrativo",
      "camposAdicionais": null,
      "cidPrincipal": {
        "id": 901,
        "descricao": "Influenza com outras manifestações respiratórias",
        "codigo": "J11.1",
        "descricaoAbreviada": "Influenza",
        "nivel": "SUBCATEGORIA"
      },
      "dependentes": [],
      "cids": [
        {
          "id": 901,
          "descricao": "Influenza com outras manifestações respiratórias",
          "codigo": "J11.1",
          "descricaoAbreviada": "Influenza",
          "nivel": "SUBCATEGORIA"
        },
        {
          "id": 902,
          "descricao": "Tosse",
          "codigo": "R05",
          "descricaoAbreviada": "Tosse",
          "nivel": "CATEGORIA"
        }
      ],
      "observacao": null
    }
  ]
}

POST `/atestados/integracao`

Cria um atestado. O id é gerado pela API e não deve ser enviado.

Exemplo de requisição

POST
Host: rh.suite.betha.cloud/dados/v1/atestados/integracao
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  "matricula": {
    "id": 12345
  },
  "numeroAtestado": "0001",
  "inicioAtestado": "2026-07-20",
  "fimAtestado": "2026-07-22",
  "retornoTrabalho": "2026-07-23",
  "unidade": "DIAS",
  "duracao": 3,
  "localAtendimento": "HOSPITAL",
  "observacao": "Atestado entregue pelo funcionário",
  "dataPericia": "2026-07-21",
  "dataEntrega": "2026-07-20T09:15:00",
  "deferido": true,
  "encaminharMedico": false,
  "acompanhamento": true,
  "tipo": {
    "id": 5
  },
  "motivoConsultaMedica": {
    "id": 12
  },
  "pessoaTerceiro": {
    "id": 7788
  },
  "estabelecimento": {
    "id": 30
  },
  "profissional": {
    "id": 44
  },
  "codigosCids": [
    "J11.1",
    "R05"
  ],
  "codigoCidPrincipal": "J11.1",
  "tipoAfastamento": {
    "id": 321
  },
  "afastamentoOrigem": {
    "id": 7654
  },
  "anexos": [
    {
      "data": "2026-07-20",
      "motivo": "Atestado médico apresentado pelo funcionário",
      "tipoDocumento": {
        "id": 10
      },
      "arquivos": [
        {
          "id": 9876
        }
      ]
    }
  ]
}

Exemplo de resposta `200 OK`

{
  "id": 84521,
  "matricula": {
    "id": 12345,
    "tipo": "FUNCIONARIO"
  },
  "numeroAtestado": "EXT-2026-0001",
  "inicioAtestado": "2026-07-20",
  "unidade": "DIAS",
  "duracao": 3,
  "localAtendimento": "HOSPITAL",
  "fimAtestado": "2026-07-22",
  "observacao": "Atestado entregue pelo funcionário",
  "retornoTrabalho": "2026-07-23",
  "encaminharMedico": false,
  "acompanhamento": true,
  "motivoConsultaMedica": {
    "id": 12,
    "descricao": "Acompanhamento de dependente"
  },
  "pessoaTerceiro": {
    "id": 7788,
    "nome": "Maria da Silva",
    "foto": null,
    "cpf": "12345678909",
    "dataNascimento": "2015-05-10",
    "sexo": "FEMININO"
  },
  "estabelecimento": {
    "id": 30,
    "cnpj": "12345678000195",
    "razaoSocial": "Clínica Exemplo Ltda.",
    "nomeFantasia": "Clínica Exemplo",
    "tipo": "GERAL"
  },
  "profissional": {
    "id": 44,
    "nome": "Dra. Ana Souza",
    "profissao": "MEDICO",
    "numeroConselho": "CRM 12345"
  },
  "anexos": [
    {
      "id": 4567,
      "data": "2026-07-20",
      "motivo": "Atestado médico apresentado pelo funcionário",
      "atestado": {
        "id": 84521
      },
      "tipoDocumento": {
        "id": 10,
        "descricao": "Atestado médico"
      },
      "arquivos": [
        {
          "id": 9876,
          "description": "Atestado médico",
          "name": "atestado-2026-0001.pdf",
          "type": "application/pdf",
          "size": 184320,
          "bucket": "folha",
          "key": "atestados/atestado-2026-0001.pdf",
          "url": "https://storage.exemplo/arquivo-assinado"
        }
      ]
    }
  ],
  "cids": [
    {
      "id": 901,
      "descricao": "Influenza com outras manifestações respiratórias",
      "codigo": "J11.1",
      "descricaoAbreviada": "Influenza",
      "nivel": "SUBCATEGORIA"
    },
    {
      "id": 902,
      "descricao": "Tosse",
      "codigo": "R05",
      "descricaoAbreviada": "Tosse",
      "nivel": "CATEGORIA"
    }
  ],
  "codigoCidPrincipal": "J11.1",
  "codigosCids": [
    "J11.1",
    "R05"
  ],
  "tipoAfastamento": {
    "id": 321,
    "descricao": "Auxílio-doença",
    "classificacao": "AUXILIO_DOENCA_EMPREGADOR"
  },
  "afastamentoOrigem": {
    "id": 7654,
    "tipoAfastamento": {
      "id": 321,
      "descricao": "Auxílio-doença",
      "classificacao": "AUXILIO_DOENCA_EMPREGADOR"
    },
    "inicioAfastamento": "2026-07-20",
    "fimAfastamento": "2026-07-22"
  },
  "cidPrincipal": {
    "id": 901,
    "descricao": "Influenza com outras manifestações respiratórias",
    "codigo": "J11.1",
    "descricaoAbreviada": "Influenza",
    "nivel": "SUBCATEGORIA"
  },
  "dataPericia": "2026-07-21",
  "tipo": {
    "id": 5,
    "descricao": "Atestado médico"
  },
  "dataEntrega": "2026-07-20T09:15:00",
  "deferido": true,
  "camposAdicionais": {},
  "dependentes": [],
  "idCargo": 44,
  "descricaoCargo": "Analista administrativo"
}

PUT `/atestados/integracao/{id}`

Atualiza um atestado existente.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer (int64)	Sim	Identificador do atestado.

O corpo deve representar o estado completo do atestado. Para evitar atualização do registro errado, envie o mesmo identificador no caminho e em id no JSON.

Exemplo de requisição

PUT
Host: rh.suite.betha.cloud/dados/v1/atestados/integracao/84521
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  "id": 84521,
  "matricula": {
    "id": 12345
  },
  "numeroAtestado": "0001-RETIFICADO",
  "inicioAtestado": "2026-07-20",
  "fimAtestado": "2026-07-23",
  "retornoTrabalho": "2026-07-24",
  "unidade": "DIAS",
  "duracao": 4,
  "localAtendimento": "HOSPITAL",
  "observacao": "Atestado retificado após conferência",
  "dataPericia": "2026-07-22",
  "dataEntrega": "2026-07-20T09:15:00",
  "deferido": true,
  "encaminharMedico": false,
  "acompanhamento": true,
  "tipo": {
    "id": 5
  },
  "motivoConsultaMedica": {
    "id": 12
  },
  "pessoaTerceiro": {
    "id": 7788
  },
  "estabelecimento": {
    "id": 30
  },
  "profissional": {
    "id": 44
  },
  "codigosCids": [
    "J11.1"
  ],
  "codigoCidPrincipal": "J11.1",
  "tipoAfastamento": {
    "id": 321
  },
  "afastamentoOrigem": {
    "id": 7654
  },
  "anexos": [
    {
      "id": 4567,
      "data": "2026-07-20",
      "motivo": "Documento retificado",
      "tipoDocumento": {
        "id": 10
      },
      "arquivos": [
        {
          "id": 9876
        }
      ]
    }
  ]
}

Exemplo de resposta `200 OK`

{
  "id": 84521,
  "matricula": {
    "id": 12345,
    "tipo": "FUNCIONARIO"
  },
  "numeroAtestado": "0001-RETIFICADO",
  "inicioAtestado": "2026-07-20",
  "unidade": "DIAS",
  "duracao": 4,
  "localAtendimento": "HOSPITAL",
  "fimAtestado": "2026-07-23",
  "observacao": "Atestado retificado após conferência",
  "retornoTrabalho": "2026-07-24",
  "encaminharMedico": false,
  "acompanhamento": true,
  "motivoConsultaMedica": {
    "id": 12,
    "descricao": "Acompanhamento de dependente"
  },
  "pessoaTerceiro": {
    "id": 7788,
    "nome": "Maria da Silva",
    "foto": null,
    "cpf": "12345678909",
    "dataNascimento": "2015-05-10",
    "sexo": "FEMININO"
  },
  "estabelecimento": {
    "id": 30,
    "cnpj": "12345678000195",
    "razaoSocial": "Clínica Exemplo Ltda.",
    "nomeFantasia": "Clínica Exemplo",
    "tipo": "GERAL"
  },
  "profissional": {
    "id": 44,
    "nome": "Dra. Ana Souza",
    "profissao": "MEDICO",
    "numeroConselho": "CRM 12345"
  },
  "anexos": [
    {
      "id": 4567,
      "data": "2026-07-20",
      "motivo": "Documento retificado",
      "atestado": {
        "id": 84521
      },
      "tipoDocumento": {
        "id": 10,
        "descricao": "Atestado médico"
      },
      "arquivos": [
        {
          "id": 9876,
          "description": "Atestado médico",
          "name": "atestado-2026-0001.pdf",
          "type": "application/pdf",
          "size": 184320,
          "bucket": "folha",
          "key": "atestados/atestado-2026-0001.pdf",
          "url": "https://storage.exemplo/arquivo-assinado"
        }
      ]
    }
  ],
  "cids": [
    {
      "id": 901,
      "descricao": "Influenza com outras manifestações respiratórias",
      "codigo": "J11.1",
      "descricaoAbreviada": "Influenza",
      "nivel": "SUBCATEGORIA"
    }
  ],
  "codigoCidPrincipal": "J11.1",
  "codigosCids": [
    "J11.1"
  ],
  "tipoAfastamento": {
    "id": 321,
    "descricao": "Auxílio-doença",
    "classificacao": "AUXILIO_DOENCA_EMPREGADOR"
  },
  "afastamentoOrigem": {
    "id": 7654,
    "tipoAfastamento": {
      "id": 321,
      "descricao": "Auxílio-doença",
      "classificacao": "AUXILIO_DOENCA_EMPREGADOR"
    },
    "inicioAfastamento": "2026-07-20",
    "fimAfastamento": "2026-07-23"
  },
  "cidPrincipal": {
    "id": 901,
    "descricao": "Influenza com outras manifestações respiratórias",
    "codigo": "J11.1",
    "descricaoAbreviada": "Influenza",
    "nivel": "SUBCATEGORIA"
  },
  "dataPericia": "2026-07-22",
  "tipo": {
    "id": 5,
    "descricao": "Atestado médico"
  },
  "dataEntrega": "2026-07-20T09:15:00",
  "deferido": true,
  "camposAdicionais": {},
  "dependentes": [],
  "idCargo": 44,
  "descricaoCargo": "Analista administrativo"
}

Se o {id} não existir, a API retorna erro de recurso não encontrado com a mensagem:

Nenhum atestado foi encontrado para o identificador informado.

DELETE `/atestados/integracao/{id}`

Exclui o atestado e trata os vínculos de afastamento, ausência e anexos associados.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer (int64)	Sim	Identificador do atestado.

Exemplo de requisição

DELETE
Host: rh.suite.betha.cloud/dados/v1/atestados/integracao/84521
Accept: application/json
Authorization: Bearer <token>

O DELETE não possui corpo JSON.

Resposta `204 No Content`

Não há corpo na resposta:

<sem conteúdo>

Se o {id} não existir, a API retorna erro de recurso não encontrado com a mensagem:

Nenhum atestado foi encontrado para o identificador informado.

Respostas de erro

Status	Situação
`400 Bad Request`	JSON inválido, campo obrigatório ausente, enum inválido, referência inexistente ou regra de negócio não atendida.
`401 Unauthorized`	Token ausente ou inválido.
`403 Forbidden`	Token sem o escopo necessário.
`404 Not Found`	Atestado informado no PUT ou DELETE não encontrado.
`500 Internal Server Error`	Erro interno não tratado.

Entre as validações que podem produzir 400 estão:

duração, unidade, data inicial ou data final ausente;
duração fora do intervalo de 0 a 999;
duração fracionada com unidade DIAS;
matrícula que não seja de funcionário ou estagiário;
CID informado que não exista no cadastro;
CID principal ausente da lista de CIDs;
documento sem data, tipo de documento ou arquivo;
arquivo repetido em um ou mais anexos.

O formato exato do envelope de erro é fornecido pela infraestrutura comum da API e pode variar conforme o tipo da exceção. A integração deve usar o status HTTP e a mensagem retornada, sem depender de um único formato de envelope.

API de integração de atestados

Informações gerais​

Resumo dos endpoints​

Campos do corpo de integração​

Regra do CID principal​

Enums aceitos na escrita​

unidade​

localAtendimento​

GET /atestados​

Parâmetros de query​

Exemplo de requisição​

Exemplo de resposta 200 OK​

POST /atestados/integracao​

Exemplo de requisição​

Exemplo de resposta 200 OK​

PUT /atestados/integracao/{id}​

Parâmetros de caminho​

Exemplo de requisição​

Exemplo de resposta 200 OK​

DELETE /atestados/integracao/{id}​

Parâmetros de caminho​

Exemplo de requisição​

Resposta 204 No Content​

Respostas de erro​

Informações gerais

Resumo dos endpoints

Campos do corpo de integração

Regra do CID principal

Enums aceitos na escrita

`unidade`

`localAtendimento`

GET `/atestados`

Parâmetros de query

Exemplo de requisição

Exemplo de resposta `200 OK`

POST `/atestados/integracao`

Exemplo de requisição

Exemplo de resposta `200 OK`

PUT `/atestados/integracao/{id}`

Parâmetros de caminho

Exemplo de requisição

Exemplo de resposta `200 OK`

DELETE `/atestados/integracao/{id}`

Parâmetros de caminho

Exemplo de requisição

Resposta `204 No Content`

Respostas de erro