Exibir origem

CONTEÚDO

Introdução
Endpoint
Parâmetros
Resposta

01. INTRODUÇÃO

Esta API cria um novo lote de importação de beneficiários em massa na operadora.
Os beneficiários serão gerados com um protocolo ao serem importados na rotina de análise de beneficiários (PLSA977AB), permitindo que a operadora análise e aprove a inclusão no grupo familiar (PLSA174).

Clique aqui para detalhes sobre como habilitar o serviço de APIs no Protheus.

02. ENDPOINT

/totvsHealthPlans/familyContract/v1/beneficiaries/importBatches

03. PARÂMETROS

Nome	Tipo	Localização	Descrição
Content-Type	string	header	multipart/form-data ou application/json (body)
Authorization	string	Header	Token de acesso obtido via a API de autenticação, no formato Bearer <access_token>.
healthInsurerCode	string	body/form	Código da operadora
companyCode	string	body/form	Código da empresa
contractCode	string	body/form	Código do contrato
contractVersion	string	body/form	Versão do contrato
subcontractCode	string	body/form	Código do subcontrato
subcontractVersion	string	body/form	Versão do subcontrato
loginUser	string	body/form	Login do portal
file	file	form-data	Arquivo CSV com os beneficiários
fileBase64	string	body	Arquivo CSV em Base64
fileName	string	body	Nome do arquivo CSV

Pode-se enviar o arquivo CSV dos beneficiários via file (form-data) ou fileBase64 (body) com o fileName.

{
  "healthInsurerCode": "0001",
  "companyCode": "1017",
  "contractCode": "000000000001",
  "contractVersion": "001",
  "subcontractCode": "000000001",
  "subcontractVersion": "001",
  "loginUser": "TOTVS",
  "fileBase64": "QjJOX0NPRFNFUTtCMk5fQ1BGVVNSO0IyTl9OT01VU1I7QjJOX0RBVE5BUztCMk5...",
  "fileName": "modelo-importacao-beneficiarios.csv"
}

04. RESPOSTA

201 - Operação realizada com sucesso

O sistema cria um novo lote na rotina de Lotes de Importação de Beneficiários (PLCTO001) com status Recebido, e anexa o arquivo CSV ao banco de conhecimento do lote.

Campo	Descrição	Campo (Protheus)
batchCode	Código do Lote	BJ5_CODLOT
status	Status do Lote	BJ5_STATUS
importDate	Data da importação	BJ5_DATIMP
importTime	Hora da importação	BJ5_HORIMP
loginUser	Usuário que gerou o lote	BJ5_USRLOG
healthInsurerCode	Código da operadora	BJ5_CODOPE
companyCode	Código da empresa	BJ5_CODEMP
contractCode	Código do contrato	BJ5_CONEMP
contractVersion	Versão do contrato	BJ5_VERCON
subcontractCode	Código do subcontrato	BJ5_SUBCON
subcontractVersion	Versão do subcontrato	BJ5_VERSUB
subcontractDescription	Descrição do subcontrato	BQC_DESCRI
totalCount	Total de beneficiários do lote	BJ5_QTDTOT
importedCount	Total de beneficiários importados (em processamento, pode variar)	BJ5_QTDIMP
errorCount	Total de beneficiários com erro (em processamento, pode variar)	BJ5_QTDERR

{
    "batchCode": "00000155",
    "status": "1",
    "importDate": "2025-08-22",
    "importTime": "17:07:17",
    "loginUser": "VINIEMP",
    "healthInsurerCode": "0001",
    "companyCode": "1017",
    "contractCode": "000000000001",
    "contractVersion": "001",
    "subcontractCode": "000000001",
    "subcontractVersion": "001",
    "subcontractDescription": "CONTRATO DE IMPOT. DE BENEFICIARIOS",
    "totalCount": 8,
    "importedCount": 0,
    "errorCount": 0
}

404 - Contrato informado não encontrado.

400 - Erro ao processar o arquivo CSV.

400 - Os campos do cabeçalho do arquivo não correspondem ao modelo esperado para a importação de beneficiários.

400 - O arquivo CSV do lote está vazio e não contém dados de beneficiários para processar.

400 - Parâmetro obrigatório não informado.

Campo	Tipo	Descrição
code		Código identificador do erro.
message		Literal no idioma da requisição descrevendo o erro para o usuário.
detailedMessage		Mensagem técnica e mais detalhada do erro.

{
  "status": 400,
  "message": "Erro ao processar o arquivo CSV",
  "detailedMessage": "Não foi possível obter o arquivo CSV. Verifique se o arquivo está disponível e se está em um formato válido."
}