- Criado por Camila Aparecida Ferreira Reis Estanislau, última alteração por Kethellen Tayna Rodrigues Lopes em 04 jun, 2024
Sumário
Objetivo
Esse documento tem o objetivo de exemplificar o uso da API de Conta/Caixa utilizando todos os métodos implementados.
Importante
Recurso disponível a partir da release 12.1.2402.
1 - Métodos
Serão apresentados 5 métodos, os quais foram implementados na API de Conta/Caixa, são eles:
- GET
- POST
- PATCH
- PUT
- DELETE
1.1 - GET
1.1.1 - Get All (Recuperar todas as contas/caixa)
GetAll
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts
Exemplo de Configuração
Exemplo de Resultado
{ "hasNext": false, "items": [ { "id": "0|0006", "company": 0, "code": "0006", "description": "UNIBANCO", "instantBalance": 31523.7459, "databaseBalance": 0.0000, "cashAccountDatabase": "2000-05-03T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "002", "agencyNumber": "1456", "accountNumber": "12345", "unpaidBalance": 317863.8200, "currencyCode": "R$", "active": 1, "cashBookCode": "666", "allowOpenning": 0 }, { "id": "0|0014", "company": 0, "code": "0014", "description": "CCX MUTUO", "instantBalance": 1000.0000, "databaseBalance": 0.0000, "cashAccountDatabase": "2011-01-01T00:00:00-03:00", "proprietaryCompany": 6, "bankNumber": "001", "agencyNumber": "3489", "accountNumber": "123456", "unpaidBalance": 0.0000, "currencyCode": "R$", "active": 1, "allowOpenning": 0 }, { "id": "0|00341", "company": 0, "code": "00341", "description": "BANCO ITAU - Global", "instantBalance": 153196.1370, "databaseBalance": 20342.7300, "cashAccountDatabase": "1999-12-15T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "1", "agencyNumber": "3150", "accountNumber": "23781", "unpaidBalance": -482.1900, "currencyCode": "R$", "active": 1, "allowOpenning": 0 }, { "id": "0|200", "company": 0, "code": "200", "description": "EDVAC - Bradesco", "instantBalance": 0.0000, "databaseBalance": 0.0000, "cashAccountDatabase": "2014-06-13T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "237", "agencyNumber": "3397", "accountNumber": "288515", "unpaidBalance": 0.0000, "currencyCode": "R$", "active": 1, "allowOpenning": 0 }, { "id": "0|203", "company": 0, "code": "203", "description": "EDVAC - Itau", "instantBalance": 0.0000, "databaseBalance": 0.0000, "cashAccountDatabase": "2014-06-13T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "341", "agencyNumber": "3150", "accountNumber": "23781", "unpaidBalance": 0.0000, "currencyCode": "R$", "active": 1, "allowOpenning": 0 } ] }
1.1.2 - Order (Retorna os dados ordenados)
Parâmetros
Order: parâmetro responsável pela ordenação do resultado, podendo ser ascendente ou descendente. O resultado com a ordem descendente deve ser precedida do caractere "-" (menos).
Exemplo 1: ?order=campo1 (Ascendente)
Exemplo 2: ?order=-campo1 (Descendente)
Múltiplos campos de ordenação: ?order=[-]campo1, [-]campo2, [-]campo3 ...
Order (Asc)
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts?order={campo}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Campo: description
Tipo de Ordenação: Ascendente
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts?order=description
Exemplo de Resultado
{ "hasNext": false, "items": [ { "id": "14|00002", "company": 14, "code": "00002", "description": "00002", "instantBalance": 0.0000, "databaseBalance": 0.0000, "cashAccountDatabase": "2020-02-19T00:00:00-03:00", "proprietaryCompany": 14, "unpaidBalance": -57378.9400, "currencyCode": "R$", "active": 1, "cashBookCode": "888", "allowOpenning": 0 }, { "id": "1|0005", "company": 1, "code": "0005", "description": "APLICACAO BANCO REAL", "instantBalance": 16620.0000, "databaseBalance": 120.0000, "cashAccountDatabase": "1999-12-15T00:00:00-03:00", "proprietaryCompany": 6, "bankNumber": "275", "agencyNumber": "002233", "accountNumber": "22200", "unpaidBalance": 0.0000, "currencyCode": "R$", "active": 1, "lastCashNumber": "1", "allowOpenning": 1 }, { "id": "1|0066", "company": 1, "code": "0066", "description": "BANCO BEMGE", "instantBalance": 200000.0000, "databaseBalance": 200000.0000, "cashAccountDatabase": "2015-01-09T00:00:00-03:00", "proprietaryCompany": 1, "unpaidBalance": 0.0000, "currencyCode": "R$", "active": 1, "branchCode": 1, "allowOpenning": 0 }, { "id": "1|0009", "company": 1, "code": "0009", "description": "BANCO BRADESCO", "instantBalance": 65155.2500, "databaseBalance": 100000.0000, "cashAccountDatabase": "2004-11-03T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "237", "agencyNumber": "0065", "accountNumber": "0019284", "unpaidBalance": 0.0000, "currencyCode": "R$", "active": 1, "allowOpenning": 0 }, { "id": "1|0008", "company": 1, "code": "0008", "description": "BANCO DO BRASIL", "instantBalance": 203690.1300, "databaseBalance": 0.0000, "cashAccountDatabase": "2004-09-14T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "001", "agencyNumber": "3489", "accountNumber": "14714", "unpaidBalance": 15500.0000, "currencyCode": "R$", "active": 1, "allowOpenning": 0 } ] }
Order (Desc)
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts?order=[-]{campo}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Campo: description
Tipo de Ordenação: Descendente
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts?order=-description
Exemplo de Resultado
{ "hasNext": false, "items": [ { "id": "0|0006", "company": 0, "code": "0006", "description": "UNIBANCO", "instantBalance": 31523.7459, "databaseBalance": 0.0000, "cashAccountDatabase": "2000-05-03T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "002", "agencyNumber": "1456", "accountNumber": "12345", "unpaidBalance": 317863.8200, "currencyCode": "R$", "active": 1, "cashBookCode": "666", "allowOpenning": 0 }, { "id": "1|0012", "company": 1, "code": "0012", "description": "SANTANDER BANESPA - PENHOR RÁPIDA", "instantBalance": 50000.0000, "databaseBalance": 0.0000, "cashAccountDatabase": "2009-06-02T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "033", "agencyNumber": "2587", "accountNumber": "147258", "unpaidBalance": 50000.0000, "currencyCode": "R$", "active": 1, "allowOpenning": 0 }, { "id": "1|033-1", "company": 1, "code": "033-1", "description": "Santander ( Conta Corrente )", "instantBalance": 11391.7700, "databaseBalance": 0.0000, "cashAccountDatabase": "2015-01-14T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "033", "agencyNumber": "0202", "accountNumber": "13001325", "unpaidBalance": 0.0000, "currencyCode": "R$", "active": 1, "allowOpenning": 0 }, { "id": "1|033_JARAG", "company": 1, "code": "033_JARAG", "description": "JARAGUAENSE", "instantBalance": 1093.5550, "databaseBalance": 0.0000, "cashAccountDatabase": "2014-07-14T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "033", "agencyNumber": "3963", "accountNumber": "013000352", "unpaidBalance": 0.0000, "currencyCode": "R$", "active": 1, "branchCode": 1, "allowOpenning": 0 }, { "id": "1|0102", "company": 1, "code": "0102", "description": "ITAU UNIVAP", "instantBalance": -5421.3400, "databaseBalance": 0.0000, "cashAccountDatabase": "2014-04-30T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "341", "agencyNumber": "0250", "accountNumber": "647088", "unpaidBalance": -23408.0000, "currencyCode": "R$", "active": 1, "branchCode": 2, "lastCashNumber": "4", "allowOpenning": 1 } ] }
1.1.3 - Filter (Resultado filtrado)
Filter
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts?{campo}={valor}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Campo: bankNumber
Valor: 005
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts?bankNumber=005
Exemplo de Resultado
{ "hasNext": false, "items": [ { "id": "1|0003", "company": 1, "code": "0003", "description": "CITIBANK", "instantBalance": 17062.1099, "databaseBalance": 182.9900, "cashAccountDatabase": "1999-12-15T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "005", "agencyNumber": "01", "accountNumber": "teste", "unpaidBalance": 4956.3900, "currencyCode": "R$", "active": 1, "allowOpenning": 0 } ] }
Filtros Complexos - OData
Para realizar filtros complexos na API de Conta/Caixa é possível adotar o padrão OData. Para entender melhor sobre a utilização desse padrão, acesse o link da documentação Utilizando filtros complexos - Exemplos do guia de API - ODATA.
1.1.4 - Paginação
Parâmetros
Page: Página que será apresentada.
PageSize: Quantidade máxima de registros por página que serão apresentados.
Exemplo: ?page=1&pageSize=1
Valores padrão: Caso não sejam preenchidos os parâmetros evidenciados acima serão preenchidos com valores padrão.
Page: 1
PageSize: 20
Paginação
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts?page={valor1}&pageSize={valor2}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Valor1: 1
Valor2: 2
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts?page=1&pageSize=2
Exemplo de Resultado
{ "hasNext": true, "items": [ { "id": "0|0006", "company": 0, "code": "0006", "description": "UNIBANCO", "instantBalance": 31523.7459, "databaseBalance": 0.0000, "cashAccountDatabase": "2000-05-03T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "002", "agencyNumber": "1456", "accountNumber": "12345", "unpaidBalance": 317863.8200, "currencyCode": "R$", "active": 1, "cashBookCode": "666", "allowOpenning": 0 }, { "id": "0|00341", "company": 0, "code": "00341", "description": "BANCO ITAU - Global", "instantBalance": 153196.1370, "databaseBalance": 20342.7300, "cashAccountDatabase": "1999-12-15T00:00:00-03:00", "proprietaryCompany": 1, "bankNumber": "1", "agencyNumber": "3150", "accountNumber": "23781", "unpaidBalance": -482.1900, "currencyCode": "R$", "active": 1, "allowOpenning": 0 } ] }
1.1.5 - Fields (Retorno de campos específicos no resultado)
Parâmetros
Fields: parâmetro responsável pela especialização de campos em um resultado, ou seja, o usuário define quais campos serão apresentados no resultado.
Exemplo: ?fields=campo1
Múltiplos campos de ordenação: ?fields=campo1, campo2, campo3 ...
Fields
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts?fields={campos}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Campo 1: company
Campo 2: description
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts?fields=company,code,description
Exemplo de Resultado
{ "hasNext": false, "items": [ { "id": "0|0006", "company": 0, "code": "0006", "description": "UNIBANCO" }, { "id": "0|00341", "company": 0, "code": "00341", "description": "BANCO ITAU - Global" } ] }
1.1.6 - GetOne (Recuperar conta/caixa pelo identificador)
Parâmetros
Nos parâmetros do GetOne é necessário passar uma chave composta ("id"), por isso informamos "company" que é o código da coligada da Conta/Caixa que queremos selecionar e o "code" que é o código da Conta/Caixa, sendo eles separados pelo caractere "|" pipe.
GetOne
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts/{company}|{code}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Company: 1
Code: 0001
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts/1|0001
Exemplo de Resultado
{ "id": "1|0001", "company": 1, "code": "0001", "description": "CAIXA GERAL", "instantBalance": 5398756.7985, "databaseBalance": -4943.3500, "cashAccountDatabase": "1999-12-15T00:00:00-03:00", "lastNumberCheckBank": "0000000065", "proprietaryCompany": 1, "bankNumber": "275", "agencyNumber": "002233", "accountNumber": "22200", "unpaidBalance": 520041.5802, "currencyCode": "R$", "bankAccountCompany": 1, "userLowerLimit": 0, "lowerLimit": 0.0000, "allowOpenning": 1, "lastCashNumber": "151", "active": 1, "cpmfAutomatic": 2, "branchCode": 1, "cashBookCode": "951" }
1.2 - POST
1.2.1 - Post (Inserir uma Conta/Caixa)
Post
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts
Exemplo de Configuração
Exemplo de Entrada
{ "company":"1", "code":"TesteAPI", "description":"Teste inclusão conta caixa", "instantBalance": 0.0, "databaseBalance": 0.0, "cashAccountDatabase":"2023-10-31", "lastNumberCheckBank":null, "proprietaryCompany":"1", "bankNumber":null, "agencyNumber": null, "accountNumber": null, "unpaidBalance":0.0, "financialApplication":null, "currencyCode":"R$", "instantBalanceCurrencyBR":0, "unpaidBalanceCurrencyBR":0, "bankAccountCompany":"1", "userLowerLimit": 0, "lowerLimit": null, "allowOpenning": 1, "lastCashNumber": null, "active":"1", "cpmfAutomatic": null, "initialInclusionDateExtract": null, "inclusionEndDateExtract": null, "branchCode": 1, "batchCode": 0, "refundBatchCode": 0, "cashBookCode": null, "cutoffDateBalance": 0 }
Exemplo de Resultado Positivo
{ "id": "1|TesteAPI", "company": 1, "code": "TesteAPI", "description": "Teste inclusão conta caixa", "instantBalance": 0.0, "databaseBalance": 0.0, "cashAccountDatabase": "2023-10-31T00:00:00-03:00", "lastNumberCheckBank": "0", "proprietaryCompany": 1, "unpaidBalance": 0.0, "currencyCode": "R$", "instantBalanceCurrencyBR": 0.0, "unpaidBalanceCurrencyBR": 0.0, "bankAccountCompany": 1, "userLowerLimit": 0, "lowerLimit": 0.0, "allowOpenning": 1, "active": 1, "cpmfAutomatic": 0, "branchCode": 1, "batchCode": 0, "refundBatchCode": 0, "cutoffDateBalance": 0.0 }
Exemplo de Resultado Negativo
{ "Code": "FE006", "Message": "Chave duplicada\r\n\r\nPossíveis causas:\r\n - inclusão de registro cujo valor da chave primária já existe\r\n - inclusão de registro cujo valor do índice único já existe", "DetailMessage": "Violation of PRIMARY KEY constraint 'PKFCXA'. Cannot insert duplicate key in object 'dbo.FCXA'. The duplicate key value is (1, TesteAPI).\r\nThe statement has been terminated.\r\n\r\nINSERT INTO [FCXA] ([CODCOLIGADA], [CODCXA], [DESCRICAO], [SALDOINSTANTANEO], [SALDODATABASE], [DATABASECXA], [ULTIMOCHEQUE], [CODCOLPROP], [NUMBANCO], [NUMAGENCIA], [NROCONTA], [SALDONAOCOMPENSADO], [CODAPLFIN], [CODMOEDA], [SALDOINSTANTANEOREAIS], [SALDONAOCOMPENSADOREAIS], [CODCOLCONTA], [USARLIMITEINFERIOR], [LIMITEINFERIOR], [PERMITIRABERTURA], [ULTIMONUMEROCAIXA], [ATIVA], [CPMFAUTOMATICO], [DATAINIINCEXTRATO], [DATAFIMINCEXTRATO], [CODFILIAL], [RECCREATEDBY], [RECCREATEDON], [RECMODIFIEDBY], [RECMODIFIEDON], [CODLOTE], [CODLOTEESTORNO], [CODLIVROCAIXA], [SALDODATACORTE]) VALUES (1, 'TesteAPI', 'Teste inclusão conta caixa', 0, 0, '31/10/2023 00:00:00', '0', 1, null, null, null, 0, null, 'R$', 0, 0, 1, 0, 0, 1, null, 1, 0, null, null, 1, 'mestre', '08/11/2023 14:21:37', 'mestre', '08/11/2023 14:21:37', 0, 0, null, 0)", "HelpUrl": "", "Details": null }
1.3 - PATCH
1.3.1 - Patch (Atualização parcial de uma Conta/Caixa)
Patch
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts/{company}|{code}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Company: 1
Code: TesteApi
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts/1|TesteAPI
Exemplo de Entrada
{ "description":"Teste edição conta caixa", "lastNumberCheckBank":"124758", "userLowerLimit": 1, "lowerLimit": 15000, "allowOpenning": 1, "lastCashNumber": "00005", "active":"1" }
Exemplo de Resultado Positivo
{ "id": "1|TesteAPI", "company": 1, "code": "TesteAPI", "description": "Teste edição conta caixa", "instantBalance": 0.0000, "databaseBalance": 0.0000, "cashAccountDatabase": "2023-10-31T00:00:00-03:00", "lastNumberCheckBank": "124758", "proprietaryCompany": 1, "unpaidBalance": 0.0000, "currencyCode": "R$", "bankAccountCompany": 1, "userLowerLimit": 1, "lowerLimit": 15000.0, "allowOpenning": 1, "lastCashNumber": "00005", "active": 1, "cpmfAutomatic": 0, "branchCode": 1, "batchCode": 0, "refundBatchCode": 0, "cutoffDateBalance": 0.0000 }
Exemplo de Resultado Negativo
{ "Code": "FE016", "Message": "O Corpo da mensagem contêm valores inválidos.", "DetailMessage": "", "HelpUrl": "http://tdn.totvs.com/x/e0F0GQ", "Details": null }
1.4 - PUT
1.4.1 - Put (Atualização completa de uma Conta/Caixa)
Put
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts/{company}|{code}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Company: 1
Code: TesteApi
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts/1|TesteAPI
Exemplo de Entrada
{ "description":"Teste edição conta caixa", "instantBalance": 0.0, "databaseBalance": 0.0, "cashAccountDatabase":"2023-10-31", "lastNumberCheckBank":null, "proprietaryCompany":"1", "bankNumber":null, "agencyNumber": null, "accountNumber": null, "unpaidBalance":0.0, "financialApplication":null, "currencyCode":"R$", "instantBalanceCurrencyBR":0, "unpaidBalanceCurrencyBR":0, "bankAccountCompany":"1", "userLowerLimit": 0, "lowerLimit": null, "allowOpenning": 1, "lastCashNumber": null, "active":"1", "cpmfAutomatic": null, "initialInclusionDateExtract": null, "inclusionEndDateExtract": null, "branchCode": 1, "batchCode": 0, "refundBatchCode": 0, "cashBookCode": null, "cutoffDateBalance": 0 }
Exemplo de Resultado Positivo
{ "id": "1|TesteAPI", "company": 1, "code": "TesteAPI", "description": "Teste edição conta caixa", "instantBalance": 0.0, "databaseBalance": 0.0, "cashAccountDatabase": "2023-10-31T00:00:00-03:00", "lastNumberCheckBank": "0", "proprietaryCompany": 1, "unpaidBalance": 0.0, "currencyCode": "R$", "instantBalanceCurrencyBR": 0.0, "unpaidBalanceCurrencyBR": 0.0, "bankAccountCompany": 1, "userLowerLimit": 0, "lowerLimit": 0.0, "allowOpenning": 1, "active": 1, "cpmfAutomatic": 0, "branchCode": 1, "batchCode": 0, "refundBatchCode": 0, "cutoffDateBalance": 0.0 }
Exemplo de Resultado Negativo
{ "Code": "FE016", "Message": "O Corpo da mensagem contêm valores inválidos.", "DetailMessage": "", "HelpUrl": "http://tdn.totvs.com/x/e0F0GQ", "Details": null }
1.5 - DELETE
1.5.1 - Delete (Exclui uma Conta/Caixa)
Delete
Máscara de Url: http://{domínio}:{porta}/api/financial/v1/cashaccounts/{company}|{code}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Company: 1
Code: TesteAPI
Url Utilizada: http://localhost:8051/api/financial/v1/cashaccounts/1|TesteAPI
Exemplo de Resultado Positivo Postman
Obs.: Em caso de sucesso, será retornado o respondeCode = 204 e a resposta em branco.
Exemplo de Resultado Negativo
{ "Code": "FE011", "Message": "Registro não encontrado na base de dados.", "DetailMessage": "", "HelpUrl": "", "Details": null }
- Sem rótulos