ContaAzul API

Este documento foi escrito com o intuito de ajudar os desenvolvedores de aplicaes a se comunicarem com o ContaAzul. Ele possui o detalhamento mnimo necessrio para que sejam realizadas as primeiras integraes 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&autenticao&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&negociaes&do&ContaAzul&...........................................................&10! Overview(das(entidades(que(envolvem(negociaes(..............................................................................................(12! Negociao(de(Venda(de(Servio(......................................................................................................................................(12! Regras&de&Negcio&Expostas&.................................................................................................&13! Clientes(........................................................................................................................................................................................(13! Vendedor(....................................................................................................................................................................................(15! Transportadora(.......................................................................................................................................................................(17! Cidades(........................................................................................................................................................................................(18! Bancos(..........................................................................................................................................................................................(19! Contas(Bancrias(Cadastradas(..........................................................................................................................................(20! Tipo(de(Servio(Prestado(.....................................................................................................................................................(21! Servio(.........................................................................................................................................................................................(22! Categoria(de(Produtos(..........................................................................................................................................................(23! Produtos(.....................................................................................................................................................................................(24! Centro(de(Custo(.......................................................................................................................................................................(26! Lista(de(preo(...........................................................................................................................................................................(27! Categoria(Financeira( ..............................................................................................................................................................(29! Lanamentos(Financeiros(...................................................................................................................................................(31! Tipo(de(Negociao(((Natureza(da(Operao()(...........................................................................................................(33! Venda(de(Produto(...................................................................................................................................................................(34! Compra(de(Produto(................................................................................................................................................................(38! Venda(de(Servio(.....................................................................................................................................................................(41! Vendas(por(perodo/vendedor/produto(......................................................................................................................(45! Ranking(de(produtos(.............................................................................................................................................................(47!

Entendendo o Protocolo
O protocolo da API do ContaAzul foi escrito no modelo REST, onde todas as requisies so feitas via HTTP puro. Os dados trafegados so estruturados no padro JSON. Para cada regra de negcio exposta pelo ContaAzul ( clientes, produtos, vendas, etc.) existe uma URL que a representa. Em nossos exemplos usamos o termo URL raz para estas URL's. Por exemplo, se fossemos buscar dados de um Cliente teramos que consumir o URL http://api.contaazul.com.br/pub/contact/customer. A partir da URL raz o sistema espera que as requisies sejam executadas com determinados mtodos HTTP para cada operao de negcio disponvel ( criao, edio, remoo e pesquisa ). Discutiremos sobre cada um, separadamente, na sequencia.

Obtendo os registros
Para se obter os dados de uma regra de negcio deve-se utilizar o mtodo HTTP GET. Sempre que for chamado mtodo GET na URL raz (http://.../customer/) de qualquer regra de ngocio ser devolvida uma lista com todos os registros encontrado. Por outro lado, sempre que chamarmos o mtodo GET na URL raz, acrescentando o identificador do cliente no final (http://.../customer/123) estaremos buscando os dados especficos deste cliente. possvel tambm filtrar quais campos desejamos trazer para regra de ngocio. 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 negcio, ainda, permitem efetuar pesquisa em suas entidades atrvez dos filtros HTTP ( ou Query String Parameters ). Na chamada de http://.../customer/?name=Silva, por exemplo, traramos apenas os clientes que tenham a palavra "Silva" no campo nome. Todas as chamadas ao mtodo 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...).

Criando registros
Cada regra de ngocio possui uma entidade que a representa. Para se criar um registro basta enviar esta entidade previamente populada atravs do mtodo HTTP POST. Se tudo correr bem, a requisio ir retornar um Status Code 204, no trazendo dado algum no corpo da resposta. Porm, dois Headers HTTP so retornados para auxiliar no rastreio do regristro recm criado: Identificator: ele contm um nmero que identifica o registro na regra de negcio; Location: o endereo no qual pode-se, diretamente, obter mais informaes sobre o registro criado. Normalmente a URL raz concatenado ao Identificator, como descrito no tpico "Obtendo Registros".

Deve-se lembrar que cada regra de negcio possui regras especficas de validao, inclusive seus prprios campos obrigatrios. Sempre que algum erro de validao acontecer ser retornado o Status Code 412, com um objeto JSON descrevendo o motivo do erro. Os demais erros que o server identificar na requisio ( entidade invlida, campos invlidos, etc...) sero 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) atravs do mtodo HTTP PUT. Se tudo correr bem, o servidor ir retornar o Status Code 201, sem corpo na resposta. Sempre que algum erro de validao acontecer ser retornado o Status Code 412, com um objeto JSON descrevendo o motivo do erro. Os demais erros que o server identificar na requisio ( entidade invlida, campos invlidos, etc...) sero tratados com o Status 400.

Removendo registros
Para remover um registro basta chamar a URL que representa o registro (http://.../customer/123) atravs do mtodo HTTP DELETE. No deve ser enviado corpo nesta requisio. Se tudo ocorrer bem, o servidor ir retornar o Status Code 201, sem corpo na resposta. Sempre que algum erro de validao acontecer ser retornado o Status Code 412, com um objeto JSON descrevendo o motivo do erro. Os demais erros que o server identificar na requisio ( entidade invlida, campos invlidos, etc...) sero tratados com o Status 400.

Entendendo o modelo de autenticao da API

Como vimos, o protocolo possui uma sintaxe bem simples e objetiva, porm, para se efetuar a comunicao com a plataforma preciso informar as credenciais corretas em cada requisio, do contrrio, um Status Code 403 ser retornado informando que as credenciais so invlidas:

{ "message": "Bad Credentials" }

Basicamente, deve-se informar dois Header's HTTP em todas as requisies: ExternalApplicationToken: Um identificador que representa a aplicao externa que ir se comunicar com o ContaAzul. CompanyToken: Um identificador que representa que o usurio do ContaAzul autorizou o envio de dados da aplicao externa com a sua conta.

Atravs destas duas informaes consguimos garantir a segurana de nossos usurios, tendo a certeza de que somente as aplicaes que foram explicitamente autorizadas possam ter acesso aos seus dados.

Como conseguir uma chave para o meu aplicativo?

Primeiramente voc deve estar logado no ContaAzul, em seguida acesse a pgina de Integraes Via API. Ser apresentado uma tela conforme imagem abaixo. Localize e clique no boto Solicitar uma chave para meu aplicativo.

Preencha o formulrio com os dados do seu aplicativo:

Nome do aplicativo: Descrio do aplicativo de integrao Email: Pessoa responsvel pelo desenvolvimento do aplicativo, ser o email que receber a chave. URL do Aplicativo: Link da pgina com informaes sobre o aplicativo Restringir o acesso do servidor ao IP (opcional): Define um IP pblico que pode acessar o contaazul via API, ou seja, somente computadores que esto inseridos nessa rede podero acessar o contaazul.

Ao clicar em enviar solicitao, 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 integrao via API.

Como integrar os meus clientes com o ContaAzul ?

Cada empresa dever possuir uma chave de autorizao para o seu aplicativo. Ser de sua responsabilidade gravar uma cpia 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 integrao com o seu aplicativo, caso no seguir no prximo passo, se sim pode fazer as consultas via REST. A criao de chave para o cliente deve ser feita em duas etapas. Primeiro voc deve solicitar uma public token. Atravs 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 pblica, universal, que nunca se repetir, muito semelhante a chave da sua aplicao. Em seguida voc dever chamar a pgina de autorizao do ContaAzul (um pop-up). O Quadro abaixo um exemplo com HTML e JavaScript para chamar essa tela de autorizao:

<a href="javascript:window.open( 'http://app.contaazul.com.br/authorization/request/0000013e-7b50-5649-0000007145a69e35? redirectTo=http://www.aplicativoxyz.com', 'popUpWindow', 'toolbar=no,location=no,status=yes,menubar=no,scrollbars=yes,resizable=yes,width=4 30, height=500')"> 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 parmetro com a CompanyToken caso o usurio autentique. O parmetro de retorno da companyKey authorizationToken. Exemplo: http://www.aplicativoxyz.com?auhorizationToken=0000013e-7b7b-bbd6-0000012a9b7962ba A token 0000013e-7b50-5649-0000-007145a69e35 nica, uma vez chamada ela descartada, ou seja, caso seja aberto o popup e usurio fechar, dever ser criada outra public token. Esse procedimento garante a segurana das informaes no caso de haver um sniffer na rede, em outras palavras, caso algum consiga interceptar esse link e tentar se conectar pela segunda vez, no ser possvel, pois o token j foi descartado.

Quando aberto o popup, essas so as duas telas possveis a serem exibidas: A da esquerda exibida caso o usurio no esteja logado no Contazul ( no mesmo Browser), j a da direita ser exibida no caso o usurio j esteja logado.

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, so ignorados quando enviados na criao de novos registros (via POST), porm, so indispensveis quando usados na atualizao dos registros (via PUT). Os campos das entidades que estamos expondo so praticamente uma referencia de 1 para 1 com os campos que possumos no software Web. Assim, fica mais fcil de entender as regras de negcio. As entidades do ContaAzul so compostas por campos de tipos comuns em qualquer linguagem de programao. Os tipos aceitos pelo ContaAzul em suas entidades so: 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 negociaes do ContaAzul

O ContaAzul se preocupa com a sade financeira das empresas. Diariamente, nossos clientes efetuam muitas compras e vendas, movimentando produtos de seus estoques e gerando lanamentos no financeiro. Analisando estas tarefas rotineiras dos clientes, o ContaAzul notou que as principais operaes do dia-a-dia giram em torno de negociaes. As negociaes so as operaes de venda e compra. A API do ContaAzul foi desenhada para agilizar ainda mais os processos mais valiosos de nossos clientes. Tratamos como negociaes, ento, os processos de venda de produto, compra de produtos e venda de servios.

Nos tpicos finais deste manual so descritas em detalhe as entidades que foram expostas na API. Sendo assim, voc poder compreender do que se trata cada tipo de negociao com detalhes.

Overview das entidades que envolvem negociaes

Todas as negociaes sero realizadas no atravs da entidade Deal (negociao). Nela temos todas as informaes necessrias para realizar negociaes atravs da API. Os dados mnimos para se realizar uma negociao so: items e parcelas. Os itens a serem informados nas negociaes podem ser produtos ou servios. No ContaAzul, a venda de produto realizada de forma totalmente separada da venda de servios. 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 servio ), a quantidade a ser vendida, valor unitrio e (opcionalemente) o custo unitrio. Para que as vendas sejam refletivas no financeiro do ContaAzul, necessrio informar como sero realizados os pagamentos das negociaes. 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 negociaes, sendo que toda negociao 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 aps a venda ser criada.

Negociao de Venda de Servio

Cada tipo de negociao possui algumas peculiaridades. A venda de servio distingui-se das demais por apresentar a opo de informar os impostos cobrados pela prestao de servio. Os servios prestados possuem classificao e taxao adequadas a legislao de cada cidade, e devem ser informadas j na emisso da venda. O primeiro campo que s existe neste tipo de negociao taskType (tipo de servio prestado). Cada cidade possui uma listagem com os tipos de servios em que incidem tributao. 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 tributao 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.

Regras de Negcio Expostas

Clientes
Clientes que a empresa cadastrou no ContaAzul. O cliente utilizado obrigatoriamente nas vendas de servio e produto, propostas comerciais e pedidos de venda. URL Raz: http://api.contaazul.com.br/pub/contact/customer/ Mtodos disponveis: 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 - Inscrio Estadual address: String - Nome da Rua, Avenida, etc...) cityId: Integer - identificador nico da Cidade postalCode: String - CEP neighborhood: String - Bairro number: Integer - Nmero 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

Exemplo de retorno: { "id": 0000000, "name": "Cliente A", "address": "Rua Rua de So Miguel", "number": "333", "complement": "Primeira esquerda", "neighborhood": "Vila dos Remdios", "documentNumber": "83.575.050/0001-24", "postalCode": "53990-000", "inscricaoEstadual": "ISENTO", "email": "email@email.com", "cityId": 5252 }

Vendedor
Vendedores que a empresa cadastrou no ContaAzul. Cada vendedor pode ser associado com um valor de comisso. Este valor preenchido como padro ao criar a venda, porm, pode ser alterado pelo usurio especificamente para cada venda. possvel calcular a comisso total de cada vendedor. URL Raz: http://api.contaazul.com.br/pub/contact/vendor/ Mtodos disponveis: GET, GET (id), POST, PUT e DELETE Campos da entidade Vendor: id: Integer - Identificador nico (READ ONLY) *name: String - Nome email: String - Email documentNumber: String - CPF/CNPJ inscricaoEstadual: String - Inscrio Estadual address: String - Nome da Rua, Avenida, etc...) cityId: Integer - identificador nico da Cidade postalCode: String - CEP neighborhood: String - Bairro number: Integer - Nmero 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

Exemplo de retorno: { "id": 0000000, "name": "Almeida", "address": "Rua Teofredo Goiania", "number": 333, "complement": "Ap 300", "neighborhood": "Cidade dos Funcionrios", "documentNumber": "99214820686", "postalCode": "60822-630", "inscricaoEstadual": "00000000", "email": "email@email.com", "cityId": 1150 }

Transportadora
Transportadoras que a empresa cadastrou no ContaAzul. A transportadora obrigatrio para vendas e compras com frete. URL Raz: http://api.contaazul.com.br/pub/contact/shipper/ Mtodos disponveis: GET, GET (id), POST, PUT e DELETE Campos da entidade Shipping: id: Integer - Identificador nico (READ ONLY) *name: String - Nome email: String - Email documentNumber: String - CPF/CNPJ inscricaoEstadual: String - Inscrio Estadual address: String - Nome da Rua, Avenida, etc...) cityId: Integer - identificador nico da Cidade postalCode: String - CEP neighborhood: String - Bairro number: Integer - Nmero

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 Exemplo de retorno: { "id": 0000000, "name": "Transportadora Best SA", "address": "Rua prudente de moraes", "number": 0001, "complement": "Ap 90", "neighborhood": "So Jos", "documentNumber": "97.083.667/0001-37", "postalCode": "13092-141", "inscricaoEstadual": "3223939", "email": "email@email.com", "cityId": 8946

Cidades
Lista das principais cidades do Brasil com seus respectivos cdigos do IBGE. URL Raz: http://api.contaazul.com.br/pub/contact/shipping/ Mtodos disponveis: GET, GET (id)

Campos da entidade City: id: Integer - Identificador nico (READ ONLY) name: String - Nome da Cidade state: String - Estado ibgeCode: String - Cdigo 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 GOIS", "ibgeCode": 5200050, "state": "GO" }

Bancos
Lista de bancos pr-cadastrados no ContaAzul. Ao cadastrar uma conta bancria, o usurio escolhe um dos bancos pr-cadastrados e define o nome da conta bancria, o saldo inicial e a data do saldo. URL Raz: http://api.contaazul.com.br/pub/bank/ Mtodos disponveis: GET, GET (id) Campos da entidade Bank: code: Integer - Identificador nico (READ ONLY) description: String - Nome do Banco

Exemplo de chamada (via linha de comando): 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

Exemplo de Retorno: { "code": 0, "description": "Banco do Brasil" }

Contas Bancrias Cadastradas

Lista de contas bancrias cadastradas pela empresa no ContaAzul. Ao cadastrar uma conta bancria, o usurio escolhe um dos bancos pr-cadastrados e define o nome da conta bancria, o saldo inicial e a data do saldo. Para baixar (definido como pago ou recebido) um lanamento (receita ou despesa) no financeiro necessrio que o usurio tenha definido uma conta bancria. Cada receita ou despesa baixada atualiza o saldo de uma conta bancria. A conta bancria utilizada para filtrar receitas e despesas no financeiro. URL Raz: http://api.contaazul.com.br/pub/bank/account/ Mtodos disponveis: GET, GET (id), POST, PUT, DELETE

Campos da entidade BankAccount: id: Integer - Identificador nico (READ ONLY) *name: String - Nome da Conta Bancria agencyNumber: String - Agencia accountNumber: String - Conta Corrente wallet: String - Carteira padro *bankId: Integer - Cdigo 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-00001db3ee0ea299' * Lembre de trocar os tokens e o id por valores reais Exemplo de Retorno: { "id": 0000000, "name": "banco de testE", "agencyNumber": "3269",

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

Tipo de Servio Prestado

Lista de todos os servios prestados possveis no pas. Normalmente cada empresa prestadora de servios possui uma lista de servios cadastrados na prefeitura que pode prestar. URL Raz: http://api.contaazul.com.br/pub/tasktype/ Mtodos disponveis: GET, GET (id)

Campos da entidade TaskType: id: Integer - Identificador nico (READ ONLY) description: String - Descrio do servio prestado

Exemplo de chamada (via linha de comando): 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

Exemplo de Retorno: { "id": 0000000, "description": "9.03 - Guias de turismo" }

Servio
Servios que a empresa cadastrou no ContaAzul. Para realizar vendas de servios o usurio deve cadastrar o servio. Este servio pode ser cadastrado na lista de servios ou pelo componente de autocomplete do formulrio de vendas. Para cadastrar um servio o usurio precisa somente definir um nome para o servio, porm os campos opcionais ajudam a gerenciar melhor a empresa. URL Raz: http://api.contaazul.com.br/pub/task/ Mtodos disponveis: GET, GET (id), POST, PUT, DELETE

Campos da entidade Task: id: Integer - Identificador nico (READ ONLY) *name: String - Nome do servio costRate: Double - Custo unitrio rate: Double - Preo de venda

Exemplo de chamada (via linha de comando): 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 Exemplo de Retorno: { "id":0000000, "name": "Servio 1" }

Categoria de Produtos
Para facilitar a organizao dos produtos dentro do ContaAzul, possvel agrupar os produtos em categorias. Para gerenciar as categorias de produtos, utilize o servio abaixo. URL Raz: http://api.contaazul.com.br/pub/product/category/ Mtodos disponveis: 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 Exemplo de retorno: { } "id": 0000000, "name": "Produto acabado"

Produtos
Produtos que a empresa cadastrou no ContaAzul. Para realizar vendas de produtos o usurio deve cadastrar o produto. Este produto pode ser cadastrado na lista de produtos ou pelo componente de autocomplete do formulrio de vendas. Para cadastrar um produto o usurio precisa somente definir um nome para o produto, porm os campos opcionais ajudam a gerenciar melhor a empresa. Ao cadastrar um produto o usurio pode definir o estoque atual e esta quantidade ser deduzida a cada venda. Se o usurio modificar esta quantidade atual, assume-se a quantidade informada e gera-se uma movimentao no histrico do estoque com a diferena entre o estoque anterior e a quantidade informada. URL Raz: http://api.contaazul.com.br/pub/product/ Mtodos disponveis: GET, GET (id), POST, PUT, DELETE Campos da entidade Product: id: Integer - Identificador nico (READ ONLY) *name: String - Nome do produto costRate: Double - Custo unitrio rate: Double - Preo de venda currentStock: Double - Quantidade disponvel em estoque lastPurchaseDate: Date - Data da ltima compra category: ProductCategory - Categoria do Produto

Exemplo de chamada (via linha de comando): 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

Exemplo de retorno: {

"id": 0000000, "name": "Produto X", "code": "9", "costRate": 10, "rate": 20, "currentStock": 10, "lastPurchaseAmount": 0

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, administrao,...). Ao cadastrar uma despesa, o usurio pode associ-la a um centro de custo e emitir um relatrio que mostra quanto gastou por departamento da empresa. URL Raz: http://api.contaazul.com.br/pub/finance/costcentre/ Mtodos disponveis: GET, GET (id)

Campos da entidade CostCentre: id: Integer - Identificador nico (READ ONLY) description: String - Descrio do centro de custo

Exemplo de chamada (via linha de comando): curl --request GET 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 }

Lista de preo
No ContaAzul, possvel trabalhar com vrias listas de preo, para controlar o preo dos produtos vendidos. Uma utilizao bastante comum da lista de preo para pocas promocionais, como Natal e Dia da Mes. URL Raz: http://api.contaazul.com.br/pub/pricelist/ Mtodos disponveis: GET, GET (id), POST, PUT, DELETE Campos da entidade PriceList: id: Integer - Identificador nico (READ ONLY) *name: String - Nome da categoria do produto defaultPriceList: Boolean - Se a lista de preo a padro para o sistema *items: PriceListItem[ ] - Lista de PriceListItem

Campos da entidade PriceListItem: id: Integer - Identificador nico (READ ONLY) *price: Double - Valor unitrio pelo qual o produto ser vendido comission: Double - Percentual do valor do produto que ser pago como comisso 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' * Lembre de trocar os tokens e o id por valores reais

Exemplo de retorno: {

"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 } ]

Categoria Financeira
Categorias financeiras que a empresa cadastrou no ContaAzul. A categoria financeira utilizada para classificar as despesas e receitas cadastradas pelos usurios. Todo lanamento (receita ou despesa) precisa ser categorizado para ser cadastrado no ContaAzul. O ContaAzul possui algumas categorias pr-cadastradas, porm, o usurio pode cadastrar novas categorias. Ao cadastrar uma nova categoria o usurio precisa definir se esta uma categoria de despesa ou receita, pois as categorias de receitas so separadas das categorias de despesas. possvel organiz-las hierarquicamente na tela de "Editar categorias", opo acessada atravs do financeiro. URL Raz: http://api.contaazul.com.br/pub/finance/category/ Mtodos disponveis: GET, GET (id)

Campos da entidade FinanceCategory: id: Integer - Identificador nico (READ ONLY) description: String - Descrio 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 Exemplo de retorno: {

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

Lanamentos Financeiros
Os lanamentos financeiros so as despesas e receitas cadastradas no ContaAzul. Todo lanamento possui obrigatoriamente uma data, um valor, uma descrio e uma categoria. O lanamento pode ser recorrente, o que faz com que sejam criadas diversas cpias do mesmo lanamento variando a data do lanamento de acordo com a periodicidade definida pelo usurio. Estes lanamentos esto vinculados, ao deletar ou alterar um lanamento recorrente o sistema questiona se o usurio deseja alterar todos os lanamentos ou somente aquele lanamento 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 Raz: http://api.contaazul.com.br/pub/finance/statement/ Mtodos disponveis: GET, POST

Campos da entidade Statement: id: Integer - Identificador nico (READ ONLY) *memo: String - Descrio do lanamento *valor: Double - Valor do lanamento *date: Date - Data do lanamento *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 lanamento foi pago ou recebido *bankAccountId: Inteiro - Identificador da Conta Bancria *categoryId: Inteiro - Identificador da Categoria Financeira contactId: Inteiro - Identificador do Fornecedor ( se despesa ) ou Cliente ( se receita ) costCenterId: Inteiro - Identificador do Centro de Custo

Exemplo de chamada (via linha de comando):

curl --request GET http://api.localhost:8080/pub/finance/statement/?memo=CARTAO%20VISA%2 0ELECTRON%20POSTO%20XYZ --header 'CompanyToken: 0002a143-bec2-44200001-4f650acb2100' --header 'ExternalApplicationToken:00031813-76db9800-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 } ]

Tipo de Negociao ( Natureza da Operao )

Natureza da operao define se a negociao que o usurio est criando uma entrada ou sada de mercadoria. Por isso, por enquanto, s acontece nas vendas e compras de produto. A operao de sada normalmente utilizada na venda de produtos. J as de entrada so normalmente utilizadas nas compras de produtos. As operaes de devoluo se aplicam em situaes em que surge a necessidade de desfazer a operao de venda (sada) ou compra (compra) de produtos. As naturezas de operao podem ser configuradas acessando o menu "Configuraes Gerais" na aba de "Faturamento". URL Raz: http://api.contaazul.com.br/pub/deal/type/ Mtodos disponveis: GET, GET (id)

Campos da entidade DealType: id: Integer - Identificador nico (READ ONLY) description: String - Descrio do tipo de operao operation: [ E, S, DE, DS ] - Operao que o tipo de negociao pode executar ( saida, entrada, devoluo de entrada ou devoluo de sada ).

Exemplo de chamada (via linha de comando): 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" }

Venda de Produto
A venda de produto uma operao que reduz o estoque de produtos e gera uma receita no financeiro da empresa. Para realizar uma venda, o usurio deve informar no mnimo 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 bancria para que o lanamento 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 atravs do gerador de parcelas, que permite que o usurio informe a quantidade de parcelas (3x ou 30 60 90) para calcular automaticamente. URL Raz: http://api.contaazul.com.br/pub/deal/product/sale/ Mtodos disponveis: 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 - Nmero da nota fiscal gerada ( se gerada ) dealDate: Date - Data da venda no sistema *contactId: Integer - Identificador do Cliente observations: String - Observaes bankAccountId: Integer - Identificador da Conta Bancria *dealTypeId:Integer - Identificador do tipo de negociao shippingContactId: Integer - Identificador da transportador shippingCost: Double - Valor do frete shippingCostPayment: String - Forma de pagamento do frete *items: DealItem[ ] - Lista de DealItem *payments: Payment[ ] - Lista de Payment

Campos da entidade DealItem: id: Integer - Identificador nico (READ ONLY) *quantity: Integer - Quantidade de produtos a ser faturada *rate: Double - Valor unitrio pelo qual foi vendido o produto vlCustoUnitario:Double - Custo unitrio do produto observation: String - Observaes itemId: Inteiro - Identificador do Produto

Campos da entidade Payment: id: Integer - Identificador nico (READ ONLY) *paymentDate: Date - Data em que foi/ser realizado pagamento *value: Double - Valor [a ser] pago observation: String - Observaes

Exemplo de chamada (via linha de comando): curl --request GET 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 }, { "id": 0000002, "itemId": 0000002,

} ], "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": [ {} ] }

"quantity": 1, "rate": 20, "vlCustoUnitario": 10, "observation": null

Compra de Produto
A compra de produto uma operao que aumenta o estoque de produtos e gera uma despesa no financeiro da empresa. Para realizar uma compra, o usurio deve informar no mnimo 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 bancria para que o lanamento 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 atravs do gerador de parcelas, que permite que o usurio informe a quantidade de parcelas (3x ou 30 60 90) para calcular automaticamente. URL Raz: http://api.contaazul.com.br/pub/deal/product/purchase/ Mtodos disponveis: 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 - Nmero da nota fiscal gerada ( se gerada ) dealDate: Date - Data da venda no sistema *contactId: Integer - Identificador do Fornecedor observations: String - Observaes bankAccountId: Integer - Identificador da Conta Bancria *dealTypeId:Integer - Identificador do tipo de negociao shippingContactId: Integer - Identificador da transportador shippingCost: Double - Valor do frete shippingCostPayment: String - Forma de pagamento do frete *items: DealItem[ ] - Lista de DealItem *payments: Payment[ ] - Lista de Payment

Campos da entidade DealItem: id: Integer - Identificador nico (READ ONLY) *quantity: Integer - Quantidade de produtos a ser faturada *rate: Double - Valor unitrio pelo qual foi vendido o produto vlCustoUnitario:Double - Custo unitrio do produto observation: String - Observaes itemId: Inteiro - Identificador do Produto

Campos da entidade Payment: id: Integer - Identificador nico (READ ONLY) *paymentDate: Date - Data em que foi/ser realizado pagamento *value: Double - Valor [a ser] pago observation: String - Observaes

Exemplo de chamada (via linha de comando): curl --request GET 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 observao", "dealTypeId": 000000, "shippingContactId": 0000000, "shippingCost": 50, "shippingCostPayment": "2",

"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": [ {} ] }

Venda de Servio
A venda de servio uma operao que adiciona uma receita no financeiro. Para realizar uma venda de servio, o usurio deve informar no mnimo o nome do cliente, pelo menos um servio a ser vendido, o valor deste do servio e a quantidade (normalmente em horas). Ao realizar uma venda, interessante informar a conta bancria para que o lanamento 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 atravs do gerador de parcelas, que permite que o usurio informe a quantidade de parcelas (3x ou 30 60 90) para calcular automaticamente. URL Raz: http://api.contaazul.com.br/pub/deal/task/sale/ Mtodos disponveis: GET, GET (id), POST

Campos da entidade Deal: id: Integer - Identificador nico (READ ONLY) discount: Double - Valor do desconto extraPayment: Double - acrescimo total: Double - Valor a ser pago (READ ONLY) serie: String - Serie invoiceNumber:Integer - Nmero da nota fiscal gerada ( se gerada ) dealDate: Integer - Nmero da venda no sistema *contactId: Integer - Identificador do Fornecedor observations: String - Observaes bankAccountId: Integer - Identificador da Conta Bancria *dealTypeId:Integer - Identificador do tipo de negociao taskTypeId:Integer - Identificador do tipo de servio prestado shippingContactId: Integer - Identificador da transportador shippingCost: Double - Valor do frete shippingCostPayment: String - Forma de pagamento do frete

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

Campos da entidade DealItem: id: Integer - Identificador nico (READ ONLY) *quantity: Integer - Quantidade de produtos a ser faturada *rate: Double - Valor unitrio pelo qual foi vendido o produto vlCustoUnitario:Double - Custo unitrio do produto observation: String - Observaes itemId: Inteiro - Identificador do Servio

Campos da entidade Payment: id: Integer - Identificador nico (READ ONLY) *paymentDate: Date - Data em que foi/ser realizado pagamento *value: Double - Valor [a ser] pago observation: String - Observaes

Campos da entidade Tax: id: Integer - Identificador nico (READ ONLY) *description: String - Descrio 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

Exemplo de chamada (via linha de comando): curl --request GET http://api.contaazul.com.br/pub/deal/task/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": 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,

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

Relatrios Expostos
Vendas por perodo/vendedor/produto
Para facilitar a apresentao de alguns dados em forma sumarizada. Neste caso, possvel se ter acesso s vendas por: Perodo, Vendedor e por Produto. URL Raz: http://api.contaazul.com.br/pub/deal/sale/report/monthly/ Mtodos disponveis: GET Parmetros disponveis: startDate: Date - data de incio do relatrio endDate: Date - data de fim do relatrio groupBy: [CUSTOMER, SALESMEN, PRODUCT] - Agrupador

Campos da entidade SaleReport: month: Integer - Identificador nico (READ ONLY) value: String - Descrio da categoria financeira groupBy: [ CUSTOMER,PRODUCT,SALESMEN ] - Tipo de agrupamento, por padro, cliente. Para agrupar por outro item, basta passar o parmetro groupBy, por exemplo: http://api.contaazul.com.br/pub/deal/sale/report/monthly?groupBy=PRODUCT

Exemplo de chamada (via linha de comando): curl --request GET 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

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 } }

}, {

Ranking de produtos
Os produtos que tem mais movimentao so os que devem estar no centro das atenes, para que no faltem no estoque. Para isso, foi criado o Ranking de produtos, sendo que podem ser listados: os mais orados (propostas comerciais), os mais pedidos, e os mais vendidos. Deste modo, o usurio pode se preparar para sempre ter em estoque estes produtos, alm de decises quem possam lhe gerar ainda mais valor. URL Raz: http://api.contaazul.com.br/pub/ranking/product/ Mtodos disponveis: GET Parmetros disponveis: startDate: Date - data de incio do relatrio endDate: Date - data de fim do relatrio dealType: [QUOTATION, ORDER, SALE] - Agrupador

Campos da entidade ProductRanking: product: Product - Produto quantity: Double - quantidade orada/pedida/vendida

Exemplo de chamada (via linha de comando): curl --request GET 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

Exemplo de retorno: [

{ "product" : { "id" : 000000, "name" : "Produto mais vendido" }, "quantity" : 50 "product" : { "id" : 111111, "name" : "Produto em segundo lugar" }, "quantity" : 10

}, {