NAV
shell php

Introdução

A API do 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.

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

Bindings:
- PHP

Autenticação

Um exemplo de chamada autenticada:

curl "https://suaempresa.faturasimples.com.br/api/..." \
    -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");

Onde 2y6v8qnX3SUHZb0sanKWrQUnTAY (sem o ‘:’) é chave de api gerada pelo sistema.

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

Para gerar sua chave de API 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.

Erros

Um exemplo de erro numa requisição:

{
  "tipo":"requisicao_invalida",
  "mensagem":"Chave de API inválida: 2y6v8qnX3S..."
}

O Fatura Simples usa códigos de resposta HTTP para indicar o sucesso ou falha de uma requisição.

De forma geral códigos na faixa de 2xx representam o sucesso da requisição. Códigos na faixa dos 4xx representam um erro nos parâmetros informados e códigos na faixa de 5xx indicam um erro no nosso servidor.

Adicionalmente, retornamos um objeto JSON no seguinte formato:

{ "tipo": "...", "mensagem": "..." }

Onde:

tipo: requisicao_invalida ou api_erro

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

Códigos HTTP utilizados

Código Descrição
200 Ok – Tudo ocorreu dentro do esperado
400 Bad Request – Algum parâmetro da requisição é inválido
401 Unauthorized – Chave de API inválida
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 – Estamos temporiariamente offline para manutenção.

Paginação

curl "https://suaempresa.faturasimples.com.br/api/servico?inicio=1&limite=2" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"

<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$servicos = FaturaSimples_Servico::listar(0, 2);

O comando acima retornará uma estrutura no seguinte formato:

{
  "inicio":"1",
  "limite":"2",
  "data":[
    {
      "id":"116",
      "nome":"Desenvolvimento de Sistemas",
      "discriminacao":"",
      "valor":"",
      "impostos_percentual":"",
      "servico":{
        "id":"101",
        "nome":"An\u00e1lise e desenvolvimento de sistemas."
      },
      "atividade":{
        "id":"6201500",
        "nome":"Desenvolvimento de programas de computador sob encomenda"
      }
    },
    {
      "id":"110",
      "nome":"Desenvolvimento de Sistemas",
      "discriminacao":"",
      "valor":"",
      "impostos_percentual":"",
      "servico":{
        "id":"101",
        "nome":"An\u00e1lise e desenvolvimento de sistemas."
      },
      "atividade":{
        "id":"6201500",
        "nome":"Desenvolvimento de programas de computador sob encomenda"
      }
    }
  ]
}

Todas as entidadas registradas na instalação do 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 10 registros.

Parâmetros da requisição

Parâmetro Valor Padrão Descrição
inicio 0 A partir de qual registro os dados serão retornados
limite 10 Número de registros a retornar. Valores possíveis de 1 a 100
ordenarColuna null Qual será o campo usado na ordenação
ordenarDirecao ASC Sentido da ordenação. Valores possíveis ASC ou DESC

Versionamento

Um exemplo de chamada com versão definida:

curl "https://suaempresa.faturasimples.com.br/api/..." \
    -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:" \
    -H "FaturaSimples-Versao: 2014-09-17"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY", "2014-09-17");

A versão na API é definida através de um Header HTTP personalizado no seguinte formato:

FaturaSimples-Versao: YYYY-MM-DD

Quando fazemos mudanças que são retroativamente incompatíveis, lançamos novas versões. A versão atual é 2014-09-17.

Sua versão é definida na primeira vez que você faz uma requisição e por isso esse parâmetro é opcional em todas as requisições.

Início Rápido

Lembre-se de substituir a sua Chave de API no lugar de 2y6v8qnX3SUHZb0sanKWrQUnTAY

curl "https://suaempresa.faturasimples.com.br/api/venda" \
    -d "data=2014-09-10" \
    -d "cliente=ERAMO SOFTWARE" \
    -d "cliente_cnpj=17737572000150" \
    -d "servico=Desenvolvimento de Sistemas" \
    -d "discriminacao=Desenvolvimento%0aNo período de 01/09/2014 a 30/09/2015" \
    -d "valor_venda=500" \
    -d "emissao_nfse=Emitir NFS-e agora" \
    -d "meio_pagamento=Espécie" \
    -d "nfse_municipio_emissao=2611606" \
    -d "nfse_item_servico=103" \
    -d "nfse_codigo_tributacao_municipio=6311900" \
    -d "nfse_inscricao_municipal=123456" \
    -d "nfse_optante_simples_nacional=1" \
    -d "nfse_incentivador_cultural=2" \
    -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php

FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");

$dados = array(
    "data" => "2014-09-10",
    "cliente" => "ERAMO SOFTWARE",
    "cliente_cnpj" => "17737572000150",
    "servico" => "Desenvolvimento de Sistemas",
    "discriminacao" => "Desenvolvimento\nNo período de 01/09/2014 a 30/09/2015",
    "valor_venda" => 2500,
    "emissao_nfse" => FaturaSimples_Venda::EMISSAO_NFSE_EMITIR_AGORA,
    "meio_pagamento" => "Depósito",
    "nfse_municipio_emissao" => 2611606,
    "nfse_item_servico" => 103,
    "nfse_codigo_tributacao_municipio" => 6311900,
    "nfse_inscricao_municipal" => 123456,
    "nfse_optante_simples_nacional" => FaturaSimples_Venda::SIM,
    "nfse_incentivador_cultural" => FaturaSimples_Venda::NAO
);
$venda = FaturaSimples_Venda::criar( $dados );

O comando acima criará uma nova venda e retornará uma estrutura no seguinte formato:

{
  "id":"47154",
  "agendamento":"",
  "agendamento_data":"",
  "agendamento_frequencia":"",
  "agendamento_automatico":"1",
  "agendamento_repetir":"",
  "agendamento_data_fim":"",
  "agendamento_numero":"",
  "agendamento_data_geracao":"",
  "agendamento_ativo":"1",
  "data":"2014-09-10",
  "discriminacao":"Desenvolvimento do sistema Fatura Simples\nDurante o Per\u00edodo de 01\/09\/2014 a 30\/09\/2015",
  "desconto":"",
  "valor_venda":"435.22",
  "metodo_cobranca":"1",
  "email_enviar":"",
  "email_enviado":"",
  "email_erro":"",
  "parcelas":"1",
  "valor_recebido":"",
  "valor_parcelas":"123.45",
  "data_vencimento":"2015-06-10",
  "parcela_status":"5",
  "vencido_dias":"237",
  "nfse_status":"6",
  "id_servico":"17",
  "dados_extra":"{}",
  "servico":{
    "id":"80",
    "nome":"Desenvolvimento de Sistemas",
    "id_servico":"103",
    "id_atividade":"6311900",
    "discriminacao":"",
    "valor":"",
    "impostos_percentual":""
  },
  "meio_pagamento":{
    "id":"78",
    "nome":"Cart?o de Cr?dito",
    "tipo":"4",
    "parcelas":"1",
    "tempo_credito":"6",
    "prazo_pagamento":"",
    "banco":"",
    "carteira":"",
    "agencia":"",
    "conta":"",
    "conta_dv":"",
    "instrucoes1":"",
    "instrucoes2":"",
    "instrucoes3":"",
    "instrucoes4":"",
    "boleto_confirmacao":"",
    "especie":"",
    "aceite":"",
    "instrucao_1":"",
    "instrucao_2":"",
    "prazo":"",
    "agencia_dv":"",
    "convenio":""
  },
  "nfse":{
    "id":"46520",
    "numero":"5",
    "codigo_verificacao":"G0UJ-UXKUO",
    "data_emissao":"2014-09-11 17:15:47",
    "cancelamento_data":"",
    "cancelamento_codigo":"",
    "status":"1",
    "id_prestador":"1",
    "id_tomador":"376",
    "natureza_operacao":"1",
    "id_municipio":"2611606",
    "id_municipio_emissao":"2611606",
    "id_servico":"103",
    "id_atividade":"6311900",
    "discriminacao":"Desenvolvimento do sistema Fatura Simples\nDurante o Per?odo de 01\/09\/2014 a 30\/09\/2015",
    "impostos_federais":"2",
    "valor_pis":"",
    "valor_cofins":"",
    "valor_inss":"",
    "valor_ir":"",
    "valor_csll":"",
    "outras_retencoes":"",
    "iss_retido":"2",
    "valor_iss_retido":"",
    "aliquota":"0.02",
    "valor_servicos":"435.22",
    "desconto_condicionado":"",
    "desconto_incondicionado":"",
    "valor_deducoes":"",
    "valor_liquido_nfse":"435.22",
    "base_calculo":"435.22",
    "valor_iss":"",
    "rps_tipo":"1",
    "rps_serie":"FSIMP",
    "rps_numero":"5",
    "url_pdf":"https:\/\/fsimp.net\/exemplo\/nfse-U4bMcCaQT8ALufEnrJ5hA"
  },
  "cliente":{
    "id":"376",
    "tipo":"",
    "cnpj":"17737572000150",
    "nome":"ERAMO SOFTWARE",
    "razao_social":"ERAMO SOFTWARE LTDA - ME",
    "inscricao_estadual":"",
    "inscricao_municipal":"",
    "cpf":"",
    "data_nascimento":"",
    "cep":"52.061-030",
    "id_cidade":"2611606",
    "estado":"26",
    "endereco":"",
    "numero":"",
    "complemento":"",
    "bairro":"",
    "obs":""
  }
}

Para emitir notas fiscais em minutos:

  1. Cadastre-se em https://www.faturasimples.com.br/experimentar
  2. Acesse https://suaempresa.faturasimples.com.br//empresa/dados-gerais
    • Carregue o Certificado Digital A1. Você pode baixar aqui um certificado para testes.
    • Complete os dados da sua empresa (carregue o CNPJ e complete o endereço)
  3. Gere uma nova chave de api em https://suaempresa.faturasimples.com.br//api-chave/
  4. Usando nossos bindings ou cURL registre uma venda. Exemplo à direita. A NFS-e pode ser obtida acessando o link do PDF disponível em:

obj->nfse->url_pdf NFS-e de Exemplo

Veja mais detalhes em Inserir Vendas

Vendas

Estrutura Padrão

As vendas do sistema seguem o seguinte formato:

{
  "id":"47154",
  "agendamento":"",
  "agendamento_data":"",
  "agendamento_frequencia":"",
  "agendamento_automatico":"1",
  "agendamento_repetir":"",
  "agendamento_data_fim":"",
  "agendamento_numero":"",
  "agendamento_data_geracao":"",
  "agendamento_ativo":"1",
  "data":"2014-09-10",
  "discriminacao":"Desenvolvimento do sistema Fatura Simples\nDurante o Per\u00edodo de 01\/09\/2014 a 30\/09\/2015",
  "desconto":"",
  "valor_venda":"435.22",
  "metodo_cobranca":"1",
  "email_enviar":"",
  "email_enviado":"",
  "email_erro":"",
  "parcelas":"1",
  "valor_recebido":"",
  "valor_parcelas":"123.45",
  "data_vencimento":"2015-06-10",
  "parcela_status":"5",
  "vencido_dias":"237",
  "nfse_status":"6",
  "id_servico":"17",
  "dados_extra":"{}",
  "servico": { DADOS_DO_SERVICO },
  "meio_pagamento": { DADOS_DO_MEIO_DE_PAGAMENTO },
  "nfse": { DADOS_DA_NOTA_FISCAL },
  "cliente": { DADOS_DO_CLIENTE },
}

Uma venda no sistema pode conter um número grande de campos, para facilitar o entendimento abreviamos as saídas padrão das chamadas da API nessa seção.

Exemplo de estrutura completa:

{
  "id":"47154",
  "agendamento":"",
  "agendamento_data":"",
  "agendamento_frequencia":"",
  "agendamento_automatico":"1",
  "data":"2014-09-10",
  "discriminacao":"Desenvolvimento do sistema Fatura Simples\nDurante o Per\u00edodo de 01\/09\/2014 a 30\/09\/2015",
  "valor_venda":"435.22",
  "metodo_cobranca":"1",
  "email_enviar":"",
  "email_enviado":"",
  "parcelas":"",
  "servico":{
    "id":"80",
    "nome":"Desenvolvimento de Sistemas",
    "id_servico":"103",
    "id_atividade":"6311900",
    "discriminacao":"",
    "valor":"",
    "impostos_percentual":""
  },
  "meio_pagamento":{
    "id":"78",
    "nome":"Cart?o de Cr?dito",
    "tipo":"4",
    "parcelas":"1",
    "tempo_credito":"6",
    "prazo_pagamento":"",
    "banco":"",
    "carteira":"",
    "agencia":"",
    "conta":"",
    "conta_dv":"",
    "instrucoes1":"",
    "instrucoes2":"",
    "instrucoes3":"",
    "instrucoes4":"",
    "boleto_confirmacao":"",
    "especie":"",
    "aceite":"",
    "instrucao_1":"",
    "instrucao_2":"",
    "prazo":"",
    "agencia_dv":"",
    "convenio":""
  },
  "nfse":{
    "id":"46520",
    "numero":"5",
    "codigo_verificacao":"G0UJ-UXKUO",
    "data_emissao":"2014-09-11 17:15:47",
    "cancelamento_data":"",
    "cancelamento_codigo":"",
    "status":"1",
    "id_prestador":"1",
    "id_tomador":"376",
    "natureza_operacao":"1",
    "id_municipio":"2611606",
    "id_municipio_emissao":"2611606",
    "id_servico":"103",
    "id_atividade":"6311900",
    "discriminacao":"Desenvolvimento do sistema Fatura Simples\nDurante o Per?odo de 01\/09\/2014 a 30\/09\/2015",
    "impostos_federais":"2",
    "valor_pis":"",
    "valor_cofins":"",
    "valor_inss":"",
    "valor_ir":"",
    "valor_csll":"",
    "outras_retencoes":"",
    "iss_retido":"2",
    "valor_iss_retido":"",
    "aliquota":"0.02",
    "valor_servicos":"435.22",
    "desconto_condicionado":"",
    "desconto_incondicionado":"",
    "valor_deducoes":"",
    "valor_liquido_nfse":"435.22",
    "base_calculo":"435.22",
    "valor_iss":"",
    "rps_tipo":"1",
    "rps_serie":"FSIMP",
    "rps_numero":"5",
    "url_pdf":"https:\/\/fsimp.net\/exemplo\/nfse-U4bMcCaQT8ALufEnrJ5hA"
  },
  "cliente":{
    "id":"376",
    "tipo":"",
    "cnpj":"17737572000150",
    "nome":"ERAMO SOFTWARE",
    "razao_social":"ERAMO SOFTWARE LTDA - ME",
    "inscricao_estadual":"",
    "inscricao_municipal":"",
    "cpf":"",
    "data_nascimento":"",
    "cep":"52.061-030",
    "id_cidade":"2611606",
    "estado":"26",
    "endereco":"",
    "numero":"",
    "complemento":"",
    "bairro":"",
    "obs":""
  },
  "boletos":[
    "https:\/\/fsimp.net\/exemplo\/boleto-3yukc0vj6liccok4skgsock8w"
  ]
}

Listar Vendas

curl "https://suaempresa.faturasimples.com.br/api/venda" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"

<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$venda = FaturaSimples_Venda::listar();

O comando acima retornará uma estrutura no seguinte formato:

{
  "inicio":"0",
  "limite":"10",
  "data":[
    ...Venda...,
    ...Venda_N...,
    ...
  ]
}

GET https://suaempresa.faturasimples.com.br/api/venda

Parâmetros da requisição

Parâmetro Valor Padrão Descrição
inicio 0 A partir de qual registro os dados serão retornados
limite 10 Número de registros a retornar. Valores possíveis de 1 a 100
ordenarColuna null Qual será o campo usado na ordenação
ordenarDirecao ASC Sentido da ordenação. Valores possíveis ASC ou DESC

Inserir

curl "https://suaempresa.faturasimples.com.br/api/venda" \
    -d "data=2014-09-10" \
    -d "cliente=ERAMO SOFTWARE" \
    -d "cliente_cnpj=17737572000150" \
    -d "servico=Desenvolvimento de Sistemas" \
    -d 'discriminacao=Desenvolvimento do sistema Fatura Simples%0ADurante o Período de 01/09/2014 a 30/09/2015' \
    -d "valor_venda=1313.22" \
    -d "emissao_nfse=Emitir NFS-e agora" \
    -d "meio_pagamento=Cartão de Crédito" \
    -d "nfse_municipio_emissao=2611606" \
    -d "nfse_item_servico=103" \
    -d "nfse_codigo_tributacao_municipio=6311900" \
    -d "nfse_inscricao_municipal=123456" \
    -d "nfse_optante_simples_nacional=1" \
    -d "nfse_incentivador_cultural=2" \
    -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php

FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");

$dados = array(
    "data" => "2014-09-10",
    "cliente" => "ERAMO SOFTWARE",
    "cliente_cnpj" => "17737572000150",
    "servico" => "Desenvolvimento de Sistema",
    "discriminacao" => "Desenvolvimento do sistema Fatura Simples%0ADurante o Período de 01/09/2014 a 30/09/2015",
    "valor_venda" => 1313.22,
    "emissao_nfse" => FaturaSimples_Venda::EMISSAO_NFSE_EMITIR_AGORA,
    "meio_pagamento" => "Depósito",
    "nfse_municipio_emissao" => 2611606,
    "nfse_item_servico" => 103,
    "nfse_codigo_tributacao_municipio" => 6311900,
    "nfse_inscricao_municipal" => 123456,
    "nfse_optante_simples_nacional" => FaturaSimples_Venda::SIM,
    "nfse_incentivador_cultural" => FaturaSimples_Venda::NAO
);
$venda = FaturaSimples_Venda::criar( $dados );

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"47206",
  "agendamento":"",
  "agendamento_data":"",
  "agendamento_frequencia":"",
  "agendamento_automatico":"0",
  "data":"2014-09-15",
  "discriminacao":"Discriminação da nota",
  "valor_venda":"2311.32",
  "metodo_cobranca":"3",
  "email_enviar":"",
  "email_enviado":"2014-09-15 10:39:14.906689",
  "parcelas":"1",
  "servico": { DADOS_DO_SERVICO },
  "meio_pagamento": { DADOS_DO_MEIO_DE_PAGAMENTO },
  "nfse": { DADOS_DA_NOTA_FISCAL },
  "cliente": { DADOS_DO_CLIENTE },
}

POST https://suaempresa.faturasimples.com.br/api/venda

Parâmetros da requisição

Parâmetro Descrição
data1 Data da Venda
agendamento_data1 Próxima Ocorrência do Agendamento
agendamento_repetir1 Define se é uma venda agendada ou recorrente (1 para Sim 0 para Não)
agendamento_frequencia1 Frequência em meses do agendamento, valores possíveis: 1,2,3,6,12
cliente* Código ou nome do cliente no sistema
cliente_cnpj CNPJ do cliente
cliente_cpf CPF do cliente
cliente_… Todos os campos do cadastro do cliente podem ser repassados nesse formato para criação do registro durante a inserção de nova venda
servico* Nome do serviço realizado
discriminacao Discriminação da venda. Obrigatório caso seja uma emissão de NFS-e
valor_venda* Valor da venda
emissao_nfse* Define se será feita a emissão de NFS-e. As três opções possíveis são: Emitir NFS-e agora:1, Emitir NFS-e quando a venda for quitada:2, Não emitir NFS-e por enquanto:3
meio_pagamento* Meio de Pagamento (um novo será criado caso não exista um com o mesmo nome)
email_enviar Define se será enviado ou agendado um email (qualquer valor diferente de 0 será considerado Sim)
email_modelo Nome do modelo de email a ser usado. Caso não seja informado será considerado o padrão para esse tipo de venda.
email Endereço do destinatário do email. Caso não seja informado o email do contato principal do cliente será utilizado.
valor_n 2 Valor da parcela n, por exemplo valor_1 para a parcela 1
data_vencimento_n 2 Data de vencimento da parcela n, por exemplo data_vencimento_1 para a parcela 1
nfse_municipio_emissao* Município da emissão (Código do IBGE)
nfse_item_servico* Item da lista de serviço baseado na lista da Lei Complementar 116, de 21 de Julho de 2003 considerando somente números. Ex: para 1.02 – Programação informe 102
nfse_codigo_tributacao_municipio* Informando somente números, ex: 6204-0/00 CONSULTORIA EM ANÁLISE DE SISTEMAS informe somente 6204000. Esse código depende da prefeitura onde a NFS-e será emitida.
nfse_inscricao_municipal* Inscrição municipal da empresa
nfse_optante_simples_nacional* Define se a empresa é optante do Simples Nacional. Sim:1, Não:2
nfse_incentivador_cultural* Define se a empresa é incentivador cultural. Sim:1, Não:2
cartao_bandeira 3 Escolhe a bandeira do cartão para pagamento online. Valores possíveis são: visa, mastercard, amex, elo e diners
cartao_numero 3 Número do cartão de crédito (somente números).
cartao_validade 3 Validade do cartão no formato AAAAMM. Ex: 202012 para Dezembro/2020
cartao_codigo 3 Código de segurança do cartão

Campos marcados com * são obrigatórios.

Obs:

Notas:

1 Os campos ‘data’ ou ‘agendamento_’ são obrigatórios quando o outro não for informado.

2 Os campos de formato valor_n e data_vencimento_n são utilizados somente em meios de pagamento do tipo Boleto. Caso esses valores não sejam informados, datas e valores serão automaticamente calculados com base nas informações do Meio de Pagamento.

3 Os campos do cartão de crédito só serão utilizados quando o Meio de Pagamento for com Pagamento Online. Ex: Cielo - Solução Webservice. Caso não sejam informados será enviado um email ao cliente com o modelo padrão Cobrança - Pagamento online com o link para que o cliente preencha os dados.

Atualizar

curl "https://suaempresa.faturasimples.com.br/api/venda/47206" \
    -d "meio_pagamento=Espécie" \
    -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php

FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");

$dados = array(
    "meio_pagamento" => "Espécie",
);
$venda = FaturaSimples_Venda::atualizar( 47206, $dados );

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"47206",
  "agendamento":"",
  "agendamento_data":"",
  "agendamento_frequencia":"",
  "agendamento_automatico":"0",
  "data":"2014-09-15",
  "discriminacao":"Discriminação da nota",
  "valor_venda":"2311.32",
  "metodo_cobranca":"3",
  "email_enviar":"",
  "email_enviado":"2014-09-15 10:39:14.906689",
  "parcelas":"1",
  "servico": { DADOS_DO_SERVICO },
  "meio_pagamento": { DADOS_DO_MEIO_DE_PAGAMENTO },
  "nfse": { DADOS_DA_NOTA_FISCAL },
  "cliente": { DADOS_DO_CLIENTE },
}

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

Parâmetros da requisição

Os mesmos parâmetros da Inserção se aplicam.

Atenção: Após a emissão da NFS-e, só será possível atualizar o campo Meio de Pagamento.

Selecionar

curl "https://suaempresa.faturasimples.com.br/api/venda/66" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$venda = FaturaSimples_Venda::selecionar( 47165 )

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

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"47165",
  "agendamento":"",
  "agendamento_data":"",
  "agendamento_frequencia":"",
  "agendamento_automatico":"0",
  "data":"2014-09-15",
  "discriminacao":"Discriminação da nota",
  "valor_venda":"2311.32",
  "metodo_cobranca":"3",
  "email_enviar":"",
  "email_enviado":"2014-09-15 10:39:14.906689",
  "parcelas":"1",
  "servico": { DADOS_DO_SERVICO },
  "meio_pagamento": { DADOS_DO_MEIO_DE_PAGAMENTO },
  "nfse": { DADOS_DA_NOTA_FISCAL },
  "cliente": { DADOS_DO_CLIENTE },
}

Parâmetros da requisição

Não há parâmetros

Excluir

curl -X DELETE "https://suaempresa.faturasimples.com.br/api/venda/47205" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$json = FaturaSimples_Venda::deletar( 66 )

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

O comando acima retornará uma estrutura no seguinte formato:

{
  "deleted":true,
  "id":"66"
}

Caso haja uma nota fiscal relacionada a essa venda o seguinte retorno será obtido:

{
  "tipo":"requisicao_invalida",
  "mensagem":"Não é possível excluir uma venda que tem uma NFS-e em situação Emitida. Primeiro faça o cancelamento da NFS-e, para só depois excluir a venda."
}

Veja como realizar uma chamada de cancelamento no tópico Cancelar NFS-e

Parâmetros da requisição

Não há parâmetros

Cancelar NFS-e

curl "https://suaempresa.faturasimples.com.br/api/venda/66/nfse-cancelar" \
     -d "cancelamento_codigo=4" \
     -d "cancelamento_motivo=Outros motivos não especificados" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
FaturaSimples_Venda::nfseCancelar( 66, FaturaSimples_Venda::NFSE_CANCELAR_OUTROS, "Outros motivos não especificados" );

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

O comando acima retornará uma estrutura no seguinte formato:

{
  "nfse-cancelar":true,
  "id":"66"
}

Parâmetros da requisição

Parâmetro Descrição
cancelamento_codigo* Código de cancelamento: Erro de Emissão:1, Serviço não Prestado:2, Duplicidade:3, Outros:4
cancelamento_motivo Motivo de cancelamento: Descrição do motivo do cancelamento. Deve conter pelo menos 15 caracteres. Obrigatório caso cancelamento_codigo = Outros:4

Campos marcados com * são obrigatórios.

Confirmar Recebimento

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

curl "https://suaempresa.faturasimples.com.br/api/venda/66/recebimento-confirmar" \
     -d "data_recebimento=2015-12-12" \
     -d "valor_recebido=123.45" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
FaturaSimples_Venda::recebimentoConfirmar( 66, '2015-12-12', 123.45 );

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

O comando acima retornará uma estrutura no seguinte formato:

{
  "recebimento-confirmar":true,
  "id":"50153"
}

Parâmetros da requisição

Parâmetro Descrição
data_recebimento* Data de recebimento no formato ISO8601, ex: 2015-12-15
valor_recebido Valor recebido, opcional. Será considerado o Valor da Venda caso não informado

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á qualquer cálculo de multa e juros implícito.

curl "https://suaempresa.faturasimples.com.br/api/venda/1010/boleto-atualizar" \
     -d "parcela=1" \
     -d "data_vencimento_novo=2015-12-12" \
     -d "valor_novo=123.45" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
FaturaSimples_Venda::boletoAtualizar( 1010, 1, '2015-12-12', 123.45 );

POST https://suaempresa.faturasimples.com.br/api/venda/{ID}/boleto-atualizar

O comando acima retornará uma estrutura no seguinte formato:

{
  "boleto-atualizar":true,
  "id":"1010"
}

Parâmetros da requisição

Parâmetro Descrição
parcela* Sequencial da parcela na venda: ex: 1, 2, 3
data_vencimento_novo* Nova data de vencimento no formato ISO8601, ex: 2015-12-15
valor_novo* Novo valor do boleto
multa Percentual da multa
multa_total Valor total da multa aplicada
juros_mensal Percentual dos juros mensais
juros_mensal_total Valor total do juros aplicado

Campos marcados com * são obrigatórios.

Serviços

Listar Serviços

curl "https://suaempresa.faturasimples.com.br/api/servico" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$servicos = FaturaSimples_Servico::listar();

O comando acima retornará uma estrutura no seguinte formato:

{
  "inicio":"0",
  "limite":"10",
  "data":[
    {
      "id":"106",
      "nome":"Consultoria em TI",
      "discriminacao":"",
      "valor":"",
      "impostos_percentual":"",
      "servico":{
        "id":"101",
        "nome":"An\u00e1lise e desenvolvimento de sistemas."
      },
      "atividade":{
        "id":"6201500",
        "nome":"Desenvolvimento de programas de computador sob encomenda"
      }
    },
    {
      "id":"78",
      "nome":"Desenvolvimento de Sistemas",
      "discriminacao":"",
      "valor":"",
      "impostos_percentual":"",
      "servico":{
        "id":"103",
        "nome":"Processamento de dados e cong\u00eaneres."
      },
      "atividade":{
        "id":"6190601",
        "nome":"Provedores de acesso \u00e0s redes de comunica\u00e7\u00f5es"
      }
    }
  ]
}

GET https://suaempresa.faturasimples.com.br/api/servico

Parâmetros da requisição

Parâmetro Valor Padrão Descrição
inicio 0 A partir de qual registro os dados serão retornados
limite 10 Número de registros a retornar. Valores possíveis de 1 a 100
ordenarColuna null Qual será o campo usado na ordenação
ordenarDirecao ASC Sentido da ordenação. Valores possíveis ASC ou DESC

Inserir

curl  "https://suaempresa.faturasimples.com.br/api/servico" \
    -d "nome=Desenvolvimento de Sistemas" \
    -d "id_servico=101" \
    -d "id_atividade=6201500" \
    -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$dados = array(
    "nome" => "Desenvolvimento de Sistemas",
    "id_servico" => 101,
    "id_atividade" => 6201500,
);
$servico = FaturaSimples_Servico::criar( $dados )

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"110",
  "nome":"Desenvolvimento de Sistemas",
  "discriminacao":"",
  "valor":"",
  "impostos_percentual":"",
  "servico":{
    "id":"101",
    "nome":"An\u00e1lise e desenvolvimento de sistemas."
  },
  "atividade":{
    "id":"6201500",
    "nome":"Desenvolvimento de programas de computador sob encomenda"
  }
}

POST https://suaempresa.faturasimples.com.br/api/servico

Parâmetros da requisição

Parâmetro Descrição
nome * Nome do serviço
id_servico Item da lista de serviço baseado na lista da Lei Complementar 116, de 21 de Julho de 2003 considerando somente números. Ex: para 1.02 – Programação informe 102
codigo_tributacao_municipio Informando somente números, ex: 6204-0/00 CONSULTORIA EM ANÁLISE DE SISTEMAS informe somente 6204000. Esse código depende da prefeitura onde a NFS-e será emitida.
discriminacao Texto descritivo
valor Valor padrão
impostos_percentual Valor percentual com dois dígitos decimais, ex: 21.44 que será usado para incluir o texto padrão ao final de cada nota emitida: Valor aproximado dos impostos: R$ XXX.YY de acordo com a Lei 12741/12

Campos marcados com * são obrigatórios.

Atenção: Há uma relação entre o Item de Serviço e codigo_tributacao_municipio. Caso o serviço não seja registrado corretamente, a emissão da NFS-e pode ser negada pela prefeitura.

Atualizar

curl "https://suaempresa.faturasimples.com.br/api/servico/120" \
    -d "nome=Desenvolvimento" \
    -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php

FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");

$dados = array(
    "nome" => "Desenvolvimento",
);
$servico = FaturaSimples_Servico::atualizar( 66, $dados );

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"120",
  "nome":"Desenvolvimento",
  "discriminacao":"",
  "valor":"",
  "impostos_percentual":"",
  "servico":{
    "id":"101",
    "nome":"An\u00e1lise e desenvolvimento de sistemas."
  },
  "atividade":{
    "id":"6201500",
    "nome":"Desenvolvimento de programas de computador sob encomenda"
  }
}

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

Parâmetros da requisição

Os mesmos parâmetros da Inserção se aplicam.

Selecionar

curl "https://suaempresa.faturasimples.com.br/api/servico/58" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$servico = FaturaSimples_Servico::selecionar( 58 )

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

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"58",
  "nome":"Desenvolvimento de Sistemas",
  "discriminacao":"",
  "valor":"",
  "impostos_percentual":"",
  "servico":{
    "id":"101",
    "nome":"An\u00e1lise e desenvolvimento de sistemas."
  },
  "atividade":{
    "id":"6201500",
    "nome":"Desenvolvimento de programas de computador sob encomenda"
  }
}

Parâmetros da requisição

Não há parâmetros

Excluir

curl -X DELETE "https://suaempresa.faturasimples.com.br/api/servico/66" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$json = FaturaSimples_Servico::deletar( 66 )

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

O comando acima retornará uma estrutura no seguinte formato:

{
  "deleted":true,
  "id":"66"
}

Parâmetros da requisição

Não há parâmetros

Clientes

Listar Clientes

curl "https://suaempresa.faturasimples.com.br/api/cliente" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$clientes = FaturaSimples_Cliente::listar();

O comando acima retornará uma estrutura no seguinte formato:

{
  "inicio":"0",
  "limite":"10",
  "data":[
    {
      "id":"52",
      "tipo":"1",
      "cnpj":"00.063.960\/0084-28",
      "nome":"WAL MART BRASIL LTDA",
      "razao_social":"WAL MART BRASIL LTDA",
      "inscricao_estadual":"",
      "inscricao_municipal":"3052671",
      "cpf":"",
      "data_nascimento":"",
      "obs":"",
      "cep":"38.050-000",
      "estado":"31",
      "endereco":"AV SANTA BEATRIZ DA SILVA",
      "numero":"1000",
      "complemento":"",
      "bairro":"SANTA MARIA",
      "cidade":{
        "id":"3170107",
        "nome":"Uberaba (MG)",
        "uf":"31"
      }
    },
    {
      "id":"217",
      "tipo":"1",
      "cnpj":"",
      "nome":"Teste PJ",
      "razao_social":"",
      "inscricao_estadual":"",
      "inscricao_municipal":"",
      "cpf":"",
      "data_nascimento":"",
      "obs":"",
      "cep":"",
      "estado":"",
      "endereco":"",
      "numero":"",
      "complemento":"",
      "bairro":"",
      "cidade":{
        "id":"2611606",
        "nome":"Recife (PE)",
        "uf":"26"
      }
    },
    ...
  ]
}

GET https://suaempresa.faturasimples.com.br/api/cliente

Parâmetros da requisição

Parâmetro Valor Padrão Descrição
inicio 0 A partir de qual registro os dados serão retornados
limite 10 Número de registros a retornar. Valores possíveis de 1 a 100
ordenarColuna null Qual será o campo usado na ordenação
ordenarDirecao ASC Sentido da ordenação. Valores possíveis ASC ou DESC

Inserir

curl "https://suaempresa.faturasimples.com.br/api/cliente" \
   -d "nome=Eramo Software" \
   -d "cnpj=17737572000150" \
   -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$dados = array(
    'nome' => 'Eramo Software',
    'cnpj' => '17737572000150',
);
$cliente = FaturaSimples_Cliente::criar($dados);

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"227",
  "tipo":"",
  "cnpj":"17737572000150",
  "nome":"Eramo Software",
  "razao_social":"",
  "inscricao_estadual":"",
  "inscricao_municipal":"",
  "cpf":"",
  "data_nascimento":"",
  "obs":"",
  "cep":"",
  "estado":"",
  "endereco":"",
  "numero":"",
  "complemento":"",
  "bairro":"",
  "cidade":{
    "id":"2611606",
    "nome":"Recife (PE)",
    "uf":"26"
  }
}

POST https://suaempresa.faturasimples.com.br/api/cliente

Parâmetros da requisição

Parâmetro Descrição
nome * Nome do cliente
tipo Pessoa Jurídica:1, Pessoa Física:2
cnpj CNPJ do cliente
razao_social Razão social da empresa
inscricao_estadual Número da inscrição estadual
inscricao_municipal Número da inscrição municipal
cpf CPF do cliente
data_nascimento Data de Nascimento no caso de cliente PF
obs Observações
cep CEP
id_cidade Código do município no IBGE
estado Código do estado no IBGE (primeiros dois dígitos do código do município)
endereco Logradouro
numero Número
complemento Complemento do endereço
bairro Nome do bairro
meio_pagamento 1 Nome do Meio de Pagamento para registro de dados de pagamento online
cartao_bandeira 1 Escolhe a bandeira do cartão para pagamento online. Valores possíveis são: visa, mastercard, amex, elo e diners
cartao_numero 1 Número do cartão de crédito (somente números).
cartao_validade 1 Validade do cartão no formato AAAAMM. Ex: 202012 para Dezembro/2020
cartao_codigo 1 Código de segurança do cartão

Campos marcados com * são obrigatórios.

Atenção: A emissão de NFS-e para clientes sem CNPJ/CPF só é permitida para pessoas físicas e para clientes residentes ou estabelecidos fora do país.

1 Os campos do cartão de crédito só serão utilizados quando o Meio de Pagamento for com Pagamento Online. Ex: Cielo - Solução Webservice. Caso não sejam informados, ao ser criada uma venda para o cliente, será enviado um email com o modelo padrão Cobrança - Pagamento online com o link para que o cliente preencha os dados.

Atualizar

curl "https://suaempresa.faturasimples.com.br/api/cliente/227" \
    -d "nome=Eramo Software LTDA" \
    -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php

FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");

$dados = array(
    "nome" => "Eramo Software LTDA",
);
$cliente = FaturaSimples_Cliente::atualizar( 227, $dados );

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"227",
  "tipo":"",
  "cnpj":"17737572000150",
  "nome":"Eramo Software LTDA",
  "razao_social":"",
  "inscricao_estadual":"",
  "inscricao_municipal":"",
  "cpf":"",
  "data_nascimento":"",
  "obs":"",
  "cep":"",
  "estado":"",
  "endereco":"",
  "numero":"",
  "complemento":"",
  "bairro":"",
  "cidade":{
    "id":"2611606",
    "nome":"Recife (PE)",
    "uf":"26"
  }
}

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

Os mesmos parâmetros da Inserção se aplicam.

Selecionar

curl "https://suaempresa.faturasimples.com.br/api/cliente/227" \
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$cliente = FaturaSimples_Cliente::selecionar(227);

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

O comando acima retornará uma estrutura no seguinte formato:

{
  "id":"227",
  "tipo":"1",
  "cnpj":"17737572000150",
  "nome":"Eramo Software",
  "razao_social":"",
  "inscricao_estadual":"",
  "inscricao_municipal":"",
  "cpf":"",
  "data_nascimento":"",
  "obs":"",
  "cep":"",
  "estado":"",
  "endereco":"",
  "numero":"",
  "complemento":"",
  "bairro":"",
  "cidade":{
    "id":"2611606",
    "nome":"Recife (PE)",
    "uf":"26"
  }
}

Parâmetros da requisição

Não há parâmetros

Excluir

curl -X DELETE "https://suaempresa.faturasimples.com.br/api/cliente/227"
     -u "2y6v8qnX3SUHZb0sanKWrQUnTAY:"
<?php
FaturaSimples::configure("https://suaempresa.faturasimples.com.br/", "2y6v8qnX3SUHZb0sanKWrQUnTAY");
$json = FaturaSimples_Cliente::deletar( 227 )

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

O comando acima retornará uma estrutura no seguinte formato:

{
  "deleted":true,
  "id":"227"
}

Parâmetros da requisição

Não há parâmetros