API Lotes de Importação - Criar Lote de Importação de Beneficiários - Versão 1.0

CONTEÚDO

Introdução
Endpoint
Parâmetros
Resposta

01. INTRODUÇÃO

Esta API permite criar 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 analise 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

POST /totvsHealthPlans/familyContract/v1/beneficiaries/importBatches

03. PARÂMETROS

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

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

Exemplo de Body

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

Exemplo

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

400 - Formato de JSON inválido.
O corpo da requisição não está em um formato JSON válido. Verifique a estrutura e tente novamente.

400 - Erro ao processar o arquivo CSV.
Não foi possível obter o arquivo CSV. Verifique se o arquivo está disponível e se está em um formato válido.

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 - Falha na validação dos dados.
"Mensagem de erro do MVC"

400 - Parâmetro obrigatório não informado.
O parâmetro obrigatório deve ser enviado na requisição.

404 - Contrato informado não encontrado.
O contrato informado não foi encontrado na tabela BQC. Verifique se o número do contrato está correto e devidamente cadastrado no sistema.

406 - Formato de dados inválido.
Os dados enviados não estão no formato form-data. Verifique se o Content-Type da requisição está definido como multipart/form-data e se os campos foram corretamente estruturados.

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

Exemplo JSON de 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."
}

Árvore de páginas