Inicio
Splitdigital Logo

Biblioteca aberta de integracao

Como usar a API da Splitdigital na central e nos tenants

Esta biblioteca explica o fluxo completo de autenticacao, descoberta dos tenants liberados e consulta dos dados disponiveis por API.

Central

splitdigital.app.br/api

Descoberta dos tenants liberados, consulta de formas de pagamento e gerenciamento das chaves.

Tenant

[tenant].splitdigital.app.br/api

Consulta dos dados do tenant atual, como movimentos e provisoes, respeitando a liberacao definida para a chave.

Seguranca

Controle de acesso

Toda chamada exige token valido, origem autorizada e, quando aplicavel, liberacao do tenant e abilities corretas.

Fluxo recomendado

  1. 1. Obtenha uma chave de acesso valida para a integracao.
  2. 2. Consulte primeiro a API central para descobrir tenants e catalogos disponiveis.
  3. 3. Consuma os dados do tenant sempre pelo dominio correto.
  4. 4. Use apenas as abilities necessarias para cada integracao.
  5. 5. Se o token for revogado, expirar ou o tenant nao estiver liberado, a API bloqueia a consulta.

Gestao da chave

  • A chave pode ter abilities centrais e de tenant.
  • A chave deve ter expiracao de 7, 30 ou 90 dias.
  • Chaves revogadas deixam de autenticar imediatamente.
  • Chaves expiradas retornam bloqueio de autenticacao.
  • A API aplica rate limiting e monitora sinais de abuso por token.

Autenticacao

Todas as chamadas usam bearer token no header Authorization. 

GET /api/me
Authorization: Bearer SEU_TOKEN

Novas chaves exigem expiracao de 7, 30 ou 90 dias, definida no momento da emissao.

Respostas esperadas

  • 200: consulta autorizada.
  • 401: token ausente, invalido ou expirado.
  • 403: origem sem liberacao, tenant nao autorizado ou ability/permissao insuficiente.
  • 429: limite de requisicoes excedido para a chave ou origem.
  • 404: recurso nao encontrado.

As respostas de sucesso, autenticacao, bloqueio e rate limit entram em trilha de auditoria.

Abilities disponiveis

Central

  • central.profile.read: consultar a identidade autenticada na central.
  • central.tenants.read: consultar tenants liberados.
  • central.payment-methods.read: consultar formas de pagamento da central.
  • central.tokens.manage: listar, criar e revogar chaves pela API.

Tenant

  • tenant.read: consultar informacoes do tenant atual.
  • tenant.movimentos.read: consultar movimentos.
  • tenant.provisoes.read: consultar provisoes.

Endpoints da central

  • GET /api/me: retorna a identidade autenticada.
  • GET /api/tenants: lista os tenants disponiveis para a chave.
  • GET /api/tenants/{tenant}: retorna um tenant especifico.
  • GET /api/payment-methods: lista formas de pagamento e percentuais.
  • GET /api/payment-methods/{id}: detalha uma forma de pagamento.
  • GET /api/tokens: lista as chaves disponiveis para a origem autenticada.
  • POST /api/tokens: cria uma nova chave.
  • DELETE /api/tokens/{token}: revoga uma chave.
POST https://splitdigital.app.br/api/tokens
Authorization: Bearer SEU_TOKEN_GERENCIAL
Content-Type: application/json

{
  "name": "ERP Integracao",
  "abilities": [
    "tenant.read",
    "tenant.movimentos.read",
    "tenant.provisoes.read"
  ],
  "expires_in_days": 30
}

Endpoints do tenant

  • GET /api/me: confirma a identidade autenticada e o tenant atual.
  • GET /api/movimentos: lista movimentos do tenant.
  • GET /api/provisoes: lista provisoes do tenant.
  • GET /api/provisoes/{id}: retorna o cabecalho da provisao com as parcelas.
No tenant, a API exige cumulativamente: token valido, tenant autorizado e abilities/permissoes corretas. 
GET https://[tenant].splitdigital.app.br/api/movimentos?limit=10&include=extras
Authorization: Bearer SEU_TOKEN
GET https://[tenant].splitdigital.app.br/api/provisoes/123?include=extras
Authorization: Bearer SEU_TOKEN

Movimentos e extras

O endpoint de movimentos retorna os campos principais e pode incluir um bloco extras quando a chamada usar ?include=extras.

  • taxa
  • origem_id
  • nome da forma de pagamento
  • dados de integracao quando existirem

Provisoes, parcelas e extras

A API de provisoes diferencia o cabecalho da provisao e as parcelas financeiras.

  • GET /api/provisoes: lista o cabecalho das provisoes.
  • ?include=parcelas: inclui parcelas na listagem.
  • GET /api/provisoes/{id}: retorna o cabecalho com parcelas por padrao.
  • ?include=extras: inclui campos extras como boleto, origem e dados auxiliares.

Resumo

Fluxo pratico para integradores

  1. 1. Obtenha uma chave de acesso valida.
  2. 2. Consulte a central para descobrir tenants e formas de pagamento.
  3. 3. Consulte o tenant para movimentos e provisoes.
  4. 4. Use `include=extras` e `include=parcelas` quando precisar dos dados adicionais.
  5. 5. Revise abilities e expiracao conforme a necessidade da integracao.
Voltar ao inicio