Entendendo&o&Protocolo&...&2! Obtendo(os(registros(...(2! Criando(registros(...(3! Atualizando(registros(...(3! Removendo(registros(...(4!

(1)

ContaAzul API

Este documento foi escrito com o intuito de ajudar os desenvolvedores de aplicações a se comunicarem com o ContaAzul. Ele possui o detalhamento mínimo necessário para que sejam realizadas as primeiras integrações com a plataforma do ContaAzul.

Table&of&Contents&

Entendendo&o&Protocolo

&...&2!

Obtendo(os(registros(...(2

!

Criando(registros(...(3

!

Atualizando(registros(...(3

!

Removendo(registros(...(4

!

Entendendo&o&modelo&de&autenticação&da&API

&...&4!

Como&conseguir&uma&chave&para&o&meu&aplicativo?

&...&5!

Como&integrar&os&meus&clientes&com&o&ContaAzul&?

&...&7!

Sobre&as&entidades

&...&10!

Entendendo&o&conceito&de&negociações&do&ContaAzul

&...&10!

Overview(das(entidades(que(envolvem(negociações(...(12

!

Negociação(de(Venda(de(Serviço(...(12

!

Regras&de&Negócio&Expostas

&...&13!

Clientes(...(13

!

Vendedor(...(15

!

Transportadora(...(17

!

Cidades(...(18

!

Bancos(...(19

!

Contas(Bancárias(Cadastradas(...(20

!

Tipo(de(Serviço(Prestado(...(21

!

Serviço(...(22

!

Categoria(de(Produtos(...(23

!

Produtos(...(24

!

Centro(de(Custo(...(26

!

Lista(de(preço(...(27

!

Categoria(Financeira(...(29

!

Lançamentos(Financeiros(...(31

!

Tipo(de(Negociação(((Natureza(da(Operação()(...(33

!

Venda(de(Produto(...(34

!

Compra(de(Produto(...(38

!

Venda(de(Serviço(...(41

!

Vendas(por(período/vendedor/produto(...(45

!

Ranking(de(produtos(...(47

!

(2)

(

Entendendo o Protocolo

O protocolo da API do ContaAzul foi escrito no modelo REST, onde todas as requisições são feitas via HTTP puro. Os dados trafegados são estruturados no padrão JSON.

Para cada regra de negócio exposta pelo ContaAzul ( clientes, produtos, vendas, etc.) existe uma URL que a representa. Em nossos exemplos usamos o termo URL raíz para estas URL's. Por exemplo, se fossemos buscar dados de um Cliente teríamos que consumir o URL http://api.contaazul.com.br/pub/contact/customer.

A partir da URL raíz o sistema espera que as requisições sejam executadas com determinados métodos HTTP para cada operação de negócio disponível ( criação, edição, remoção e pesquisa ). Discutiremos sobre cada um, separadamente, na sequencia.

Obtendo os registros

Para se obter os dados de uma regra de negócio deve-se utilizar o método HTTP GET. Sempre que for chamado método GET na URL raíz (http://.../customer/) de qualquer regra de négocio será devolvida uma lista com todos os registros encontrado.

Por outro lado, sempre que chamarmos o método GET na URL raíz, acrescentando o identificador do cliente no final (http://.../customer/123) estaremos buscando os dados específicos deste cliente.

É possível também filtrar quais campos desejamos trazer para regra de négocio. Basta acrescentar ao fim da URL desejada o caracter ":" ( dois pontos ) e listar, na sequencia, os atributos desejadas, separados por virgula como, por exemplo, em http://.../customer/123/:id,name.

Algumas regras de negócio, ainda, permitem efetuar pesquisa em suas entidades atrávez dos filtros HTTP ( ou Query String Parameters ). Na chamada de http://.../customer/?name=Silva, por exemplo, traríamos apenas os clientes que tenham a palavra "Silva" no campo nome. Todas as chamadas ao método GET retornam o Status Code 200, representando sucesso da busca. Ele só retornará outro Status em caso de erro ( pesquisa por campo inexistente, campo pesquisado em formato diferente do esperado, etc...).

(3)

Criando registros

Cada regra de négocio possui uma entidade que a representa. Para se criar um registro basta enviar esta entidade previamente populada através do método HTTP POST.

Se tudo correr bem, a requisição irá retornar um Status Code 204, não trazendo dado algum no corpo da resposta. Porém, dois Headers HTTP são retornados para auxiliar no rastreio do regristro recém criado:

● Identificator: ele contém um número que identifica o registro na regra de negócio;

● Location: o endereço no qual pode-se, diretamente, obter mais informações sobre o registro criado. Normalmente é a URL raíz concatenado ao Identificator, como descrito no tópico "Obtendo Registros".

Deve-se lembrar que cada regra de negócio possui regras específicas de validação, inclusive seus próprios campos obrigatórios. Sempre que algum erro de validação acontecer será retornado o Status Code 412, com um objeto JSON descrevendo o motivo do erro.

Os demais erros que o server identificar na requisição ( entidade inválida, campos inválidos, etc...) serão tratados com o Status 400.

Atualizando registros

A mesma entidade que é enviada para se criar um registro deve ser utilizada para atualizá-lo. Este procedimento deve ser feito chamando a URL que representa o registro (http://.../customer/123) através do método HTTP PUT. Se tudo correr bem, o servidor irá retornar o Status Code 201, sem corpo na resposta.

Sempre que algum erro de validação acontecer será retornado o Status Code 412, com um objeto JSON descrevendo o motivo do erro. Os demais erros que o server identificar na requisição ( entidade inválida, campos inválidos, etc...) serão tratados com o Status 400.

(4)

Removendo registros

Para remover um registro basta chamar a URL que representa o registro (http://.../customer/123) através do método HTTP DELETE. Não deve ser enviado corpo nesta requisição. Se tudo ocorrer bem, o servidor irá retornar o Status Code 201, sem corpo na resposta.

Sempre que algum erro de validação acontecer será retornado o Status Code 412, com um objeto JSON descrevendo o motivo do erro. Os demais erros que o server identificar na requisição ( entidade inválida, campos inválidos, etc...) serão tratados com o Status 400.

Entendendo o modelo de autenticação da API

Como vimos, o protocolo possui uma sintaxe bem simples e objetiva, porém, para se efetuar a comunicação com a plataforma é preciso informar as credenciais corretas em cada requisição, do contrário, um Status Code 403 será retornado informando que as credenciais são inválidas:

{

"message": "Bad Credentials" }

Basicamente, deve-se informar dois Header's HTTP em todas as requisições:

● ExternalApplicationToken: Um identificador que representa a aplicação externa que irá se comunicar com o ContaAzul.

● CompanyToken: Um identificador que representa que o usuário do ContaAzul autorizou o envio de dados da aplicação externa com a sua conta.

Através destas duas informações consguimos garantir a segurança de nossos usuários, tendo a certeza de que somente as aplicações que foram explicitamente autorizadas possam ter acesso aos seus dados.

(5)

Como conseguir uma chave para o meu aplicativo?

Primeiramente você deve estar logado no ContaAzul, em seguida acesse a página de Integrações Via API. Será apresentado uma tela conforme imagem abaixo. Localize e clique no botão Solicitar uma chave para meu aplicativo.

(6)

Preencha o formulário com os dados do seu aplicativo:

● Nome do aplicativo: Descrição do aplicativo de integração

● Email: Pessoa responsável pelo desenvolvimento do aplicativo, será o email que receberá a chave.

● URL do Aplicativo: Link da página com informações sobre o aplicativo

● Restringir o acesso do servidor ao IP (opcional): Define um IP público que pode acessar o contaazul via API, ou seja, somente computadores que estão inseridos nessa rede poderão acessar o contaazul.

(7)

Ao clicar em enviar solicitação, será enviado um email conforme imagem abaixo. É muito importante nunca passar essa chave para outras pessoas, essa chave é a maneira no qual o ContaAzul identifica os aplicativos na integração via API.

Como integrar os meus clientes com o ContaAzul ?

Cada empresa deverá possuir uma chave de autorização para o seu aplicativo. Será de sua responsabilidade gravar uma cópia segura dessas chaves.

Para criar uma chave você deverá seguir os seguintes passos:

● Verificar em sua base de dados se um cliente já possui chave de integração com o seu aplicativo, caso não seguir no próximo passo, se sim pode fazer as consultas via REST. ● A criação de chave para o cliente deve ser feita em duas etapas. Primeiro você deve solicitar uma public token. Através da URL abaixo passando a chave do seu aplicativo que foi recebida por email:

○ http://api.contaazul.com.br/pub/oauth/requestkey/{suachave}

● Será devolvida uma chave pública, universal, que nunca se repetirá, muito semelhante a chave da sua aplicação.

● Em seguida você deverá chamar a página de autorização do ContaAzul (um pop-up). O Quadro abaixo é um exemplo com HTML e JavaScript para chamar essa tela de autorização:

(8)

Desejo Integrar com o ContaAzul</a>

Onde:

● 0000013e-7b50-5649-0000-007145a69e35 é a public token

● redirectTo é a URL de retorno para o Aplicativo XYZ. Para essa URL será passado um parâmetro com a CompanyToken caso o usuário autentique. O parâmetro de retorno da

companyKey é authorizationToken. Exemplo:

http://www.aplicativoxyz.com?auhorizationToken=0000013e-7b7b-bbd6-0000-012a9b7962ba

A token 0000013e-7b50-5649-0000-007145a69e35 é única, uma vez chamada ela é descartada, ou seja, caso seja aberto o popup e usuário fechar, deverá ser criada outra public token. Esse procedimento garante a segurança das informações no caso de haver um sniffer na rede, em outras palavras, caso alguém consiga interceptar esse link e tentar se conectar pela segunda vez, não será possível, pois o token já foi descartado.

(9)

Quando aberto o popup, essas são as duas telas possíveis a serem exibidas: A da esquerda é exibida caso o usuário não esteja logado no Contazul ( no mesmo Browser), já a da direita será exibida no caso o usuário já esteja logado.

(10)

Sobre as entidades

É importante notar que as entidades foram desenhadas para possuir um identificador único que a representa universalmente entre as entidades da API. Estes identificadores, representados pelo campo 'id' de cada entidade, são ignorados quando enviados na criação de novos registros (via POST), porém, são indispensáveis quando usados na atualização dos registros (via PUT).

Os campos das entidades que estamos expondo são praticamente uma referencia de 1 para 1 com os campos que possuímos no software Web. Assim, fica mais fácil de entender as regras de negócio.

As entidades do ContaAzul são compostas por campos de tipos comuns em qualquer linguagem de programação. Os tipos aceitos pelo ContaAzul em suas entidades são:

● String: sequencia de caracteres enviadas entre aspas; ● Boolean: true ou false

● Double: em formato americado, utilizando "." (ponto) como delimitador de casas decimais;

● Integer

● Date: no formato 'yyyy-[mm+1]-[dd+1]'

● DateTime: no formato 'yyyy-[mm+1]-[dd+1] hh:MM:ss'

Entendendo o conceito de negociações do ContaAzul

O ContaAzul se preocupa com a saúde financeira das empresas. Diariamente, nossos clientes efetuam muitas compras e vendas, movimentando produtos de seus estoques e gerando lançamentos no financeiro. Analisando estas tarefas rotineiras dos clientes, o ContaAzul notou que as principais operações do dia-a-dia giram em torno de negociações.

As negociações são as operações de venda e compra. A API do ContaAzul foi desenhada para agilizar ainda mais os processos mais valiosos de nossos clientes. Tratamos como negociações, então, os processos de venda de produto, compra de produtos e venda de serviços.

(11)

Nos tópicos finais deste manual são descritas em detalhe as entidades que foram expostas na API. Sendo assim, você poderá compreender do que se trata cada tipo de negociação com detalhes.

(12)

Overview das entidades que envolvem negociações

Todas as negociações serão realizadas no através da entidade Deal (negociação). Nela temos todas as informações necessárias para realizar negociações através da API. Os dados mínimos para se realizar uma negociação são: items e parcelas.

Os itens a serem informados nas negociações podem ser produtos ou serviços. No ContaAzul,

a venda de produto é realizada de forma totalmente separada da venda de serviços. Na

entidade Deal existe um campo chamado items, que espera ser populado com uma lista de objetos do tipo DealItem (itens a serem negociados).

DealItem é uma entidade importante, nela informamos o identificador do item que queremos vender ( seja ele produto ou um serviço ), a quantidade a ser vendida, valor unitário e (opcionalemente) o custo unitário.

Para que as vendas sejam refletivas no financeiro do ContaAzul, é necessário informar como serão realizados os pagamentos das negociações. Na entidade Deal existe um campo chamado payments, que espera ser populado com uma lista de objetos do tipo Payment (pagamentos ou parcelas). Ela representa as parcelas de pagamento das negociações, sendo que toda negociação deve possuir ao menos uma parcela de pagamento.

O campo 'total' da entidade Deal informa o total da nota. Ele é de preenchimento opcional, e é calculado automaticamente após a venda ser criada.

Negociação de Venda de Serviço

Cada tipo de negociação possui algumas peculiaridades. A venda de serviço distingui-se das demais por apresentar a opção de informar os impostos cobrados pela prestação de serviço. Os serviços prestados possuem classificação e taxação adequadas a legislação de cada cidade, e devem ser informadas já na emissão da venda.

O primeiro campo que só existe neste tipo de negociação é taskType (tipo de serviço prestado). Cada cidade possui uma listagem com os tipos de serviços em que incidem tributação. Ele é de preenchimento opcional.

O segundo campo é taxes (impostos). Ele espera uma lista de objetos do tipo DealTax, entidade criada para preencher os dados com a tributação da venda. O preenchimento destes campos podem trazer um ganho muito grande de produtividade, pois o valor de imposto (se for imposto retido) é deduzido do valor da venda e a receita criada no financeiro já desconta o valor dos impostos.

(13)

Regras de Negócio Expostas

Clientes

Clientes que a empresa cadastrou no ContaAzul. O cliente é utilizado obrigatoriamente nas vendas de serviço e produto, propostas comerciais e pedidos de venda.

URL Raíz: http://api.contaazul.com.br/pub/contact/customer/ Métodos disponíveis: GET, GET (id), POST, PUT e DELETE Campos da entidade Customer:

● id: Integer - Identificador único (READ ONLY) ● *name: String - Nome

● email: String - Email

● documentNumber: String - CPF/CNPJ

● inscricaoEstadual: String - Inscrição Estadual ● address: String - Nome da Rua, Avenida, etc...) ● cityId: Integer - identificador único da Cidade ● postalCode: String - CEP

● neighborhood: String - Bairro ● number: Integer - Número

Exemplo de chamada (via linha de comando): curl --request GET

http://api.contaazul.com.br/pub/contact/customer/0000000 --header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100' --header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299' * Lembre de trocar os tokens e o id por valores reais

(14)

Exemplo de retorno: {

"id": 0000000,

"name": "Cliente A",

"address": "Rua Rua de São Miguel", "number": "333",

"complement": "Primeira esquerda", "neighborhood": "Vila dos Remédios", "documentNumber": "83.575.050/0001-24", "postalCode": "53990-000", "inscricaoEstadual": "ISENTO", "email": "email@email.com", "cityId": 5252 }

(15)

Vendedor

Vendedores que a empresa cadastrou no ContaAzul. Cada vendedor pode ser associado com um valor de comissão. Este valor é preenchido como padrão ao criar a venda, porém, pode ser alterado pelo usuário especificamente para cada venda. É possível calcular a comissão total de cada vendedor.

URL Raíz: http://api.contaazul.com.br/pub/contact/vendor/ Métodos disponíveis: GET, GET (id), POST, PUT e DELETE Campos da entidade Vendor:

Exemplo de chamada ( via linha de comando): curl --request GET

http://api.contaazul.com.br/pub/contact/vendor/0000000 --header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100' --header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299' * Lembre de trocar os tokens e o id por valores reais

(16)

"id": 0000000, "name": "Almeida",

"address": "Rua Teofredo Goiania", "number": 333,

"complement": "Ap 300",

"neighborhood": "Cidade dos Funcionários", "documentNumber": "99214820686", "postalCode": "60822-630", "inscricaoEstadual": "00000000", "email": "email@email.com", "cityId": 1150 }

(17)

Transportadora

Transportadoras que a empresa cadastrou no ContaAzul. A transportadora é obrigatório para vendas e compras com frete.

URL Raíz: http://api.contaazul.com.br/pub/contact/shipper/ Métodos disponíveis: GET, GET (id), POST, PUT e DELETE Campos da entidade Shipping:

Exemplo de chamada ( via linha de comando): curl --request GET

http://api.contaazul.com.br/pub/contact/shipper/0000000 --header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100' --header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299' * Lembre de trocar os tokens e o id por valores reais

"id": 0000000,

"name": "Transportadora Best SA", "address": "Rua prudente de moraes", "number": 0001,

"complement": "Ap 90", "neighborhood": "São José",

"documentNumber": "97.083.667/0001-37", "postalCode": "13092-141",

"inscricaoEstadual": "3223939", "email": "email@email.com", "cityId": 8946

(18)

}

Cidades

Lista das principais cidades do Brasil com seus respectivos códigos do IBGE.

URL Raíz: http://api.contaazul.com.br/pub/contact/shipping/ Métodos disponíveis: GET, GET (id)

Campos da entidade City:

● id: Integer - Identificador único (READ ONLY) ● name: String - Nome da Cidade

● state: String - Estado

● ibgeCode: String - Código do IBGE para a cidade

Exemplo de chamada (via linha de comando):

curl request GET http://api.contaazul.com.br/pub/city/00000 --header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100' ----header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299' * Lembre de trocar os tokens e o id por valores reais

Exemplo de Retorno: {

"id": 2049,

"name": "ABADIA DE GOIÁS", "ibgeCode": 5200050,

"state": "GO" }

(19)

Bancos

Lista de bancos pré-cadastrados no ContaAzul. Ao cadastrar uma conta bancária, o usuário escolhe um dos bancos pré-cadastrados e define o nome da conta bancária, o saldo inicial e a data do saldo.

URL Raíz: http://api.contaazul.com.br/pub/bank/ Métodos disponíveis: GET, GET (id)

Campos da entidade Bank:

● code: Integer - Identificador único (READ ONLY) ● description: String - Nome do Banco

curl --request GET http://api.contaazul.com.br/pub/bank/0 --header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100' --header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299' * Lembre de trocar os tokens e o id por valores reais

"code": 0,

"description": "Banco do Brasil" }

(20)

Contas Bancárias Cadastradas

Lista de contas bancárias cadastradas pela empresa no ContaAzul. Ao cadastrar uma conta bancária, o usuário escolhe um dos bancos pré-cadastrados e define o nome da conta bancária, o saldo inicial e a data do saldo. Para baixar (definido como pago ou recebido) um lançamento (receita ou despesa) no financeiro é necessário que o usuário tenha definido uma conta bancária. Cada receita ou despesa baixada atualiza o saldo de uma conta bancária. A conta bancária é utilizada para filtrar receitas e despesas no financeiro.

URL Raíz: http://api.contaazul.com.br/pub/bank/account/ Métodos disponíveis: GET, GET (id), POST, PUT, DELETE

Campos da entidade BankAccount:

● id: Integer - Identificador único (READ ONLY) ● *name: String - Nome da Conta Bancária ● agencyNumber: String - Agencia

● accountNumber: String - Conta Corrente ● wallet: String - Carteira padrão

● *bankId: Integer - Código do banco

● initialBalanceAmount: Double - Saldo inicial

● initialBalanceDate: Date - Data em que foi visto o saldo Exemplo de chamada (via linha de comando):

curl --request GET http://api.localhost:8080/pub/bank/account/0000000 header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100'

--header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299'

* Lembre de trocar os tokens e o id por valores reais Exemplo de Retorno:

{

(21)

"accountNumber": "210862", "wallet": "1", "bankId": 999, "initialBalanceAmount": null, "initialBalanceDate": null }

Tipo de Serviço Prestado

Lista de todos os serviços prestados possíveis no país. Normalmente cada empresa prestadora de serviços possui uma lista de serviços cadastrados na prefeitura que pode prestar.

URL Raíz: http://api.contaazul.com.br/pub/tasktype/ Métodos disponíveis: GET, GET (id)

Campos da entidade TaskType:

● id: Integer - Identificador único (READ ONLY) ● description: String - Descrição do serviço prestado

curl request GET http://api.localhost:8080/pub/tasktype/000000 --header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100' ----header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299' * Lembre de trocar os tokens e o id por valores reais

"id": 0000000,

"description": "9.03 - Guias de turismo" }

(22)

Serviço

Serviços que a empresa cadastrou no ContaAzul. Para realizar vendas de serviços o usuário deve cadastrar o serviço. Este serviço pode ser cadastrado na lista de serviços ou pelo componente de autocomplete do formulário de vendas. Para cadastrar um serviço o usuário precisa somente definir um nome para o serviço, porém os campos opcionais ajudam a gerenciar melhor a empresa.

URL Raíz: http://api.contaazul.com.br/pub/task/

Métodos disponíveis: GET, GET (id), POST, PUT, DELETE

Campos da entidade Task:

● id: Integer - Identificador único (READ ONLY) ● *name: String - Nome do serviço

● costRate: Double - Custo unitário ● rate: Double - Preço de venda

curl request GET http://api.localhost:8080/pub/task/0000000 --header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100' ----header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299' * Lembre de trocar os tokens e o id por valores reais

"id":0000000,

"name": "Serviço 1" }

(23)

Categoria de Produtos

Para facilitar a organização dos produtos dentro do ContaAzul, é possível agrupar os produtos em categorias. Para gerenciar as categorias de produtos, utilize o serviço abaixo.

URL Raíz: http://api.contaazul.com.br/pub/product/category/ Métodos disponíveis: GET, GET (id), POST, PUT, DELETE

Campos da entidade ProductCategory:

● id: Integer - Identificador único (READ ONLY) ● *name: String - Nome da categoria do produto Exemplo de chamada (via linha de comando):

curl --request GET

http://api.contaazul.com.br/pub/product/category/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' --header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2' * Lembre de trocar os tokens e o id por valores reais

"id": 0000000,

"name": "Produto acabado" }

(24)

Produtos

Produtos que a empresa cadastrou no ContaAzul. Para realizar vendas de produtos o usuário deve cadastrar o produto. Este produto pode ser cadastrado na lista de produtos ou pelo componente de autocomplete do formulário de vendas. Para cadastrar um produto o usuário precisa somente definir um nome para o produto, porém os campos opcionais ajudam a gerenciar melhor a empresa. Ao cadastrar um produto o usuário pode definir o estoque atual e esta quantidade será deduzida a cada venda. Se o usuário modificar esta quantidade atual, assume-se a quantidade informada e gera-se uma movimentação no histórico do estoque com a diferença entre o estoque anterior e a quantidade informada.

URL Raíz: http://api.contaazul.com.br/pub/product/

Campos da entidade Product:

● id: Integer - Identificador único (READ ONLY) ● *name: String - Nome do produto

● costRate: Double - Custo unitário ● rate: Double - Preço de venda

● currentStock: Double - Quantidade disponível em estoque ● lastPurchaseDate: Date - Data da última compra

● category: ProductCategory - Categoria do Produto

curl request GET http://api.contaazul.com.br/pub/product/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' ----header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2' * Lembre de trocar os tokens e o id por valores reais

(25)

Exemplo de retorno: { "id": 0000000, "name": "Produto X", "code": "9", "costRate": 10, "rate": 20, "currentStock": 10, "lastPurchaseAmount": 0 }

(26)

Centro de Custo

Centros de custo que a empresa cadastrou no ContaAzul. O centro de custo serve para saber quanto é gasto em cada área da empresa. Normalmente o centro de custo é utilizado de forma similar aos departamentos da empresa (marketing, desenvolvimento, design, administração,...). Ao cadastrar uma despesa, o usuário pode associá-la a um centro de custo e emitir um

relatório que mostra quanto gastou por departamento da empresa.

URL Raíz: http://api.contaazul.com.br/pub/finance/costcentre/ Métodos disponíveis: GET, GET (id)

Campos da entidade CostCentre:

● id: Integer - Identificador único (READ ONLY) ● description: String - Descrição do centro de custo

http://api.contaazul.com.br/pub/finance/costcentre/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' --header

'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2' * Lembre de trocar os tokens e o id por valores reais

Exemplo de retorno: { "id": 000000, "description": "Comercial", "type": null }

(27)

Lista de preço

No ContaAzul, é possível trabalhar com várias listas de preço, para controlar o preço dos produtos vendidos. Uma utilização bastante comum da lista de preço é para épocas promocionais, como Natal e Dia da Mães.

URL Raíz: http://api.contaazul.com.br/pub/pricelist/

Campos da entidade PriceList:

● id: Integer - Identificador único (READ ONLY) ● *name: String - Nome da categoria do produto

● defaultPriceList: Boolean - Se a lista de preço é a padrão para o sistema ● *items: PriceListItem[ ] - Lista de PriceListItem

Campos da entidade PriceListItem:

● id: Integer - Identificador único (READ ONLY)

● *price: Double - Valor unitário pelo qual o produto será vendido

● comission: Double - Percentual do valor do produto que será pago como comissão para o vendedor

● itemId: Inteiro - Identificador do Produto Exemplo de chamada (via linha de comando):

curl --request GET http://api.contaazul.com.br/pub/pricelist/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' --header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2'

(28)

"id" : 0000000,

"defaultPriceList" : true, "name" : "Lista Padrao", "items" : [ { "id" : 111111, "itemId" : 1111, "price" : 10, "comission" : 0 }, { "id" : 222222, "itemId" : 2222, "price" : 150, "comission" : 0 }, { "id" : 333333, "itemId" : 3333, "price" : 10, "comission" : 0 } ] }

(29)

Categoria Financeira

Categorias financeiras que a empresa cadastrou no ContaAzul. A categoria financeira é utilizada para classificar as despesas e receitas cadastradas pelos usuários. Todo lançamento (receita ou despesa) precisa ser categorizado para ser cadastrado no ContaAzul. O ContaAzul possui algumas categorias pré-cadastradas, porém, o usuário pode cadastrar novas categorias. Ao cadastrar uma nova categoria o usuário precisa definir se esta é uma categoria de despesa ou receita, pois as categorias de receitas são separadas das categorias de despesas. É

possível organizá-las hierarquicamente na tela de "Editar categorias", opção acessada através do financeiro.

URL Raíz: http://api.contaazul.com.br/pub/finance/category/ Métodos disponíveis: GET, GET (id)

Campos da entidade FinanceCategory:

● description: String - Descrição da categoria financeira

● type: [ EXPENSE, REVENUE ] - Tipo de categoria financeira Exemplo de chamada (via linha de comando):

curl --request GET

http://api.contaazul.com.br/pub/finance/category/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' --header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2' * Lembre de trocar os tokens e o id por valores reais

"id": 0000000,

"description": "Despesas de Produtos Vendidos ", "type": "EXPENSE"

(30)

(31)

Lançamentos Financeiros

Os lançamentos financeiros são as despesas e receitas cadastradas no ContaAzul. Todo lançamento possui obrigatoriamente uma data, um valor, uma descrição e uma categoria. O lançamento pode ser recorrente, o que faz com que sejam criadas diversas cópias do mesmo lançamento variando a data do lançamento de acordo com a periodicidade definida pelo

usuário. Estes lançamentos estão vinculados, ao deletar ou alterar um lançamento recorrente o sistema questiona se o usuário deseja alterar todos os lançamentos ou somente aquele

lançamento alterado. Ao criar uma venda, gera-se uma receita no financeiro automaticamente. O mesmo acontece com as compras, que ao serem criadas, geram uma despesa.

URL Raíz: http://api.contaazul.com.br/pub/finance/statement/ Métodos disponíveis: GET, POST

Campos da entidade Statement:

● id: Integer - Identificador único (READ ONLY) ● *memo: String - Descrição do lançamento ● *valor: Double - Valor do lançamento ● *date: Date - Data do lançamento

● *repeat: Boolean - Verdadeiro se possuir recorrencias

● repeatingCycle [NEVER, DIARY, WEEKLY, MONTHLY, BIMONTHLY, YEARLY ] - Ciclo de recorrencia

● *statementType: [ EXPENSE, REVENUE ] - informa se é receita ou despesa ● *done:Boolean - Verdadeiro se o lançamento foi pago ou recebido

● *bankAccountId: Inteiro - Identificador da Conta Bancária ● *categoryId: Inteiro - Identificador da Categoria Financeira

● contactId: Inteiro - Identificador do Fornecedor ( se despesa ) ou Cliente ( se receita ) ● costCenterId: Inteiro - Identificador do Centro de Custo

(32)

curl --request GET

http://api.localhost:8080/pub/finance/statement/?memo=CARTAO%20VISA%2 0ELECTRON%20POSTO%20XYZ --header 'CompanyToken: 0002a143-bec2-4420-0001-4f650acb2100' --header 'ExternalApplicationToken:00031813-76db-9800-0000-1db3ee0ea299'

* Lembre de trocar os tokens e o memo por valores reais

Exemplo de retorno: [ { "id": 0000000, "valor": 80.02, "date": 1354500000000, "repeat": null, "done": true,

"memo": "CARTAO VISA ELECTRON POSTO XYZ", "repeatingCycle": "NEVER", "statementType": "EXPENSE", "bankAccountId":000000, "categoryId": 0000000, "contactId": null, "costCenterId": null } ]

(33)

Tipo de Negociação ( Natureza da Operação )

Natureza da operação define se a negociação que o usuário está criando é uma entrada ou saída de mercadoria. Por isso, por enquanto, só acontece nas vendas e compras de produto. A operação de saída é normalmente utilizada na venda de produtos. Já as de entrada são

normalmente utilizadas nas compras de produtos. As operações de devolução se aplicam em situações em que surge a necessidade de desfazer a operação de venda (saída) ou compra (compra) de produtos. As naturezas de operação podem ser configuradas acessando o menu "Configurações Gerais" na aba de "Faturamento".

URL Raíz: http://api.contaazul.com.br/pub/deal/type/ Métodos disponíveis: GET, GET (id)

Campos da entidade DealType:

● id: Integer - Identificador único (READ ONLY) ● description: String - Descrição do tipo de operação

● operation: [ E, S, DE, DS ] - Operação que o tipo de negociação pode executar ( saida, entrada, devolução de entrada ou devolução de saída ).

curl --request GET http://api.contaazul.com.br/pub/deal/type/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' --header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2'

* Lembre de trocar os tokens e o id por valores reais Exemplo de retorno: { "id":0000000, "description": "Venda", "operation": "S" }

(34)

Venda de Produto

A venda de produto é uma operação que reduz o estoque de produtos e gera uma receita no financeiro da empresa. Para realizar uma venda, o usuário deve informar no mínimo o nome do cliente, pelo menos um produto a ser vendido, e por fim, a quantidade e valor deste produto. Ao realizar uma venda, é interessante informar a conta bancária para que o lançamento gerado no financeiro já esteja pronto para ser baixado (pago). A venda pode ser a vista ou parcelada, caso a venda seja parcelado deve-se definir o valor das parcelas e a data de pagamento de cada parcela. No ContaAzul a parcela pode ser definida rapidamente através do gerador de parcelas, que permite que o usuário informe a quantidade de parcelas (3x ou 30 60 90) para calcular automaticamente.

URL Raíz: http://api.contaazul.com.br/pub/deal/product/sale/ Métodos disponíveis: GET, GET (id), POST

Campos da entidade Deal:

● id: Integer - Identificador único (READ ONLY) ● discount: Double - Valor do desconto

● total: Double - Valor a ser pago (READ ONLY) ● serie: String - Serie

● invoiceNumber:Integer - Número da nota fiscal gerada ( se gerada ) ● dealDate: Date - Data da venda no sistema

● *contactId: Integer - Identificador do Cliente ● observations: String - Observações

● bankAccountId: Integer - Identificador da Conta Bancária ● *dealTypeId:Integer - Identificador do tipo de negociação ● shippingContactId: Integer - Identificador da transportador ● shippingCost: Double - Valor do frete

● shippingCostPayment: String - Forma de pagamento do frete ● *items: DealItem[ ] - Lista de DealItem

(35)

Campos da entidade DealItem:

● *quantity: Integer - Quantidade de produtos a ser faturada ● *rate: Double - Valor unitário pelo qual foi vendido o produto ● vlCustoUnitario:Double - Custo unitário do produto

● observation: String - Observações ● itemId: Inteiro - Identificador do Produto

(36)

Campos da entidade Payment:

● *paymentDate: Date - Data em que foi/será realizado pagamento ● *value: Double - Valor [a ser] pago

● observation: String - Observações

http://api.contaazul.com.br/pub/deal/product/sale/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' --header

'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2' * Lembre de trocar os tokens e o id por valores reais

Exemplo de retorno: { "id": 0000000, "discount": 0, "total": 140, "serie": "1", "dealNumber": 31, "dealDate": "2013-05-06", "contactId":0000000, "observations": "", "bankAccountId":000000, "dealTypeId": 000000, "shippingContactId": 000000, "shippingCost": 60, "shippingCostPayment": "1", "items": [ { "id": 0000001, "itemId": 000001, "quantity": 1, "rate": 60, "vlCustoUnitario": 0, "observation": null }, {

(37)

"quantity": 1, "rate": 20, "vlCustoUnitario": 10, "observation": null } ], "payments": [ { "id": 000003, "paymentDate": "2013-08-06", "value": 46.66, "observation": "Parcela 3" }, { "id": 0000002, "paymentDate": "2013-07-06", "value": 46.67, "observation": "Parcela 2" }, { "id": 0000001, "paymentDate": "2013-06-06", "value": 46.67, "observation": "Parcela 1" } ], "taxes": [ {} ] }

(38)

Compra de Produto

A compra de produto é uma operação que aumenta o estoque de produtos e gera uma despesa no financeiro da empresa. Para realizar uma compra, o usuário deve informar no mínimo o nome do fornecedor, pelo menos um produto a ser comprado, e por fim, a quantidade e valor deste produto. Ao realizar uma compra, é interessante informar a conta bancária para que o lançamento gerado no financeiro já esteja pronto para ser baixado (recebido). A compra pode ser a vista ou parcelada, caso a compra seja parcelado deve-se definir o valor das parcelas e a data de pagamento de cada parcela. No ContaAzul a parcela pode ser definida rapidamente através do gerador de parcelas, que permite que o usuário informe a quantidade de parcelas (3x ou 30 60 90) para calcular automaticamente.

URL Raíz: http://api.contaazul.com.br/pub/deal/product/purchase/ Métodos disponíveis: GET, GET (id), POST

● invoiceNumber:Integer - Número da nota fiscal gerada ( se gerada ) ● dealDate: Date - Data da venda no sistema

● *contactId: Integer - Identificador do Fornecedor ● observations: String - Observações

● bankAccountId: Integer - Identificador da Conta Bancária ● *dealTypeId:Integer - Identificador do tipo de negociação ● shippingContactId: Integer - Identificador da transportador ● shippingCost: Double - Valor do frete

● shippingCostPayment: String - Forma de pagamento do frete ● *items: DealItem[ ] - Lista de DealItem

(39)

● observation: String - Observações ● itemId: Inteiro - Identificador do Produto

Campos da entidade Payment:

● observation: String - Observações

http://api.contaazul.com.br/pub/deal/product/purchase/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' ----header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2' * Lembre de trocar os tokens e o id por valores reais

Exemplo de retorno: { "id": 0000000, "discount": 0, "total": 408.52, "serie": "1", "dealDate": "2013-05-06", "contactId":000000,

"observations": "Texto de observação", "dealTypeId": 000000,

"shippingContactId": 0000000, "shippingCost": 50,

(40)

"items": [ { "id": 0000001, "itemId":000001, "quantity": 1.31, "rate": 3.12, "vlCustoUnitario": null, "observation": null }, { "id":0000002, "itemId":0000002, "quantity": 31.11, "rate": 13, "vlCustoUnitario": null, "observation": null } ], "payments": [ { "id": 0000002, "paymentDate": "2013-07-06", "value": 204.26, "observation": "Parcela 2" }, { "id": 0000001, "paymentDate": "2013-06-06", "value": 204.26, "observation": "Parcela 1" } ], "taxes": [ {} ] }

(41)

Venda de Serviço

A venda de serviço é uma operação que adiciona uma receita no financeiro. Para realizar uma venda de serviço, o usuário deve informar no mínimo o nome do cliente, pelo menos um serviço a ser vendido, o valor deste do serviço e a quantidade (normalmente em horas). Ao realizar uma venda, é interessante informar a conta bancária para que o lançamento gerado no financeiro já esteja pronto para ser baixado (pago). A venda pode ser a vista ou parcelada, caso a venda seja parcelado deve-se definir o valor das parcelas e a data de pagamento de cada parcela. No ContaAzul a parcela pode ser definida rapidamente através do gerador de parcelas, que permite que o usuário informe a quantidade de parcelas (3x ou 30 60 90) para calcular automaticamente.

URL Raíz: http://api.contaazul.com.br/pub/deal/task/sale/ Métodos disponíveis: GET, GET (id), POST

● extraPayment: Double - acrescimo

● invoiceNumber:Integer - Número da nota fiscal gerada ( se gerada ) ● dealDate: Integer - Número da venda no sistema

● *contactId: Integer - Identificador do Fornecedor ● observations: String - Observações

● bankAccountId: Integer - Identificador da Conta Bancária ● *dealTypeId:Integer - Identificador do tipo de negociação ● taskTypeId:Integer - Identificador do tipo de serviço prestado ● shippingContactId: Integer - Identificador da transportador ● shippingCost: Double - Valor do frete

(42)

● *items: DealItem[ ] - Lista de DealItem ● *payments: Payment[ ] - Lista de Payment ● taxes: Tax[ ] - Lista de Tax

● observation: String - Observações ● itemId: Inteiro - Identificador do Serviço Campos da entidade Payment:

● observation: String - Observações Campos da entidade Tax:

● id: Integer - Identificador único (READ ONLY) ● *description: String - Descrição da taxa a ser paga

● *percentage: Double - Porcentagem de imposto a ser paga ● *value: Double - Valor a ser pago de imposto

● *type: [ ISS, COFINS, PIS, INSS, CSLL, IRRF ] - Tipo de imposto a ser pago

http://api.contaazul.com.br/pub/deal/task/sale/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' --header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2'

(43)

Exemplo de retorno: { "id": 0000000, "discount": 0, "total": 1676.3, "serie": "SN", "dealNumber": 32, "dealDate": "2013-05-06", "contactId": 0000000, "observations": "", "bankAccountId": 0000000, "dealTypeId": 0000000, "taskTypeId": 593, "shippingCostPayment": "2", "items": [ { "id": 0000001, "itemId":000000, "quantity": 133.33, "rate": 11.11, "vlCustoUnitario": 1, "observation": null }, { "id": 0000002, "itemId": 0000003, "quantity": 65, "rate": 3, "vlCustoUnitario": 0, "observation": null } ], "payments": [ { "id": 000001, "paymentDate": "2013-05-06", "value": 1558.95, "observation": "" } ], "taxes": [ { "id":000001, "percentage": 2, "value": 33.53, "type": "ISS" }, { "id": 000002,

(44)

"percentage": 5, "value": 83.82, "type": "COFINS" } ] }

(45)

Relatórios Expostos

Vendas por período/vendedor/produto

Para facilitar a apresentação de alguns dados em forma sumarizada. Neste caso, é possível se ter acesso às vendas por: Período, Vendedor e por Produto.

URL Raíz: http://api.contaazul.com.br/pub/deal/sale/report/monthly/ Métodos disponíveis: GET

Parâmetros disponíveis:

● startDate: Date - data de início do relatório ● endDate: Date - data de fim do relatório

● groupBy: [CUSTOMER, SALESMEN, PRODUCT] - Agrupador Campos da entidade SaleReport:

● month: Integer - Identificador único (READ ONLY) ● value: String - Descrição da categoria financeira

● groupBy: [ CUSTOMER,PRODUCT,SALESMEN ] - Tipo de agrupamento, por padrão, cliente. Para agrupar por outro item, basta passar o parâmetro groupBy, por exemplo: http://api.contaazul.com.br/pub/deal/sale/report/monthly?groupBy=PRODUCT

http://api.contaazul.com.br/pub/deal/sale/report/0000000 --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' --header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2' * Lembre de trocar os tokens e o id por valores reais

(46)

Exemplo de retorno: [ { "month" : 1358647200000, "value" : 331.35, "customer" : { "address" : null, "number" : null, "cityId" : null, "id" : 321321, "complement" : null, "documentNumber" : null, "postalCode" : null, "neighborhood" : null, "email" : null,

"name" : "Cliente Teste", "inscricaoEstadual" : null } }, { "month" : 1369364400000, "value" : 0, "customer" : { "address" : null, "number" : null, "cityId" : null, "id" : 123123, "complement" : null, "documentNumber" : null, "postalCode" : null, "neighborhood" : null, "email" : null,

"name" : "Outro Cliente", "inscricaoEstadual" : null }

} ]

(47)

Ranking de produtos

Os produtos que tem mais movimentação são os que devem estar no centro das atenções, para que não faltem no estoque. Para isso, foi criado o Ranking de produtos, sendo que podem ser listados: os mais orçados (propostas comerciais), os mais pedidos, e os mais vendidos. Deste modo, o usuário pode se preparar para sempre ter em estoque estes produtos, além de decisões quem possam lhe gerar ainda mais valor.

URL Raíz: http://api.contaazul.com.br/pub/ranking/product/ Métodos disponíveis: GET

Parâmetros disponíveis:

● startDate: Date - data de início do relatório ● endDate: Date - data de fim do relatório

● dealType: [QUOTATION, ORDER, SALE] - Agrupador Campos da entidade ProductRanking:

● product: Product - Produto

● quantity: Double - quantidade orçada/pedida/vendida

http://api.contaazul.com.br/pub/ranking/product?dealType=ORDER --header 'CompanyToken:0000013e-6ba7-7797-0000-00470355d8b2' ----header 'ExternalApplicationToken:0000013e-6ac3-bf2b-0000-00569b9a1af2' * Lembre de trocar os tokens e o id por valores reais

(48)

Exemplo de retorno: [

{

"product" : { "id" : 000000,

"name" : "Produto mais vendido" }, "quantity" : 50 }, { "product" : { "id" : 111111,

"name" : "Produto em segundo lugar" },

"quantity" : 10 }