NAV Navbar
shell php python

Introdução

A API da Fatura Simples é 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 Fatura Simples. 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:

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

Um exemplo de chamada autenticada:

Onde 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo (sem o ':') é chave de api gerada pelo sistema.

curl "https://suaempresa.faturasimples.com.br/api/v2/servicos/" \
    -u "4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo:"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

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

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

https://suaempresa.faturasimples.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 Fatura Simples 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

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

Exemplo de 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 Fatura Simples, 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

Exemplo de 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.

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

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

Um exemplo de erro numa requisição:

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

A Fatura Simples 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.faturasimples.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.faturasimples.com.br/api/v2/servicos/?_fields=id,nome',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.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.faturasimples.com.br/api/v2/servicos/?_offset=1&_limit=2',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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 Fatura Simples 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.faturasimples.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.faturasimples.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.faturasimples.com.br/api/v2/servicos/?_sort=-valor&_fields=id,nome,valor', auth=(apiKey, '')
)

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.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.faturasimples.com.br/api/v2/municipios/?nome[contains]=recife',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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

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.faturasimples.com.br/api/v2/clientes/?_fields=id,cpf,nome&contato.nome[contains]=fulano

Múltiplas condições

  1. Vários filtros podem ser usados em conjunto para criar uma consulta com múltiplas condições.

  2. Filtros repetidos para o mesmo campo e operador serão considerados como uma operação OU. Exemplo:

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

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

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

GET https://suaempresa.faturasimples.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.faturasimples.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.faturasimples.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.faturasimples.com.br/api/v2/clientes/?_fields=id,nome&cpf=070.613.880-56&_expand=contatos', auth=(apiKey, '')
)

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/servicos/"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

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

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

Inserir Serviço

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"nome":"Serviço de Teste"}' \
    "https://suaempresa.faturasimples.com.br/api/v2/servicos/"
<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.faturasimples.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.faturasimples.com.br/api/v2/servicos/',
    auth = (apiKey, ''),
    data = json.dumps({"nome":"Serviço de Teste"})
)

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/servicos/

Atualizar Serviço

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"nome":"Serviço de Teste - Atualizado"}' \
     -X PUT \
    "https://suaempresa.faturasimples.com.br/api/v2/servicos/4"
<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'PUT',
    'https://suaempresa.faturasimples.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.faturasimples.com.br/api/v2/servicos/4',
    auth = (apiKey, ''),
    data = json.dumps({"nome":"Serviço de Teste - Atualizado"})
)

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/servicos/{ID}

Selecionar Serviço

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.faturasimples.com.br/api/v2/servicos/4"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

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

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/servicos/4"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

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

O comando acima retornará uma estrutura no seguinte formato:

{
    "id": "4"
}

Meios de Pagamento

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.faturasimples.com.br/api/v2/meios-pagamento/"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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 Fatura Simples.

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
multa percentual Valor percentual da multa por atraso de pagamento
juros percentual Valor percentual dos juros mensais por atraso de pagamento

GET https://suaempresa.faturasimples.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.faturasimples.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.faturasimples.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.faturasimples.com.br/api/v2/clientes/?id=2&id=3&_expand=contatos,cartoes', auth=(apiKey, '')
)

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

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

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

Inserir Cliente

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"tipo":1,"nome":"Cliente de Teste"}' \
    "https://suaempresa.faturasimples.com.br/api/v2/clientes/"
<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.faturasimples.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.faturasimples.com.br/api/v2/clientes/',
    auth = (apiKey, ''),
    data = json.dumps({"tipo":1,"nome":"Cliente de Teste"})
)

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/clientes/

Atualizar Cliente

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"tipo":1,"nome":"Cliente de Teste Alterado"}' \
     -X PUT \
    "https://suaempresa.faturasimples.com.br/api/v2/clientes/7"
<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'PUT',
    'https://suaempresa.faturasimples.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.faturasimples.com.br/api/v2/clientes/7',
    auth = (apiKey, ''),
    data = json.dumps({"tipo":1,"nome":"Cliente de Teste - Alterado"})
)

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/clientes/{ID}

Selecionar Cliente

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.faturasimples.com.br/api/v2/clientes/2"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

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

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/clientes/7"

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

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

echo $res->getBody();
import requests

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

print(res.text)

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

O comando acima retornará uma estrutura no seguinte formato:

{
    "id": "7"
}

Vendas

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
        }
    ],
    "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
data1 data data de registro da venda
agendamento inteiro se é ou foi uma venda agendada
1 Sim
0 Não
agendamento_data1 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_data2 data e hora data de última modificação do agendamento_ativo
agendamento_ultima_ocorrencia2 inteiro 1 Sim - essa venda é a última de uma sequência de agendamento
agendamento_data_geracao2 data data de geração de uma venda Cadastrada originária de uma Agendada
agendamento_sequencia2 inteiro ordem de geração de uma venda Cadastrada originária de uma Agendada
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_enviado2 data e hora informação de envio de email de cobrança para essa venda
email_erro2 data e hora informação de erro de envio de email, caso haja
email_entrega2 data e hora informação de entrega de email, caso haja
email_leitura2 data e hora informação de leitura de email, caso haja
sms_enviar inteiro 1 Sim
2 Não
sms_enviado2 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_status2 inteiro 1 Pendente
2 Quitado
3 Recebimento Parcial
4 Cancelado
5 Vencido
pagamento_online_codigo2 texto 1 Emitida
2 Cancelada
3 Pendente
4 Erro
nfse_status2 inteiro 1 Emitida
2 Cancelada
3 Pendente
4 Erro

Observações

1 Uma Venda é considerada Cadastrada se data está preenchida, caso contrário agendamento_data deve estar preenchido e ela será uma Venda Agendada/Recorrente

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

Estrutura dos Dados de Agendamento

Essa estrutura é opcional e determinar 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_repasse1 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

1 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 da Venda Agendada / Recorrente
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.faturasimples.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.faturasimples.com.br/api/v2/vendas/?id=39&id=40',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

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

GET https://suaempresa.faturasimples.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 Fatura Simples","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.faturasimples.com.br/api/v2/vendas/"
<?php
require 'vendor/autoload.php';

$apiKey = '4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo';
$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://suaempresa.faturasimples.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 Fatura Simples",
            "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.faturasimples.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 Fatura Simples",
            "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)

Uma estrutura no formato descrito no Objeto da Venda será retornada.

POST https://suaempresa.faturasimples.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.

Uma estrutura no formato descrito no Objeto da Venda será retornada.

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

Selecionar Venda

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.faturasimples.com.br/api/v2/vendas/39"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

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

Uma estrutura no formato descrito no Objeto da Venda será retornada.

Excluir Venda

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    -X DELETE \
    "https://suaempresa.faturasimples.com.br/api/v2/vendas/39"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

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

O comando acima retornará uma estrutura no seguinte formato:

{
    "id": "39"
}

Cancelar Nota Fiscal

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
     -d '{"cancelamento_codigo":1}' \
    "https://suaempresa.faturasimples.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.faturasimples.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.faturasimples.com.br/api/v2/vendas/42/nfse-cancelar',
    auth = (apiKey, ''),
    data = json.dumps({"cancelamento_codigo":1})
)

print(res.text)

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

Uma estrutura no formato descrito no Objeto da Venda será retornada.

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.faturasimples.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.faturasimples.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.faturasimples.com.br/api/v2/vendas/42/recebimento-confirmar',
    auth = (apiKey, ''),
    data = json.dumps({"data_recebimento":"2020-06-22"})
)

print(res.text)

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

Uma estrutura no formato descrito no Objeto da Venda será retornada.

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.faturasimples.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.faturasimples.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.faturasimples.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.faturasimples.com.br/api/v2/vendas/{ID}/boleto-atualizar

Uma estrutura no formato descrito no Objeto da Venda será retornada.

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.

CNAE

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.faturasimples.com.br/api/v2/cnae/?_limit=1"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/cnae/

Item da Lista de Serviços

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.faturasimples.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.faturasimples.com.br/api/v2/lista-servicos/?_limit=1',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/lista-servicos/

Municípios

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.faturasimples.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.faturasimples.com.br/api/v2/municipios/?nome[contains]=recife',
    ['auth' => [$apiKey, '']]
);

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.faturasimples.com.br/api/v2/municipios/

Índices de Reajustes

curl -u 4vOqPRfmno5vjHo962ThrdxX8Sv7GnqlilVwOVBvVfo: \
    "https://suaempresa.faturasimples.com.br/api/v2/indices/"
<?php
require 'vendor/autoload.php';

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

echo $res->getBody();
import requests

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

print(res.text)

O comando acima retornará uma estrutura no seguinte formato:

{
    "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.