NAV
Shell

Informativos

Introdução

A Clicksign Securities é uma plataforma que permite gerar, endossar e assinar eletronicamente Cédulas de Crédito Bancário (CCB).

Disponibilizamos essa API com o intuito de fornecer acesso aos recursos do produto Clicksign Securities, por meio da arquitetura REST. É possível fazer uso dos recursos do nosso sistema fora do nosso ambiente UI, e com isso, contextualizar melhor as funcionalidades dentro da sua necessidade.

Visão geral

O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com a SECURITIES-API, descrevendo as funcionalidades, os métodos a serem utilizados, listando informações a serem enviadas e recebidas, e provendo exemplos.

O mecanismo de integração com o SECURITIES-API é simples, de modo que apenas conhecimentos intermediários em linguagem de programação para Web, requisições HTTP/HTTPS e manipulação de arquivos JSON são necessários para integrar com a SECURITIES-API.

Nesse documento você encontrará a referência sobre todas as operações disponíveis na SECURITIES-API. As operações devem ser executadas utilizando um token de acesso obtido através do recurso de autenticação. Esse token é gerado com base em uma organização ativa (arranjo) na Clicksign Securities.

Disponibilizamos abaixo as urls de acesso aos nossos ambientes:

Ambiente Produção: https://app.securities.com.br/api

Ambiente Homologação: https://app-sandbox.securities.com.br/api

Códigos de status

Na API da Clicksign Securities, os status de retorno das requisições devem ser esperados conforme especificado nas situações abaixo:

CÓDIGO DESCRIÇÃO SITUAÇÃO
200 OK Requisição atendida com sucesso
201 Created Registro criado (geralmente em método POST /recurso)
204 No Content Registro alterado ou excluído (geralmente em método PATCH ou DELETE /recurso)
401 Unauthorized Token ausente, expirado ou não autorizado
403 Forbidden Acesso proibido ao recurso requisitado (usuário sem permissão)
404 Resource Not Found Registro ou recurso não encontrado
422 Unprocessable Entity Quando ocorrer erros de validação, como, um campo obrigatório não informado
429 Too Many Requests Excedeu o seu limite de requisições por minuto
500 Internal Server Error Quando ocorrer um erro interno no recurso da API
502 Bad Gateway No momento estamos offline para manutenção no sistema, tente mais tarde
503 Service Unavailable No momento estamos offline para manutenção no sistema, tente mais tarde

Token de Acesso

Para obter o token de acesso às nossas APIs, solicite pelo e-mail suporte@securities.com.br.

Migração da Antiga Securities

Trata-se de uma API transitória, para que nossos atuais clientes Clicksign Securities possam se planejar para refazer a conexão de API atual, mesmo assim, usufruindo da nova plataforma Clicksign Securities com suas novas features, melhor performance e maior escalabilidade.

Para os clientes atuais, essa API de compatibilidade vai funcionar como uma ponte para conectá-lo da API legada (atual deste cliente) até a Nova Clicksign Securities, realizando a conversão dos formatos que os dados são enviados para o formato que a Nova Securities espera receber.

Para novos clientes, a conexão com a nova Securities deve se dar pela criação da conexão da Nova API. Para os atuais clientes, o uso da API de compatibilidade será uma aceleração para usufruir do novo produto, sem maiores esforços de desenvolvimento inicial.

É importante ressaltar que novas features serão lançadas a partir de abril/2023 apenas para a nova API, o que nos leva a reforçar que após conectar a API de compatibilidade com esforço mínimo, o planejamento para conectar-se com a nova API é essencial para garantir que todos terão acesso aos lançamentos futuros.

Mudanças importantes nas integrações

Para os clientes que vierem do Securities Legado, provavelmente, os documentos de CCBs estão sendo criados diretamente na plataforma de assinatura da Clicksign através das API fornecidas pela plataforma de assinatura e não pela API do sistema de securitização.

No novo Securities será diferente, disponibilizamos algumas APIs de compatibilidade para a criação das CCBs, dessa forma, toda a comunicação via API deverá ser com o novo sistema. Essa mudança foi feita porque todas as informações sobre os documentos, bem como as assinaturas pendentes e realizadas e o arquivo PDF estarão disponíveis nas novas APIs do novo Securities, portanto, não será necessário acessar a interface gráfica da plataforma de assinatura da Clicksign para localizar os documentos das CCBs, endossos referenciado ou dos termos de cessão.

É importante ressaltar que, todos os documentos assinados serão baixados para o Securities e vinculados aos registros de cada operação, tornando possível a visualização de cada um desses documentos dentro de suas respectivas operações, ou seja, quando pesquisar por uma CCB utilizando as novas APIs, será possível obter todos os documentos relacionados a ela.

Criar proposta (Legado)

Request:

curl -X POST https://app.securities.com.br/api/legacy/proposals \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
          "proposal": {
            "template_key": "e7c3534c-2b04-11ed-a261-02422b00ac13",
            "document_data": {
              "number": 231387,
              "issuer_full_name": "Hugo Fonseca",
              "issuer_full_address": "Setor M QNM 03 Conjunto Z - 72200-000, Brasília - DF",
              "issuer_cpf": "657.565.000-73",
              "issuer_rg": "47.825.277-8",
              "issuer_cnh": "81457959115",
              "issuer_email": "hugo@email.com",
            }
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "proposal": {
    "template_key": "e7c3534c-2b04-11ed-a261-02422b00ac13",
    "document_data": {
      "number": 231387,
      "issuer_full_name": "Hugo Fonseca",
      "issuer_full_address": "Setor M QNM 03 Conjunto Z - 72200-000, Brasília - DF",
      "issuer_cpf": "657.565.000-73",
      "issuer_rg": "47.825.277-8",
      "issuer_cnh": "81457959115",
      "issuer_email": "hugo@email.com"
    },
    "document": {
      "id": 25,
      "key": "f91e734e-ad1e-42f4-b12f-755e67178929",
      "status": "validated",
      "created_at": "2022-12-21T02:41:28.748Z",
      "updated_at": "2022-12-21T02:41:28.748Z",
      "file": "https://example.com/path/to/document.pdf"
    }
  }
}

Esse endpoint cria uma proposta

POST https://app.securities.com.br/api/legacy/proposals

Parâmetro Obrigatório Tipo Descrição
template_key sim string Chave do template no assinador
document_data sim json Dados do documento para compor o título

Buscar contrato (CCB) existente

Request:

curl -X GET https://app.securities.com.br/api/legacy/securities/:id \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": 2,
  "process": 3,
  "number": 231387,
  "issuer_cpf": "657.565.000-73",
  "issuer_full_name": "Hugo Fonseca",
  "parcels": 5,
  "first_installment_due_date": "2022-12-01",
  "last_installment_due_date": "2023-12-01",
  "parcels_value": 200.0,
  "today_value": 160.0,
  "leasing_total_value": 192.0,
  "cession_value": 180.0,
  "metadata": {
    // Todos os dados do modelo
  }
}

Esse endpoint obtém todos os dados de uma CCB

GET https://app.securities.com.br/api/legacy/securities/:id

Parâmetro Obrigatório Tipo Descrição
id sim integer Chave da security (CCB)

Buscar lote existente (assignments)

Request:

curl -X GET https://app.securities.com.br/api/legacy/assignments/:id \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "process": 3,
  "status": "pending",
  "cession_number": 442142,
  "cession_value": 1877.99,
  "cession_parcels": 30,
  "cession_contracts": 2,
  "assignor": 7,
  "transferee": 8,
  "contracts": [231387, 231388]
}

Esse endpoint obtém todos os dados de lote de CCB

GET https://app.securities.com.br/api/legacy/assignments/:id

Parâmetro Obrigatório Tipo Descrição
id sim integer Chave do lote de CCBs (assignment)

Cancelar lote existente

Request:

curl -X POST https://app.securities.com.br/api/legacy/assignments/:id/cancel \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "process": 3,
  "status": "canceling",
  "cession_number": 442142,
  "cession_value": 1877.99,
  "cession_parcels": 30,
  "cession_contracts": 2,
  "assignor": 7,
  "transferee": 8,
  "contracts": [231387, 231388]
}

Esse endpoint cancela um lote de cessão de CCBs

POST https://app.securities.com.br/api/legacy/assignments/:id/cancel

Parâmetro Obrigatório Tipo Descrição
id sim integer Chave do lote de CCBs (assignment)

Criar Signatário (Legado)

Request:

curl -X POST https://app.securities.com.br/api/legacy/signers \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
    -d '{
          "signer": {
            "email": "fulano@example.com",
            "auth": "email",
            "full_name": "Marcos Zumba",
            "has_documentation": true,
            "documentation": "123.321.123-40",
            "birthday": "1983-03-31",
            "phone_number": "11999999999",
            "sign_as": "sign",
            "communicate_by": "email",
            "selfie_enabled": false,
            "facial_biometrics_enabled": false,
            "handwritten_enabled": false,
            "official_document_enabled": false,
            "liveness_enabled": false
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "signer": {
    "id": 4,
    "full_name": "Marcos Zumba",
    "has_documentation": true,
    "documentation": "123.321.123-40",
    "email": "fulano@example.com",
    "birthday": "1983-03-31",
    "phone_number": "11999999999",
    "auth": "email",
    "communicate_by": "email",
    "key": null,
    "sign_as": "sign",
    "created_at": "2022-09-16T18:41:00.079-03:00",
    "updated_at": "2022-09-16T18:41:00.079-03:00",
    "selfie_enabled": false,
    "facial_biometrics_enabled": false,
    "handwritten_enabled": false,
    "official_document_enabled": false,
    "liveness_enabled": false
  }
}

Esse endpoint cria um signatário

POST https://app.securities.com.br/api/legacy/signers

Parâmetro Obrigatório Tipo Descrição
full_name sim string Nome completo
has_documentation não boolean Tem documentação, como CPF, CNPJ ou Passaporte. Padrão é TRUE
documentation condicional string CPF, CNPJ ou Passaporte
birthday condicional string Data de nascimento
email condicional string E-mail
phone_number sim string Numero de telefone
auth sim string Tipo de autenticação: "email" ou "api"
communicate_by sim string Por onde será notificado: "email"
sign_as sim string Assinar como: sign, party, witness, contractor, contractee...
selfie_enabled não boolean Padrão é FALSE
facial_biometrics_enabled não boolean Padrão é FALSE
handwritten_enabled não boolean Padrão é FALSE
official_document_enabled não boolean Padrão é FALSE
liveness_enabled não boolean Padrão é FALSE

Vincular Signatário ao documento

Request:

curl -X POST https://app.securities.com.br/api/legacy/signers/signer_id:/lists \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
    -d '{
          "list": {
            "document_id": 1,
            "group": null,
            "message": null,
            "refusable": false,
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "list": {
    "id": 4,
    "document_id": 1,
    "signer_id": 4,
    "created_at": "2022-09-16T18:41:00.079-03:00",
    "updated_at": "2022-09-16T18:41:00.079-03:00",
    "group": null,
    "message": null,
    "refusable": false
  }
}

Esse endpoint Vincula um signatário a um documento

POST https://app.securities.com.br/api/legacy/signers/:signer_id/lists

Parâmetro Obrigatório Tipo Descrição
document_id sim integer Chave única do documento dentro do Securities
group não integer Determina o grupo que o signatário deve ser vinculado. Deve ser número, inteiro e maior que 0. Não adicione esse parâmetro caso não deseje uma ordenação de assinaturas.
message não string Mensagem que será enviada no body do e-mail de solicitação de assinatura aos signatários. O parâmetro funciona com sequence_enabledcomo true e group é obrigatório
refusable não boolean Padrão é FALSE

Criar um processo de cessão

Request:

curl -X POST https://app.securities.com.br/api/legacy/assignments\
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
    -d '{
          "cession_number": "123456789",
          "cession_value": 1000,
          "cession_parcels": 1,
          "cession_contracts": 30,
          "issue_date": "2021-09-16",
          "arrangement": 1,
          "callback_url": "https://example.com/callback"
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "process": "123456789",
  "status": "pending"
}

Esse endpoint cria um processo de cessão

POST https://app.securities.com.br/api/legacy/assignments

Parâmetro Obrigatório Tipo Descrição
cession_number sim string Número da cessão
cession_value sim integer Valor da cessão
cession_parcels sim integer Quantidade de parcelas negociadas na cessão
cession_contracts sim integer Quantidade de contratos negociados na cessão
issue_date sim string Data de emissão da cessão
arrangement sim integer ID do Arranjo
callback_url não string URL de callback

Executar um processo de cessão

Request:

curl -X POST https://app.securities.com.br/api/legacy/contracts\
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
    -d '{
          "process": "123",
          "contracts": [
            { "number": "123456789", issuer_name: "Issuer Name"... },
            { "number": "125468797", issuer_name: "Issuer Name"... }
          ]
        }'

Response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{
  "status": "accepted"
}

Esse endpoint Executa um processo de cessão

POST https://app.securities.com.br/api/legacy/contracts

Parâmetro Obrigatório Tipo Descrição
process sim Integer ID do processo de cessão
contracts sim Array Array de contratos

API Nova Securities

Registro de CCBs

Proposta

A proposta é o documento que representa a CCB antes dela ser assinada pelo tomador. Enquanto o tomador não assina o documento, ele ainda não se tornou uma CCB para ser cedida, então esse documento é uma Proposta de se tornar uma CCB.

A proposta conterá todos os dados de uma CCB, seguindo o modelo preconizado entre originador e fundo, entretanto, o que o diferencia de uma CCB é o fato de ainda não estar assinado pelo tomador.

Listar propostas

Request:

curl -X GET https://app.securities.com.br/api/v1/proposals \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "proposals": [
    {
      "id": 218,
      "number": "123456",
      "issuer_full_name": "Hugo Fonseca",
      "issuer_document": "882.793.334-44",
      "installments": 48,
      "created_at": "2022-10-07T12:00:33.571-03:00",
      "updated_at": "2022-10-07T12:00:33.571-03:00",
      "url": "https://app.securities.com.br/api/v1/proposals/218"
    }
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todas as propostas

GET https://app.securities.com.br/api/v1/proposals

Parâmetro Tipo Descrição
page integer Paginação

Obter proposta

Request:

curl -X GET https://app.securities.com.br/api/v1/proposals/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "proposal": {
    "id": 3073,
    "number": "123321",
    "issuer_full_name": "Hugo Fonseca",
    "issuer_document": "882.793.334-44",
    "installments": 48,
    "created_at": "2022-10-27T09:44:50.772-03:00",
    "updated_at": "2022-10-27T09:44:50.772-03:00",
    "document_data": {
      "number": 231387,
      "issuer_full_name": "Hugo Fonseca",
      "issuer_full_address": "Setor M QNM 03 Conjunto Z - 72200-000, Brasília - DF",
      "issuer_cpf": "657.565.000-73",
      "issuer_rg": "47.825.277-8",
      "issuer_cnh": "81457959115",
      "issuer_email": "hugo@email.com",
      "guarantor_full_name": "Juan Isaac Fogaça",
      "guarantor_cpf": "822.448.901-98",
      "guarantor_rg": "34.576.797-4",
      "guarantor_full_address": "Quadra Quadra 300 Conjunto 31 - 72260-132, Brasília - DF",
      "financed_amount": 125314.12,
      "bank_name": "341 - Banco Itaú",
      "bank_agency_number": 7957,
      "bank_account_number": 423762,
      "disbursed_amount": 108323.45,
      "tac": 42.89,
      "pmt": 2784.12,
      "maturity": 60,
      "ccb_registration_fee": 88.32,
      "first_installment_due_date": "31/10/2022",
      "last_installment_due_date": "31/10/2027",
      "iof": 43.21,
      "commercial_yearly_interest_rate": 13.42,
      "commercial_monthly_interest_rate": 2.21,
      "cet_yearly_rate": 21.32,
      "cet_monthly_rate": 9.87
    },
    "documents": [
      {
        "id": 2955,
        "key": "fadef9ce-0f28-4792-bb3f-6d0bd5c6a055",
        "status": "created",
        "created_at": "2022-10-27T09:44:50.800-03:00",
        "updated_at": "2022-10-27T09:46:45.968-03:00",
        "file": null
      }
    ],
    "url": "https://app.securities.com.br/api/v1/proposals/3073"
  }
}

Esse endpoint obtem todos os dados de uma proposta. É possível obter a CCB pelo :id ou pelo :number

GET https://app.securities.com.br/api/v1/proposals/:id GET https://app.securities.com.br/api/v1/proposals/bynumber/:number

Criar proposta

Request:

curl -X POST https://app.securities.com.br/api/v1/proposals \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
        "proposal": {
          "number": "1234567",
          "issuer_full_name": "Hugo Fonseca",
          "issuer_document": "525.403.396-61",
          "installments": 48,
          "template_key": "e7c3534c-2b04-11ed-a261-02422b00ac13",
          "document_data": {
            "number": 231387,
            "issuer_full_name": "Hugo Fonseca",
            "issuer_full_address": "Setor M QNM 03 Conjunto Z - 72200-000, Brasília - DF",
            "issuer_cpf": "657.565.000-73",
            "issuer_rg": "47.825.277-8",
            "issuer_cnh": "81457959115",
            "issuer_email": "hugo@email.com",
            "guarantor_full_name": "Juan Isaac Fogaça",
            "guarantor_cpf": "822.448.901-98",
            "guarantor_rg": "34.576.797-4",
            "guarantor_full_address": "Quadra Quadra 300 Conjunto 31 - 72260-132, Brasília - DF",
            "financed_amount": 125314.12,
            "bank_name": "341 - Banco Itaú",
            "bank_agency_number": 7957,
            "bank_account_number": 423762,
            "disbursed_amount": 108323.45,
            "tac": 42.89,
            "pmt": 2784.12,
            "maturity": 60,
            "ccb_registration_fee": 88.32,
            "first_installment_due_date": "31/10/2022",
            "last_installment_due_date": "31/10/2027",
            "iof": 43.21,
            "commercial_yearly_interest_rate": 13.42,
            "commercial_monthly_interest_rate": 2.21,
            "cet_yearly_rate": 21.32,
            "cet_monthly_rate": 9.87
          }
        }
      }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "proposal": {
    "id": 3073,
    "number": "123321",
    "issuer_full_name": "Hugo Fonseca",
    "issuer_document": "882.793.334-44",
    "installments": 48,
    "created_at": "2022-10-27T09:44:50.772-03:00",
    "updated_at": "2022-10-27T09:44:50.772-03:00",
    "document_data": {
      "number": 231387,
      "issuer_full_name": "Hugo Fonseca",
      "issuer_full_address": "Setor M QNM 03 Conjunto Z - 72200-000, Brasília - DF",
      "issuer_cpf": "657.565.000-73",
      "issuer_rg": "47.825.277-8",
      "issuer_cnh": "81457959115",
      "issuer_email": "hugo@email.com",
      "guarantor_full_name": "Juan Isaac Fogaça",
      "guarantor_cpf": "822.448.901-98",
      "guarantor_rg": "34.576.797-4",
      "guarantor_full_address": "Quadra Quadra 300 Conjunto 31 - 72260-132, Brasília - DF",
      "financed_amount": 125314.12,
      "bank_name": "341 - Banco Itaú",
      "bank_agency_number": 7957,
      "bank_account_number": 423762,
      "disbursed_amount": 108323.45,
      "tac": 42.89,
      "pmt": 2784.12,
      "maturity": 60,
      "ccb_registration_fee": 88.32,
      "first_installment_due_date": "31/10/2022",
      "last_installment_due_date": "31/10/2027",
      "iof": 43.21,
      "commercial_yearly_interest_rate": 13.42,
      "commercial_monthly_interest_rate": 2.21,
      "cet_yearly_rate": 21.32,
      "cet_monthly_rate": 9.87
    },
    "documents": [
      {
        "id": 2955,
        "key": "fadef9ce-0f28-4792-bb3f-6d0bd5c6a055",
        "status": "created",
        "created_at": "2022-10-27T09:44:50.800-03:00",
        "updated_at": "2022-10-27T09:46:45.968-03:00",
        "file": null
      }
    ],
    "url": "https://app.securities.com.br/api/v1/proposals/3073"
  }
}

Esse endpoint cria uma proposta

POST https://app.securities.com.br/api/v1/proposals

Parâmetro Obrigatório Tipo Descrição
number sim string Número da proposta
issuer_full_name sim string Nome completo do emitente
issuer_document sim string Documento do emitente
installments sim integer Quantidade de parcelas
template_key sim string Chave do template no assinador
document_data sim json Dados do documento para compor o título

Signatário

Os signatários são aqueles que irão assinar os documentos envolvidos no processo de securitização, desde o registro de uma proposta, sendo o signatário o tomador, até a cessão de uma ou mais CCBs num lote, sendo assinadas pelo originador do crédito e fundo de investimento, como signatários.

Listar signatários

Request:

curl -X GET https://app.securities.com.br/api/v1/signers \
     -H "Authorization: Bearer $TOKEN"

curl -X GET https://app.securities.com.br/api/v1/documents/:document_id/signers \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "signers": [
    {
      "id": 3,
      "full_name": "John Carter",
      "has_documentation": false,
      "documentation": null,
      "email": "signer@example.com",
      "birthday": "1987-09-09",
      "phone_number": "(16) 98234-3045",
      "auth": "email",
      "communicate_by": "email",
      "key": "690e1c32-7edd-48e4-b083-a738f05b4d7e",
      "sign_as": "sign",
      "selfie_enabled": false,
      "official_document_enabled": false,
      "liveness_enabled": false,
      "handwritten_enabled": false,
      "facial_biometrics_enabled": false,
      "created_at": "2022-09-08T15:37:05.189-03:00",
      "updated_at": "2022-09-15T15:26:18.880-03:00",
      "url": "https://app.securities.com.br/api/v1/signers/3" 
    }
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todos os signatários

Todos os signatários

GET https://app.securities.com.br/api/v1/signers


Signatários por documento

GET https://app.securities.com.br/api/v1/documents/:document_id/signers

Parâmetro Tipo Descrição
page integer Paginação

Obter signatário

Request:

curl -X GET https://app.securities.com.br/api/v1/documents/:document_id/signers/:id \
     -H "Authorization: Bearer $TOKEN"

curl -X GET https://app.securities.com.br/api/v1/signers/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "signer": {
    "id": 1,
    "full_name": "John Carter",
    "has_documentation": false,
    "documentation": null,
    "email": "signer@example.com",
    "birthday": "1987-09-09",
    "phone_number": "(16) 98234-3045",
    "auth": "email",
    "communicate_by": "email",
    "key": "690e1c32-7edd-48e4-b083-a738f05b4d7e",
    "sign_as": "sign",
    "selfie_enabled": false,
    "official_document_enabled": false,
    "liveness_enabled": false,
    "handwritten_enabled": false,
    "facial_biometrics_enabled": false,
    "created_at": "2022-09-08T15:37:05.189-03:00",
    "updated_at": "2022-09-15T15:26:18.880-03:00"
  }
}

Esse endpoint obtém todos os dados de um signatário. É possível obter o signatário pelo :id ou pela :key

Obter signatário

GET https://app.securities.com.br/api/v1/signers/:id
GET https://app.securities.com.br/api/v1/signers/bykey/:key


Obter signatário de um documento

GET https://app.securities.com.br/api/v1/documents/:document_id/signers/:id
GET https://app.securities.com.br/api/v1/documents/:document_id/signers/bykey/:key

Criar signatário

Request:

curl -X POST https://app.securities.com.br/api/v1/documents/:document_id/signers \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
          "signer": {
            "email": "fulano@example.com",
            "auth": "email",
            "full_name": "Marcos Zumba",
            "has_documentation": true,
            "documentation": "123.321.123-40",
            "birthday": "1983-03-31",
            "phone_number": "11999999999",
            "sign_as": "sign",
            "communicate_by": "email"
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "signer": {
    "id": 4,
    "full_name": "Marcos Zumba",
    "has_documentation": true,
    "documentation": "123.321.123-40",
    "email": "fulano@example.com",
    "birthday": "1983-03-31",
    "phone_number": "11999999999",
    "auth": "email",
    "communicate_by": "email",
    "key": null,
    "sign_as": "sign",
    "selfie_enabled": false,
    "official_document_enabled": false,
    "liveness_enabled": false,
    "handwritten_enabled": false,
    "facial_biometrics_enabled": false,
    "created_at": "2022-09-16T18:41:00.079-03:00",
    "updated_at": "2022-09-16T18:41:00.079-03:00"
  }
}

Esse endpoint cria um signatário

Criar signatário avulso

POST https://app.securities.com.br/api/v1/signers


Criar signatário vinculado a um documento

POST https://app.securities.com.br/api/v1/documents/:document_id/signers

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "signer": {
    "id": 4,
    "full_name": "Marcos Zumba",
    "has_documentation": true,
    "documentation": "123.321.123-40",
    "email": "fulano@example.com",
    "birthday": "1983-03-31",
    "phone_number": "11999999999",
    "auth": "email",
    "communicate_by": "email",
    "key": null,
    "sign_as": "sign",
    "selfie_enabled": false,
    "official_document_enabled": false,
    "liveness_enabled": false,
    "handwritten_enabled": false,
    "facial_biometrics_enabled": false,
    "created_at": "2022-09-16T18:41:00.079-03:00",
    "updated_at": "2022-09-16T18:41:00.079-03:00"
  },
  "lists": [
    {
      "id": 113,
      "signer_id": 4,
      "document_id": 43,
      "key": "2dd1f865-2154-4f7c-8b3b-9bcbcbcbac9b",
      "batch_key": "14fb4ce9-f28e-4954-a884-ad125931181b",
      "request_signature_key": "c1243577-73f5-4071-9ba4-59d5a2f13ee7",
      "signed": false,
      "sign_as": "sign",
      "created_at": "2022-10-26T15:53:18.825-03:00",
      "updated_at": "2022-10-26T15:55:51.010-03:00",
      "url": "https://app.securities.com.br/api/v1/lists/113"
    }
  ]
}
Parâmetro Obrigatório Tipo Descrição
full_name sim string Nome completo
has_documentation não boolean (default true) Tem documentação, como CPF, CNPJ ou Passaporte.
documentation condicional string CPF, CNPJ ou Passaporte
birthday condicional string Data de nascimento
email condicional string E-mail
phone_number sim string Número de telefone
auth sim string Tipo de autenticação: "email", "api" ou "tokenless", "icp_brasil" (Certificado digital)
communicate_by sim string Por onde será notificado: "email"
sign_as sim string Assinar como: sign, party, witness, contractor, contractee...
selfie_enabled não boolean (default false) Define a solicitação de selfie dinâmica como ponto de autenticação para o signatário.
handwritten_enabled não boolean (default false) Define a solicitação de assinatura manuscrita como ponto de autenticação para o signatário.
official_document_enabled não boolean (default false) Define a solicitação da foto (frente e verso) do documento oficial como ponto de autenticação para o signatário.
liveness_enabled não boolean (default false) Define a solicitação de selfie dinâmica como ponto de autenticação para o signatário.
facial_biometrics_enabled não boolean (default false) Define a solicitação de biometria facial como ponto de autenticação para o signatário.

CCB

CCB é a Cédula de crédito bancário: A Cédula de Crédito Bancário é título de crédito emitido por emissor-devedor em favor de instituição financeira, representando promessa de pagamento em dinheiro, decorrente de operação de crédito, de qualquer modalidade. Sobre a regulação da CCB, vide o art. 26 da Lei 10.931/2004.

Em outras palavras, a CCB é o que representará um crédito tomado e que foi assinado pelo tomador para que possa ser negociado como um título no mercado financeiro.

ATENCÃO

Foram atualizadas as rotas das CCBs:

Antes: /api/v1/securities

Agora: /api/v1/bank_credit_notes

Listar CCBs

Request:

curl -X GET https://app.securities.com.br/api/v1/bank_credit_notes \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "bank_credit_notes": [
    {
      "id": 2,
      "number": "123456",
      "issuer_full_name": "Hugo Fonseca",
      "issuer_document": "630.427.604-48",
      "installments": 1,
      "created_at": "2022-09-15T15:27:00.691-03:00",
      "updated_at": "2022-09-15T15:27:00.691-03:00",
      "url": "https://app.securities.com.br/api/v1/bank_credit_notes/2"
    }
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todas as CCBs

GET https://app.securities.com.br/api/v1/bank_credit_notes

Parâmetro Tipo Descrição
number string Número da CCB
page integer Paginação

Obter CCB

Request:

curl -X GET https://app.securities.com.br/api/v1/bank_credit_notes/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "bank_credit_note": {
    "id": 2,
    "number": "123456",
    "issuer_full_name": "Hugo Fonseca",
    "issuer_document": "630.427.604-48",
    "installments": 1,
    "signature_provider": "clicksign",
    "created_at": "2022-09-15T15:27:00.691-03:00",
    "updated_at": "2022-09-15T15:27:00.691-03:00",
    "documents": [
      {
        "id": 23,
        "key": "fadef9ce-0f28-4792-bb3f-6d0bd5c6a055",
        "status": "created",
        "created_at": "2022-10-27T09:44:50.800-03:00",
        "updated_at": "2022-10-27T09:46:45.968-03:00",
        "file": null
      }
    ],
    "url": "https://app.securities.com.br/api/v1/bank_credit_notes/2"
  }
}

Esse endpoint obtém todos os dados de uma CCB. É possível obter a CCB pelo :id ou pelo :number

GET https://app.securities.com.br/api/v1/bank_credit_notes/:id
GET https://app.securities.com.br/api/v1/bank_credit_notes/bynumber/:number

Criar CCB já assinada para Cessão

Request:

curl -v POST https://app.securities.com.br/api/v1/bank_credit_notes \
     -H "Authorization: Bearer $TOKEN"
     -F "file=@file1.pdf"
     -F "signed=true"
     -F "signature_provider=govbr"
     -F "number=37891673"
     -F "installments=12"
     -F "issuer_full_name=Hugo Fonseca"
     -F "issuer_document=04218776143"
     -F "document_data={\"car\": \"Volkswagen\"}"

Response:

HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8

{
  "bank_credit_note": {
    "id": 2,
    "number": "123456",
    "issuer_full_name": "Hugo Fonseca",
    "issuer_document": "630.427.604-48",
    "installments": 1,
    "signature_provider": "clicksign",
    "created_at": "2022-09-15T15:27:00.691-03:00",
    "updated_at": "2022-09-15T15:27:00.691-03:00",
    "documents": [
      {
        "id": 23,
        "key": "fadef9ce-0f28-4792-bb3f-6d0bd5c6a055",
        "status": "validated",
        "created_at": "2022-10-27T09:44:50.800-03:00",
        "updated_at": "2022-10-27T09:46:45.968-03:00",
        "file": {
          "url": "https://example.com/path/to/document.pdf"
        }
      }
    ],
    "url": "https://app.securities.com.br/api/v1/bank_credit_notes/2"
  }
}

Endpoint que recebe títulos CCBs já assinados pelo tomador fora dos produtos Clicksign, mas que serão cedidos na Clicksign Securities.

POST https://app.securities.com.br/api/v1/bank_credit_notes

Essa requisição deve ser um multipart/form-data com os seguintes parâmetros:

Parâmetro Tipo Descrição
file File Upload do pdf que será anexado a CCB
signed boolean Boolean indicando se o pdf fornecido está assinado
signature_provider string String indicando qual assinador foi utilizado. Ver assinadores aceitos abaixo.
number string Número da CCB
issuer_full_name string Nome completo do emitente
issuer_document string Documento do emitente
installments integer Número de parcelas
document_data string Serialização do json com os dados do documento para compor a CCB
Parâmetro (utilizar na request) Nome de exibição
d4sign D4Sign
zapsign ZapSign
docusign Docusign
totvs Assinatura eletrônica TOTVS
autentique Autentique
assinebem Assine Bem
contraktor Contraktor
juridoc Juridoc
santocontrato Santo Contrato
certisign Certisign
signnow SignNow
adobesign Adobe Sign
hellosign Hello Sign
webdox Webdox
sdocsafe Sdoc Safe
accesscorp Access Corp
ebox eBox Digital
arquivar Arquivar
unico Unico
formalizar Formalizar e-Signature
onedoc 1Doc
bry Bry
quicksoft QuickSoft
fepweb FepWeb
govbr Gov.br
flexdoc Flexdoc
brysigner Bry Signer
besign Besign
letssign LetsSign
assertiva Assertiva
optime Optime
digicert Digicert
qcertifica Q Certifica
fast4sign Fast4Sign
bancomaster Banco Master

Cessão de títulos

Arranjo

Partes envolvidas no processo de compra e venda de uma operação financeira. São os stakeholders da operação de oferta e aceite de CCBs, que vão originar, enviar para assinatura do tomador e por fim, vender esses títulos aos fundos. Juntos, essas partes formam um arranjo que fazem negociações entre si e possuem contas de originação e destino dentro desse grupo.

Listar Arranjos

Request:

curl -X GET https://app.securities.com.br/api/v1/arrangements \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "arrangements": [
    {
      "id": 120,
      "account_id": 7,
      "name": "Arranjo 1",
      "operation_type": "duplicate",
      "url": "https://app.securities.com.br/api/v1/arrangements/120"
    },
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todos os Arranjos nos quais a conta é cessionária

GET https://app.securities.com.br/api/v1/arrangements

Parâmetro Tipo Descrição
page integer Paginação

Obter Arranjo

Request:

curl -X GET https://app.securities.com.br/api/v1/arrangements/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "arrangement": {
    "id": 120,
    "account_id": 7,
    "name": "Arranjo 1",
    "operation_type": "duplicate",
    "signers": [
      {
        "id": 500,
        "full_name": "Bilck Endorser",
        "has_documentation": true,
        "documentation": "304.336.560-77",
        "email": "guilherme.bilck+endossante@clicksign.com",
        "birthday": "1981-08-17",
        "phone_number": "+5561999999999",
        "auth": "email",
        "communicate_by": "email",
        "key": "e19a0a2a-e245-45bc-a914-1c42c587cf45",
        "sign_as": "endorser",
        "selfie_enabled": false,
        "official_document_enabled": false,
        "liveness_enabled": false,
        "handwritten_enabled": false,
        "facial_biometrics_enabled": false,
        "created_at": "2023-03-08T15:05:45.342-03:00",
        "updated_at": "2023-03-08T15:05:45.499-03:00"
      }
    ]
  }
}

Esse endpoint obtém todos os dados de um Arranjo

GET https://app.securities.com.br/api/v1/arrangements/:id

Termos de Cessão

O termo de cessão é o instrumento através do qual se opera a transmissão de direitos sobre determinado bem. Por meio dela, o vendedor, conhecido como cedente, repassa ao comprador, denominado cessionário, os direitos sobre o bem objeto da Cessão.

O termo de cessão é o documento que transcreve de forma resumida a operação que está sendo cedida naquele momento, com o resumo das CCBs que estão em operação no lote.

Listar termos de cessão

Request:

curl -X GET https://app.securities.com.br/api/v1/assignments \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": 1,
    "arrangement_id": 1,
    "batch_id": 3,
    "number": "123456",
    "issue_date": "2022-09-30",
    "status": "pending",
    "full_amount": "100.0",
    "operation_type": "duplicate",
    "created_at": "2022-09-30T18:13:53.140-03:00",
    "updated_at": "2022-09-30T18:13:53.175-03:00",
    "url": "https://app.securities.com.br/api/v1/assignments/1"
  }
]

Esse endpoint lista todos os termos de cessão

GET https://app.securities.com.br/api/v1/assignments

Obter contrato de cessão

Request:

curl -X GET https://app.securities.com.br/api/v1/assignments/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": 1,
  "arrangement_id": 1,
  "batch_id": 3,
  "number": "123456",
  "issue_date": "2022-09-30",
  "status": "pending",
  "full_amount": "100.0",
  "operation_type": "duplicate",
  "created_at": "2022-09-30T18:13:53.140-03:00",
  "updated_at": "2022-09-30T18:13:53.175-03:00",\
  "template_data": {
    "total_value": "1000,00",
    "installments": "24",
    "bank_name": "Itau",
    ...
  },
  "batch": {
    "id": 3,
    "status": "signing",
    "number": "508",
    "quantity": 1,
    "quantity_approved": 1
  },
  "documents": [
    {
      "id": 23,
      "key": "fadef9ce-0f28-4792-bb3f-6d0bd5c6a055",
      "status": "created",
      "created_at": "2022-10-27T09:44:50.800-03:00",
      "updated_at": "2022-10-27T09:46:45.968-03:00",
      "file": null
    }
  ],
  "url": "https://app.securities.com.br/api/v1/assignments/1"
}

Esse endpoint obtem todos os dados de um termo de cessão. É possível obter um termo pelo :id ou pelo :number

GET https://app.securities.com.br/api/v1/assignments/:id
GET https://app.securities.com.br/api/v1/assignments/bynumber/:number

Criar termo de cessão

Request:

curl -X POST https://app.securities.com.br/api/v1/assignments \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
          "assignment": {
            "arrangement_id": 1,
            "number": "123456",
            "issue_date": "2022-09-30",
            "full_amount": 100.0,
            "batch_id": 3
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "id": 1,
  "arrangement_id": 1,
  "batch_id": 3,
  "number": "123456",
  "issue_date": "2022-09-30",
  "status": "pending",
  "full_amount": "100.0",
  "operation_type": "duplicate",
  "created_at": "2022-09-30T18:13:53.140-03:00",
  "updated_at": "2022-09-30T18:13:53.175-03:00",
  "batch": {
    "id": 3,
    "status": "signing",
    "number": "508",
    "quantity": 1,
    "quantity_approved": 0
  },
  "documents": [
    {}
  ],
  "url": "https://app.securities.com.br/api/v1/assignments/1"
}

Esse endpoint cria um termo de cessão

POST https://app.securities.com.br/api/v1/assignments

Parâmetro Obrigatório Tipo Descrição
arrangement_id sim integer ID do Arranjo da cessão
number sim string Número do termo de cessão
issue_date sim date (YYYY-MM-DD) Data de emissão
full_amount sim float Valor do termo (soma de todos os títulos)
batch_id sim integer ID do Lote de CCBs

Validações

O valor inserido em full_amount não é validado, ou seja, se inserir um valor diferente da soma dos valores dos títulos poderá ter divergências. O motivo da não validação é porque o valor negociado pode ser menor que o valor da soma dos títulos, sendo assim, não há com que comparar os valores inseridos, sendo esperado, em alguns casos, alguma divergência.

Lote

O Lote de cessão é o conjunto de CCBs que estão agrupadas para a mesma finalidade: Serem cedidas numa negociação entre cedente e cessionário.

Listar lotes

Request:

curl -X GET https://app.securities.com.br/api/v1/batches \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "batches": [
    {
      "id": 1,
      "status": "pending",
      "number": "123",
      "quantity": 1,
      "quantity_added": 1,
      "quantity_approved": 1,
      "quantity_signed": 1,
      "created_at": "2022-10-06T16:46:40.705-03:00",
      "updated_at": "2022-10-06T16:46:40.889-03:00",
      "url": "https://app.securities.com.br/api/v1/batches/1"
    }
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todos os lotes

GET https://app.securities.com.br/api/v1/batches

Parâmetro Tipo Descrição
page integer Paginação

Obter um lote

Request:

curl -X GET https://app.securities.com.br/api/v1/batches/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "batch": {
    "id": 1,
    "status": "pending",
    "number": "123",
    "quantity": 1,
    "quantity_added": 1,
    "quantity_approved": 1,
    "quantity_signed": 1,
    "created_at": "2022-10-06T16:46:40.705-03:00",
    "updated_at": "2022-10-06T16:46:40.889-03:00"
  }
}

Esse endpoint obtem todos os dados de um lote

GET https://app.securities.com.br/api/v1/batches/:id

Criar lote

Request:

curl -X POST https://app.securities.com.br/api/v1/batches \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
          "batch": {
            "number": "123",
            "quantity": 1
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "batch": {
    "id": 1,
    "status": "pending",
    "number": "123",
    "quantity": 1,
    "quantity_added": 0,
    "quantity_approved": 0,
    "quantity_signed": 0,
    "created_at": "2022-10-06T16:46:40.705-03:00",
    "updated_at": "2022-10-06T16:46:40.889-03:00"
  }
}

Esse endpoint cria um lote

POST https://app.securities.com.br/api/v1/batches

Parâmetro Obrigatório Tipo Descrição
quantity sim integer Quantidade de títulos no lote
number sim string Número do lote

Validações

Enquanto quantity não for equivalente a quantidade total de títulos do lote, o processamento não será finalizado, o status iniciará em pending, irá para checking após adicionar o primeiro título no lote e, até que todos os títulos sejam enviados, permanecerá nesse status.

CCB em Lote

Endpoints utilizados para vincular CCBs a um Lote específico, permitindo futuras consultas de lastro da operação por completo, considerando seu ciclo de vida.

Listar CCBs do lote

Request:

curl -X GET https://app.securities.com.br/api/v1/batches/:batch_id/security_batches \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "security_batches": [
    {
      "id": 1,
      "security_id": 1,
      "batch_id": 1,
      "status": "pending",
      "created_at": "2022-10-06T16:46:40.705-03:00",
      "updated_at": "2022-10-06T16:46:40.889-03:00",
      "url": "https://app.securities.com.br/api/v1/batches/1/security_batches/1"
    }
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todas as CCBs do lote

GET https://app.securities.com.br/api/v1/batches/:batch_id/security_batches

Parâmetro Tipo Descrição
page integer Paginação

Obter uma CCB do lote

Request:

curl -X GET https://app.securities.com.br/api/v1/batches/:batch_id/security_batches/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "security_batch": {
    "id": 1,
    "security_id": 1,
    "batch_id": 1,
    "status": "pending",
    "created_at": "2022-10-06T16:46:40.705-03:00",
    "updated_at": "2022-10-06T16:46:40.889-03:00"
  }
}

Esse endpoint obtem todos os dados de uma CCB de um lote

GET https://app.securities.com.br/api/v1/batches/:batch_id/security_batches/:id

Adicionar CCB no lote

Request:

curl -X POST https://app.securities.com.br/api/v1/batches/:batch_id/security_batches \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
          "security_batch": {
            "security_data": {
              "number": "123456",
              "assignor_name": "Fulano",
              "cession_value": "2002.20",
              "number": "12346"
            }
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "security_batch": {
    "id": 1,
    "security_id": 1,
    "batch_id": 1,
    "status": "pending",
    "created_at": "2022-10-06T16:46:40.705-03:00",
    "updated_at": "2022-10-06T16:46:40.889-03:00"
  }
}

Esse endpoint adiciona uma CCB no lote

POST https://app.securities.com.br/api/v1/batches/:batch_id/security_batches

Parâmetro Obrigatório Tipo Descrição
security_data sim jsonb metadados da CCB

OBS: O parâmetro security_data deve conter o atributo number com o número da CCB.

Validações

Não será permitido enviar uma CCB se não for criada uma cessão associada ao lote.

Enquanto quantity não for equivalente a quantidade total de CCBs do lote, o processamento não será finalizado, o status iniciará em pending, irá para checking após adicionar o primeiro CCB no lote e, até que todas as CCBs sejam enviadas, permanecerá nesse status.

Não será permitido enviar uma quantidade de CCBs maior que quantity.

Não será permitido enviar uma CCB que já esteja no lote.

Duplicatas

A duplicata é um título de crédito que representa uma venda a prazo. Ela é emitida pelo vendedor e entregue ao comprador como comprovante de que existe uma dívida a ser paga. Com a duplicata, o vendedor terá a certeza de que receberá o valor da venda

Listar Duplicatas

Request:

curl -X GET https://app.securities.com.br/api/v1/duplicates \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "duplicates": [
    {
      "id": 2,
      "number": "123456",
      "issuer_full_name": "Hugo Fonseca",
      "issuer_document": "630.427.604-48",
      "total_value": 9999.99,
      "invoice": "99999",
      "created_at": "2022-09-15T15:27:00.691-03:00",
      "updated_at": "2022-09-15T15:27:00.691-03:00",
      "url": "https://app.securities.com.br/api/v1/duplicates/2"
    }
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todas as Duplicatas

GET https://app.securities.com.br/api/v1/duplicates

Parâmetro Tipo Descrição
number string Número da Duplicata
page integer Paginação

Obter Duplicata

Request:

curl -X GET https://app.securities.com.br/api/v1/duplicates/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "duplicate": {
    "id": 2,
    "number": "123456",
    "issuer_full_name": "Hugo Fonseca",
    "issuer_document": "630.427.604-48",
    "total_value": 9999.99,
    "invoice": "99999",
    "created_at": "2022-09-15T15:27:00.691-03:00",
    "updated_at": "2022-09-15T15:27:00.691-03:00",
    "documents": [
      {
        "id": 23,
        "key": "fadef9ce-0f28-4792-bb3f-6d0bd5c6a055",
        "status": "created",
        "created_at": "2022-10-27T09:44:50.800-03:00",
        "updated_at": "2022-10-27T09:46:45.968-03:00",
        "file": null
      }
    ],
    "url": "https://app.securities.com.br/api/v1/duplicates/2"
  }
}

Esse endpoint obtém todos os dados de uma Duplicata. É possível obter a CCB pelo :id ou pelo :number

GET https://app.securities.com.br/api/v1/duplicates/:id
GET https://app.securities.com.br/api/v1/duplicates/bynumber/:number

Duplicata em Lote

Endpoints utilizados para vincular Duplicatas a um Lote específico, permitindo futuras consultas de lastro da operação por completo, considerando seu ciclo de vida.

Listar Duplicatas do lote

Request:

curl -X GET https://app.securities.com.br/api/v1/batches/:batch_id/duplicates/security_batches \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "security_batches": [
    {
      "id": 1,
      "security_id": 1,
      "batch_id": 1,
      "status": "pending",
      "created_at": "2022-10-06T16:46:40.705-03:00",
      "updated_at": "2022-10-06T16:46:40.889-03:00",
      "url": "https://app.securities.com.br/api/v1/batches/1/duplicates/security_batches/1"
    }
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todas as Duplicatas do lote

GET https://app.securities.com.br/api/v1/batches/:batch_id/duplicates/security_batches

Parâmetro Tipo Descrição
page integer Paginação

Obter uma Duplicata do lote

Request:

curl -X GET https://app.securities.com.br/api/v1/batches/:batch_id/duplicates/security_batches/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "security_batch": {
    "id": 1,
    "security_id": 1,
    "batch_id": 1,
    "status": "pending",
    "created_at": "2022-10-06T16:46:40.705-03:00",
    "updated_at": "2022-10-06T16:46:40.889-03:00"
  }
}

Esse endpoint obtém todos os dados de uma Duplicata de um lote

GET https://app.securities.com.br/api/v1/batches/:batch_id/duplicates/security_batches/:id

Adicionar Duplicata no lote

Request:

curl -X POST https://app.securities.com.br/api/v1/batches/:batch_id/duplicates/security_batches \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
          "security_batch": {
            "security_data": {
              "number": "123456",
              "issuer_full_name": "Fulano",
              "issuer_document": "54194131000186",
              "total_value": 12554.42,
              "invoice": "551000125"
            }
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "security_batch": {
    "id": 1,
    "security_id": 1,
    "batch_id": 1,
    "status": "pending",
    "created_at": "2022-10-06T16:46:40.705-03:00",
    "updated_at": "2022-10-06T16:46:40.889-03:00"
  }
}

Esse endpoint adiciona uma Duplicata no lote

POST https://app.securities.com.br/api/v1/batches/:batch_id/duplicates/security_batches

Parâmetro Obrigatório Tipo Descrição
security_data sim jsonb metadados da Duplicata

Validações

Não será permitido enviar uma Duplicata se não for criada uma cessão associada ao lote.

Enquanto quantity não for equivalente a quantidade total de Duplicatas do lote, o processamento não será finalizado, o status iniciará em pending, irá para checking após adicionar a primeira Duplicata no lote e, até que todas as Duplicatas sejam enviadas, permanecerá nesse status.

Não será permitido enviar uma quantidade de Duplicatas maior que quantity.

Não será permitido enviar uma Duplicata que já esteja no lote.

Documentos

Recursos utilizados para gerenciar arquivos em PDF.

Obter um documento pela key

Request:

curl -X GET https://app.securities.com.br/api/v1/documents/bykey/:key \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "document": {
        "id": 394193,
        "key": "0aa3e5bc-3a88-4873-b680-8ec7ecea585e",
        "status": "validated",
        "created_at": "2023-07-24T10:53:54.295-03:00",
        "updated_at": "2023-07-24T11:02:44.586-03:00",
        "file": {
            "url": "https://securities-app.s3.amazonaws.com/"
        }
    }
}

Esse endpoint obtêm um documento e pela key.

GET https://app.securities.com.br/api/v1/documents/bykey/:key

Parâmetro Tipo Descrição
key uuid Chave do documento

Signatário do documento

Endpoint utilizado para adicionar um ou mais signatários a um documento que deverá ser assinado.

Listar signatários do documento

Request:

curl -X GET https://app.securities.com.br/api/v1/lists \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "lists": [
    {
      "id": 113,
      "signer_id": 18,
      "document_id": 43,
      "key": "2dd1f865-2154-4f7c-8b3b-9bcbcbcbac9b",
      "batch_key": "14fb4ce9-f28e-4954-a884-ad125931181b",
      "request_signature_key": "c1243577-73f5-4071-9ba4-59d5a2f13ee7",
      "signed": false,
      "sign_as": "sign",
      "created_at": "2022-10-26T15:53:18.825-03:00",
      "updated_at": "2022-10-26T15:55:51.010-03:00",
      "url": "https://app.securities.com.br/api/v1/lists/113"
    }
  ],
  "page_infos": {
    "total_pages": 3,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "first_page?": true,
    "last_page?": false
  }
}

Esse endpoint lista todos signatários de um documento e vice-versa

GET https://app.securities.com.br/api/v1/lists

Parâmetro Tipo Descrição
page integer Paginação

Obter signatário do documento

Request:

curl -X GET https://app.securities.com.br/api/v1/lists/:id \
     -H "Authorization: Bearer $TOKEN"

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "list": {
    "id": 113,
    "signer_id": 18,
    "document_id": 43,
    "key": "2dd1f865-2154-4f7c-8b3b-9bcbcbcbac9b",
    "batch_key": "14fb4ce9-f28e-4954-a884-ad125931181b",
    "request_signature_key": "c1243577-73f5-4071-9ba4-59d5a2f13ee7",
    "signed": false,
    "sign_as": "sign",
    "created_at": "2022-10-26T15:53:18.825-03:00",
    "updated_at": "2022-10-26T15:55:51.010-03:00"
  }
}

Esse endpoint obtém todos signatários de um documento e vice-versa

GET https://app.securities.com.br/api/v1/lists/:id

Adicionar signatários no documento

Request:

curl -X POST https://app.securities.com.br/api/v1/lists \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
          "list": {
            "signer_id": 1,
            "document_id": 2,
            "sign_as": "sign",
            "group": null,
            "message": null,
            "refusable": false
          }
        }'

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "list": {
    "id": 113,
    "signer_id": 18,
    "document_id": 43,
    "key": "2dd1f865-2154-4f7c-8b3b-9bcbcbcbac9b",
    "batch_key": "14fb4ce9-f28e-4954-a884-ad125931181b",
    "request_signature_key": "c1243577-73f5-4071-9ba4-59d5a2f13ee7",
    "sign_as": "sign",
    "created_at": "2022-10-26T15:53:18.825-03:00",
    "updated_at": "2022-10-26T15:55:51.010-03:00"
  }
}

Esse endpoint associa o signatário a um documento e vice-versa

POST https://app.securities.com.br/api/v1/lists

Parâmetro Obrigatório Tipo Descrição
signer_id sim integer ID do signatário
document_id sim string ID do documento
sign_as não string Assinar como: sign (padrão), party, witness, contractor...
group não integer Determina o grupo que o signatário deve ser vinculado.Deve ser número, inteiro e maior que 0
message não string Mensagem que será enviada no body do e-mail de solicitação de assinatura aos signatários.
refusable não boolean Determina se o signatário pode recusar ou não a assinatura do documento.
Shell