Consulte e lance dados do Financeiro da sua conta a partir do seu ERP, de uma planilha ou de um site. Esta página descreve o contrato da versão 1, as convenções e as limitações, com exemplos em curl, Node e Python.
A API pública do SSTFLIX deixa o seu ERP, a sua planilha ou o seu site consultarem e lançarem dados da sua conta. Esta é a versão 1 e ela cobre o setor Financeiro. Os demais setores estão em breve (veja a situação dos setores).
Um administrador da conta cria uma chave de API. Veja como em Autenticação.
Guarde a chave numa variável de ambiente do seu servidor, por exemplo SSTFLIX_API_KEY. Nunca no código, nem no navegador.
Chame a API enviando a chave no cabeçalho Authorization: Bearer. O endereço base é https://sstflix.com.br/api/v1, a resposta é sempre JSON, e a versão vai no caminho.
O contrato completo, legível por máquina, está em /api/v1/openapi.json (OpenAPI 3.1). Ferramentas como o Postman e os geradores de cliente o importam. Ele é gerado do mesmo catálogo e dos mesmos esquemas que a API usa.
Autenticação
Criar a chave
Quem administra a conta cria a chave em Configurações, Integrações, API para desenvolvedores, escolhendo o nome, os escopos e, se quiser, a validade. A chave completa aparece uma única vez, na criação: copie na hora. O SSTFLIX guarda só o hash (SHA-256) da chave e não consegue mostrá-la de novo. Se perder, revogue e crie outra.
Enviar a chave
A chave tem o formato sst_live_<prefixo>_<segredo>. O prefixo é o que aparece na tela e nos registros, para você reconhecer qual chave é qual. Envie a chave inteira no cabeçalho de toda requisição:
Authorization: Bearer <chave>
Chave na URL é recusada com 401 chave_invalida: parâmetros com nome de credencial (por exemplo key, token, api_key) ou com valor no formato da chave nunca são aceitos.
Use a chave só no servidor. A API não envia cabeçalhos CORS: ela foi feita para chamadas de servidor, não de navegador. Nunca ponha a chave em código que roda no navegador, em aplicativo de celular ou em repositório.
A chave vale para a conta inteira, ou seja, para todas as empresas do grupo.
Escopos e plano
Escopos de uma chave
Escopo
O que permite
financeiro:ler
Consultar o Financeiro: todas as listagens e leituras por id.
financeiro:gravar
Criar e alterar no Financeiro: lançamentos e fornecedores, baixa e desfazer baixa. Inclui ler.
Os escopos têm a forma <setor>:ler e <setor>:gravar, e só se oferecem setores disponíveis e incluídos no plano da conta. O Financeiro está disponível a partir do plano Starter; uma conta em teste (trial) não tem o Financeiro. O plano vale no momento de cada requisição, não no da criação da chave: se o plano mudar, a chave passa a receber 403 modulo_indisponivel.
Quantas chaves
Cada conta pode ter até 10 chaves não revogadas. Uma chave expirada que não foi revogada continua contando: revogue as que você não usa mais para abrir espaço.
Erros de autenticação
Erros de autenticação e de permissão
Código
Status
Quando acontece
chave_ausente
401
A requisição não trouxe o cabeçalho Authorization: Bearer com a chave.
chave_invalida
401
A chave não existe, está mal formada, o cabeçalho não usa o esquema Bearer, ou a chave foi enviada na URL (isso é sempre recusado).
chave_revogada
401
A chave foi revogada por um administrador da conta. Crie outra.
chave_expirada
401
A chave passou da data de validade escolhida na criação. Crie outra.
escopo_insuficiente
403
A chave não tem o escopo que a operação exige, por exemplo financeiro:gravar para criar ou alterar.
modulo_indisponivel
403
O setor ou a página do recurso não está disponível no plano atual da conta. Vale o plano de agora, não o de quando a chave foi criada.
empresa_bloqueada
403
A conta da chave está inativa, bloqueada, não foi encontrada ou está com o período de teste vencido.
O formato do erro e a tabela completa de códigos estão em Códigos de erro.
Convenções
Dinheiro, datas e nomes
Dinheiro é sempre número inteiro em centavos, nunca decimal: R$ 4.500,00 é 450000. Os campos de dinheiro terminam em _centavos, por exemplo valor_centavos.
Datas vão no formato YYYY-MM-DD. Instantes vão em ISO 8601, em UTC, por exemplo 2026-11-17T14:32:10.482Z.
Os nomes são em português e em snake_case. O identificador de todo recurso é id, que é um UUID ou um número inteiro conforme o recurso (a referência de cada um diz qual).
Listas e paginação
As listagens paginam por cursor opaco. O parâmetro limite vai de 1 a 200 (padrão 50, máximo 200). A resposta traz os registros em dados e, em proximo_cursor, o cursor da próxima página, ou null quando esta é a última. Para ler a página seguinte, envie esse valor sem alterar no parâmetro cursor, no mesmo recurso.
O GET por id (GET /financeiro/<recurso>/{id}) devolve o registro direto, sem o envelope dados.
O cursor não fica preso aos filtros
O cursor guarda só a posição na listagem, não os filtros: reutilizá-lo com outros filtros reposiciona a leitura na nova listagem. Mantenha os mesmos filtros de uma página para a seguinte.
Parâmetro de consulta que o recurso não conhece responde 422 campo_desconhecido, para o erro de digitação aparecer em vez de a API devolver tudo em silêncio.
limite ou cursor inválidos respondem 422 paginacao_invalida. Um filtro com valor fora do tipo responde 422 validacao.
Filtros e sincronização incremental
O filtro atualizado_desde (ISO 8601 com fuso, por exemplo 2026-11-08T10:00:00Z) devolve só o que mudou a partir daquele instante, inclusive. Ele existe somente em transações, faturas e cobranças, que têm uma coluna de atualização confiável. Os cadastros (contas, fornecedores, categorias, centros de custo e plano de contas) são pequenos: liste-os por inteiro.
Exclusões não são visíveis na v1
A v1 não mostra exclusões. Não existe DELETE na API e não há um feed de remoções: o registro que uma pessoa apaga na plataforma simplesmente deixa de aparecer nas listagens. Para descobrir o que sumiu, reconcilie de tempos em tempos: nas transações, por janela de datas (data_inicio e data_fim); nos demais recursos, listando tudo e comparando com o que você já guardou.
Formato de erro
Todo erro tem o mesmo formato e o mesmo identificador no cabeçalho X-Request-Id. Decida pelo codigo, que é estável, e não pela mensagem, que é um texto para uma pessoa ler. Os status usados são 400, 401, 403, 404, 409, 422, 429 e 500; a tabela de códigos está em Códigos de erro.
Corpo de um erro
{
"erro": {
"codigo": "valor_invalido",
"mensagem": "Corpo inválido: valor_centavos (informe centavos inteiros, de 1 a 2000000000 (número, não texto)).",
"detalhes": [
{
"campo": "valor_centavos",
"motivo": "informe centavos inteiros, de 1 a 2000000000 (número, não texto)"
}
]
},
"id_requisicao": "req_0123456789abcdef0123456789abcdef"
}
Limite de requisições
Cada chave pode fazer 120 requisições por minuto. Toda resposta depois da autenticação traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (época em segundos), e o 429 traz também Retry-After, com os segundos a esperar.
É um freio de rajada, não uma cota
O limite de 120 requisições por minuto por chave é um freio de rajada, e não é uma cota exata: ele é contado em memória, por instância do servidor, então o total aceito num minuto pode passar de 120 quando mais de uma instância atende a mesma chave. Não dimensione a integração contando com esse excedente.
Cache e versão
Todas as respostas da API, menos o próprio openapi.json, trazem Cache-Control: no-store: o dado da sua conta nunca fica em cache compartilhado. A versão está no caminho (/api/v1).
Recursos somente leitura
Só transações e fornecedores aceitam escrita. POST ou PATCH em um recurso somente leitura responde 404 recurso_desconhecido, não 405.
Códigos de erro
Todo erro responde { "erro": { "codigo", "mensagem", "detalhes": [{ "campo", "motivo" }] }, "id_requisicao" }. O id_requisicao é o mesmo do cabeçalho X-Request-Id: cite-o ao abrir um chamado e a requisição é encontrada. O detalhes traz um item por campo com problema, e fica vazio quando o erro não é de um campo.
Todos os códigos de erro da API
Código
Status
Quando acontece
chave_ausente
401
A requisição não trouxe o cabeçalho Authorization: Bearer com a chave.
chave_invalida
401
A chave não existe, está mal formada, o cabeçalho não usa o esquema Bearer, ou a chave foi enviada na URL (isso é sempre recusado).
chave_revogada
401
A chave foi revogada por um administrador da conta. Crie outra.
chave_expirada
401
A chave passou da data de validade escolhida na criação. Crie outra.
escopo_insuficiente
403
A chave não tem o escopo que a operação exige, por exemplo financeiro:gravar para criar ou alterar.
modulo_indisponivel
403
O setor ou a página do recurso não está disponível no plano atual da conta. Vale o plano de agora, não o de quando a chave foi criada.
empresa_bloqueada
403
A conta da chave está inativa, bloqueada, não foi encontrada ou está com o período de teste vencido.
json_invalido
400
O corpo da requisição não é um JSON válido. Envie JSON com Content-Type: application/json.
nao_encontrado
404
O registro não existe na conta da chave. Um id com formato impossível também responde assim.
recurso_desconhecido
404
O setor ou o recurso não existe na v1, ou o recurso é somente leitura e a operação (POST ou PATCH) não é oferecida. Não é 405.
validacao
422
Um campo do corpo ou um parâmetro de consulta tem valor inválido. O detalhe traz um item por campo, com o motivo.
valor_invalido
422
Valor em centavos fora do aceito: precisa ser número inteiro, de 1 a 2.000.000.000 no lançamento e de 0 a 2.000.000.000 nos componentes da baixa. Também quando o valor efetivo da baixa fica zerado ou acima do limite.
campo_desconhecido
422
Campo do corpo ou parâmetro de consulta que a operação não conhece ou não aceita, como status, data_pagamento e referencia_externa no PATCH de transações.
paginacao_invalida
422
O limite está fora de 1 a 200, ou o cursor foi alterado, é de outro recurso ou está malformado.
categoria_invalida
422
A categoria, ou o par categoria e subcategoria, não existe no catálogo de categorias da conta, ou veio subcategoria sem categoria.
categoria_reservada
422
Categoria de transferência entre contas, que não pode ser usada em lançamento pela API. A mesma regra vale na saída: a API não move para outra categoria um lançamento que já está classificado como transferência.
referencia_invalida
422
Um identificador de outro recurso (conta_id, empresa_id, fornecedor_id, centro_custo_id, plano_contas_id ou cliente_empresa_id) não existe na conta da chave.
conflito_idempotencia
409
Durante os 30 dias de retenção, a mesma referencia_externa só aceita o mesmo corpo, e esta chamada trouxe outro. Para repetir a chamada reenvie exatamente o mesmo corpo; para criar outro lançamento use outra referência. Depois dos 30 dias o corpo não é comparado: se o lançamento ainda existe, a mesma referência o devolve como repetição.
lancamento_removido
409
O lançamento criado com esta referencia_externa foi apagado por uma pessoa. Durante os 30 dias de retenção, a referência fica queimada: use outra. Depois dos 30 dias, a mesma referência cria um lançamento novo.
lancamento_conciliado
409
O lançamento é ancorado (conciliado, de extrato bancário, ligado a fatura, cobrança, PDV, repasse ou transferência) e a operação mudaria valor, tipo, datas ou conta (numa perna de transferência, também categoria e subcategoria), ou a baixa. O detalhe traz o motivo, em motivo_da_trava.
lancamento_alterado
409
O lançamento mudou durante a chamada, numa janela de milissegundos. Leia o lançamento de novo e repita a chamada se ainda fizer sentido.
limite_de_requisicoes
429
Mais de 120 requisições por minuto com a mesma chave. Espere os segundos do cabeçalho Retry-After.
erro_interno
500
Erro do nosso lado. Informe o id_requisicao ao suporte do SSTFLIX.
Transações
As transações são os lançamentos de entrada e saída, e são o recurso mais delicado da API: ela lê e grava dinheiro. Leia esta seção inteira antes de gravar. Os campos e os filtros de cada recurso estão na referência.
Contas a pagar e a receber
Contas a pagar e a receber não são recursos à parte: são transações filtradas por tipo e status. A conta a pagar é uma saída (tipo=saida) e a conta a receber é uma entrada (tipo=entrada); ainda não paga é pendente ou agendado. O filtro status aceita um valor por vez, então “em aberto” e “agendadas” são duas consultas.
Contas a pagar em aberto, vencendo até o fim do ano
O campo data_pagamento vem nula enquanto o lançamento não estiver pago. Criar um lançamento pendente ou agendado com data_pagamento no corpo é 422: a data prevista de pagamento vai em data_vencimento. Os filtros data_inicio e data_fim valem sobre a data do pagamento ou, se não houver, sobre a data de competência.
O que entra no resultado
A resposta traz computa_no_resultado, que é falso para a transferência entre contas e para o pagamento de fatura de cartão, porque eles não são receita nem despesa. É a mesma regra da tela de transações. O filtro computa_no_resultado=true tira esses lançamentos da listagem, e computa_no_resultado=false devolve só eles.
Transferências aparecem nos dois recursos: não some um com o outro
Não some o recurso /transferencias com /transacoes. O recurso /transferencias lista os pares de movimentação entre duas contas, e os dois lados de cada transferência já estão em /transacoes.
Filtros
tipo, status, conta_id, empresa_id, empresa_beneficiaria_id, data_inicio, data_fim, vencimento_de, vencimento_ate, atualizado_desde, referencia_externa, computa_no_resultado. O que cada um faz está na tabela de filtros.
Criar uma transação e a idempotência
O POST exige referencia_externa: uma referência do seu sistema (por exemplo o número do título), que é a chave de idempotência. Se a chamada falhar no meio do caminho, repita exatamente a mesma chamada, dentro dos 30 dias de retenção: a API não cria o lançamento duas vezes.
Primeira chamada: 201 com o lançamento criado e o cabeçalho Location.
Mesma referencia_externa e mesmo corpo: 200 com o lançamento atual (que pode já ter sido baixado ou editado) e o cabeçalho Idempotent-Replayed: true.
Mesma referencia_externa com corpo diferente, dentro dos 30 dias de retenção: 409 conflito_idempotencia. Reenvie exatamente o mesmo corpo para repetir, ou use outra referência para criar outro lançamento.
Se uma pessoa apagou o lançamento na plataforma: 409 lancamento_removido. Durante os 30 dias de retenção, a referência fica queimada: use outra.
Os registros de idempotência são guardados por 30 dias, e o corpo só é comparado durante esse prazo. Depois dos 30 dias, se o lançamento ainda existe, a mesma referencia_externa devolve esse lançamento como repetição, sem comparar o corpo; e se uma pessoa o apagou, ela cria um lançamento novo (201). Por isso não repita uma chamada por mais de 30 dias, ou confira antes listando as transações com o filtro referencia_externa.
valor_centavos é um número inteiro de 1 a 2.000.000.000. Texto, número decimal, zero, negativo, nulo ou acima do limite é 422 valor_invalido; o campo ausente é 422 validacao.
Categorias
A categoria é o par de texto categoria e subcategoria, conferido no catálogo de categorias da conta (o recurso /categorias), sem diferenciar maiúsculas de minúsculas. Pode-se enviar só a categoria se ela existir no catálogo. A categoria é gravada com a grafia do catálogo, como texto: renomear uma categoria depois não atualiza os lançamentos antigos.
Categoria inexistente, ou subcategoria sem categoria: 422 categoria_invalida.
Categoria de transferência entre contas: 422 categoria_reservada. Transferência não se lança por esta API.
A mesma regra vale na saída: a API não move para outra categoria um lançamento que já está classificado como transferência (PATCH com outra categoria ou subcategoria: 422 categoria_reservada). Numa perna de transferência, categoria e subcategoria não mudam: 409 lancamento_conciliado, com o motivo transferencia.
Categoria inativa no catálogo é aceita.
Referências a outros recursos
conta_id, empresa_id, fornecedor_id, centro_custo_id, plano_contas_id e cliente_empresa_id são conferidos na sua conta. Um identificador que não existe, ou que é de outra conta, é 422 referencia_invalida.
Editar uma transação
O PATCH altera só os campos enviados e devolve o lançamento atual. Os campos aceitos são tipo, descricao, valor_centavos, data_competencia, data_vencimento, forma_pagamento, categoria, subcategoria, conta_id, empresa_id, fornecedor_id, cliente_empresa_id, centro_custo_id, plano_contas_id, documento, observacoes. Ao menos um campo é obrigatório. Os campos de apoio, que são todos menos tipo, descricao, valor_centavos e data_competencia, aceitam null para limpar o valor.
O PATCH não editastatus, data_pagamento nem referencia_externa: a situação de pagamento só muda pela baixa e pelo desfazer baixa, e a referência é a identidade do lançamento. Um campo fora do esquema é 422 campo_desconhecido.
Linhas ancoradas são somente leitura para valor, tipo, datas e conta. Uma linha é ancorada quando está conciliada, tem fechamento de caixa, veio de extrato bancário, está ligada a fatura, cobrança, fatura de cartão, venda do PDV ou repasse, ou é uma das duas pernas de uma transferência. Pedir a mudança de valor_centavos, tipo, data_competencia, data_vencimento ou conta_id, dar baixa em uma linha ancorada que ainda não está paga, ou desfazer a baixa de uma linha ancorada e paga responde 409 lancamento_conciliado, com o motivo nos detalhes (campo motivo_da_trava). Os demais campos (descricao, forma_pagamento, categoria, subcategoria, empresa_id, fornecedor_id, cliente_empresa_id, centro_custo_id, plano_contas_id, documento e observacoes) continuam editáveis, com uma exceção: numa perna de transferência, categoria e subcategoria também não mudam (409 lancamento_conciliado, motivo transferencia), porque transferência não é receita nem despesa e, com outra categoria, as duas pernas passariam a contar no resultado como uma entrada e uma saída. Mandar o valor que a linha já tem não é mudança. Por essa mesma regra, a API não move um lançamento para fora de categoria de transferência: pedir outra categoria ou subcategoria numa linha que já está classificada como transferência responde 422 categoria_reservada, do mesmo modo que lançar em categoria de transferência. Numa conta que importa extrato, concilia ou emite faturas pela plataforma, a maior parte do histórico de lançamentos é ancorada: para a API, é leitura.
Motivos de uma linha ser ancorada (campo motivo_da_trava dos detalhes do erro)
Motivo
O que significa
conciliado
A linha foi conciliada com o extrato bancário.
fechamento_de_caixa
A linha está presa a um fechamento de caixa.
extrato_bancario
A linha veio de um extrato bancário importado, mesmo que ainda não esteja conciliada.
fatura
A linha está ligada a uma fatura de venda.
cobranca
A linha está ligada a uma cobrança.
fatura_de_cartao
A linha faz parte de uma fatura de cartão.
venda_pdv
A linha nasceu de uma venda do PDV.
pagamento_pdv
A linha nasceu de um pagamento do PDV.
repasse
A linha está ligada a um repasse.
transferencia
A linha é uma das duas pernas de uma transferência entre contas.
Baixa e desfazer baixa
POST /financeiro/transacoes/{id}/baixa marca o lançamento como pago. O corpo é opcional e traz data_pagamento, juros_centavos, multa_centavos, acrescimo_centavos, desconto_centavos e justificativa. Sem data_pagamento vale a data de hoje em America/Sao_Paulo.
Com diferença, o valor efetivo é valor_centavos + juros_centavos + multa_centavos + acrescimo_centavos - desconto_centavos, e a justificativa é obrigatória, com no mínimo 5 caracteres. O desconto não pode passar do valor da conta mais os acréscimos, e o valor efetivo precisa ser maior que zero (422).
Baixa de um lançamento que já está pago: 200 com ja_estava_pago: true, sem alterar nada.
POST /financeiro/transacoes/{id}/desfazer-baixa devolve um lançamento pago para pendente, restaurando o valor previsto e zerando os componentes da diferença, se a baixa teve diferença. Sobre um lançamento que já está pendente responde 200 com ja_estava_pendente: true.
Linha ancorada e ainda não paga não recebe baixa, e linha ancorada e paga não tem a baixa desfeita: 409 lancamento_conciliado.
Dar baixa com juros e multa (curl)
curl -s -X POST "https://sstflix.com.br/api/v1/financeiro/transacoes/7b1f3c8e-2a4d-4e5b-9c6a-0d8e1f2a3b4c/baixa" \
-H "Authorization: Bearer $SSTFLIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"data_pagamento": "2026-11-12",
"juros_centavos": 1500,
"multa_centavos": 900,
"justificativa": "Pago com dois dias de atraso"
}'
Limitações conhecidas
A janela da baixa
Existe uma janela de milissegundos entre a API conferir se a linha é ancorada e a baixa ser gravada. Ela não depende do que o integrador envia, e o desfecho depende de quando a mudança cai nela. Se a linha já estava paga quando a baixa a leu (por exemplo, por outra baixa feita na tela, na agenda ou em outra chamada), a resposta é 200 com ja_estava_pago verdadeiro. Se foi paga depois dessa leitura e antes da gravação, a resposta é 409 lancamento_alterado (o mesmo vale, na baixa com diferença, se o valor mudou nesse intervalo). E se a linha passou a ser conciliada ou ancorada sem ter sido paga nesse intervalo, a baixa é aplicada, porque a gravação confere só o status e, na baixa com diferença, o valor, e não as âncoras. Em qualquer dos casos, leia o lançamento de novo antes de repetir a chamada.
A janela do desfazer baixa
O desfazer baixa tem a mesma janela de milissegundos. Se a linha já estava pendente ou agendada quando ele a leu, a resposta é 200 com ja_estava_pendente verdadeiro. Se deixou de estar paga depois dessa leitura e antes da gravação (por exemplo, por outro desfazer), a resposta é 409 lancamento_alterado. E se a linha passou a ser ancorada depois dessa leitura e antes da gravação, o desfazer é aplicado, porque a gravação confere só o status, e não as âncoras. Em qualquer dos casos, leia o lançamento de novo antes de repetir a chamada.
Editar o valor de um lançamento pago com diferença
Editar valor_centavos de um lançamento pago que teve diferença na baixa (juros, multa, acréscimo ou desconto) deixa valor_previsto_centavos e os componentes da diferença desatualizados, e um desfazer a baixa posterior perde essa edição e restaura o valor previsto original. É o mesmo comportamento da tela.
Fornecedores
Os fornecedores aceitam POST e PATCH, com o escopo financeiro:gravar. Não existe DELETE: para tirar um fornecedor de uso, desative-o enviando ativo falso no PATCH.
Campos do cadastro
O POST aceita razao_social, nome_fantasia, tipo, cpf_cnpj, email, telefone, categoria, contato_nome, observacoes e empresa_id, e só razao_social é obrigatória. O campo de texto que não vier no POST fica vazio, o tipo ausente vale pj e a categoria ausente vale outros. O PATCH aceita os mesmos campos mais ativo, todos opcionais, com ao menos um por chamada; texto vazio limpa o campo (menos razao_social) e empresa_id nulo desvincula a empresa. A chave Pix do fornecedor não é lida nem escrita pela API.
CPF e CNPJ
Envie o CPF (11 dígitos) ou o CNPJ (14 dígitos), com ou sem pontuação: a API grava com a pontuação padrão (000.000.000-00 para o CPF e 00.000.000/0000-00 para o CNPJ), no POST e no PATCH. Por exemplo, 11222333000181 fica 11.222.333/0001-81. Outros formatos de documento não são suportados: texto com outra quantidade de dígitos (um documento estrangeiro, por exemplo) fica como veio, mas texto com exatamente 11 dígitos, ou com 14 ou mais, é reescrito como CPF ou CNPJ, descartando o que não for dígito e cortando o que passar de 14 dígitos. Ao comparar com a sua base, normalize os dois lados.
O POST não é idempotente
Antes de criar, liste
O POST de fornecedores não é idempotente e não recusa cpf_cnpj repetido: uma nova tentativa cria outro fornecedor. A listagem não tem filtro por cpf_cnpj. Antes de criar, liste os fornecedores (até 200 por página) e confira se ele já existe; depois de um erro de rede ou de tempo esgotado, releia a lista antes de tentar de novo.
As faturas e as cobranças são somente leitura na v1: a API só as consulta. Para criar ou alterar uma fatura ou uma cobrança, use a plataforma. Os dois recursos têm o filtro atualizado_desde para sincronização incremental.
Faturas
As faturas são as faturas de venda emitidas aos clientes, com valor, retenções, vencimento e situação. O link da nota fiscal não é exposto. O campo status é um texto livre da plataforma, não uma enumeração fechada. Uma transação ligada a uma fatura traz o fatura_id dela e é uma linha ancorada (veja linhas ancoradas).
Cobranças
As cobranças são as emitidas por boleto, Pix ou cartão. Elas expõem cliente_nome e cliente_cnpj_cpf, o CPF ou o CNPJ do cliente da conta, como cadastrado. Não expõem e-mail nem telefone do cliente, link de boleto, código de Pix nem linha digitável. O campo status também é texto livre.
Referência dos recursos
Esta é a referência do setor Financeiro, lida do mesmo catálogo que a API usa. Todo caminho parte de https://sstflix.com.br/api/v1. Cada recurso lista as operações, os campos, os filtros e exemplos.
Contas bancárias
Contas bancárias, caixas e cartões da empresa. O saldo inicial é o ponto de partida do livro-caixa, não o saldo de hoje.
Caminho: /financeiro/contas. O id é um número inteiro.
Operações
Operações de Contas bancárias
Operação
Método e caminho
Escopo
Erros específicos
Listar
GET /financeiro/contas
financeiro:ler
campo_desconhecido, paginacao_invalida, validacao
Obter por id
GET /financeiro/contas/{id}
financeiro:ler
nao_encontrado
Campos
Todo campo vem sempre na resposta; o que não tem valor vem nulo.
Campos de Contas bancárias
Campo
Tipo
Descrição
id
inteiro
Identificador do registro (inteiro).
nome
texto
Nome da conta.
banco
texto
Banco, quando houver. Vazio para caixa.
tipo
enum: corrente, poupanca, investimento, cartao, dinheiro, outros
Tipo da conta.
agencia
texto
Agência. Vazio quando não se aplica.
numero
texto
Número da conta. Vazio quando não se aplica.
saldo_inicial_centavos
inteiro, em centavos
Saldo inicial em centavos.
cor
texto
Cor de exibição na plataforma, em hexadecimal.
ativo
booleano
Falso quando o registro foi desativado (nunca é apagado pela API).
empresa_id
uuid
Empresa do grupo dona da conta, quando a conta é de uma delas.
criado_em
instante (ISO 8601, UTC)
Quando a conta foi cadastrada.
Filtros
Este recurso não tem filtros: a listagem aceita só limite e cursor. Leia página por página até o proximo_cursor vir nulo.
async function main() {
const resposta = await fetch("https://sstflix.com.br/api/v1/financeiro/fornecedores/42", {
headers: { Authorization: `Bearer ${process.env.SSTFLIX_API_KEY}` },
});
const dados = await resposta.json();
if (!resposta.ok) throw new Error(`${dados.erro.codigo}: ${dados.erro.mensagem}`);
console.log(resposta.status, dados);
}
main().catch((erro) => {
console.error(erro);
process.exitCode = 1;
});
Python, com a biblioteca requests
import os
import requests
resposta = requests.get(
"https://sstflix.com.br/api/v1/financeiro/fornecedores/42",
headers={"Authorization": f"Bearer {os.environ['SSTFLIX_API_KEY']}"},
timeout=30,
)
dados = resposta.json()
if not resposta.ok:
raise RuntimeError(f"{dados['erro']['codigo']}: {dados['erro']['mensagem']}")
print(resposta.status_code, dados)
Transações
Lançamentos de entrada e saída, inclusive contas a pagar e a receber (filtre por tipo e status). Devolve também as transferências entre contas; use computa_no_resultado para separá-las.
Todo campo vem sempre na resposta; o que não tem valor vem nulo.
Campos de Transações
Campo
Tipo
Descrição
id
uuid
Identificador do registro (UUID).
tipo
enum: entrada, saida
Entrada (receita) ou saída (despesa).
descricao
texto
Descrição do lançamento.
valor_centavos
inteiro, em centavos
Valor previsto ou efetivo do lançamento, em centavos.
status
enum: pago, pendente, agendado
Situação do pagamento.
data_competencia
data (YYYY-MM-DD)
Data de competência (YYYY-MM-DD).
data_pagamento
data (YYYY-MM-DD)
Data em que foi pago (YYYY-MM-DD). Nula enquanto o status não for pago.
data_vencimento
data (YYYY-MM-DD)
Data de vencimento (YYYY-MM-DD).
mes_competencia
texto
Mês de competência, quando informado.
forma_pagamento
texto
Forma de pagamento, em texto livre.
categoria
texto
Categoria. Junto com subcategoria forma o par do catálogo de categorias.
subcategoria
texto
Subcategoria.
conta_id
inteiro
Conta bancária (recurso contas).
empresa_id
uuid
Empresa do grupo dona do lançamento.
empresa_beneficiaria_id
uuid
Empresa do grupo beneficiada pelo lançamento, quando diferente da dona.
cliente_empresa_id
uuid
Empresa cliente vinculada ao lançamento.
fornecedor_id
inteiro
Fornecedor (recurso fornecedores).
centro_custo_id
inteiro
Centro de custo (recurso centros-custo).
plano_contas_id
inteiro
Conta contábil (recurso plano-contas).
documento
texto
Número do documento, por exemplo da nota fiscal.
observacoes
texto
Observações livres.
referencia_externa
texto
Referência do sistema de origem. É a chave de idempotência dos lançamentos criados pela API.
conciliado
booleano
Verdadeiro quando o lançamento já foi conferido com o extrato bancário.
fatura_id
uuid
Fatura de venda vinculada (recurso faturas).
cobranca_id
inteiro
Cobrança vinculada (recurso cobrancas).
multa_centavos
inteiro, em centavos
Multa paga ou recebida, em centavos.
juros_centavos
inteiro, em centavos
Juros pagos ou recebidos, em centavos.
desconto_centavos
inteiro, em centavos
Desconto concedido ou obtido, em centavos.
acrescimo_centavos
inteiro, em centavos
Acréscimo, em centavos.
valor_previsto_centavos
inteiro, em centavos
Valor previsto antes da baixa, em centavos. Nulo quando o lançamento nunca foi baixado.
computa_no_resultado
booleano
Falso para transferência entre contas e para o pagamento de fatura de cartão, que não são receita nem despesa. Calculado com a mesma regra da tela de transações.
atualizado_em
instante (ISO 8601, UTC)
Última alteração do lançamento. Base do filtro atualizado_desde.
criado_em
instante (ISO 8601, UTC)
Quando o lançamento foi criado.
Filtros
Além de limite e cursor, a listagem aceita estes parâmetros de consulta. Cada um pode aparecer uma única vez.
Filtros de Transações
Parâmetro
Tipo
O que faz
tipo
enum: entrada, saida
Só entradas ou só saídas.
status
enum: pago, pendente, agendado
Situação do pagamento. Contas a pagar e a receber são pendente e agendado.
conta_id
inteiro
Só lançamentos desta conta bancária.
empresa_id
uuid
Só lançamentos desta empresa do grupo.
empresa_beneficiaria_id
uuid
Só lançamentos cuja empresa beneficiária é esta.
data_inicio
data (YYYY-MM-DD)
A partir desta data (inclusive), sobre a data do pagamento ou, sem ela, a da competência.
data_fim
data (YYYY-MM-DD)
Até esta data (inclusive), sobre a data do pagamento ou, sem ela, a da competência.
vencimento_de
data (YYYY-MM-DD)
Vencimento a partir desta data (inclusive).
vencimento_ate
data (YYYY-MM-DD)
Vencimento até esta data (inclusive).
atualizado_desde
instante (ISO 8601, UTC)
Só o que mudou a partir deste instante (inclusive), ISO 8601 com fuso. Para sincronização incremental.
referencia_externa
texto
Só o lançamento com esta referência externa.
computa_no_resultado
booleano
true tira as transferências entre contas e os pagamentos de fatura de cartão; false devolve só eles.
async function main() {
const resposta = await fetch("https://sstflix.com.br/api/v1/financeiro/transferencias/42", {
headers: { Authorization: `Bearer ${process.env.SSTFLIX_API_KEY}` },
});
const dados = await resposta.json();
if (!resposta.ok) throw new Error(`${dados.erro.codigo}: ${dados.erro.mensagem}`);
console.log(resposta.status, dados);
}
main().catch((erro) => {
console.error(erro);
process.exitCode = 1;
});
Python, com a biblioteca requests
import os
import requests
resposta = requests.get(
"https://sstflix.com.br/api/v1/financeiro/transferencias/42",
headers={"Authorization": f"Bearer {os.environ['SSTFLIX_API_KEY']}"},
timeout=30,
)
dados = resposta.json()
if not resposta.ok:
raise RuntimeError(f"{dados['erro']['codigo']}: {dados['erro']['mensagem']}")
print(resposta.status_code, dados)
Exemplos
A chave vem do ambiente, nunca do código
Todos os exemplos leem a chave da variável de ambiente SSTFLIX_API_KEY e a enviam em Authorization: Bearer $SSTFLIX_API_KEY. Nunca escreva a chave no código nem a envie na URL. Os exemplos em Node usam o fetch da versão 18 ou mais nova, dentro de uma função async para rodar em CommonJS e em módulo ES, e os de Python usam a biblioteca requests.
async function main() {
const resposta = await fetch("https://sstflix.com.br/api/v1/financeiro/transacoes?limite=50", {
headers: { Authorization: `Bearer ${process.env.SSTFLIX_API_KEY}` },
});
const dados = await resposta.json();
if (!resposta.ok) throw new Error(`${dados.erro.codigo}: ${dados.erro.mensagem}`);
console.log(resposta.status, dados);
}
main().catch((erro) => {
console.error(erro);
process.exitCode = 1;
});
Python, com a biblioteca requests
import os
import requests
resposta = requests.get(
"https://sstflix.com.br/api/v1/financeiro/transacoes",
headers={"Authorization": f"Bearer {os.environ['SSTFLIX_API_KEY']}"},
params={
"limite": "50",
},
timeout=30,
)
dados = resposta.json()
if not resposta.ok:
raise RuntimeError(f"{dados['erro']['codigo']}: {dados['erro']['mensagem']}")
print(resposta.status_code, dados)
Ler todas as páginas
curl
# primeira página
curl -s "https://sstflix.com.br/api/v1/financeiro/transacoes?limite=200" \
-H "Authorization: Bearer $SSTFLIX_API_KEY"
# páginas seguintes: o proximo_cursor da resposta anterior, sem alterar
curl -s "https://sstflix.com.br/api/v1/financeiro/transacoes?limite=200&cursor=$PROXIMO_CURSOR" \
-H "Authorization: Bearer $SSTFLIX_API_KEY"
Node, a partir da versão 18
async function main() {
const base = "https://sstflix.com.br/api/v1/financeiro/transacoes";
const cabecalhos = { Authorization: `Bearer ${process.env.SSTFLIX_API_KEY}` };
let cursor = null;
do {
const consulta = new URLSearchParams({ limite: "200" });
if (cursor) consulta.set("cursor", cursor);
const resposta = await fetch(`${base}?${consulta}`, { headers: cabecalhos });
const pagina = await resposta.json();
if (!resposta.ok) throw new Error(`${pagina.erro.codigo}: ${pagina.erro.mensagem}`);
for (const registro of pagina.dados) console.log(registro.id);
cursor = pagina.proximo_cursor;
} while (cursor);
}
main().catch((erro) => {
console.error(erro);
process.exitCode = 1;
});
Python, com a biblioteca requests
import os
import requests
base = "https://sstflix.com.br/api/v1/financeiro/transacoes"
cabecalhos = {"Authorization": f"Bearer {os.environ['SSTFLIX_API_KEY']}"}
cursor = None
while True:
params = {"limite": 200}
if cursor:
params["cursor"] = cursor
resposta = requests.get(base, headers=cabecalhos, params=params, timeout=30)
pagina = resposta.json()
if not resposta.ok:
raise RuntimeError(f"{pagina['erro']['codigo']}: {pagina['erro']['mensagem']}")
for registro in pagina["dados"]:
print(registro["id"])
cursor = pagina["proximo_cursor"]
if cursor is None:
break
async function main() {
const resposta = await fetch("https://sstflix.com.br/api/v1/financeiro/transacoes?atualizado_desde=2026-11-08T10%3A00%3A00Z&limite=200", {
headers: { Authorization: `Bearer ${process.env.SSTFLIX_API_KEY}` },
});
const dados = await resposta.json();
if (!resposta.ok) throw new Error(`${dados.erro.codigo}: ${dados.erro.mensagem}`);
console.log(resposta.status, dados);
}
main().catch((erro) => {
console.error(erro);
process.exitCode = 1;
});
Python, com a biblioteca requests
import os
import requests
resposta = requests.get(
"https://sstflix.com.br/api/v1/financeiro/transacoes",
headers={"Authorization": f"Bearer {os.environ['SSTFLIX_API_KEY']}"},
params={
"atualizado_desde": "2026-11-08T10:00:00Z",
"limite": "200",
},
timeout=30,
)
dados = resposta.json()
if not resposta.ok:
raise RuntimeError(f"{dados['erro']['codigo']}: {dados['erro']['mensagem']}")
print(resposta.status_code, dados)
Criar uma transação
Repetir esta mesma chamada, com o mesmo corpo, não cria um segundo lançamento: a resposta é 200 com Idempotent-Replayed: true. Isso vale dentro da retenção de 30 dias, explicada em Criar uma transação e a idempotência.
async function main() {
const corpo = {
"descricao": "Aluguel do escritório, novembro (reajustado)",
"valor_centavos": 465000,
"observacoes": null
};
const resposta = await fetch("https://sstflix.com.br/api/v1/financeiro/transacoes/7b1f3c8e-2a4d-4e5b-9c6a-0d8e1f2a3b4c", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SSTFLIX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(corpo),
});
const dados = await resposta.json();
if (!resposta.ok) throw new Error(`${dados.erro.codigo}: ${dados.erro.mensagem}`);
console.log(resposta.status, dados);
}
main().catch((erro) => {
console.error(erro);
process.exitCode = 1;
});
Python, com a biblioteca requests
import os
import requests
corpo = {
"descricao": "Aluguel do escritório, novembro (reajustado)",
"valor_centavos": 465000,
"observacoes": None,
}
resposta = requests.patch(
"https://sstflix.com.br/api/v1/financeiro/transacoes/7b1f3c8e-2a4d-4e5b-9c6a-0d8e1f2a3b4c",
headers={"Authorization": f"Bearer {os.environ['SSTFLIX_API_KEY']}"},
json=corpo,
timeout=30,
)
dados = resposta.json()
if not resposta.ok:
raise RuntimeError(f"{dados['erro']['codigo']}: {dados['erro']['mensagem']}")
print(resposta.status_code, dados)
Dar baixa em uma transação
curl
curl -s -X POST "https://sstflix.com.br/api/v1/financeiro/transacoes/7b1f3c8e-2a4d-4e5b-9c6a-0d8e1f2a3b4c/baixa" \
-H "Authorization: Bearer $SSTFLIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"data_pagamento": "2026-11-12",
"juros_centavos": 1500,
"multa_centavos": 900,
"justificativa": "Pago com dois dias de atraso"
}'
Node, a partir da versão 18
async function main() {
const corpo = {
"data_pagamento": "2026-11-12",
"juros_centavos": 1500,
"multa_centavos": 900,
"justificativa": "Pago com dois dias de atraso"
};
const resposta = await fetch("https://sstflix.com.br/api/v1/financeiro/transacoes/7b1f3c8e-2a4d-4e5b-9c6a-0d8e1f2a3b4c/baixa", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SSTFLIX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(corpo),
});
const dados = await resposta.json();
if (!resposta.ok) throw new Error(`${dados.erro.codigo}: ${dados.erro.mensagem}`);
console.log(resposta.status, dados);
}
main().catch((erro) => {
console.error(erro);
process.exitCode = 1;
});
Python, com a biblioteca requests
import os
import requests
corpo = {
"data_pagamento": "2026-11-12",
"juros_centavos": 1500,
"multa_centavos": 900,
"justificativa": "Pago com dois dias de atraso",
}
resposta = requests.post(
"https://sstflix.com.br/api/v1/financeiro/transacoes/7b1f3c8e-2a4d-4e5b-9c6a-0d8e1f2a3b4c/baixa",
headers={"Authorization": f"Bearer {os.environ['SSTFLIX_API_KEY']}"},
json=corpo,
timeout=30,
)
dados = resposta.json()
if not resposta.ok:
raise RuntimeError(f"{dados['erro']['codigo']}: {dados['erro']['mensagem']}")
print(resposta.status_code, dados)
Desfazer a baixa
curl
curl -s -X POST "https://sstflix.com.br/api/v1/financeiro/transacoes/7b1f3c8e-2a4d-4e5b-9c6a-0d8e1f2a3b4c/desfazer-baixa" \
-H "Authorization: Bearer $SSTFLIX_API_KEY"
import os
import requests
corpo = {
"razao_social": "Gráfica Rápida Ltda",
"nome_fantasia": "Gráfica Rápida",
"tipo": "pj",
"cpf_cnpj": "11222333000181",
"email": "financeiro@graficarapida.example",
"telefone": "(41) 3000-0000",
}
resposta = requests.post(
"https://sstflix.com.br/api/v1/financeiro/fornecedores",
headers={"Authorization": f"Bearer {os.environ['SSTFLIX_API_KEY']}"},
json=corpo,
timeout=30,
)
dados = resposta.json()
if not resposta.ok:
raise RuntimeError(f"{dados['erro']['codigo']}: {dados['erro']['mensagem']}")
print(resposta.status_code, dados)
Como uma transação vem na resposta
Um exemplo ilustrativo de GET /financeiro/transacoes/{id}. Todo campo vem sempre; o que não tem valor vem nulo. O que a sua conta devolve depende dos lançamentos dela.
A v1 abre o setor Financeiro. Os demais setores ainda não têm nenhum caminho na API: chamar um deles responde 404 recurso_desconhecido.
Situação dos setores da API
Setor
Situação
Financeiro
Disponível
Contabilidade
Em breve
Marketing
Em breve
Suporte
Em breve
Operações
Em breve
Comercial
Em breve
Pessoas
Em breve
SST: Saúde e Segurança
Em breve
Coworking
Em breve
Restaurante
Em breve
PDV: Ponto de Venda
Em breve
Imóveis
Em breve
Registro de mudanças
Versão 1.0.0
Primeira versão da API pública.
Setor Financeiro, com leitura de 9 recursos: contas bancárias, categorias, centros de custo, plano de contas, fornecedores, transações, faturas, cobranças, transferências entre contas.
Criação e edição de transações e de fornecedores, com idempotência por referencia_externa nas transações.
Baixa e desfazer baixa de transações.
Chaves por conta, com escopos financeiro:ler e financeiro:gravar, criadas por um administrador.