API Titles - v1.000 (Invoicing)

CONTEÚDO

Visão Geral
Exemplo de utilização
Tela api titles
1. Outras Ações / Ações relacionadas
Tela api titles
1. Principais Campos e Parâmetros
Tabelas utilizadas

01. VISÃO GERAL

API para a entidade titles (títulos) do produto TOTVS Saúde Planos Linha Protheus.

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

Autenticação das APIs

API para obtenção do token de acesso às API’s REST no Protheus

De posse então do access_token obtido na api token, basta fazer a requisição à API desejada incluindo no cabeçalho o parâmetro Authorization com o valor Bearer mais o token de acesso.

02. EXEMPLO DE UTILIZAÇÃO

Titles - Retorna os títulos dos beneficiários/empresas

Retorna os títulos da empresa ou do beneficiário no Financeiro (Contas a receber).

/totvsHealthPlans/invoicing/v1/titles

GET

Parameters

Authorization (header)	string	Cabeçalho usado para autorização das requisições (Bearer token)	*required
Content-Type (header)	string	'application/json' é o formato do conteúdo	*required
healthInsurerCode (query)	string	Código da operadora (E1_CODINT)	*required (Quando o subcriberId não for informado)
companyCode (query)	string	Código da empresa (E1_CODEMP)	*required (Quando o subcriberId não for informado)
subscriberId (query)	string	Matricula do beneficiário (BA1_CODINT+BA1_CODEMP+BA1_MATRIC+BA1_TIPREG+BA1_DIGITO)
familyCode (query)	string	Matricula da família (E1_MATRIC) Obs: Filtro para títulos referente a família do beneficiário.
contractCode (query)	string	Contrato da empresa (E1_CONEMP) Obs: Filtro para títulos referente a empresa
contractVersionCode (query)	string	Versão do contrato (E1_VERCON) Obs: Filtro para títulos referente a empresa
subcontractCode (query)	string	Subcontrato do contrato da empresa (E1_SUBCON) Obs: Filtro para títulos referente a empresa
subcontractVersionCode (query)	string	Versão do subcontrato (E1_VERSUB) Obs: Filtro para títulos referente a empresa
type (query)	string	Tipo do título (E1_TIPO), pode ser enviado mais de um tipo. Ex: NCC,DP
status (query)	string	Status do título (E1_STATUS)
situation (query)	string	FIltro dos títulos pela situação, sendo: 0 = Carteira 1 = Cob.Simples 2 = Descontada 3 = Caucionada 4 = Vinculada 5 = Advogado;6=Judicial Pode ser informado mais de uma situação, ex: 2,3,4
page (query)	string	Valor numérico (maior que zero) representando a página solicitada
pageSize (query)	string	Valor numérico (maior que zero) representando o total de registros retornados na consulta
order (query)	string	Lista de campos para ordenação, separada por virgula (,).
fields (query)	string	Lista com o nome das propriedades JSON que serão retornadas.
filter (query)	string	Filtros seguindo o padrão ODATA

Request

Body

Não possui body!

(200) - Operação realizada com sucesso

hasNext	boolean	Indica se ainda existem registros a serem retornados		*required
remainingRecords	integer	Quantidade de registros ainda existem para retorno		*required
items	array	Lista de títulos retornados
items.customer_id	string	Código	E1_CLIENTE	*required
items.customer_store	string	Descrição	E1_LOJA	*required
items.customer_name	string	Tipo de grupo (Pessoa física ou jurídica)	E1_NOMCLI
items.issue_date	string (date)	Data de Emissão do Titulo	E1_EMISSAO	*required
items.prefix	string	Prefixo do titulo	E1_PREFIXO
items.number	string	Numero do Titulo	E1_NUM	*required
items.parcel	string	Parcela do Titulo	E1_PARCELA
items.type	string	Tipo do titulo	E1_TIPO	*required
items.base_month	string	Mês Base	E1_MESBASE
items.base_year	string	Ano Base	E1_ANOBASE
items.real_due_date	string (date)	Vencimento real do Titulo	E1_VENCREA	*required
items.amount	number (double)	Valor do Titulo	E1_VALOR	*required
items.balance	number (double)	Saldo a Receber	E1_SALDO
items.net_value	number (double)	Valor Liquido da Baixa	E1_VALLIQ
items.low_date	string (date)	Data de Baixa do Titulo	E1_BAIXA
items.status	string	Status do Titulo	Sendo: A = Aberto P = Baixado Parcial B = Baixado
items.title_id	string	Chave de busca do Titulo	E1_PREFIXO+E1_NUM+E1_PARCELA+E1_TIPO	*required
items.situation	string	Situação do titulo	E1_SITUACA
items.links	array	links relacionados ao recurso títles (Padrão HATEOAS): rel: bankSlip rel: bankSlip/base64		*required

Exemplo

{
    "items": [
        {
            "customer_id": "PLS103",
            "customer_store": "01",
            "customer_name": "ARTHUR E BETINA PAES",
            "issue_date": "2021-04-05",
            "prefix": "PLS",
            "number": "000007027",
            "parcel": "",
            "type": "DP",
            "base_month": "04",
            "base_year": "2021",
            "real_due_date": "2021-04-26",
            "amount": 30351.4,
            "balance": 0,
            "net_value": 28541.08,
            "low_date": "2022-12-20",
            "status": "B",
            "title_id": "PLS000007027+DP",
			"situation": "1",
            "links": [
                {
                    "rel": "bankSlip",
                    "href": "/totvsHealthPlans/invoicing/v1/titles/PLS000007027+DP/bankSlip"
                },
                {
                    "rel": "bankSlip/base64",
                    "href": "/totvsHealthPlans/invoicing/v1/titles/PLS000007027+DP/bankSlip/base64"
                }
            ]
        }
    ],
    "hasNext": true,
    "remainingRecords": 11
}

(406) - Parâmetros obrigatórios

code	string	Código identificador do erro.	*required
message	string	Literal no idioma da requisição descrevendo o erro para o usuário.	*required
detailedMessage	string	Mensagem técnica e mais detalhada do erro.	*required
details	array	Lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo

{
    "code": "E001",
    "message": "Existem chaves obrigatórias que não foram informadas.",
    "detailedMessage": "Verifique a lista de erros no campo details para mais detalhes.",
    "details": [
        {
            "code": "E001-406",
            "message": "Chave health-insurer-code obrigatória",
            "detailedMessage": "Não foi informado no queryParams da requisição a chave health-insurer-code."
        }
    ]
}

BankSlip - Retorna os dados do boleto bancário

Retorna os dados no json do boleto bancário informado.

/totvsHealthPlans/invoicing/v1/titles/{titleId}/bankSlip

GET

Parameters

Authorization (header)	string	Cabeçalho usado para autorização das requisições (Bearer token)	*required
Content-Type (header)	string	'application/json' é o formato do conteúdo	*required
titleId (path)	string	Chave do Titulo (E1_PREFIXO+E1_NUM+E1_PARCELA+E1_TIPO)	*required
fields (query)	string	Lista com o nome das propriedades JSON que serão retornadas.
expand (query)	string	Lista com o nome das propriedades para expandir, descritos no campo *_expandables* da api.

Request

Body

Não possui body!

(200) - Operação realizada com sucesso

digitableLine	string	Linha digitável
dueDate	string (date)	Vencimento
documentDate	string (date)	Data do Documento
documentNumber	string	Nro.Documento
documentType	string	Espécie Doc.
acceptance	string	Aceite
processingDate	string (date)	Data do Processamento
documentValue	number (double)	(=)Valor do Documento
otherAdditions	number (double)	(+)Outros Acréscimos
discount	number (double)	(-)Desconto/Abatimento
competenceMonth	string	Mês Competencia
competenceYear	string	Ano Competencia
assignor	object (json)	Operadora Saúde - Cedente do boleto
assignor.name	string	Nome
assignor.address	string	Endereço
assignor.addressComplement	string	Complemento de Endereço
assignor.district	string	Bairro
assignor.cityCodeResidence	string	Cidade
assignor.stateAbbreviation	string	Estado
assignor.zipCode	string	CEP
assignor.phoneNumber	string	Telefone
assignor.cnpj	string	CNPJ
assignor.codeSusep	string	Código SUSEP - ANS
assignor.observation	string	Observação
assignor.instructions	string	Instruções/Texto de responsabilidade do cedente
drawee	object (json)	Recibo do Sacado
drawee.name	string	Nome do Cliente
drawee.code	string	Código do Cliente
drawee.cpf	string	CPF (Para pessoa física)
drawee.cnpj	string	CNPJ (Para pessoa jurídica)
drawee.address	string	Endereço do Cliente
drawee.district	string	Bairro do Cliente
drawee.cityCodeResidence	string	Cidade
drawee.stateAbbreviation	string	Estado
drawee.zipCode	string	CEP
bank	object (json)	Banco
bank.name	string	Nome do Banco
bank.code	string	Código do Banco
bank.agencyAssignorCode	string	Agência/Código Cedente
bank.ourNumber	string	Nosso Número
bank.walletCode	string	Carteira
_expandables	array	Propriedades expansíveis: billingDetails openMonths users userUsage
billingDetails	array	Detalhes da Cobrança dos beneficiários
billingDetails.subscriberId	string	Matricula do Beneficiário
billingDetails.name	string	Nome do Beneficiário
billingDetails.compositions	array	Composições do título do Beneficiário
billingDetails.compositions.typeCode	string	Código do lançamento
billingDetails.compositions.typeDescription	string	Descrição do lançamento
billingDetails.compositions.value	number (double)	Valor
billingDetails.compositions.numberANS	string	Número na ANS
openMonths	array	Meses em aberto
openMonths.month	string	Mês em aberto
openMonths.year	string	Ano em aberto
users	array	Usuários (Beneficiários da Família)
users.recordType	string	Tipo de Registro do Beneficiário
users.name	string	Nome do Beneficiário
users.effectiveDate	string (date)	Data de Inclusão
userUsage	array	Detalhes da Utilização
userUsage.subscriberName	string	Nome do Beneficiário
userUsage.healthProviderName	string	Nome da Rede de Atendimento
userUsage.procedureCode	string	Código do Procedimento
userUsage.procedureName	string	Descrição do Procedimento
userUsage.executionDate	string (date)	Data Utilização
userUsage.quantity	number (double)	Quantidade
userUsage.coPaymentValue	number (double)	Valor Total

Exemplo

{
    "digitableLine": "",
    "dueDate": "2022-10-17",
    "documentDate": "2023-05-26",
    "documentNumber": "000007042",
    "documentType": "R$",
    "acceptance": "N",
    "processingDate": "2022-10-17",
    "documentValue": 0,
    "otherAdditions": 0,
    "discount": 0,
    "competenceMonth": "01",
    "competenceYear": "2022",
    "assignor": {
        "name": "OPERADORA 417505",
        "address": "RUA COPACABANA",
        "addressComplement": "",
        "district": "SAO PAULO",
        "cityCodeResidence": "SAO PAULO",
        "stateAbbreviation": "SP",
        "zipCode": "02461000",
        "phoneNumber": "",
        "cnpj": "54097504000109",
        "codeSusep": "417505",
        "observation": "",
        "instructions": ""
    },
    "drawee": {
        "name": "VITOR MIGUEL FREITAS",
        "code": "TMSWBI",
        "cpf": "40492401810",
        "cnpj": "",
        "address": "ALBERT BARTHOLOME ,100",
        "district": "JARDIM DAS VERTENTES",
        "cityCodeResidence": "SAO PAULO",
        "stateAbbreviation": "SP",
        "zipCode": "05541000"
    },
    "bank": {
        "name": "BANCO DO PRE FA",
        "code": "-9",
        "agencyAssignorCode": "00001/0000000001",
        "ourNumber": "",
        "walletCode": "9"
    },
    "_expandables": [
        "billingDetails",
        "openMonths",
        "users",
        "userUsage"
    ]
}

(406) - Parâmetros obrigatórios

code	string	Código identificador do erro.	*required
message	string	Literal no idioma da requisição descrevendo o erro para o usuário.	*required
detailedMessage	string	Mensagem técnica e mais detalhada do erro.	*required
details	array	Lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo

{
    "code": "E002",
    "message": "Existem chaves obrigatórias que não foram informadas.",
    "detailedMessage": "Verifique a lista de erros no campo details para mais detalhes.",
    "details": [
        {
            "code": "E002-406",
            "message": "Chave titleId obrigatória",
            "detailedMessage": "Não foi informado no pathParams da requisição a chave titleId."
        }
    ]
}

(404) - Titulo não encontrada

code	string	Código identificador do erro.	*required
message	string	Literal no idioma da requisição descrevendo o erro para o usuário.	*required
detailedMessage	string	Mensagem técnica e mais detalhada do erro.	*required
details	array	Lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo

{
    "code": "E003",
    "message": "Título não encontrado no Financeiro",
    "detailedMessage": "Não foi encontrada na tabela SE1 o título PLS000007942 DP (E1_PREFIXO+E1_NUM+E1_PARCELA+E1_TIPO)."
}

(400) - Boleto não disponível

code	string	Código identificador do erro.	*required
message	string	Literal no idioma da requisição descrevendo o erro para o usuário.	*required
detailedMessage	string	Mensagem técnica e mais detalhada do erro.	*required
details	array	Lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo

{
    "code": "E004",
    "message": "Boleto Bancário não disponível.",
    "detailedMessage": "O título PLS000007032 DP se encontra na situação em Carteira no Financeiro."
}

BankSlip/Base64 - Retorna o boleto bancário em arquivo base 64

Retorna o boleto bancário informado em arquivo base 64.

/totvsHealthPlans/invoicing/v1/titles/{titleId}/bankSlip/base64

GET

Parameters

Authorization (header)	string	Cabeçalho usado para autorização das requisições (Bearer token)	*required
Content-Type (header)	string	'application/json' é o formato do conteúdo	*required
titleId (path)	string	Chave do Titulo (E1_PREFIXO+E1_NUM+E1_PARCELA+E1_TIPO)	*required

Request

Body

Não possui body!

(200) - Operação realizada com sucesso

fileName	string	Nome do arquivo em PDF		*required
file	string	String do arquivo em base 64		*required

Exemplo

{
    "fileName": "boletosc005630.pdf",
    "file": "JVBERi0xLjMKJbe+raoKMSAwIG9iago8PAovVHlwZSAvQ2F0YW..."
}

(406) - Parâmetros obrigatórios

code	string	Código identificador do erro.	*required
message	string	Literal no idioma da requisição descrevendo o erro para o usuário.	*required
detailedMessage	string	Mensagem técnica e mais detalhada do erro.	*required
details	array	Lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo

{
    "code": "E002",
    "message": "Existem chaves obrigatórias que não foram informadas.",
    "detailedMessage": "Verifique a lista de erros no campo details para mais detalhes.",
    "details": [
        {
            "code": "E002-406",
            "message": "Chave titleId obrigatória",
            "detailedMessage": "Não foi informado no pathParams da requisição a chave titleId."
        }
    ]
}

(404) - Titulo não encontrada

code	string	Código identificador do erro.	*required
message	string	Literal no idioma da requisição descrevendo o erro para o usuário.	*required
detailedMessage	string	Mensagem técnica e mais detalhada do erro.	*required
details	array	Lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo

{
    "code": "E003",
    "message": "Título não encontrado no Financeiro",
    "detailedMessage": "Não foi encontrada na tabela SE1 o título PLS000007942 DP (E1_PREFIXO+E1_NUM+E1_PARCELA+E1_TIPO)."
}

(400) - Boleto não disponível

code	string	Código identificador do erro.	*required
message	string	Literal no idioma da requisição descrevendo o erro para o usuário.	*required
detailedMessage	string	Mensagem técnica e mais detalhada do erro.	*required
details	array	Lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo

{
    "code": "E004",
    "message": "Boleto Bancário não disponível.",
    "detailedMessage": "O título PLS000007032 DP se encontra na situação em Carteira no Financeiro."
}

03. TELA API TITLES

Outras Ações / Ações relacionadas

Ação	Descrição
Não se aplica	Não se aplica

04. TELA API TITLES

Principais Campos e Parâmetros

Campo	Descrição
E1_CODINT	Código da operadora saúde
E1_CODEMP	Código da empresa
E1_MATRIC	Matricula da família
E1_PREFIXO	Prefixo do titulo
E1_NUM	Número do titulo
E1_PARCELA	Parcela do titulo
E1_TIPO	Tipo do titulo
MV_RELT	Diretório no servidor para gravar os boletos gerados pela api

05. TABELAS UTILIZADAS

Contas a Receber (SE1)
Bancos (SA6)
Operadoras de Saúde (BA0)
Clientes (SA1)
Composição da Cobrança (BM1)
Cabeçalho de Mensagem (BH1)
Itens de Mensagem (BH2)
Beneficiários (BA1)
Eventos Processamentos Contas (BD6)

Árvore de páginas

API Titles - v1.000 (Invoicing)

CONTEÚDO

01. VISÃO GERAL

02. EXEMPLO DE UTILIZAÇÃO

03. TELA API TITLES

04. TELA API TITLES

05. TABELAS UTILIZADAS