Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

...

Dica
titleAutenticaçã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.

Informações
titleNomenclatura das APIs

Para nome composto, as APIs utilizam o padrão camelCase e quando a houver paginação será utilizado o padrão tudo minúsculo separado por hífen para os campos dentro do array items


02. EXEMPLO DE UTILIZAÇÃO

...

Painel
titleColorOrange
borderStylesolid
titleRefunds - Retorna os protocolos de reembolso

Retorna os protocolos de reembolso do beneficiário

/totvsHealthPlans/attendance/v1/refunds

GET

Nota
Expandir
titleParameters
protocol
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
subscriberId (query)string

Matricula do beneficiário (BA1_CODINT+BA1_CODEMP+BA1_MATRIC+BA1_TIPREG+BA1_DIGITO)

(obtido através da API Beneficiaries - v1.000 (Family Contract))

*required
requestDateInitial (query)string (date)

Data inicial de solicitação do protocolo

Obrigatório para quando não for informado o query param

protocol ou previousMonths


requestDateFinal (query)string (date)

Data final de solicitação do protocolo

Obrigatório para quando não for informado o query param protocol  ou previousMonths


protocol (query)stringNumero do protocolo (BOW_PROTOC)
status (query)string

Status do protocolo de reembolso, sendo:

  • 0 - Solicitação não concluída
  • 1 - Protocolado
  • 2 - Em analise
  • 3 - Reembolso aprovado
  • 4 - Reembolso rejeitado
  • 5 - Aguardando informação do Beneficiário
  • 6 - Aprovado Parcialmente
  • 7 - Cancelado
  • 8 - Reembolso revertido

pode ser enviado mais de um status. Exemplo: 0,1,2,3


previousMonths (query)string

Quantidade de meses anteriores dos protocolos, exemplo: caso seja informado "2", o sistema irá trazer os protocolos dos últimos 2 meses.


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
Dica
Expandir
titleRequest

Body


Não possui body!

Dica
Expandir
title(200) - Operação realizada com sucesso
hasNextbooleanIndica se ainda existem registros a serem retornados
*required
remainingRecordsnumeric (integer)Quantidade de registros ainda existem para retorno
*required
itemsarrayLista de protocolos de reembolso retornados

items.statusstring

Status do protocolo:

  • 0 - Solicitação não concluída
  • 1 - Protocolado
  • 2 - Em analise
  • 3 - Reembolso aprovado
  • 4 - Reembolso rejeitado
  • 5 - Aguardando informação do Beneficiário
  • 6 - Aprovado Parcialmente
  • 7 - Cancelado
  • 8 - Reembolso revertido
BOW_STATUS*required
items.protocolstringNumero do protocolo de reembolsoBOW_PROTOC*required
items.requestDaterequest_datestring (date)Data da solicitaçãoBOW_DTDIGI*required
items.presentedAmountpresented_amountnumeric (double)Valor apresentadoBOW_VLRAPR*required
items.refundedAmountrefunded_amountnumeric (double)Valor reembolsadoBOW_VLRREE
items.paymentDatepayment_datestring (date)Data de pagamento do reembolsoBOW_PGMTO
items.beneficiaryNamebeneficiary_namestring

Nome do beneficiário solicitante

BOW_NOMUSR*required
items.observationstringObservação do Protocolo

items.linksarray

links relacionados ao recurso refunds (Padrão HATEOAS):

  • rel: expenses (Despesas do protocolo)
  • rel: attachments (Anexos do protocolo)

*required
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "items": [
        {
            "status": "2",
            "protocol": "41750520230607000001",
            "requestDaterequest_date": "2023-06-07",
            "presentedAmountpresented_amount": 250,
            "refundedAmountrefunded_amount": 0,
            "paymentDatepayment_date": "",
            "beneficiaryNamebeneficiary_name": "HERNANDES ALVES DA SILVA",
            "observation": "",
            "links": [
                {
                    "rel": "expenses",
                    "href": "/totvsHealthPlans/attendance/v1/refunds/41750520230607000001/expenses"
                },
                {
                    "rel": "attachments",
                    "href": "/totvsHealthPlans/attendance/v1/refunds/41750520230607000001/attachments"
                }
            ]
        },
        {
            "status": "1",
            "protocol": "41750520230607000003",
            "requestDaterequest_date": "2023-06-07",
            "presentedAmountpresented_amount": 250,
            "refundedAmountrefunded_amount": 0,
            "paymentDatepayment_date": "",
            "beneficiaryNamebeneficiary_name": "HERNANDES ALVES DA SILVA",
            "observation": "",
            "links": [
                {
                    "rel": "expenses",
                    "href": "/totvsHealthPlans/attendance/v1/refunds/41750520230607000003/expenses"
                },
                {
                    "rel": "attachments",
                    "href": "/totvsHealthPlans/attendance/v1/refunds/41750520230607000003/attachments"
                }
            ]
        }
    ],
    "hasNext": false,
    "remainingRecords": 0
}
Aviso
Expandir
title(406) - Parâmetros obrigatórios
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.*required
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E001",
    "message": "as chaves do query param estão inválidos",
    "detailedMessage": "Verifique a lista de erros no campo details para mais detalhes.",
    "details": [
        {
            "code": "E001A-406",
            "message": "Campo requestDateInitial não informado",
            "detailedMessage": "Não foi informado o campo request-date-initial."
        },
        {
            "code": "E001A-406",
            "message": "Campo requestDateFinal não informado",
            "detailedMessage": "Não foi informado o campo request-date-final."
        },
        {
            "code": "E001A-406",
            "message": "Campo subscriberId não informado",
            "detailedMessage": "Não foi informado o campo subscriber-id."
        }
    ]
}
Aviso
Expandir
title(404) - Beneficiário não encontrado
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E002",
    "message": "Beneficiário não encontrado",
    "detailedMessage": "Não foi encontrado nenhum beneficiário com a matricula 00011008000027013 no cadastro (BA1)"
}

...

Painel
titleColorOrange
borderStylesolid
titleExpenses - Retorna as despesas do protocolo de reembolso

Retorna as despesas do protocolo de reembolso

/totvsHealthPlans/attendance/v1/refunds/{protocol}/expenses

GET

Nota
Expandir
titleParameters
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
protocol (path)stringNumero do protocolo de reembolso (BOW_PROTOC)*required
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
Dica
Expandir
titleRequest

Body


Não possui body!

Dica
Expandir
title(200) - Operação realizada com sucesso
hasNextbooleanIndica se ainda existem registros a serem retornados
*required
remainingRecordsnumeric (integer)Quantidade de registros ainda existem para retorno
*required
itemsarrayLista de despesas do protocolo de reembolso

items.statusstring

Status da despesa, sendo: 

  • 0 - Negado
  • 1 - Autorizado
B1N_IMGSTA*required
items.subscriberIdsubscriber_idstringMatricula do beneficiário da despesaB1N_MATRIC*required
items.beneficiaryNamebeneficiary_namestringNome do beneficiárioBA1_NOMUSR*required
items.protocolstringNumero do protocolo B1N_PROTOC*required
items.sequentialstringSequencial da despesa no protocoloB1N_SEQUEN*required
items.procedureClassprocedure_classstring

Código do tipo de despesa utilizado

B1N_TIPSER*required
items.tableCodetable_codestringCódigo da tabela da despesaB1N_CODPAD*required
items.procedureCodeprocedure_codestringCódigo da despesaB1N_CODPRO*required
items.procedureDescriptionprocedure_descriptionstringDescrição da despesaBR8_DESCRI*required
items.continuousUsecontinuous_usestring

Medicamento de uso continuo:

  • 0 - Não
  • 1 - Sim
B1N_USOCON*required
items.quantitynumeric (integer)Quantidade de despesaB1N_QTDPRO*required
items.expenseAmountexpense_amountnumeric (double)Valor apresentado da despesaB1N_VLRAPR*required
items.totalExpenseAmounttotal_expense_amountnumeric (double)Valor total da despesaB1N_VLRTOT*required
items.refundedAmountrefunded_amountnumeric (double)Valor reembolsadoB1N_VLRREE*required
items.unreferencedNetworkIdentifierunreferenced_network_identifierstringCPF/CNPJ do prestador de serviçoB1N_PRCNPJ*required
items.unreferencedNetworkNameunreferenced_network_namestringNome do prestador de serviçoB1N_PRNOME*required
items.stateAbbreviationstate_abbreviationstringEstado do prestadorB1N_EST*required
items.cityCodecity_codestring

Código do Município do prestador

B1N_CODMUN*required
items.documentCodedocument_codestring

Código do tipo de comprovante

B1N_TIPDOC (BBS_COD)*required
items.documentDescriptiondocument_descriptionstring

Descrição do tipo de comprovante

B1N_TIPDOC *required
items.documentNumberdocument_numberstringNumero do documentoB1N_NUMDOC
items.documentDatedocument_datestring (date)Data de emissão do documentoB1N_DATDOC*required
items.executionDateexecution_datestring (date)Data de execução da despesaB1N_DATPRO*required
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "items": [
        {
            "status": "1",
            "subscriberIdsubscriber_id": "00011008000027010",
            "beneficiaryNamebeneficiary_name": "HERNANDES ALVES DA SILVA",
            "protocol": "41750520230605000040",
            "sequential": "001",
            "procedureClassprocedure_class": "000001",
            "tableCodetable_code": "01",
            "procedureCodeprocedure_code": "10101012",
            "procedureDescriptionprocedure_description": "CONSULTA EM CONSULTORIO",
            "continuousUsecontinuous_use": "0",
            "quantity": 1,
            "expenseAmountexpense_amount": 1000,
            "totalExpenseAmounttotal_expense_amount": 1000,
            "refundedAmountrefunded_amount": 0,
            "unreferencedNetworkIdentifierunreferenced_network_identifier": "77077733000159",
            "unreferencedNetworkNameunreferenced_network_name": "JOSE",
            "stateAbbreviationstate_abbreviation": "SP",
            "cityCodecity_code": "3500105",
            "documentCodedocument_code": "03",
            "documentDescriptiondocument_description": "RECIBO",
            "documentNumberdocument_number": "2222223",
            "documentDatedocument_date": "2023-06-02",
            "executionDateexecution_date": "2023-06-02"
        }
    ],
    "hasNext": false,
    "remainingRecords": 0
}
Aviso
Expandir
title(406) - Parâmetros obrigatórios
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.*required
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E001",
    "message": "as chaves do query param estão inválidos",
    "detailedMessage": "Verifique a lista de erros no campo details para mais detalhes.",
    "details": [
        {
            "code": "E001A-406",
            "message": "Campo requestDateInitial não informado",
            "detailedMessage": "Não foi informado o campo requestDateInitialrequestDateInitial."
        },
        {
            "code": "E001A-406",
            "message": "Campo requestDateFinal não informado",
            "detailedMessage": "Não foi informado o campo requestDateFinal."
        },
        {
            "code": "E001A-406",
            "message": "Campo subscriberId não informado",
            "detailedMessage": "Não foi informado o campo subscriberId."
        }
    ]
}
Aviso
Expandir
title(404) - Beneficiário não encontrado
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E002",
    "message": "Beneficiário não encontrado",
    "detailedMessage": "Não foi encontrado nenhum beneficiário com a matricula 00011008000027013 no cadastro (BA1)"
}

...

Painel
titleColorOrange
borderStylesolid
titleAttachments - Inclusão de novos anexos ao protocolo de reembolso

Realiza a inclusão de anexos ao protocolo de reembolso com o status de solicitação não concluída.

/totvsHealthPlans/attendance/v1/refunds/attachments

POST

Nota
Expandir
titleParameters
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
Dica
Expandir
titleRequest
protocolstring

Numero do protocolo de reembolso

BOW_PROTOC*required
attachmentsarrayLista de anexos a serem adicionados ao protocolo
*required
attachments.hrefstring

URL do arquivo para download


*required (quando fileName e base64 não for informado)
attachments.fileNamestring

Nome do arquivo com a extensão, exemplo: comprovante.jpg


*required (quando o href não for informado)
attachments.base64string

Base 64 do arquivo


*required (quando o href não for informado)
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "protocol" : "41750520230607000012",
    "attachments" : [
        {
            "href" : "https://www.totvs.com/wp-content/uploads/2021/04/totvs-shared.png"
        },
        {
            "hreffileName" : "https://www.totvs.com/wp-content/uploads/2022/03/sistema-de-gestao-erp-protheus-01-financeiro.jpg"comprovante.jpg",
			"base64" : "iVBORw0KGgoAAAANSUhEUgAACT4AAATACAYAAADTW8q7AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv..."
        }
    ]
}
Dica
Expandir
title(201) - Operação realizada com sucesso
hasNextbooleanIndica se ainda existem registros a serem retornados
*required
remainingRecordsnumeric (integer)Quantidade de registros ainda existem para retorno
*required
itemsarrayLista de anexos do protocolo

items.codestring

Código do anexo no sistema

ACB_CODOBJ*required
items.filestringNome do arquivo com extensãoACB_OBJETO*required
items.descriptionstringNome do arquivoACB_DESCRI*required
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "items": [
        {
            "code": "0000000410",
            "file": "TOTVS-SHARED_2023_06_07_15_09_46.PNG",
            "description": "totvs-shared_2023_06_07_15_09_46"
        },
        {
            "code": "0000000447",
            "file": "TOTVS-SHARED_2023_06_12_15_31_25.PNG",
            "description": "totvs-shared_2023_06_12_15_31_25"
        },
        {
            "code": "0000000448",
            "file": "SISTEMA-DE-GESTAO-ERP-PROTHEUS-01-FINANCEIRO_2023_06_12_15_31_25.JPG",
            "description": "sistema-de-gestao-erp-protheus-01-financeiro_2023_06_12_15_3"
        }
    ],
    "hasNext": false,
    "remainingRecords": 0
}
Aviso
Expandir
title(406) - Json do body invalido
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E001",
    "message": "JSON inválido",
    "detailedMessage": "Json Error: >>{\r\n            \"href\" : \"https://www.totvs.com/wp-content/uploads/2022/03/sistema-de-gestao-erp-protheus-01-financeiro.jpg\"\r\n        }\r\n    ]\r\n}<<"
}
Aviso
Expandir
title(406) - Campos do body inválidos
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E002",
    "message": "Os campos do json no body estão inválidos",
    "detailedMessage": "Verifique a lista de erros no campo details para mais detalhes.",
    "details": [
        {
            "code": "E002E-406",
            "message": "Tamanho inválido para o campo protocol",
            "detailedMessage": "O valor do campo protocol deve ter o tamanho 20."
        },
        {
            "code": "E002B-406",
            "message": "Campo attachments obrigatório",
            "detailedMessage": "Não foi informado valor do campo attachments."
        }
    ]
}
Aviso
Expandir
title(404) - Protocolo não encontrado
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E003",
    "message": "Protocolo de reembolso não encontrado",
    "detailedMessage": "Não foi encontrado nenhum protocolo de reembolso com o numero 41750520230607000099 (BOW_PROTOC)"
}
Aviso
Expandir
title(400) - Status do protocolo não permitido
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E007",
    "message": "Permitido anexar documentos no protocolo somente no status de solicitação não concluida e aguardando informação do beneficiário",
    "detailedMessage": "Permitido somente anexar documentos no protocolo com o status (BOW_STATUS) igual a A (Solicitação não concluida) ou B (Aguardando informação do beneficiário)"
}
Aviso
Expandir
title(400) - Dados do protocolo inválidos
codestringCódigo identificador do erro.*required
messagestringLiteral no idioma da requisição descrevendo o erro para o usuário.*required
detailedMessagestringMensagem técnica e mais detalhada do erro.*required
detailsarrayLista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.
Bloco de código
languagec#
themeEmacs
titleExemplo
linenumberstrue
{
    "code": "E006",
    "message": "Dados inválidos para realizar a inclusão dos anexos",
    "detailedMessage": "Verifique os detalhes dos erros no campo details",
    "details": [
        {
            "code": "E005-400",
            "message": "Erro ao realizar download do arquivo.",
            "detailedMessage": "Status code: 404; Erro: Not Found\r\n; Url: https://www.totvs.com/wp-content/uploads/2021/09/totvs-shared.png"
        }
    ]
}

...