Introdução

A API da Tenex é organizada baseando-se em REST.

Ela é projetada para ter URLs previsíveis e orientadas a recursos.

Os erros são indicados por códigos de resposta HTTP e uma resposta JSON descrevendo o problema.

Todas as respostas da API serão retornadas em JSON, incluindo erros.

Versões

Essa é a versão mais recente da API da Tenex. Para a v1, veja a documentação em API v1.

Recomendamos que novas implementações utilizem a v2, mesmo em contas antigas.

As duas serão mantidas, porém a v1 não receberá novas funcionalidades.

PHP

Recomendamos o uso da biblioteca Guzzle para realizar as chamadas.

Os exemplos em PHP consideram que a bibloteca Guzzle foi instalada utilizando Composer.

Python 3

Recomendamos o uso da biblioteca Requests para realizar as chamadas

Estrutura Padrão da API

Todos os endpoints da API compartilham uma estrutura padrão para:

Autenticação
Formatos
Tipos de Respostas
Tipos de Requisições
Erros
Limitação de Conteúdo
Paginação
Ordenação
Filtragem
Expansão de Referências

De forma geral, parâmetros de URL (Query String) começando com _ (underscore) são reservados para funções da API e outros parâmetros são considerados filtros.

Atenção: Todos dados de entrada e saída da API são em JSON, Content-Type sempre é considerado como sendo text/json e não há suporte para application/x-www-form-urlencoded

Autenticação

curl "https://suaempresa.tenex.com.br/api/v2/servicos/" \
    -u "4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo:"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/servicos/',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/servicos/', auth=(apiKey, '')
)

print(res.text)

A Tenex usa chaves de API para permitir acesso a uma instalação.

Para gerar sua chave de API associando a um Perfil acesse:

https://suaempresa.tenex.com.br/api-chave/

A autenticação ocorre via HTTP Basic Auth. Informe somente a sua chave de API como nome de usuário. Você não precisa informar uma senha.

Todas as requisições devem ser feitas via HTTPS. A chave de API também precisa estar presente em todas as requisições.

Formatos

A API da Tenex tem o seguinte padrão de formatos.

Tipo de Campo	Descrição	Exemplo
data	ISO 8601 somente com ano, mês e dia	2021-04-25
data e hora	ISO 8601 completo com fuso horário	2021-05-20T12:24:59-03:00
hora	Com 4 dígitos separados por :	11:20
monetário	Com até 2 casas decimais (opcionais) e sempre separado por ponto	14232.22
percentual	Com até 2 casas decimais (opcionais) e sempre separado por ponto	55.1
inteiro	Sem casas decimais	1234
texto	Texto em UTF-8	Descrição

Campos do tipo data e hora devem considerar o fuso horário descrito. Esse pode mudar e por isso deve ser tratado com cuidado.
Campos do tipo Chave Estrangeira (Foreign Key / FK) sempre possuem tanto chave e valor nas respostas.

Por exemplo: no Serviço a chave id_atividade que aponta para o CNAE possui o campo extra atividade que mostrará sempre o texto de exibição dessa atividade. Esse campo de exibição deve ser utilizado só como atalho para evitar uma consulta extra e não é considerado na Inserção ou Atualização.

Tipos de Respostas

A API retorna dois tipos de respostas em caso de sucesso:

Registro Único

{
    "id": 3,
    "nome": "Servi\u00e7o Exemplo 3",
    "status": 1,
    "id_servico": 104,
    "id_atividade": 6202300,
    "discriminacao": "Referente para presta\u00e7\u00e3o de Servi\u00e7o Exemplo 3. \r\nCompet\u00eancia: #venda.mesanterior",
    "valor": 300,
    "impostos_percentual": 6,
    "codigo_tributacao_municipio": "6202300",
    "servico": "01.04 Elabora\u00e7\u00e3o de programas de computadores, inclusive de jogos eletr\u00f4nicos.",
    "atividade": "6202-3\/00 Desenvolvimento e licenciamento de programas de computador customiz\u00e1veis"
}

Um Registro Único representa uma entidade na Tenex, por exemplo, um Cliente, uma Venda ou um Município.

Operações diretamente sobre um registro sempre retornam um Registro Único.

Exemplo: A inserção de um Serviço sempre retornará um Registro Único com o elemento que acabou de ser inserido.

Listagem de Registros

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 3,
        "sort": null,
        "requestId": "c6dde1d7819e49a25389b52d78486ec601d27795"
    },
    "data": [
        {
            "id": 5201405,
            "nome": "Aparecida de Goi\u00e2nia (GO)",
            "uf": 52
        },
        {
            "id": 5201801,
            "nome": "Aragoi\u00e2nia (GO)",
            "uf": 52
        },
        {
            "id": 5208707,
            "nome": "Goi\u00e2nia (GO)",
            "uf": 52
        }
    ]
}

Uma listagem padrão da API contém um cabeçalho (header) com metadados e um conjunto de dados (data) com 0 ou mais registros únicos. Todos os endpoints genéricos retornam listagens e permitem a filtragem, ordenação e paginação dos dados.

header

Contém metadados úteis com informação de paginação e ordenação da consulta realizada.

Campo	Descrição
offset	índice do primeiro registro retornado no conjunto geral de dados
limit	limite máximo de registros por resposta
count	contagem total de registros existentes com os critérios de filtragem utilizados
sort	parâmetros de ordenacão utilizados
requestId	hash único para rastreamento do suporte

data

Contém a lista de Registros Únicos de acordo com os critérios da busca e segue o formato de cada tipo de entidade sendo selecionada.

Tipos de Requisições

A API suporta requisições dos métodos do HTTP: GET, POST, PUT e DELETE

HTTP Method	Descrição
GET	Seleciona um ou múltilos registros
POST	Cria um novo registro
PUT	Atualiza um registro existente
DELETE	Exclui um registro

Erros

{
    "code": 401,
    "message": "Chave de API invalida: 4vOqPRfmql..."
}

A Tenex usa códigos de resposta HTTP para indicar o sucesso ou falha de uma requisição.

401 Unauthorized

De forma geral códigos na faixa de 200-299 representam o sucesso da requisição. Códigos na faixa dos 400-499 representam um erro nos parâmetros informados e códigos na faixa de 500-599 indicam um erro no nosso servidor.

Adicionalmente, retornamos também um objeto JSON no seguinte formato:

{ "code": "...", "message": "..." }

Onde:

code: o código de erro HTTP retornado (em adição ao retornado no cabeçalho da requisição HTTP)

message: breve descrição do problema ocorrido e possível solução

Códigos de erro comuns

Código	Nome	Descrição
400	Bad Request	Algum parâmetro da requisição é inválido
401	Unauthorized	Chave de API inválida ou permissões inválidas (ver Perfil associado à chave da API)
404	Not Found	Não há serviço disponível na URL informada
500	Internal Server Error	Ocorreu um problema no sistema. Nossa equipe sempre é informada quando isso acontece.
503	Service Unavailable	Serviço temporariamente indisponível. Por favor, tente novamente.

Limitação de Conteúdo

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/servicos/?_fields=id,nome"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/servicos/?_fields=id,nome',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/servicos/?_fields=id,nome', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 3,
        "sort": null,
        "requestId": "85b17f9b7e826d8e36bce75ea1b0f93f5afb6a26"
    },
    "data": [
        {
            "id": 1,
            "nome": "Servi\u00e7o Exemplo 1"
        },
        {
            "id": 2,
            "nome": "Servi\u00e7o Exemplo 2"
        },
        {
            "id": 3,
            "nome": "Servi\u00e7o Exemplo 3"
        }
    ]
}

Requisições da API podem escolher quais campos de um objeto serão retornados.

Para limitar os campos deve-se informar uma lista de campos no parâmetro reservado _fields. Exemplo:

_fields=id,nome

Os campos suportados são todos aqueles presentes na estrutura padrão de um objeto.

Paginação

curl "https://suaempresa.tenex.com.br/api/v2/servicos/?_offset=1&_limit=2" \
     -u "4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo:"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/servicos/?_offset=1&_limit=2',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/servicos/?_offset=1&_limit=2', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 1,
        "limit": 2,
        "count": 3,
        "sort": null,
        "requestId": "0447c8e417756b645c2c0c36c765518d892d57d1"
    },
    "data": [
        {
            "id": 2,
            "nome": "Servi\u00e7o Exemplo 2",
            "status": 1,
            "id_servico": 104,
            "id_atividade": 6202300,
            "discriminacao": "Referente para presta\u00e7\u00e3o de Servi\u00e7o Exemplo 2. \r\nCompet\u00eancia: #venda.mesanterior",
            "valor": 200,
            "impostos_percentual": 6,
            "codigo_tributacao_municipio": "6202300",
            "servico": "01.04 Elabora\u00e7\u00e3o de programas de computadores, inclusive de jogos eletr\u00f4nicos.",
            "atividade": "6202-3\/00 Desenvolvimento e licenciamento de programas de computador customiz\u00e1veis"
        },
        {
            "id": 3,
            "nome": "Servi\u00e7o Exemplo 3",
            "status": 1,
            "id_servico": 104,
            "id_atividade": 6202300,
            "discriminacao": "Referente para presta\u00e7\u00e3o de Servi\u00e7o Exemplo 3. \r\nCompet\u00eancia: #venda.mesanterior",
            "valor": 300,
            "impostos_percentual": 6,
            "codigo_tributacao_municipio": "6202300",
            "servico": "01.04 Elabora\u00e7\u00e3o de programas de computadores, inclusive de jogos eletr\u00f4nicos.",
            "atividade": "6202-3\/00 Desenvolvimento e licenciamento de programas de computador customiz\u00e1veis"
        }
    ]
}

Todas as entidadas registradas na Tenex possuem suporte através da API para obtenção em conjunto. Dessa forma é possível listar vários clientes, serviços ou vendas, por exemplo.

Para controlar os dados retornados utilizamos uma paginação baseada em índices. Sempre iniciando a partir da posição 0 e tendo um limite padrão de retorno de 100 registros.

Parâmetros da requisição

Parâmetro	Valor Padrão	Descrição
_offset	0	A partir de qual registro os dados serão retornados
_limit	10	Número de registros a retornar. Valores possíveis de 1 a 1000

Ordenação

curl "https://suaempresa.tenex.com.br/api/v2/servicos/?_sort=-valor&_fields=id,nome,valor" \
     -u "4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo:"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/servicos/?_sort=-valor&_fields=id,nome,valor',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/servicos/?_sort=-valor&_fields=id,nome,valor', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 3,
        "sort": "-valor",
        "requestId": "7696d807d3a15707eb26a2dc6d622640c819a8bd"
    },
    "data": [
        {
            "id": 3,
            "nome": "Servi\u00e7o Exemplo 3",
            "valor": 300
        },
        {
            "id": 2,
            "nome": "Servi\u00e7o Exemplo 2",
            "valor": 200
        },
        {
            "id": 1,
            "nome": "Servi\u00e7o Exemplo 1",
            "valor": 100
        }
    ]
}

É possível ordenar uma listagem por um ou vários campos, em ordem crescente ou decrescente. Caso não seja definida uma ordem a padrão será utilizada e não garantimos que sempre será a mesma.

Parâmetros da requisição

Parâmetro	Valor Padrão	Descrição
_sort	null	Qual campo será usado na ordenação. Opcionalmente um - pode ser usado para inverter a ordenação. Uma lista de campos separada por vírgula pode ser usada para ordenação. Exemplos `-nome`, `valor` ou `-nome,valor`

Filtragem

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/municipios/?nome\[contains\]=recife"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/municipios/?nome[contains]=recife',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/municipios/?nome[contains]=recife', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 1,
        "sort": null,
        "requestId": "8d60ad0ff3dc3601972a5e5fb789324290f47b4d"
    },
    "data": [
        {
            "id": 2611606,
            "nome": "Recife (PE)",
            "uf": 26
        }
    ]
}

Requisições da API de listagem podem ser filtradas com um esquema de operadores disponíveis através de parâmetros da URL. É possível filtrar por qualquer um dos campos de um objeto, porém deve-se observar os operadores de acordo com o tipo de campo filtrado.

O formato de um parâmetro de URL para ser usado como filtro é:

campo[operador]=valor

campo é o nome do campo no objeto
operador dentro dos colchetes é um dos operadores suportados. [eq] é o padrão caso não informado
valor é o valor a ser usado na filtragem

Filtragem por registro referenciado

Pode-se filtrar, por exemplo, Clientes que possuem um Contato com certo nome. Para isso o seguinte formato deve ser utilizado:

secao.campo[operador]=valor

Onde secao é o registro referenciado. Um caso comum seria o Contato dentro da estrutura de Clientes. A seguinte requisição filtraria todo os clientes que possuem um contato com nome "Fulano":

GET https://suaempresa.tenex.com.br/api/v2/clientes/?_fields=id,cpf,nome&contato.nome[contains]=fulano

Múltiplas condições

Vários filtros podem ser usados em conjunto para criar uma consulta com múltiplas condições.
Filtros repetidos para o mesmo campo e operador serão considerados como uma operação OU. Exemplo:

GET https://suaempresa.tenex.com.br/api/v2/servicos/?id=1&id=2

Trará os serviços de id 1 e 2.

Filtros para campos diferentes são considerados como uma operação E. Exemplo:

GET https://suaempresa.tenex.com.br/api/v2/servicos/?discriminacao[contains]=referente&valor[gte]=150

Trará os serviços que contém o texto "referente" no campo discriminacao e valor maiores ou igual a 150.

Lista de operadores suportados

Operador	Exemplo	Descrição
eq	id=2 ou id[eq]=2	filtro padrão, sempre considerado de forma implícita quando não se define um operador
neq	id[neq]=2	é diferente
gt	id[gt]=100	maior que
lt	id[lt]=200	menor que
gte	id[gte]=100	maior que ou igual
lte	id[lte]=200	menor que ou igual
between	id[between]=10,20	entre dois valores
isnull	nome[isnull]	é nulo
isnotnull	nome[isnotnull]	não é nulo
contains	nome[contains]=maria	contém o texto
notcontains	nome[notcontains]=joaquim	não contém o texto

Expansão de Referências

curl "https://suaempresa.tenex.com.br/api/v2/clientes/?_fields=id,nome&cpf=070.613.880-56&_expand=contatos" \
    -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo:

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/clientes/?_fields=id,nome&cpf=070.613.880-56&_expand=contatos',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/clientes/?_fields=id,nome&cpf=070.613.880-56&_expand=contatos', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 1,
        "sort": null,
        "requestId": "729b0c1db380766de09410d888e9ba4917147f3e"
    },
    "data": [
        {
            "id": 2,
            "nome": "Cliente Exemplo 1",
            "contatos": [
                {
                    "id": 1,
                    "id_pessoa": 2,
                    "tipo": null,
                    "principal": null,
                    "nome": "Fulano",
                    "cpf": null,
                    "data_nascimento": null,
                    "identidade": null,
                    "email": "fulano@exemplo.com",
                    "telefone": null,
                    "celular": null,
                    "obs": null,
                    "cep": null,
                    "id_cidade": null,
                    "estado": null,
                    "endereco": null,
                    "numero": null,
                    "complemento": null,
                    "bairro": null,
                    "cidade": null
                },
                {
                    "id": 2,
                    "id_pessoa": 2,
                    "tipo": null,
                    "principal": null,
                    "nome": "Sicrano",
                    "cpf": null,
                    "data_nascimento": null,
                    "identidade": null,
                    "email": "sicrano@exemplo.com",
                    "telefone": null,
                    "celular": null,
                    "obs": null,
                    "cep": null,
                    "id_cidade": null,
                    "estado": null,
                    "endereco": null,
                    "numero": null,
                    "complemento": null,
                    "bairro": null,
                    "cidade": null
                }
            ]
        }
    ]
}

Utilizando o parâmetro _expand é possível expandir objetos aninhados. Evitando assim outras consultas para obter dados relacionados.

Serviços

Objeto do Serviço

{
    "id": 1,
    "nome": "Servi\u00e7o Exemplo 1",
    "status": 1,
    "id_servico": 104,
    "id_atividade": 6202300,
    "discriminacao": "Referente para presta\u00e7\u00e3o de Servi\u00e7o Exemplo 1. \r\nCompet\u00eancia: #venda.mesanterior",
    "valor": 100,
    "impostos_percentual": 6,
    "codigo_tributacao_municipio": "6202300",
    "servico": "01.04 Elabora\u00e7\u00e3o de programas de computadores, inclusive de jogos eletr\u00f4nicos.",
    "atividade": "6202-3\/00 Desenvolvimento e licenciamento de programas de computador customiz\u00e1veis"
}

Estrutura do Serviço

Campo	Tipo	Descrição
id	inteiro	Chave primária do registro, auto incrementada automaticamente
nome	texto	Nome de exibição
status	inteiro	1 Ativo 2 Inativo
id_servico	inteiro	Item da Lista de Serviço baseado na Lei Complementar 116, de 21 de Julho de 2003 considerando somente números. Ex: para 1.02 – Programação informe 102 Veja como consultar a lista completa em Item da Lista de Serviços
servico	texto	Nome de exibição do Item da Lista de Serviço.
id_atividade	inteiro	Aponta para um CNAE no sistema. Veja a lista em CNAE
atividade	texto	Nome de exibição do CNAE.
discriminacao	texto	Texto descritivo do Serviço
impostos_percentual	percentual	Valor estimado de impostos incidentes. Para impressão em NF
codigo_tributacao_municipio	texto	Código necessário para emissão de NF nas prefeituras.

Listar Serviços

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/servicos/"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/servicos/',
    [
        'auth' => [$apiKey, ''],
    ]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/servicos/', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 3,
        "sort": null,
        "requestId": "40e691832bec22a1d827d77d12ff95f7a301ed53"
    },
    "data": [
        { SERVICO 1 },
        { SERVICO 2 },
        { SERVICO 3 }
    ]
}

GET https://suaempresa.tenex.com.br/api/v2/servicos/

Inserir Serviço

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"nome":"Serviço de Teste"}' \
    "https://suaempresa.tenex.com.br/api/v2/servicos/"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.tenex.com.br/api/v2/servicos/',
    [
        'auth' => [$apiKey, ''],
        'json' => [
            'nome' => 'Serviço de Teste',
        ]
    ]
);

echo $res->getBody();

import requests
import json

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.post(
    'https://suaempresa.tenex.com.br/api/v2/servicos/',
    auth = (apiKey, ''),
    data = json.dumps({"nome":"Serviço de Teste"})
)

print(res.text)

{
    "id": 4,
    "nome": "Servi\u00e7o de Teste",
    "status": 1,
    "id_servico": null,
    "id_atividade": null,
    "discriminacao": null,
    "valor": 0,
    "impostos_percentual": 0,
    "codigo_tributacao_municipio": null,
    "servico": null,
    "atividade": null
}

POST https://suaempresa.tenex.com.br/api/v2/servicos/

Atualizar Serviço

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"nome":"Serviço de Teste - Atualizado"}' \
     -X PUT \
    "https://suaempresa.tenex.com.br/api/v2/servicos/4"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'PUT',
    'https://suaempresa.tenex.com.br/api/v2/servicos/',
    [
        'auth' => [$apiKey, ''],
        'json' => [
            'nome' => 'Serviço de Teste - Atualizado',
        ]
    ]
);

echo $res->getBody();

import requests
import json

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.put(
    'https://suaempresa.tenex.com.br/api/v2/servicos/4',
    auth = (apiKey, ''),
    data = json.dumps({"nome":"Serviço de Teste - Atualizado"})
)

print(res.text)

{
    "id": 4,
    "nome": "Servi\u00e7o de Teste - Atualizado",
    "status": 1,
    "id_servico": null,
    "id_atividade": null,
    "discriminacao": null,
    "valor": 0,
    "impostos_percentual": 0,
    "codigo_tributacao_municipio": null,
    "servico": null,
    "atividade": null
}

PUT https://suaempresa.tenex.com.br/api/v2/servicos/{ID}

Selecionar Serviço

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/servicos/4"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/servicos/4',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/servicos/4', auth=(apiKey, '')
)

print(res.text)

GET https://suaempresa.tenex.com.br/api//v2/servicos/{ID}

{
    "id": 4,
    "nome": "Servi\u00e7o de Teste - Atualizado",
    "status": 1,
    "id_servico": null,
    "id_atividade": null,
    "discriminacao": null,
    "valor": 0,
    "impostos_percentual": 0,
    "codigo_tributacao_municipio": null,
    "servico": null,
    "atividade": null
}

Excluir Serviço

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    -X DELETE \
    "https://suaempresa.tenex.com.br/api/v2/servicos/4"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'DELETE',
    'https://suaempresa.tenex.com.br/api/v2/servicos/4',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.delete(
    'https://suaempresa.tenex.com.br/api/v2/servicos/4', auth=(apiKey, '')
)

print(res.text)

DELETE https://suaempresa.tenex.com.br/api/v2/servicos/{ID}

{
    "id": "4"
}

Meios de Pagamento

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/meios-pagamento/"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/meios-pagamento/',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/meios-pagamento/', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 2,
        "sort": null,
        "requestId": "11312ce82dcd26762afddfd3eadc122b755edef2"
    },
    "data": [
        {
            "id": 4,
            "nome": "Esp\u00e9cie",
            "status": 2,
            "tipo": 1,
            "multa": 0,
            "juros": 0
        },
        {
            "id": 7,
            "nome": "Boleto (Testes)",
            "status": 1,
            "tipo": 2,
            "multa": 2,
            "juros": 1
        }
    ]
}

Lista de Meios de Pagamento cadastrados na Tenex.

Essa estrutura está disponível somente para consulta.

Campo	Tipo	Descrição
id	inteiro	chave do Meio de Pagamento
nome	texto	Nome de exibição
status	inteiro	1 Ativo 2 Inativo
tipo	inteiro	1 Espécie 2 Boleto 3 Cheque 4 Cartão de Crédito Externo 5 Cartão de Débito Externo 6 Depósito 7 Transferência 9 Cobrança Externa 11 Cartão Online 12 PIX
multa	percentual	Valor percentual da multa por atraso de pagamento
juros	percentual	Valor percentual dos juros mensais por atraso de pagamento

GET https://suaempresa.tenex.com.br/api/v2/meios-pagamento/

Clientes

Objeto do Cliente

{
    "id": 2,
    "codigo": 1,
    "data_cadastro": "2020-06-01T16:22:48+00:00",
    "status": 1,
    "tipo": 2,
    "cnpj": null,
    "nome": "Cliente Exemplo 1",
    "razao_social": "Cliente Exemplo 1",
    "inscricao_estadual": null,
    "inscricao_municipal": null,
    "cpf": "070.613.880-56",
    "data_nascimento": "1989-08-10",
    "identidade": "1234567",
    "genero": "Masculino",
    "obs": null,
    "cep": "52.061-030",
    "id_cidade": 2611606,
    "estado": 26,
    "endereco": "Rua Silveira Lobo",
    "numero": "32",
    "complemento": null,
    "bairro": "Poco",
    "cidade": "Recife (PE)",
    "contatos": [
        {
            "id": 1,
            "id_pessoa": 2,
            "tipo": null,
            "principal": null,
            "nome": "Contado de Exemplo 1",
            "cpf": null,
            "data_nascimento": null,
            "identidade": null,
            "genero": "Masculino",
            "email": "fulano@exemplo.com",
            "telefone": null,
            "celular": null,
            "obs": null,
            "cep": null,
            "id_cidade": null,
            "estado": null,
            "endereco": null,
            "numero": null,
            "complemento": null,
            "bairro": null,
            "cidade": null
        },
        {
            "id": 2,
            "id_pessoa": 2,
            "tipo": null,
            "principal": null,
            "nome": "Contato de Exemplo 2",
            "cpf": null,
            "data_nascimento": null,
            "identidade": null,
            "genero": "Feminino",
            "email": "sicrano@exemplo.com",
            "telefone": null,
            "celular": null,
            "obs": null,
            "cep": null,
            "id_cidade": null,
            "estado": null,
            "endereco": null,
            "numero": null,
            "complemento": null,
            "bairro": null,
            "cidade": null
        }
    ],
    "cartoes": [
        {
            "id": 2,
            "id_pessoa": 2,
            "id_meio_pagamento": 8,
            "padrao": 1,
            "titular": "CLIENTE EXEMPLO",
            "bandeira": "visa",
            "numero": "************1112",
            "validade": "2028-11-30",
            "meio_pagamento": "Cart\u00e3o de Cr\u00e9dito Online (Testes)"
        }
    ]
}

Estrutura do Cliente

Campo	Tipo	Descrição
id	inteiro	chave primária do registro, auto incrementada automaticamente
codigo	inteiro	código do cliente para referência extra
data_cadastro	data e hora	momento da realizaçao do cadastro
status	inteiro	1 Ativo 2 Inativo
tipo	inteiro	1 Pessoa Jurídica 2 Pessoa Física
nome	texto	nome de exibição do cliente
cnpj	texto	dados da Pessoa Jurídica
razao_social	texto	dados da Pessoa Jurídica
inscricao_estadual	texto	dados da Pessoa Jurídica
inscricao_municipal	texto	dados da Pessoa Jurídica
cpf	texto	dados da Pessoa Física
data_nascimento	data	dados da Pessoa Física
identidade	texto	dados da Pessoa Física
genero	texto	1 Feminino 2 Masculino 3 Outro
obs	texto	texto livre para anotações
cep	texto	CEP no formato XX.YYY-ZZZ
id_cidade	inteiro	código da cidade no IBGE. Veja Municípios
cidade	texto	nome de exibição da cidade.
estado	inteiro	código da Unidade Federativa no IGBE (primeiros dois dígitos do código do município). Veja Municípios
endereco	texto	dados de endereço
numero	texto	dados de endereço
complemento	texto	dados de endereço
bairro	texto	dados de endereço
contatos	lista	Lista de Contatos conforme estrutura de um Contato
cartoes	lista	Lista de Cartões associados ao cliente conforme estrutura de um cartão
custom_...	-	Todos os campos customizados serão retornados com o prefixo custom_ e seguirão os tipos escolhidos no seu cadastro. Para mais informações contacte nosso suporte.

Estrutura do Contato

Campo	Tipo	Descrição
id	inteiro	chave primária do registro, auto incrementada automaticamente
id_pessoa	inteiro	chave para o cliente
tipo	texto	tipo de Contato
principal	inteiro	1 Sim 0 Não
nome	texto	nome do contato Pessoa Física
cpf	texto	CPF
data_nascimento	data	data de nascimento
identidade	texto	número de identidade
genero	texto	1 Feminino 2 Masculino 3 Outro
email	texto	email do contato
telefone	texto	número de telefone
celular	texto	número de telefone
obs	texto	texto livre para anotações
cep	texto	CEP no formato XX.YYY-ZZZ
id_cidade	inteiro	código da cidade no IBGE. Veja Municípios
cidade	texto	nome de exibição da cidade.
estado	inteiro	código da Unidade Federativa no IGBE (primeiros dois dígitos do código do município). Veja Municípios
endereco	texto	dados de endereço
numero	texto	dados de endereço
complemento	texto	dados de endereço
bairro	texto	dados de endereço

Estrutura do Cartão

Campo	Tipo	Descrição
id	inteiro	chave primária do registro, auto incrementada automaticamente
id_pessoa	inteiro	chave da pessoa
id_meio_pagamento	inteiro	chave do meio de pagamento
meio_pagamento	texto	nome de exibição do meio de pagamento
padrao	inteiro	1 Sim 0 Não
titular	texto	nome to titular do cartão
bandeira	texto	nome da bandeira
numero	texto	últimos dígitos do número
validade	data	data de validade
codigo	inteiro	três ou quatro dígitos do código de segurança do cartão

Listar Clientes

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/clientes/?id=2&id=3&_expand=contatos,cartoes"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/clientes/?id=2&id=3&_expand=contatos,cartoes',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/clientes/?id=2&id=3&_expand=contatos,cartoes', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 3,
        "sort": null,
        "requestId": "f42a5bfea3d478e9abc88aefae2dfec252879117"
    },
    "data": [
        { CLIENTE 1 },
        { CLIENTE 2 },
        { CLIENTE 3 }
    ]
}

GET https://suaempresa.tenex.com.br/api/v2/clientes/

Inserir Cliente

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"tipo":1,"nome":"Cliente de Teste"}' \
    "https://suaempresa.tenex.com.br/api/v2/clientes/"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.tenex.com.br/api/v2/clientes/',
    [
        'auth' => [$apiKey, ''],
        'json' => [
            'tipo' => 1,
            'nome' => 'Cliente de Teste',
        ]
    ]
);

echo $res->getBody();

import requests
import json

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.post(
    'https://suaempresa.tenex.com.br/api/v2/clientes/',
    auth = (apiKey, ''),
    data = json.dumps({"tipo":1,"nome":"Cliente de Teste"})
)

print(res.text)

{
    "id": 7,
    "codigo": 1,
    "data_cadastro": "2021-06-16T19:34:17+00:00",
    "status": 1,
    "tipo": 1,
    "cnpj": null,
    "nome": "Cliente de Teste",
    "razao_social": "Cliente de Teste",
    "inscricao_estadual": null,
    "inscricao_municipal": null,
    "cpf": null,
    "data_nascimento": null,
    "identidade": null,
    "genero": "Feminino",
    "obs": null,
    "cep": null,
    "id_cidade": null,
    "estado": null,
    "endereco": null,
    "numero": null,
    "complemento": null,
    "bairro": null,
    "cidade": null,
    "contatos": [],
    "cartoes": []
}

POST https://suaempresa.tenex.com.br/api/v2/clientes/

Atualizar Cliente

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"tipo":1,"nome":"Cliente de Teste Alterado"}' \
     -X PUT \
    "https://suaempresa.tenex.com.br/api/v2/clientes/7"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'PUT',
    'https://suaempresa.tenex.com.br/api/v2/clientes/7',
    [
        'auth' => [$apiKey, ''],
        'json' => [
            'tipo' => 1,
            'nome' => 'Cliente de Teste - Alterado',
        ]
    ]
);

echo $res->getBody();

import requests
import json

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.put(
    'https://suaempresa.tenex.com.br/api/v2/clientes/7',
    auth = (apiKey, ''),
    data = json.dumps({"tipo":1,"nome":"Cliente de Teste - Alterado"})
)

print(res.text)

{
    "id": 7,
    "codigo": 1,
    "data_cadastro": "2021-06-16T19:34:17+00:00",
    "status": 1,
    "tipo": 1,
    "cnpj": null,
    "nome": "Cliente de Teste - Alterado",
    "razao_social": "Cliente de Teste - Alterado",
    "inscricao_estadual": null,
    "inscricao_municipal": null,
    "cpf": null,
    "data_nascimento": null,
    "identidade": null,
    "genero": "Feminino",
    "obs": null,
    "cep": null,
    "id_cidade": null,
    "estado": null,
    "endereco": null,
    "numero": null,
    "complemento": null,
    "bairro": null,
    "cidade": null,
    "contatos": [],
    "cartoes": []
}

PUT https://suaempresa.tenex.com.br/api/v2/clientes/{ID}

Selecionar Cliente

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/clientes/2"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/clientes/2',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/clientes/2?_expand=cartoes', auth=(apiKey, '')
)

print(res.text)

GET https://suaempresa.tenex.com.br/api/v2/clientes/{ID}

{
    "id": 2,
    "codigo": 1,
    "data_cadastro": "2020-06-01T16:22:48+00:00",
    "status": 1,
    "tipo": 2,
    "cnpj": null,
    "nome": "Cliente Exemplo 1",
    "razao_social": "Cliente Exemplo 1",
    "inscricao_estadual": null,
    "inscricao_municipal": null,
    "cpf": "070.613.880-56",
    "data_nascimento": "1989-08-10",
    "identidade": "1234567",
    "genero": "Feminino",
    "obs": null,
    "cep": "52.061-030",
    "id_cidade": 2611606,
    "estado": 26,
    "endereco": "Rua Silveira Lobo",
    "numero": "32",
    "complemento": null,
    "bairro": "Poco",
    "cidade": "Recife (PE)",
    "cartoes": [
        {
            "id": 2,
            "id_pessoa": 2,
            "id_meio_pagamento": 8,
            "padrao": 1,
            "titular": "CLIENTE EXEMPLO",
            "bandeira": "visa",
            "numero": "************1112",
            "validade": "2028-11-30",
            "meio_pagamento": "Cart\u00e3o de Cr\u00e9dito Online (Testes)"
        }
    ]
}

Excluir Cliente

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    -X DELETE \
    "https://suaempresa.tenex.com.br/api/v2/clientes/7"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'DELETE',
    'https://suaempresa.tenex.com.br/api/v2/clientes/7',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.delete(
    'https://suaempresa.tenex.com.br/api/v2/clientes/7', auth=(apiKey, '')
)

print(res.text)

DELETE https://suaempresa.tenex.com.br/api/v2/clientes/{ID}

{
    "id": "7"
}

Vendas / Contratos

Objeto da Venda

{
    "id": 39,
    "agendamento": 1,
    "agendamento_data": null,
    "agendamento_frequencia": null,
    "agendamento_automatico": 1,
    "agendamento_repetir": 1,
    "agendamento_data_fim": null,
    "agendamento_numero": 0,
    "agendamento_dados": {
        "modelo": "Cobran\u00e7a - Venda",
        "anexo_1": null,
        "anexo_2": null,
        "id_venda": 39,
        "id_modelo": 1,
        "anexo_nfse": 1,
        "id_contato": -1,
        "anexo_boleto": 1
    },
    "agendamento_data_geracao": "2020-06-08T17:53:18+00:00",
    "agendamento_sequencia": 3,
    "agendamento_ativo": 1,
    "agendamento_ativo_data": "2020-06-08T17:49:29+00:00",
    "agendamento_ultima_ocorrencia": null,
    "data": "2020-05-01",
    "id_cliente": 3,
    "discriminacao": "Referente para presta\u00e7\u00e3o de Servi\u00e7o Exemplo 2. \r\nCompet\u00eancia: Abril de 2020",
    "desconto": 0,
    "valor_venda": 200,
    "metodo_cobranca": 1,
    "email_enviar": 1,
    "email_enviado": "2020-06-08T17:53:18+00:00",
    "email_erro": null,
    "email_entrega": null,
    "email_leitura": null,
    "sms_enviar": null,
    "sms_enviado": null,
    "id_meio_pagamento": 8,
    "parcelas": [
        {
            "id": 39,
            "id_venda": 39,
            "parcela": 1,
            "numero": "00003901",
            "data_vencimento": "2020-11-10",
            "data_credito": null,
            "data_vencimento_original": null,
            "valor": 200,
            "valor_original": 0,
            "valor_recebido": 0,
            "valor_tarifas": 0,
            "status": 1,
            "data_recebimento": null,
            "data_repasse": null,
            "pdf_url": null,
            "linha_digitavel": null,
            "pix_imagem_url": null,
            "pix_codigo": null
        }
    ],
    "nfse_dados": {
        "aliquota": null,
        "rps_tipo": "1",
        "valor_ir": null,
        "rps_serie": "FSIMP",
        "valor_pis": null,
        "iss_retido": "2",
        "valor_csll": null,
        "valor_inss": null,
        "id_municipio": "2611606",
        "valor_cofins": null,
        "valor_deducoes": null,
        "outras_retencoes": null,
        "impostos_federais": "2",
        "natureza_operacao": "1",
        "id_municipio_emissao": "2611606"
    },
    "cliente": "Cliente Exemplo 2",
    "meio_pagamento": "Cart\u00e3o de Cr\u00e9dito Online (Testes)",
    "parcela_status": 5,
    "nfse_status": 1,
    "pagamento_online_codigo": "lW3hCH6XaEw0htOvCAwVVA",
    "itens": [
        {
            "id": 40,
            "id_venda": 39,
            "recorrente": 1,
            "id_servico": 2,
            "valor": 200,
            "qtd": 1,
            "total": 200,
            "servico": "Servi\u00e7o Exemplo 2"
        }
    ]
}

Estrutura da Venda

Campo	Tipo	Descrição
id	inteiro	chave primária do registro, auto incrementada automaticamente
data¹	data	data de registro da venda
agendamento	inteiro	se é um Contrato 1 Sim 0 Não
agendamento_data¹	data	data de geração esperada dessa venda
agendamento_frequencia	inteiro	0 Somente uma Vez 2 Bimestral 3 Trimestral 6 Semestral 12 Anual
agendamento_automatico	inteiro	determina se a venda será gerada automaticamente no dia agendamento_data 1 Sim 0 Não
agendamento_repetir	inteiro	opções extra de controle de agendamento: 1 Sempre 2 Qtd. de Ocorrências 3 Data Específica
agendamento_data_fim	data	no caso de 3 Data Específica, determina a data de última ocorrência
agendamento_numero	inteiro	no caso de 2 Qtd. de Ocorrências, determina quantas ocorrências da venda existirão
agendamento_ativo	inteiro	determinar se o agendamento está ativo ou pausado 1 Ativo 0 Pausado
agendamento_ativo_data²	data e hora	data de última modificação do agendamento_ativo
agendamento_ultima_ocorrencia²	inteiro	1 Sim - essa venda é a última de uma sequência de agendamento
agendamento_data_geracao²	data	data de geração de uma venda Cadastrada originária de um Contrato
agendamento_sequencia²	inteiro	ordem de geração de uma venda Cadastrada originária de um Contrato
id_cliente	inteiro	Id do cliente relacionado a essa venda
cliente	inteiro	Nome de exibição do cliente
discriminacao	texto	texto descritivo da venda que também será utilizado na emissão da Nota Fiscal
desconto	monetário	desconto dado sobre o valor total dos serviços
valor_venda	monetário	valor da venda, usado como base para emissão de NF mas não necessariamente o valor que será cobrado em parcelas
metodo_cobranca	inteiro	1 Emitir NF Agora 2 Aguardar Pagamento para Emitir NF 3 Não emitir NF
email_enviar	inteiro	1 Sim 2 Não
email_enviado²	data e hora	informação de envio de email de cobrança para essa venda
email_erro²	data e hora	informação de erro de envio de email, caso haja
email_entrega²	data e hora	informação de entrega de email, caso haja
email_leitura²	data e hora	informação de leitura de email, caso haja
sms_enviar	inteiro	1 Sim 2 Não
sms_enviado²	data e hora	null
id_meio_pagamento	inteiro	id do meio de pagamento a ser utilizado
meio_pagamento	texto	nome de exibição do meio de pagamento
parcela_status²	inteiro	1 Pendente 2 Quitado 3 Recebimento Parcial 4 Cancelado 5 Vencido
pagamento_online_codigo²	texto	Código único para essa venda permitindo utilização da página de pagamento online na URL com formato https://suaempresa.tenex.com.br/fatura/<pagamento_online_codigo>
nfse_status²	inteiro	1 Emitida 2 Cancelada 3 Pendente 4 Erro

Observações

¹ Para Vendas Cadastradas a data deve ser preenchida, caso contrário agendamento_data deve ser preenchido e o registro será um Contrato/Recorrência

² Campos preenchidos automaticamente pelo sistema para somente leitura nas respostas.

Estrutura dos Dados de Agendamento

Essa estrutura é opcional e determina parâmetros extras para o envio do email na venda (email_enviar = 1).

Campo	Tipo	Descrição
anexo_N	texto	onde N é um número maior ou igual a 1: anexo manualmente incluído no email
id_venda	inteiro	Id da Venda
id_modelo	inteiro	Id do Modelo a ser usado no envio
modelo	texto	nome de exibição do modelo de email
anexo_nfse	inteiro	determina se será anexado o PDF da NF (quando existe)
anexo_boleto	inteiro	determina se será anexado o PDF do BOleto (quando existe)
id_contato	inteiro	-1 para enviar para os Contatos Principais ou o Id do Contato relacionado ao cliente dessa venda

Estrutura dos Dados de NFS-e

Campo	Tipo	Descrição
aliquota	monetário	alíquota do ISS
iss_retido	monetário	1 Sim 2 Não
rps_tipo	monetário	1 Normal 2 Misto 3 Cupom
rps_serie	texto	1 a 5 caracteres descrevendo a série do RPS
valor_ir	monetário	valor do IR retido
valor_pis	monetário	valor do PIS retido
valor_csll	monetário	valor do CSLL retido
valor_inss	monetário	valor do INSS retido
valor_cofins	monetário	valor do COFINS retido
valor_deducoes	monetário	valor total de outras deduções
outras_retencoes	monetário	valor de outras retenções
impostos_federais	inteiro	Impostos Federais Retidos: 1 Sim 2 Não
natureza_operacao	inteiro	1 Tributada no Município 2 Tributado fora do Município 3 Isento 4 Imune 5 Suspenso por Decisão Judicial 6 Suspenso por Procedimento Admin. 51 Exportação de Serviços
id_municipio	inteiro	município de prestação dos serviços da NF, código no IBGE. Veja Municípios
id_municipio_emissao	inteiro	município de emissão da NF, código no IBGE. Veja Municípios

Os campos necessários para emissão de NF variam conforme municípios. Alguns munícipios, por exemplo, requerem o valor da alíquota de ISS informada e outros não.

Estrutura dos Dados das Parcelas

Campo	Tipo	Descrição
id	inteiro	chave primária do registro, auto incrementada automaticamente
id_venda	inteiro	Id da Venda
parcela	inteiro	número de sequência da parcela na venda começando em 1
numero	texto	número da parcela gerado automaticamente pelo sistema
data_vencimento	data	data de vencimento da parcela
data_credito	data	data estimada de crédito de acordo com o meio de pagamento e informações recebidas na conciliação
data_vencimento_original	data	data original antes da atualização da parcela
valor	monetário	valor efetivo da cobrança
valor_original	monetário	valor original antes da atualização da parcela
valor_recebido	monetário	valor efetivamente recebimento na conciliação bancária ou preenchido manualmente pelo usuário
valor_tarifas	monetário	total de tarifas cobradas no meio de pagamento
status	inteiro	1 Pendente 2 Quitado 3 Recebimento Parcial 4 Cancelado 5 Vencido
data_recebimento	data e hora	Data do recebimento realizado
data_repasse¹	data	Data de repasse realizado para meios de pagamento com Repasse através de terceiros
pdf_url	texto	URL para download do PDF para boletos emitidos
linha_digitavel	texto	linha digitável para boletos emitidos
pix_imagem_url	texto	URL para download da imagem com QR Code PIX
pix_codigo	texto	código "Copia e Cola" para PIX

¹ Campos preenchidos automaticamente pelo sistema para somente leitura nas respostas.

Estrutura dos Dados dos Itens das Venda (Serviços)

Campo	Tipo	Descrição
id	inteiro	chave primária do registro, auto incrementada automaticamente
id_venda	inteiro	Id da Venda
recorrente	inteiro	Determinar se recorrente ou não. Se não for recorrente não será incluído na próxima ocorrência do Contrato
id_servico	inteiro	Id do Serviço nesse item
servico	texto	Nome de exibição do Serviço da venda
valor	monetário
qtd	monetário/decimal	Quantidade cobrada do Serviço
total	montário	Calculado com Valor * Qtd

Listar Vendas

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/vendas/?id=39&id=40"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/vendas/?id=39&id=40',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/vendas/?id=39&id=40', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 3,
        "sort": null,
        "requestId": "f42a5bfea3d478e9abc88aefae2dfec252879117"
    },
    "data": [
        { VENDA 1 },
        { VENDA 2 }
    ]
}

GET https://suaempresa.tenex.com.br/api/v2/vendas/

Inserir Venda

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"agendamento":1,"agendamento_data":"2021-06-20","agendamento_frequencia":1,"agendamento_repetir":1,"agendamento_automatico":1,"discriminacao":"Teste da Tenex","id_cliente":2,"id_meio_pagamento":7,"metodo_cobranca":2,"email_enviar":1,"valor_venda":149.99,"nfse_dados":{"rps_tipo":1,"rps_serie":"FSIMP"},"itens":[{"recorrente":1,"id_servico":2,"valor":200,"qtd":1,"total":200}],"parcelas":[{"data_vencimento":"2021-06-30","valor":79.99},{"data_vencimento":"2021-07-30","valor":80}]}' \
    "https://suaempresa.tenex.com.br/api/v2/vendas/"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.tenex.com.br/api/v2/vendas/',
    [
        'auth' => [$apiKey, ''],
        'json' => [
            "agendamento" => 1,
            "agendamento_data" => "2021-06-20",
            "agendamento_frequencia" => 1, // frequencia mensagel
            "agendamento_repetir" => 1, // repetir sempre
            'agendamento_automatico' => 1, // realizar geração automaticamente
            "discriminacao" => "Teste da Tenex",
            "id_cliente" => 2,
            "id_meio_pagamento" => 7,
            "metodo_cobranca" => 2, // aguardar pagamento para emitir FS
            "email_enviar" => 1,
            "valor_venda" => 149.99,
            "nfse_dados" => [
                "rps_tipo" => 1,
                "rps_serie" => "FSIMP",
            ],
            "itens" => [
                [
                    "recorrente" => 1,
                    "id_servico" => 2,
                    "valor" => 200,
                    "qtd" => 1,
                    "total" => 200,
                ]
            ],
            "parcelas" => [
                [
                    "data_vencimento" => "2021-06-30",
                    "valor" => 79.99,
                ],
                [
                    "data_vencimento" => "2021-07-30",
                    "valor" => 80,
                ]
            ]
        ]
    ]
);

echo $res->getBody();

import requests
import json

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.post(
    'https://suaempresa.tenex.com.br/api/v2/vendas/',
    auth = (apiKey, ''),
    data = json.dumps(
        {
            "agendamento": 1,
            "agendamento_data": "2021-06-20",
            "agendamento_frequencia": 1,
            "agendamento_repetir": 1,
            "agendamento_automatico": 1,
            "discriminacao": "Teste da Tenex",
            "id_cliente": 2,
            "id_meio_pagamento": 7,
            "metodo_cobranca": 2,
            "email_enviar": 1,
            "valor_venda": 149.99,
            "nfse_dados": {
            "rps_tipo": 1,
            "rps_serie": "FSIMP"
            },
            "itens": [
            {
              "recorrente": 1,
              "id_servico": 2,
              "valor": 200,
              "qtd": 1,
              "total": 200
            }
            ],
            "parcelas": [
            {
              "data_vencimento": "2021-06-30",
              "valor": 79.99
            },
            {
              "data_vencimento": "2021-07-30",
              "valor": 80
            }
            ]
        }
)
)

print(res.text)

POST https://suaempresa.tenex.com.br/api/v2/vendas/

Atualizar Venda

A atualização da venda requer o envio de um JSON equivalente ao recebido na resposta da requisição de Selecionar Venda.

POST https://suaempresa.tenex.com.br/api/v2/vendas/{ID}

Selecionar Venda

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/vendas/39"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/vendas/39',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/vendas/39', auth=(apiKey, '')
)

print(res.text)

GET https://suaempresa.tenex.com.br/api/v2/vendas/{ID}

Excluir Venda

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    -X DELETE \
    "https://suaempresa.tenex.com.br/api/v2/vendas/39"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'DELETE',
    'https://suaempresa.tenex.com.br/api/v2/vendas/39',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.delete(
    'https://suaempresa.tenex.com.br/api/v2/vendas/39', auth=(apiKey, '')
)

print(res.text)

DELETE https://suaempresa.tenex.com.br/api/v2/vendas/{ID}

{
    "id": "39"
}

Cancelar Nota Fiscal

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"cancelamento_codigo":1}' \
    "https://suaempresa.tenex.com.br/api/v2/vendas/42/nfse-cancelar"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.tenex.com.br/api/v2/vendas/42/nfse-cancelar',
    [
        'auth' => [$apiKey, ''],
        'json' => [
            'cancelamento_codigo' => 1,
        ]
    ]
);

echo $res->getBody();

import requests
import json

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.put(
    'https://suaempresa.tenex.com.br/api/v2/vendas/42/nfse-cancelar',
    auth = (apiKey, ''),
    data = json.dumps({"cancelamento_codigo":1})
)

print(res.text)

POST https://suaempresa.tenex.com.br/api/v2/vendas/{ID}/nfse-cancelar

Objeto da Requisição

Campo	Tipo	Descrição
cancelamento_codigo*	inteiro	código de cancelamento: 1 Erro de Emissão 2 Serviço não Prestado 3 Duplicidade: 4 Outros
cancelamento_motivo*	texto	descrição textual do motivo do cancelamento. Deve conter pelo menos 15 caracteres.

Campos marcados com * são obrigatórios.

Confirmar Recebimento

Faz a confirmação de recebimento de uma venda.

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"data_recebimento":"2020-06-22"}' \
    "https://suaempresa.tenex.com.br/api/v2/vendas/42/recebimento-confirmar"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.tenex.com.br/api/v2/vendas/42/recebimento-confirmar',
    [
        'auth' => [$apiKey, ''],
        'json' => [
            'data_recebimento' => '2020-06-22',
        ]
    ]
);

echo $res->getBody();

import requests
import json

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.put(
    'https://suaempresa.tenex.com.br/api/v2/vendas/42/recebimento-confirmar',
    auth = (apiKey, ''),
    data = json.dumps({"data_recebimento":"2020-06-22"})
)

print(res.text)

POST https://suaempresa.tenex.com.br/api/v2/vendas/{ID}/recebimento-confirmar

Objeto da Requisição

Campo	Tipo	Descrição
data_recebimento*	data	data de recebimento
id_parcela	data	obrigatório só se a venda tiver mais de uma parcela.
valor_recebido	monetário	será considerado o Valor da Parcela caso não informado
obs	text	observações a serem registradas no histórico da parcela

Campos marcados com * são obrigatórios.

Atualizar Boleto

Faz a atualização de um boleto modificando data de vencimento e valor.

Todos os valores e informações devem ser definidos na chamada realizada. Não há cálculo automático de multa e juros.

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"id_parcela":42,"valor_novo":105.22,"data_vencimento_novo":"2020-06-30"}' \
    "https://suaempresa.tenex.com.br/api/v2/vendas/42/boleto-atualizar"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.tenex.com.br/api/v2/vendas/42/boleto-atualizar',
    [
        'auth' => [$apiKey, ''],
        'json' => [
            'id_parcela' => 42,
            'valor_novo' => 105.22,
            'data_vencimento_novo' => '2020-06-30',
        ]
    ]
);

echo $res->getBody();

import requests
import json

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.put(
    'https://suaempresa.tenex.com.br/api/v2/vendas/42/boleto-atualizar',
    auth = (apiKey, ''),
    data = json.dumps({"id_parcela":42,"valor_novo":105.22,"data_vencimento_novo":"2020-06-30"})
)

print(res.text)

POST https://suaempresa.tenex.com.br/api/v2/vendas/{ID}/boleto-atualizar

Objeto da Requisição

Campo	Tipo	Descrição
id_parcela*	ingteiro	Id da parcela sendo atualizada
data_vencimento_novo*	data	nova data de vencimento
valor_novo*	monetário	novo valor
multa	percentual	percentual da multa
multa_total	monetário	valor total da multa aplicada
juros_mensal	percentual	percentual dos juros mensais
juros_mensal_total	monetário	valor total do juros aplicado

Campos marcados com * são obrigatórios.

Carteira Virtual

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/carteira-virtual/11122233344"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/carteira-virtual/11122233344',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/carteira-virtual/11122233344', auth=(apiKey, '')
)

print(res.text)

[
  {
    "nome": "Nome do Cliente da Silva",
    "titular": null,
    "cpf": "111.222.444-55",
    "cnpj": null,
    "carteira_virtual_status": true,
    "planos_contratados": [
      {
        "id": 20,
        "id_plano": null,
        "id_cliente": 2,
        "data_inicio_vigente": "2024-08-27",
        "data_fim_vigente": "2024-10-01",
        "carteira_virtual_data_liberacao": null,
        "carteira_virtual_status": true
      },
      {
        "id": 26,
        "id_plano": 1,
        "id_cliente": 2,
        "data_inicio_vigente": "2024-08-27",
        "data_fim_vigente": "2024-10-01",
        "carteira_virtual_data_liberacao": null,
        "carteira_virtual_status": true
      }
    ]
  },
  {
    "nome": "Filho do Cliente da Silva",
    "titular": "Nome do Cliente da Silva",
    "cpf": "555.666.777-88",
    "cnpj": null,
    "carteira_virtual_status": true,
    "planos_contratados": [
      {
        "id": 20,
        "id_plano": null,
        "id_cliente": 2,
        "data_inicio_vigente": "2024-08-27",
        "data_fim_vigente": "2024-10-01",
        "carteira_virtual_data_liberacao": null,
        "carteira_virtual_status": true
      },
      {
        "id": 26,
        "id_plano": 1,
        "id_cliente": 2,
        "data_inicio_vigente": "2024-08-27",
        "data_fim_vigente": "2024-10-01",
        "carteira_virtual_data_liberacao": null,
        "carteira_virtual_status": true
      }
    ]
  }
]

Permite executar a busca de carteira virtual de um cliente e seus dependentes.

Estrutura de Consulta da Carteira Virtual

Campo	Tipo	Descrição
nome	texto	Nome do cliente ou dependente.
titular	texto	Nome do titular da carteira virtual (se aplicável).
cpf	texto	CPF do cliente ou dependente.
cnpj	texto	CNPJ do cliente ou dependente (se aplicável).
carteira_virtual_status	booleano	Status da carteira virtual: true para ativo, false para inativo.
planos_contratados	array	Lista de planos contratados pelo cliente ou dependente, contendo os campos abaixo relacionados a cada plano.
id	inteiro	Identificador único do plano contratado.
id_plano	inteiro	Identificador do plano associado (se aplicável).
id_cliente	inteiro	Identificador do cliente.
data_inicio_vigente	data	Data de início da vigência do plano.
data_fim_vigente	data	Data de término da vigência do plano.
carteira_virtual_data_liberacao	data	Data de liberação da carteira virtual (se aplicável).
carteira_virtual_status (plano)	booleano	Status da carteira virtual para o plano: true para ativo, false para inativo.

CNAE

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/cnae/?_limit=1"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/cnae/?_limit=1',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/cnae/?_limit=1', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 1,
        "count": 534,
        "sort": null,
        "requestId": "40e479833661a07cd78fde25da56f98736edf003"
    },
    "data": [
        {
            "id": 161001,
            "nome": "Servi\u00e7o de pulveriza\u00e7\u00e3o e controle de pragas agr\u00edcolas"
        }
    ]
}

Lista de códigos de CNAE para serem utilizados no cadastro de serviços.

Essa estrutura está disponível somente para consulta.

Campo	Tipo	Descrição
id	inteiro	Chave primária do registro
nome	texto	Nome de exibição

GET https://suaempresa.tenex.com.br/api/v2/cnae/

Item da Lista de Serviços

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/lista-servicos/?_limit=1"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/lista-servicos/?_limit=1',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/lista-servicos/?_limit=1', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 1,
        "count": 194,
        "sort": null,
        "requestId": "5568296bb4997f8186fe3c5e80994a470e4e1d02"
    },
    "data": [
        {
            "id": 101,
            "nome": "An\u00e1lise e desenvolvimento de sistemas."
        }
    ]
}

Item da lista de serviço baseado na lista da Lei Complementar 116, de 21 de Julho de 2003 para serem utilizados no cadastro de Serviços.

Essa estrutura está disponível somente para consulta.

Campo	Tipo	Descrição
id	inteiro	Chave primária do registro
nome	texto	Nome de exibição

GET https://suaempresa.tenex.com.br/api/v2/lista-servicos/

Municípios

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/municipios/?nome\[contains\]=recife"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/municipios/?nome[contains]=recife',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/municipios/?nome[contains]=recife', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 1,
        "sort": null,
        "requestId": "8d60ad0ff3dc3601972a5e5fb789324290f47b4d"
    },
    "data": [
        {
            "id": 2611606,
            "nome": "Recife (PE)",
            "uf": 26
        }
    ]
}

Municípios do Brasil com seu código do IBGE.

Essa estrutura está disponível somente para consulta.

Campo	Tipo	Descrição
id	inteiro	Código do município no IBGE
nome	texto	Nome de exibição
uf	inteiro	Código de Unidade Federativa no IBGE (primeiros dois dígitos do código do município): 12 AC 27 AL 13 AM 16 AP 29 BA 23 CE 53 DF 32 ES 52 GO 21 MA 31 MG 50 MS 51 MT 15 PA 25 PB 26 PE 22 PI 41 PR 33 RJ 24 RN 11 RO 14 RR 43 RS 42 SC 28 SE 35 SP 17 TO

GET https://suaempresa.tenex.com.br/api/v2/municipios/

Índices de Reajustes

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.tenex.com.br/api/v2/indices/"

<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://suaempresa.tenex.com.br/api/v2/indices/',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();

import requests

apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
res = requests.get(
    'https://suaempresa.tenex.com.br/api/v2/indices/', auth=(apiKey, '')
)

print(res.text)

{
    "header": {
        "offset": 0,
        "limit": 100,
        "count": 2753,
        "sort": null,
        "requestId": "c76421d22102780b4b8b6598c058ffd50259e1c9"
    },
    "data": [
        {
            "codigo": 188,
            "sigla": "INPC",
            "nome": "\u00cdndice nacional de pre\u00e7os ao consumidor",
            "mes": "1979-04",
            "valor": 3.45
        },
    ...
}

Retorna todos os dados de Índices de reajuste utilizados no cálculo do Reajuste Automático.

Filtros, paginação e ordenação não são suportados.

Essa estrutura está disponível somente para consulta.

Webhooks

A funcionalidade de Webhooks permite que se registre servidores que receberão requisições sempre que um registro for Inserido, Alterado ou Excluído na Tenex.

O principal caso de aplicação dos Webhooks são em sistemas que necessitem de notificações.

E possível, por exemplo, sempre que uma venda for Alterada (e.g. recebimento realizado) o disparo seja feito e não haja necessidade de consultar diariamente a situação de Recebimento das Parcelas da Venda.

Objeto de Webhook

{
  "header": {
    "api": "v2",
    "endpoint": "clientes",
    "operation": "update",
    "timestamp": 1662552264,
    "signature": [
      "0c18c3fd3828985e4b9ac8893f0e7e85c705fcd9781ca6547f8bb6b16bf13775"
    ]
  },
  "data": {
    "id": 633,
    "codigo": 429445822,
    "data_cadastro": "2022-02-24T13:04:37+00:00",
    "status": 1,
    "tipo": 2,
    "cnpj": null,
    "nome": "Alana",
    "razao_social": "Alana",
    "inscricao_estadual": null,
    "inscricao_municipal": null,
    "cpf": "521.350.209-15",
    "data_nascimento": null,
    "identidade": null,
    "genero": null,
    "obs": null,
    "cep": "58.052-750",
    "id_cidade": 2507507,
    "estado": 25,
    "endereco": "Rua Exemplo",
    "numero": "123",
    "complemento": null,
    "bairro": "Jardim Cidade Universitária",
    "cidade": "João Pessoa (PB)"
  }
}

Cabeçalho (header)

Contém metadados relacioanados à chamada feita.

Campo	Tipo	Descrição
api	string	versão da API sendo utilizada (determina o formato dos objetos recebidos)
endpoint	string	estrutura (e.g. clientes ou vendas) recebido
operation	string	operação que aconteceu (insert, update ou delete)
timestamp	int	timestamp unix de geração
signature	string[]	lista de assinaturas do conteúdo (ver Assinatura)

Dados (data)

Um objeto no mesmo formato do estrutura correspondente em GET <api>/endpoint/<ID> é disponibilizado. Ver Objeto da Venda e Objeto do Cliente.

Utilização

Para registrar as URL que receberão as chamadas HTTP acesse

https://suaempresa.tenex.com.br/api-webhook/

Nessa tela várias URL podem ser registradas para cada Estrutura e Método.

Webhook 1

Validação de Assinatura de Webhook

O campo signature contém a asinatura dos conteúdo da requisição utilizando o método HMAC com algoritmo SHA256.

Para validar a assinatura a entrada signature precisa ser removida e um novo hash gerado com o JSON sem formatação.

A Chave Secreta utilizada para assinar as requisições pode ser obtida em https://suaempresa.tenex.com.br/api-webhook/.

cat response.json \
    | jq 'del(.header.signature)' -rc \
    | hmac256 1313249bc0f6ed48e6e8ea2bade9efab17e2dcb33440257752675bcc69ef3db0

<?php

$secretKey = "1313249bc0f6ed48e6e8ea2bade9efab17e2dcb33440257752675bcc69ef3db0";
$request = json_decode("{...}", true);
$signature = $request["header"]["signature"];
unset($request["header"]["signature"]);

$signatureCheck = hash_hmac("sha256", json_encode($request), $secretKey);

var_dump($signature);
var_dump($signatureCheck);
var_dump($signature[0] === $signatureCheck);

import hashlib
import hmac
import json

payload = json.loads('{...}')

signature = payload["header"].pop("signature")

secret = '1313249bc0f6ed48e6e8ea2bade9efab17e2dcb33440257752675bcc69ef3db0'
signatureCheck = hmac.new(bytes(secret, 'utf-8'), bytes(json.dumps(payload), 'utf-8'), hashlib.sha256).hexdigest()

print(signature)
print(signatureCheck)
print(signature[0] == signatureCheck)