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 | | header | multipart/form-data ou application/json (body) |
| Authorization | string | | Token de acesso obtido via a API de autenticação, no formato Bearer <access_token>. | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| healthInsurerCode | string | | Código da operadora | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| companyCode | string | | Código da empresa | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| contractCode | string | | Código do contrato | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| contractVersion | string | | Versão do contrato | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| subcontractCode | string | | Código do subcontrato | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| subcontractVersion | string | | Versão do subcontrato | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| loginUser | string | | Login do portal | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| file | file | | Arquivo CSV com os beneficiários | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| fileBase64 | string | | Arquivo CSV em Base64 | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| fileName | string | | Nome do arquivo CSV | Estado |
|---|
| subtle | true |
|---|
| colour | Red |
|---|
| title | Required |
|---|
|
|
| Informações |
|---|
Pode-se enviar o arquivo CSV dos beneficiários via file (form-data) ou fileBase64 (body) com o fileName. |
| Bloco de código |
|---|
| language | c# |
|---|
| theme | Midnight |
|---|
| title | Exemplo de Body |
|---|
| collapse | true |
|---|
|
{
"healthInsurerCode": "0001",
"companyCode": "1017",
"contractCode": "000000000001",
"contractVersion": "001",
"subcontractCode": "000000001",
"subcontractVersion": "001",
"loginUser": "TOTVS",
"fileBase64": "QjJOX0NPRFNFUTtCMk5fQ1BGVVNSO0IyTl9OT01VU1I7QjJOX0RBVE5BUztCMk5...",
"fileName": "modelo-importacao-beneficiarios.csv"
} |
04. RESPOSTA
| Informações |
|---|
|
| Dica |
|---|
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 | | Código do Lote | BJ5_CODLOT | | status | | Status do Lote | BJ5_STATUS | | importDate | | Estado |
|---|
| |
|---|
| subtle | true |
|---|
| title | string (DATE) |
|---|
|
| 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 |
| Bloco de código |
|---|
| language | c# |
|---|
| theme | Midnight |
|---|
| title | Exemplo |
|---|
| collapse | true |
|---|
| {
"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
} |
|
| Informações |
|---|
|
| Aviso |
|---|
400 - Erro ao processar o arquivo CSV. |
| Aviso |
|---|
400 - Os campos do cabeçalho do arquivo não correspondem ao modelo esperado para a importação de beneficiários. |
| Aviso |
|---|
400 - O arquivo CSV do lote está vazio e não contém dados de beneficiários para processar. |
| 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. |
| Bloco de código |
|---|
| language | c# |
|---|
| theme | Midnight |
|---|
| title | Exemplo JSON de Erro |
|---|
| collapse | true |
|---|
| {
"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."
} |
|
