API de Cessões

API REST para registro, consulta e acompanhamento do ciclo de vida de cessões de direitos creditórios (duplicatas, notas fiscais, debêntures e demais títulos representativos de crédito) destinadas à tokenização em estruturas TIDC.

O registro de uma cessão via API é o evento que dispara o mint do NFT representativo do recebível na rede blockchain configurada pelo fundo (Polygon, Base ou Arbitrum). Toda a cadeia de eventos posteriores — tokenização, liquidação, vencimento, recompra — é refletida tanto no banco de dados quanto on-chain.

Sumário

Ambientes

Criar cessões em lote

Consultar cessão

Listar cessões

Atualizar status da cessão

Ambientes

Ambiente	URL base	Observações
Sandbox	`https://api.sandbox.tokenone.com.br/v1`	Testes de integração. Cessões são mintadas em testnets (Polygon Amoy etc.).
Produção	`https://api.tokenone.com.br/v1`	Operação real. Requer credenciais aprovadas pelo time comercial.

Recomendamos que toda integração seja validada em Sandbox antes da promoção para Produção. As contas e CNPJs de Sandbox são isolados — dados de produção não vazam para o ambiente de testes e vice-versa.

Autenticação

A API utiliza OAuth 2.0 client credentials. Cada parceiro recebe um par client_id / client_secret no onboarding.

Obtenção do token

Resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "cessoes:write cessoes:read"
}

Uso do token

Inclua o token no header Authorization de toda requisição:

Escopos disponíveis

Escopo	Permissão
`cessoes:read`	Consultar cessões e listagens
`cessoes:write`	Criar cessões e atualizar status
`webhooks:manage`	Gerenciar inscrições em webhooks

Tokens têm validade de 1 hora. Recomendamos cachear o token e renovar somente quando próximo da expiração — não solicite um token novo a cada requisição.

Convenções

Formato de dados

Encoding: application/json; charset=utf-8

Datas: ISO 8601 no formato YYYY-MM-DD (datas) ou YYYY-MM-DDTHH:mm:ssZ (timestamps, sempre em UTC)

Valores monetários: número decimal com até 2 casas após o ponto. Use ponto como separador decimal, nunca vírgula. Não envie como string.

CNPJ: 14 dígitos sem máscara (45678901000123, e não 45.678.901/0001-23)

Moeda: padrão ISO 4217 (BRL, USD)

Idempotência

Toda requisição POST aceita o header Idempotency-Key com um UUID gerado pelo cliente. Em caso de reenvio (timeout, falha de rede), a API retornará exatamente a mesma resposta da primeira chamada sem criar registro duplicado.

A chave é válida por 24 horas. Após esse prazo, uma nova requisição com a mesma chave gerará um novo registro.

Paginação

Endpoints de listagem usam paginação por cursor:

Parâmetro	Tipo	Default	Máximo	Descrição
`limit`	integer	50	200	Quantidade de registros por página
`cursor`	string	—	—	Cursor opaco devolvido pela página anterior

A resposta inclui o objeto meta:

{
  "data": [...],
  "meta": {
    "tem_proxima_pagina": true,
    "proximo_cursor": "eyJpZCI6IjEyM2U0NTY3In0",
    "total_estimado": 1247
  }
}

Tratamento de erros

Erros seguem a especificação RFC 7807 — Problem Details for HTTP APIs:

{
  "type": "https://docs.tokenone.com.br/errors/cnpj-invalido",
  "title": "CNPJ inválido",
  "status": 422,
  "detail": "O dígito verificador do CNPJ do sacado não confere",
  "instance": "/v1/cessoes",
  "campo": "cnpj_sacado",
  "request_id": "req_8a2f1b3c9d4e5f6a"
}

Sempre inclua o request_id em comunicações com o suporte da TokenOne — ele permite localizar a chamada exata nos logs.

O objeto Cessão

{
  "id_cessao": "f7d3a91e-2b8c-4e5f-9a01-3c8d7e6f2a14",
  "numero_documento": "NF000148",
  "tipo_documento": "NOTA_FISCAL",
  "cnpj_cedente": "45678901000123",
  "cnpj_sacado": "11111111000101",
  "valor_futuro": 57286.48,
  "valor_presente": 54822.10,
  "taxa_desconto_aa": 0.2680,
  "prazo_dias": 61,
  "data_cessao": "2025-11-15",
  "data_vencimento": "2026-01-15",
  "data_pagamento": null,
  "rating": "A",
  "moeda": "BRL",
  "status": "TOKENIZADA",
  "lastro": {
    "url": "https://docs.tokenone.com.br/nf/abc123.pdf",
    "hash_sha256": "9af15b3e7c4d2a..."
  },
  "tokenizacao": {
    "rede": "polygon",
    "contrato": "0xAb12cD34eF56...",
    "token_id": "1247",
    "tx_hash": "0x8f7e6d5c4b3a...",
    "status_onchain": "MINTADA",
    "mintada_em": "2025-11-15T14:23:08Z"
  },
  "metadados": {
    "fundo_destino": "TIDC-PRIVATE-CREDIT-I",
    "tranche": "SENIOR"
  },
  "criado_em": "2025-11-15T14:22:31Z",
  "atualizado_em": "2025-11-15T14:23:08Z"
}

Campos

Campo	Tipo	Obrigatório	Descrição
`id_cessao`	UUID	gerado	Identificador único da cessão (gerado pela TokenOne)
`numero_documento`	string	sim	Número do documento de origem (NF, duplicata etc.)
`tipo_documento`	enum	sim	`NOTA_FISCAL`, `DUPLICATA`, `CCB`, `CRA`, `CRI`, `DEBENTURE`
`cnpj_cedente`	string(14)	sim	CNPJ do cedente (originador do crédito), apenas dígitos
`cnpj_sacado`	string(14)	sim	CNPJ do sacado (devedor)
`valor_futuro`	decimal	sim	Valor de face — montante que o sacado pagará no vencimento
`valor_presente`	decimal	sim	Valor pago pelo cessionário na data da cessão (≤ `valor_futuro`)
`taxa_desconto_aa`	decimal	calculado	Taxa de desconto anual implícita (calculada pela API)
`prazo_dias`	integer	calculado	Dias corridos entre `data_cessao` e `data_vencimento`
`data_cessao`	date	sim	Data em que o direito creditório foi transferido
`data_vencimento`	date	sim	Data em que o sacado deve liquidar o título
`data_pagamento`	date	não	Data efetiva da liquidação (preenchida via PATCH)
`rating`	enum	sim	`A`, `B`, `C`, `D`, `E`
`moeda`	string(3)	não	ISO 4217. Default `BRL`
`status`	enum	gerado	Ver Estados da cessão
`lastro.url`	string	sim	URL pública (signed URL) do documento que lastreia o crédito
`lastro.hash_sha256`	string(64)	sim	Hash SHA-256 hexadecimal do arquivo de lastro (garante integridade)
`tokenizacao`	object	gerado	Estado da operação on-chain (preenchido após o mint)
`metadados`	object	não	Campos customizados livres (até 16 chaves, 256 chars por valor)

Endpoints

Criar cessão

Registra uma nova cessão e dispara o processo de tokenização.

Request

Respostas

201 Created — Cessão registrada. O mint on-chain ocorre de forma assíncrona; acompanhe pelo webhook cessao.tokenizada ou pelo endpoint de consulta.

{
  "id_cessao": "f7d3a91e-2b8c-4e5f-9a01-3c8d7e6f2a14",
  "numero_documento": "NF000148",
  "status": "REGISTRADA",
  "taxa_desconto_aa": 0.2680,
  "prazo_dias": 61,
  "tokenizacao": {
    "rede": "polygon",
    "contrato": "0xAb12cD34eF56...",
    "token_id": null,
    "tx_hash": null,
    "status_onchain": "PENDENTE_MINT"
  },
  "criado_em": "2025-11-15T14:22:31Z",
  "_links": {
    "self": "/v1/cessoes/f7d3a91e-2b8c-4e5f-9a01-3c8d7e6f2a14"
  }
}

409 Conflict — Já existe cessão para a tupla (numero_documento, cnpj_cedente, data_cessao).

422 Unprocessable Entity — Validação falhou (CNPJ inválido, valor_presente > valor_futuro, datas inconsistentes etc.).

Criar cessões em lote

Para volumes maiores, registra até 500 cessões em uma única chamada. Cada item é validado individualmente; itens inválidos não bloqueiam os demais.

Request

{
  "lote_id": "lote-banrisul-2025-11-15-001",
  "cessoes": [
    { "numero_documento": "NF000148", "...": "..." },
    { "numero_documento": "NF000149", "...": "..." }
  ]
}

Resposta `207 Multi-Status`

{
  "lote_id": "lote-banrisul-2025-11-15-001",
  "total": 2,
  "sucesso": 1,
  "falha": 1,
  "resultados": [
    {
      "indice": 0,
      "numero_documento": "NF000148",
      "status_http": 201,
      "id_cessao": "f7d3a91e-2b8c-4e5f-9a01-3c8d7e6f2a14"
    },
    {
      "indice": 1,
      "numero_documento": "NF000149",
      "status_http": 422,
      "erro": {
        "type": "https://docs.tokenone.com.br/errors/cnpj-invalido",
        "title": "CNPJ inválido",
        "campo": "cnpj_sacado"
      }
    }
  ]
}

Reprocesse apenas os itens com falha; não reenvie o lote inteiro.

Consultar cessão

Resposta `200 OK`

Retorna o objeto Cessão completo.

Listar cessões

Parâmetros de query

Parâmetro	Tipo	Descrição
`cnpj_cedente`	string	Filtra por CNPJ do cedente
`cnpj_sacado`	string	Filtra por CNPJ do sacado
`status`	enum	Filtra por status. Aceita múltiplos: `?status=REGISTRADA,TOKENIZADA`
`data_cessao_inicio`	date	Data mínima de cessão (inclusiva)
`data_cessao_fim`	date	Data máxima de cessão (inclusiva)
`vence_em_dias`	integer	Cessões a vencer nos próximos N dias
`rating`	enum	Filtra por rating
`limit`	integer	Tamanho da página (default 50, máximo 200)
`cursor`	string	Cursor de paginação

Exemplo

Atualizar status da cessão

Usado principalmente para registrar liquidações, vencimentos confirmados ou cancelamentos. Transições inválidas retornam 422.

Request

{
  "novo_status": "LIQUIDADA",
  "data_pagamento": "2026-01-14",
  "valor_recebido": 57286.48,
  "observacao": "Liquidação antecipada em 1 dia"
}

Resposta `200 OK`

Retorna o objeto Cessão atualizado.

Estados da cessão

REGISTRADA ──► TOKENIZADA ──► LIQUIDADA
                          └─► VENCIDA ──► RECUPERADA
                          └─► CANCELADA

Status	Descrição
`REGISTRADA`	Cessão validada e gravada. Mint on-chain pendente.
`TOKENIZADA`	NFT mintado com sucesso. Token está no wallet do fundo destino.
`LIQUIDADA`	Sacado pagou o título integralmente. Token queimado on-chain.
`VENCIDA`	Data de vencimento ultrapassada sem pagamento.
`RECUPERADA`	Cessão vencida que foi posteriormente recuperada (parcial ou totalmente).
`CANCELADA`	Cessão cancelada antes da liquidação (recompra, erro de registro etc.).

Importante: a vencer não é um status. Trata-se de um filtro de consulta (vence_em_dias=N) sobre cessões TOKENIZADA cuja data_vencimento ainda não passou.

Webhooks

Em vez de fazer polling, recomendamos assinar webhooks para receber notificações em tempo real.

Eventos disponíveis

Evento	Disparado quando…
`cessao.registrada`	Cessão validada e persistida
`cessao.tokenizada`	NFT mintado com sucesso na blockchain
`cessao.tokenizacao_falhou`	Mint falhou após 3 tentativas
`cessao.liquidada`	Status alterado para `LIQUIDADA`
`cessao.vencida`	Cessão atingiu `data_vencimento` sem pagamento
`cessao.cancelada`	Cessão cancelada

Inscrição

Payload entregue

{
  "evento": "cessao.tokenizada",
  "id_evento": "evt_8a2f1b3c9d4e5f6a",
  "ocorrido_em": "2025-11-15T14:23:08Z",
  "dados": {
    "id_cessao": "f7d3a91e-2b8c-4e5f-9a01-3c8d7e6f2a14",
    "numero_documento": "NF000148",
    "tokenizacao": {
      "rede": "polygon",
      "contrato": "0xAb12cD34eF56...",
      "token_id": "1247",
      "tx_hash": "0x8f7e6d5c4b3a..."
    }
  }
}

Verificação de assinatura

Todo webhook inclui o header X-TokenOne-Signature com HMAC-SHA256 do corpo da requisição usando a secret configurada:

Exemplo de verificação em Node.js:

Política de reentrega

Webhooks que retornarem status diferente de 2xx são reenviados com backoff exponencial: 1min, 5min, 30min, 2h, 6h, 24h. Após 6 tentativas, o evento é marcado como falho e disponibilizado no dashboard para reenvio manual.

Códigos de erro

HTTP	`type` (slug)	Significado
400	`requisicao-malformada`	JSON inválido ou campos ausentes
401	`nao-autenticado`	Token ausente, expirado ou inválido
403	`escopo-insuficiente`	Token não tem o escopo necessário
404	`recurso-nao-encontrado`	`id_cessao` não existe
409	`cessao-duplicada`	Cessão já registrada para a tupla informada
422	`cnpj-invalido`	CNPJ não passou na validação do dígito verificador
422	`valor-presente-maior-que-futuro`	`valor_presente > valor_futuro`
422	`datas-inconsistentes`	`data_cessao > data_vencimento` etc.
422	`transicao-status-invalida`	Tentativa de transição não permitida na máquina de estados
422	`hash-lastro-divergente`	Hash informado não bate com o do arquivo em `lastro.url`
429	`rate-limit-excedido`	Veja Limites de uso
500	`erro-interno`	Falha inesperada. Reporte ao suporte com o `request_id`
503	`servico-indisponivel`	Manutenção ou indisponibilidade temporária

A lista completa fica em docs.tokenone.com.br/errors.

Limites de uso

Plano	Requisições/min	Cessões/mês
Sandbox	60	ilimitado
Standard	300	10.000
Institucional	1.500	sob contrato

Headers de resposta em toda chamada:

Ao receber 429, respeite o header Retry-After (em segundos).

Changelog

v1.0.0 — 2025-11-15

Lançamento da API de Cessões

Endpoints: criação individual e em lote, consulta, listagem, atualização de status

Webhooks para os 6 eventos do ciclo de vida

Suporte a redes Polygon, Base e Arbitrum

Suporte

E-mail técnico: developers@tokenone.com.br

Status da plataforma: status.tokenone.com.br

Comercial e parcerias: comercial@tokenone.com.br

Para questões regulatórias relacionadas à Resolução CVM 88 e à conformidade do TIDC, contate diretamente o time jurídico da TokenOne pelo canal institucional.

Ativos

API de Cessões#

Sumário#

Ambientes#

Autenticação#

Obtenção do token#

Uso do token#

Escopos disponíveis#

Convenções#

Formato de dados#

Idempotência#

Paginação#

Tratamento de erros#

O objeto Cessão#

Campos#

Endpoints#

Criar cessão#

Request#

Respostas#

Criar cessões em lote#

Request#

Resposta 207 Multi-Status#

Consultar cessão#

Resposta 200 OK#

Listar cessões#

Parâmetros de query#

Exemplo#

Atualizar status da cessão#

Request#

Resposta 200 OK#

Estados da cessão#

Webhooks#

Eventos disponíveis#

Inscrição#

Payload entregue#

Verificação de assinatura#

Política de reentrega#

Códigos de erro#

Limites de uso#

Changelog#

v1.0.0 — 2025-11-15#

Suporte#

API de Cessões

Sumário

Ambientes

Autenticação

Obtenção do token

Uso do token

Escopos disponíveis

Convenções

Formato de dados

Idempotência

Paginação

Tratamento de erros

O objeto Cessão

Campos

Endpoints

Criar cessão

Request

Respostas

Criar cessões em lote

Request

Resposta `207 Multi-Status`

Consultar cessão

Resposta `200 OK`

Listar cessões

Parâmetros de query

Exemplo

Atualizar status da cessão

Request

Resposta `200 OK`

Estados da cessão

Webhooks

Eventos disponíveis

Inscrição

Payload entregue

Verificação de assinatura

Política de reentrega

Códigos de erro

Limites de uso

Changelog

v1.0.0 — 2025-11-15

Suporte