MeuSimples Logo

API para Desenvolvedores

Download OpenAPI
Site App

Visão Geral

Bem-vindo à documentação da API do MeuSimples. Esta API permite consultar, adicionar, editar e excluir dados do sistema MeuSimples.

A API segue os princípios RESTful e utiliza JSON para troca de dados.

Recursos Principais

  • Autenticação OAuth 2.0 com client_id e client_secret
  • Endpoints organizados por schema e tabela
  • Suporte a operações POST, GET e PUT
  • Relacionamentos pai-filho entre registros
  • Sandbox para testar chamadas de API

Relacionamentos entre Tabelas

As tabelas no MeuSimples seguem uma convenção de nomenclatura para IDs que facilita o entendimento dos relacionamentos:

Dica: Ao trabalhar com a API, você pode usar os IDs ou campos com valor único para estabelecer relacionamentos entre registros. Por exemplo, ao criar um lançamento, você pode fornecer o id_fcliente com um número (ex: 1234) ou usar codigo=CLI1 para associá-lo a um cliente específico.

Servidores

Selecione o servidor que deseja utilizar para as operações de API:

Servidor
Ambiente URL Descrição
Produção https://api.meusimples.com.br/1.0 Ambiente de produção para aplicações em uso real. Use este servidor para suas aplicações em produção.
Beta https://beta.api.meusimples.com.br/1.0 Ambiente de teste para validação final. Use este servidor para testar suas integrações antes de ir para produção.
Desenvolvimento https://dev.api.meusimples.com.br/1.0 Ambiente para desenvolvimento e testes iniciais. Use este servidor durante o desenvolvimento da sua integração.
Nota: O servidor selecionado será utilizado para todas as operações no Explorador de API e no Sandbox.

Autenticação

A API do MeuSimples utiliza OAuth 2.0 para autenticação. Você precisará de um client_id e um client_secret para obter um token de acesso.

Obtendo Credenciais

  1. Acesse o app do MeuSimples
  2. No menu do usuário (canto superior direito), selecione "APIs"
  3. Cadastre uma nova API
  4. Gere o client_id e client_secret
  5. Selecione as permissões de tabelas
  6. Opcionalmente, informe uma data de validade
Importante: O client_secret deve ser guardado em segurança. Caso você o perca, será necessário gerar um novo.

Detalhes Técnicos

Para obter um token de acesso via API, faça uma requisição POST para o endpoint de autenticação:

POST https://api.meusimples.com.br/1.0/auth/token
Content-Type: application/json

{
  "client_id": "seu_client_id",
  "client_secret": "seu_client_secret",
  "grant_type": "client_credentials"
}

A resposta será um JSON contendo o token de acesso:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Usando o Token

Inclua o token em todas as requisições à API no cabeçalho Authorization:

GET https://api.meusimples.com.br/1.0/financeiro.lancamentos
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token

Informe suas credenciais abaixo para gerar um token de acesso:

Token

Token gerado com sucesso! Validade: 60 minutos

Bearer Token
O token foi automaticamente adicionado ao Sandbox para testes.

Explorador de API

Dados
Caminho
Método

Selecione um endpoint para ver os detalhes

Sandbox

Token

Gerador de Script

Notas de Implementação

Formato de Dados

Todas as requisições e respostas da API utilizam o formato JSON (JavaScript Object Notation). Certifique-se de incluir o cabeçalho Content-Type: application/json em suas requisições.

Convenção de Identificadores

Os identificadores (IDs) na API seguem um padrão consistente com o formato:

id_[letra identificadora do schema][nome da tabela no singular][_identificação adicional (opcional)]

Exemplos:

  • id_flancamento - Identificador de um lançamento financeiro
  • id_fcategoria - Identificador de uma categoria financeira
  • id_flancamento_empresa - Identificador específico de empresa em um lançamento

Relacionamentos entre Entidades

A API suporta relacionamentos hierárquicos entre registros. Registros pai podem conter registros filhos, que são representados como arrays de objetos dentro do objeto pai. Isso permite a criação e manipulação de estruturas de dados complexas em uma única requisição.

Referência por Identificadores Alternativos

Ao invés de usar o ID numérico padrão, você pode referenciar registros usando campos com valores únicos:

{"campo": "valor_unico"}

Exemplo: {"codigo": "123456789"} ao invés de {"id_flancamento": 12345}

Se o valor fornecido não for único no contexto da tabela, a API retornará um erro 409 (Conflict).

Caso queira usar o código do seu sistema, informe o campo cod_externo. Exemplo: {"cod_externo": "123456789"}

Operações em Lote

A API suporta operações em lote para processamento eficiente de múltiplos registros:

POST Para criar múltiplos registros em uma única requisição, envie um array de objetos no corpo da requisição:

[
  { "campo1": "valor1", "campo2": "valor2" },
  { "campo1": "valor3", "campo2": "valor4" }
]

PUT Para atualizar múltiplos registros, especifique na URL apenas o campo que servirá como chave e envie um array de objetos no corpo da requisição:

Exemplo: /financeiro.lancamentos/codigo com corpo:

[
  { "codigo": "A001", "descricao": "Nova descrição 1" },
  { "codigo": "A002", "descricao": "Nova descrição 2" }
]

PATCH Similar ao PUT, mas para atualizações parciais de múltiplos registros. Especifique o campo chave na URL e envie apenas os campos que deseja atualizar para cada registro:

[
  { "codigo": "A001", "descricao": "Nova descrição 1" },
  { "codigo": "A002", "valor": 150.00 }
]

Paginação e Ordenação

GET Para controlar o número de registros retornados, use o parâmetro limit. O valor padrão é 100 registros por página.

Exemplo: /financeiro.lancamentos?limit=50

GET Para implementar paginação, use o parâmetro offset em conjunto com limit. O valor padrão de offset é 0 (primeira página).

Exemplo: /financeiro.lancamentos?limit=50&offset=50 (segunda página)

GET Para alterar a ordenação dos resultados, use o parâmetro order. Por padrão, os registros são ordenados pela chave primária em ordem ascendente.

Exemplos:

  • /financeiro.lancamentos?order=dt_lancamento (ordem ascendente por data)
  • /financeiro.lancamentos?order=dt_lancamento:desc (ordem descendente por data)
  • /financeiro.lancamentos?order=dt_lancamento:desc,vl_lancamento:asc (ordenação múltipla)