Como começar
Objetivo desta página
Em poucos minutos, você entende os conceitos mínimos e o fluxo essencial para operar nossas APIs com segurança e organização.
Em poucos minutos, você entende os conceitos mínimos e o fluxo essencial para operar nossas APIs com segurança e organização.
1) Conceitos Básicos
Conta (tenantId)
Identifica a entidade (CNPJ/CPF) em nome da qual as operações acontecem.
- Contexto de todas as operações
- Isolamento de dados e auditoria por conta
- Escolha o tenantId antes de qualquer ação
Participantes (papéis da conta)
O mesmo tenantId pode atuar como:
- Sacado — recebe a cobrança
- Sacador/Cedente — emite duplicatas
- Agente Financiador — financia/compra recebíveis
O papel define as jornadas disponíveis.
Usuário × Conta (personId)
Usuário é a pessoa física (identidade). Conta é o CNPJ/CPF.
- O personId representa o usuário
- Um personId pode operar vários tenantId
- Permissões são sempre por conta (vínculo personId ↔ tenantId)
| Conceito | O que é | Por que importa |
|---|---|---|
| tenantId (conta) | Identificador da entidade (CNPJ/CPF) | Define escopo, dados e trilha de auditoria |
| Papéis (participantes) | Sacado • Sacador/Cedente • Agente Financiador | Desbloqueia jornadas/recursos específicos |
| personId (usuário) | Identidade da pessoa física operadora | Permissões são por conta; um usuário pode ter várias contas |
Modelo mental
Quem sou? (personId) +
em nome de quem opero? (tenantId) +
qual papel essa conta exerce? (participante).
Quem sou? (personId) +
em nome de quem opero? (tenantId) +
qual papel essa conta exerce? (participante).
2) Começando a se conectar
2.1 Autenticação (Bearer Token)
- Comprova a identidade do usuário e libera um token de acesso.
- O token deve ser enviado em todas as requisições enquanto estiver válido.
- Renove/roteie tokens com segurança e separe sandbox de produção.
Atenção — Falhas intermitentes costumam ser expiração de token não tratada.
2.2 Definir o contexto da conta (tenantId)
- Após autenticado, escolha a conta em nome da qual irá operar.
- O tenantId impacta quais recursos você vê e quais ações tem permissão de executar.
- Mantenha coerência: um fluxo inteiro deve usar o mesmo tenantId.
Boa prática — Registre o request id e o tenantId nos logs de cada requisição.
2.3 Gestão de usuários (quando preciso) — o papel do personId
- Use personId quando for criar/vincular usuários à conta ou ajustar permissões.
- Um personId pode ser membro de vários tenantId, com perfis diferentes em cada um.
- Sem vínculo personId ↔ tenantId, o usuário não terá autorizações efetivas.
Erro comum — Criar o usuário e esquecer de atribuir perfil/permissões na conta correta.
3) Fluxo mínimo (visão conceitual)
| Passo | Objetivo | Pontos de atenção |
|---|---|---|
| 1 | Autenticar (obter Bearer token) | Armazene com segurança; trate expiração; separe sandbox/prod |
| 2 | Definir a conta (tenantId) | Use o mesmo tenant em todo o fluxo; valide permissões |
| 3 | (Opcional) Gestão de usuários (personId) | Vincule personId ↔ tenantId e atribua perfil/permissões |
Regra de ouro — Token primeiro → defina o tenant → ajuste usuários (se necessário). Só então avance para as jornadas específicas do papel da conta.