Se hoje você utiliza um app de vendas que não tem integração direta com o eNotas ou quer conectar sua loja online diretamente com o nosso sistema, você pode fazer essa integração via API!
Para que essa opção seja válida, você vai precisar da nossa documentação de API e da ajuda do seu time de TI para configurar, beleza?
Em anexo você consegue baixar o PDF a documentação também!
eNotas – API (REST)
1. Especificação
A API Web é disponibilizada por meio de um serviço REST HTTP, onde a comunicação de dados é feita por meio de JSON, especificando o Content-type a ser utilizado como application/json.
Todos os métodos da API necessitam de autenticação prévia por meio de uma API Key, uma chave única. A API Key é fundamental para manter a integridade das comunicações feitas com o eNotas, mantenha-a em segurança.
A url base da api é https://app.enotas.com.br/api/.
2. Autenticação
Para autenticar e assim poder usar a API do eNotas, a cada requisição, basta incluir no header a sua API Key utilizando Basic Authentication:
Authorization: Basic {sua-APIKey-aqui}
Por exemplo:
Authorization: Basic MEJCRTM1RTgtMjg0Ri00MDIyLTlEOUYtM0Y0QkQzRENDMzBB
Onde MEJCRTM1RTgtMjg0Ri00MDIyLTlEOUYtM0Y0QkQzRENDMzBB é a sua API Key.
3. Métodos
3.1 Venda
GET /api/vendas/getFilterBy
Retorna uma lista de vendas encontradas pelo critério de pesquisa e paginação definidos.
Exemplo de resposta:
{ "totalRecords": 1, "data": [{ "id": "03be4de4-9775-4af7-8fa4-aa7ea8c70100", "data": "02/08/2016", "cliente": { "id": "532760c3-5159-4cd4-99e2-c994a7c70100", "nome": "Wesley Marques", "email": "[email protected]", "cpfCnpj": "00000000000", "nomeFantasia": null }, "produto": { "id": "6bd9a5cb-25c7-48b5-86d7-2be0a7c70100",
"nome": "Consultoria Financeira Master" }, "nfe": { "situacao": 1, "id": "8ceae9d1-8b3f-4e40-93bf-aa7ea8c70100", "prefeitura": { "numero": "201200000000487", "linkImpressao": "http://api.enotasgw.com.br/file/bb3e1752-461f-4be8-972e-550dbf470100/b28bf594aeaa-4e08-8227-5780a7900100/bb2443b9-24e6-4db2-8d69-2521d4d90100/pdf", "linkXml": "http://api.enotasgw.com.br/file/bb3e1752-461f-4be8-972e-550dbf470100/b28bf594-aeaa4e08-8227-5780a7900100/bb2443b9-24e6-4db2-8d69-2521d4d90100/xml", "dataEmissao": "25/08/2016" } }, "dataNFeEnviadoPorEmail": null, "idExterno": null, "situacao": 3, "valorTotal": 90.00, "tags": "", "vencimento": null, "quandoEmitirNFe": 0, "enviarNFeCliente": true, "meioPagamento": 0 }] }
Parâmetros:
pageNumber int Número da página, sendo 0 o número da primeira página. pageSize int Total de itens a serem retornados por página. filter string Filtro para realização da pesquisa.
Possíveis campos: data situacao tags/id cliente/id cliente/nome cliente/nomeFantasia cliente/cpfCnpj produto/id nfe/situacao nfe/prefeituraNumero nfe/rpsNumero
Exemplos de filtro: data ge '2015-01-01' and data le '2015-01-31' orderBy string Ordenação dos itens retornados.
Possíveis campos: data
situacao valorTotal cliente/nome produto/nome canal/nome nfe/situacao
Exemplo de ordenação: data desc
GET /api/vendas/{vendaId}
Recupera informações da venda pelo seu identificado único. O retorno inclui os dados da venda requisitada.
Exemplo de resposta:
{ "id": "e1d47c0a-3d6e-49a9-9773-685467de0100", "data": "31/08/2016", "cliente": { "id": "75fbea85-6305-4703-8658-19a4f9d80100", "nome": null, "email": "[email protected]", "cpfCnpj": null, "nomeFantasia": null }, "produto": { "id": "ca569445-657f-4ecb-86ba-7811abd80100", "nome": "Comissões Google AdSense" }, "nfe": { "situacao": 0, "id": "7d6fb7ea-8da7-4bf0-b167-685467de0100", "rps": { "dataCompetencia": "03/09/2016" }, "prefeitura": { "numero": "201200000000487", "linkImpressao": "http://api.enotasgw.com.br/file/bb3e1752-461f-4be8-972e-550dbf470100/b28bf594-aeaa4e08-8227-5780a7900100/bb2443b9-24e6-4db2-8d69-2521d4d90100/pdf", "linkXml": "http://api.enotasgw.com.br/file/bb3e1752-461f-4be8-972e-550dbf470100/b28bf594-aeaa-4e088227-5780a7900100/bb2443b9-24e6-4db2-8d69-2521d4d90100/xml", "dataEmissao": "25/08/2016" }, "motivoSituacao": null, "cancelamentoRejeitado": false, "dataTentativaCancelamento": null, "motivoRejeicaoCancelamento": null, "empresa": { "id": "bbea6f85-069f-472e-a5aa-7751c9b80100", "nomeFantasia": "VIRTUAL GROUP" }, "observacoes": null, "discriminacao": "Comissões Google AdSense",
"municipioPrestacao": { "codigoIbge": 3106200, "nome": "Belo Horizonte" }, "valorIss": null, "issRetidoFonte": false, "valorTotal": 500.00, "aliquotaIss": null, "valorLiquido": 500.00, "deducoes": null, "baseCalculo": 500.00, "impostosFederais": { "valorCofins": null, "valorCsll": null, "valorInss": null, "valorIr": null, "valorPis": null, "porcentagemCofins": null, "porcentagemCsll": null, "porcentagemInss": null, "porcentagemIr": null, "porcentagemPis": null } }, "dataNFeEnviadoPorEmail": null, "idExterno": null, "situacao": 2, "valorTotal": 500.00, "tags": "37;testeDeTag", "vencimento": "03/09/2016", "quandoEmitirNFe": 1, "enviarNFeCliente": true, "meioPagamento": 1 }
Parâmetros:
vendaId string Identificador único da venda.
POST /api/vendas
Insere ou atualiza uma venda. O retorno inclui o identificador único da venda.
Exemplo de pedido:
{ "cliente": { "id": "75fbea85-6305-4703-8658-19a4f9d80100" }, "data": "31/08/2016", (obrigatório) "vencimento": "10/09/2016", "produto": { (obrigatório) "nome": "Como adestrar cachorros",
"idExterno": "324", "valorTotal": 29, "diasGarantia": 30, "tags": "adestramento" }, "valorTotal": 5990.00, (obrigatório) "quandoEmitirNFe": 1, "enviarNFeCliente": true, "meioPagamento": 2, "tags": "exemplodevenda;exemplodetag2", "municipioPrestacao": { "nome": "Belo Horizonte", "codigoIbge": 3106200 }, "dataCompetencia": "10/09/2016", "discriminacao": "Consultoria Financeira Master", "valorTotalNFe": 5990.00, "aliquotaIss": null, "valorIss": null, "issRetidoFonte": false, "deducoes": null, "observacoes": null, "porcentagemCofins": 1.5, "porcentagemCsll": 2.2, "porcentagemInss": 3, "porcentagemIr": 4.3, "porcentagemPis": 5 }
Exemplo de resposta:
{ "vendaId": "e1d47c0a-3d6e-49a9-9773-685467de0100" }
POST /api/vendas/{vendaId}/cancelar
Cancelar uma venda e sua nota fiscal caso a venda tenha nota fiscal emitida. O retorno inclui o identificador único da venda.
Exemplo de resposta:
{ "vendaId": "e1d47c0a-3d6e-49a9-9773-685467de0100" }
3.2 Cliente
GET /api/clientes/getFilterBy
Retorna uma lista de clientes encontradas pelo critério de pesquisa e paginação definidos.
Exemplo de resposta:
{ "totalRecords": 1, "data": [{ "id": "6cf136c0-9af1-4a9d-8ded-e96302d90100", "createdAt": "24/08/2016", "cpfCnpj": null, "nome": null, "nomeFantasia": null, "inscricaoMunicipal": null, "inscricaoEstadual": null, "email": "[email protected]", "telefone": null, "endereco": { "pais": null, "uf": null, "codigoIbgeUf": null, "cidade": null, "codigoIbgeCidade": null, "logradouro": null, "numero": null, "complemento": null, "bairro": null, "cep": null }, "valorMovimentado": null }] }
Parâmetros:
pageNumber int Número da página, sendo 0 o número da primeira página. pageSize int Total de itens a serem retornados por página. filter string Filtro para realização da pesquisa.
Possíveis campos: createdAt nome email cpfCnpj uf cidade
Exemplos de filtro: contains(nome, 'josé') or contains(nome, 'maria') orderBy string Ordenação dos itens retornados.
Possíveis campos: createdAt nome email cpfCnpj
uf cidade valorMovimentado
Exemplo de ordenação: nome desc
GET /api/clientes/{clienteId}
Recupera informações do cliente pelo seu identificado único. O retorno inclui os dados do cliente requisitado.
Exemplo de resposta:
{ "id": "6cf136c0-9af1-4a9d-8ded-e96302d90100", "createdAt": "24/08/2016", "cpfCnpj": null, "nome": null, "nomeFantasia": null, "inscricaoMunicipal": null, "inscricaoEstadual": null, "email": "[email protected]", "telefone": null, "endereco": { "pais": null, "uf": null, "codigoIbgeUf": null, "cidade": null, "codigoIbgeCidade": null, "logradouro": null, "numero": null, "complemento": null, "bairro": null, "cep": null }, "valorMovimentado": null }
Parâmetros:
clienteId string Identificador único do cliente.
POST /api/clientes
Insere ou atualiza um cliente. O retorno inclui o identificador único do cliente.
Exemplo de pedido:
{ "nomeFantasia": null, "inscricaoMunicipal": null, "inscricaoEstadual": null, "email": "[email protected]", (obrigatório se nome/cpfCnpj não forem preenchidos) "telefone": "31231231231", "nome": "José Romualdo", (obrigatório se cpfCnpj/email não forem preenchidos)
"cpfCnpj": "15112512121", (obrigatório se nome/email não forem preenchidos) "endereco": { "cidade": "Belo Horizonte", "codigoIbgeCidade": 3106200, "logradouro": "R. Engenheiro Alberto Pontes", "numero": "427", "complemento": null, "bairro": "Buritis", "cep": "12412512" } }
Exemplo de resposta:
{ "clienteId": "016f030c-510a-4aea-a5e4-9b126ede0100" }
3.3 Produto
GET /api/produtos/getFilterBy
Retorna uma lista de produtos encontradas pelo critério de pesquisa e paginação definidos.
Exemplo de resposta:
{ "totalRecords": 1, "data": [{ "id": "2ffab063-644f-4c95-8c37-6ee36ede0100", "createdAt": "31/08/2016", "cadastradoAutomaticamente": false, "nome": "Como adestrar cachorros", "idExterno": "324", "diasGarantia": 30, "valorTotal": 29.00, "aliquotaIss": null, "discriminacaoServico": null, "tags": "39;adestramento" }] }
Parâmetros:
pageNumber int Número da página, sendo 0 o número da primeira página. pageSize int Total de itens a serem retornados por página. filter string Filtro para realização da pesquisa.
Possíveis campos: createdAt nome
idExterno tags
Exemplos de filtro: contains(idExterno, '123') orderBy string Ordenação dos itens retornados.
Possíveis campos: createdAt proprio idExterno nomenfe/situacao
Exemplo de ordenação: createdAt desc
GET /api/produtos/{produtoId}
Recupera informações do produto pelo seu identificado único. O retorno inclui os dados do produto requisitado.
Exemplo de resposta:
{ "id": "2ffab063-644f-4c95-8c37-6ee36ede0100", "createdAt": "31/08/2016", "cadastradoAutomaticamente": false, "nome": "Como adestrar cachorros", "idExterno": "324", "diasGarantia": 30, "valorTotal": 29.00, "aliquotaIss": null, "discriminacaoServico": null, "tags": "39;adestramento" }
Parâmetros:
produtoId string Identificador único do produto.
POST /api/produtos
Insere ou atualiza um produto. O retorno inclui o identificador único do produto.
Exemplo de pedido:
{ "nome": "Como adestrar cachorros", (obrigatório) "idExterno": "324", "valorTotal": 29.00, "diasGarantia": 30, "tags": "adestramento" }
Exemplo de resposta:
{ "produtoId": "2ffab063-644f-4c95-8c37-6ee36ede0100" }
4. Anexos
4.1 Situação da venda
EmAberto 0 Essa situação é raramente usada. Salvo exceções como integrações via canais de venda. Vencida 1 EmGarantia 2 Completa 3 Reembolsada 4 Cancelada 5
4.2 Situação da NFe
Pendente 0 EmProcessoDeEmissao 1 Emitida 2 FalhaAoEmitir 3 EmProcessoDeCancelamento 4 Cancelada 5 FalhaAoCancelar 6 NaoEmitir 7 EnviadoPorEmail 8
4.3 Quando emitir NFe
Venda 0 AposAGarantia 1 NaoEmitir 2
4.4 Meio pagamento
NaoInformado 0 BoletoBancario 1 CartaoCredito 2 Deposito 3 TransferenciaBancaria 4 BCash 5 PayPal 6 Outro 7