NAV
json

Introdução

Requisições e respostas

Nossa API utiliza o padrão REST, todas as requisições e respostas são no formato JSON e os endpoints utilizam como base os seguintes endereços:

Para indiciar sucesso na operação utilizaremos um código HTTP >= 200 e <400. Além disso, JSON retornado contém um campo booleano chamado success que pode ser utilizado no lugar dos códigos para verificar o sucesso da operação.

A segurança no envio e recebimento dos dados é realizada através de autenticação via token.

Alem do bearer token, deve ser enviado o parterHashId e userHashId quando necessários. Os parâmetros parterHashId e userHashId serão diferentes entre os ambientes produção e sandbox.
Você deve solicitar esses parâmetros ao responsável da Credoro.

Observações quanto aos tipos de campos

Tipo Formato
Date Utiliza o formato DD/MM/YYYY, exemplo 29/10/2021
Date Utiliza o formato DD-MM-YYYY HH:MM:SS, exemplo 29-10-2021 00:00:00

Observações quanto a obrigatoriedade de campos

A coluna Obrigatório presente na secção URL Parameters e Body Parameters de cada endpoint, pode assumir um dos seguintes valores:

Utilizaremos expressões no campo Obrigatório para determinar sua obrigatoriedade com base em outro campo submetido.

Parceiro

TODO: Explicar sobre o hash id do parceiro.

Autenticação

A autenticação é feita através do envio de um token no header das requisições, exemplo:

Authorization: Bearer token_here

Cliente

Criar

Criar cliente para utilização na criação de operações.

Criação de clientes

{
   "partner_id":"hash",
   "person_type":"1",
   "tax_id":"83680274971",
   "name":"Maya Márcia da Paz",
   "company_name":"",
   "address_zipcode":"88904278",
   "address_street":"Rua Madre Tereza de Calcutá",
   "address_number":"556",
   "address_complement":"",
   "address_district":"Lagoão",
   "address_city_id":"4330",
   "address_city_name":"Araranguá - SC",
   "address_state_id":null,
   "address_state_code":null,
   "address_state_name":null,
   "name_contact":"Maya Márcia da Paz",
   "email_contact":"[email protected]",
   "phone_1":"4837604183",
   "phone_2":"48993397760",
   "notes":"",
   "cpf_contact":"83680274971",
   "mother_name":"Laura Flávia",
   "birthday":"03/08/1992",
   "open_date":"",
   "main_activity":"",
   "revenue":[
      "001",
      "001",
      "001",
      "001",
      "001",
      "001",
      "001",
      "001",
      "001",
      "001",
      "001",
      "001"
   ],
   "revenue_avg":",00",
   "partner_user_id":"nzkevq3g35",
   "bank_id":"1",
   "bank_agency":"0737",
   "bank_agency_digit":"0",
   "bank_number":"62902",
   "bank_digit":"2",
   "bank_account_type":"1",
   "bank_name":"Maya Márcia da Paz",
   "bank_document":"83680274971"
}

HTTP Request

POST /partner-customer/insert

Body Parameters

Propriedade Tipo Obrigatório Descrição
partner_id Texto Sim Hash Id do parceiro relacionado
person_type Texto Sim Informe 1 para "PF" ou 2 para "PJ"
tax_id Texto Sim "CPF" ou "CNPJ", apenas números
name Texto Sim Nome do cliente quando for "PF" e nome da empresa quando for "PJ"
company_name Texto Quando for PJ Razão Social da empresa
address_zipcode Texto Sim CEP
address_street Texto Sim Nome da rua
address_number Número Sim Número
address_complement Texto Não Complemento do endereço
address_district Texto Sim Bairro
address_city_id Número Sim Id da Cidade, buscar o id na lista de cidades
address_state_id Número Sim Id do Estado, buscar junto a lista de cidades
name_contact Texto Sim Nome para contato
email_contact Texto Sim E-mail para contato
phone_1 Texto Não Telefone
phone_2 Texto Sim Celular
notes Texto Não Observações
cpf_contact Texto Sim CPF do responsável
mother_name Texto Sim Nome da mãe do responsável
birthday Data Sim Data de nascimento. Formato DD/MM/YYYY
open_date Data Quando for PF Data de nascimento. Formato DD/MM/YYYY
main_activity Texto Quando for PF Atividade Principal
revenue Lista Quando for PF Informar faturamento de cada mês

Os campos abaixo, devem ser informados quando a configuração do parceiro exigir conta bancária.

Propriedade Tipo Obrigatório Descrição
bank_id Número Sim Id do banco, buscar o id na lista de bancos
bank_agency Texto Sim Número da Agência
bank_agency_digit Texto Sim Digito verificador da agênvia. Quando não exisitr, informe "0"
bank_number Texto Sim Número da conta
bank_digit Texto Sim Digito verificado da conta
bank_account_type Texto Sim Informe 1 para Conta Corrente e 2 para Conta Poupança
bank_name Texto Sim Nome do titular da conta
bank_document Texto Sim CPF ou CNPJ da conta

Exemplo de response com sucesso:

{
    "data": {
        "id": "hash"
    },
    "success": true
}

Atualizar

HTTP Request

PUT /partner-customer/update/{customerHashId}

Utilize os mesmos campos e regras da criação de clientes.

Obter

Obter os dados de um único cliente.

HTTP Request

PUT /partner-customer/get/{customerHashId}

Exemplo de response com sucesso:

{
    "data": {
        "id": "hash",
        "name": "HEITOR MORAES",
        "notes": "",
        "tax_id": "CPF ou CNPJ",
        "bank_id": null,
        "phone_1": "",
        "phone_2": "48999999999",
        "revenue": ["001","001","001","001","001","001","001","001","001","001","001","001"],
        "birthday": "26/06/1997",
        "bank_name": null,
        "open_date": null,
        "bank_digit": null,
        "partner_id": "hash",
        "bank_agency": null,
        "bank_number": null,
        "cpf_contact": "CPF ou CNPJ",
        "mother_name": "",
        "person_type": 1,
        "company_name": "",
        "name_contact": "HEITOR MORAES DO PRADO",
        "bank_document": null,
        "email_contact": "[email protected]",
        "main_activity": "",
        "address_number": "100",
        "address_street": "Rua 20 de Abril",
        "bank_code_name": "",
        "address_city_id": 4330,
        "address_zipcode": "88900047",
        "address_district": "Centro",
        "address_state_id": 22,
        "address_city_name": "Araranguá",
        "bank_account_type": null,
        "bank_agency_digit": null,
        "address_complement": "",
        "address_state_code": "SC",
        "address_state_name": "Santa Catarina"
    },
    "success": true
}

Obter todos

HTTP Request

GET /partner-customer/all/{partnerHashId}

Exemplo de filtro e paginação

{
    "limit": 50,
    "filter": {
        "filter": "Fabiel"
    },
    "offset": 0
}

Exemplo de response

{
    "data": {
        "total": "2",
        "values": [
            {
                "id": "hash",
                "name": "Credoro",
                "tax_id": "XXX.XXX.XXX-XX",
                "created_at": 1652708353,
                "term_accept": false,
                "email_contact": "[email protected]",
                "partner_term_accept_config": false
            },
            //...
        ]
    },
    "success": true
}

Body Parameters

Propriedade Tipo Obrigatório Descrição
limit Inteiro Não Determina o limite de dados retornados
offset Inteiro Não Determina a quantidade registros a serem "ignorados"
filter Objeto Não Informe o paramêtro "filter" para pesquisar pelo nome do cliente.

Reenviar termos de aceite

HTTP Request

GET /partner-customer/resend-access-terms-email?customerHashId=hash

Exemplo de response sucesso

{
    "data": [],
    "success": true
}

Operação

Permite criar e consultar operações de emprestimo.

Criar

Criar uma operação em consjuto a criação do cliente.

Exemplo de request pessoa física (PF)

{
  "name": "Joaquim Giovanni Murilo Moura",
  "person_type": "PF",
  "tax_id": "00011122244",
  "birthdate": "27/06/1952",
  "phone1": "1122223333",
  "phone2": "11922223333",
  "phone3": "1122223333",
  "email_contact": "[email protected]",
  "postal_code": "01234567",
  "address_street": "Rua Raimundo Ferreira",
  "address_complement": "",
  "address_number": "521",
  "address_district": "Conjunto Universitário",
  "city": "Rio Branco",
  "state": "AC",
  "amount": 1200,
  "installment": 12
}

Exemplo de request pessoa jurídica (PJ)

{
  "name": "Erick Locações de Automóveis",
  "company_name": "Luzia e Erick Locações de Automóveis Ltda",
  "person_type": "PJ",

  "tax_id": "94872972000110",

  "phone1": "1122223333",
  "phone2": "11922223333",
  "phone3": "1122223333",

  "postal_code": "01234567",
  "address_street": "Praça Vidal Antônio de Castro",
  "address_complement": "casa",
  "address_number": "682",
  "address_district": "Lapa",
  "city": "São Paulo",
  "state": "SP",

  "name_contact": "Alexandre Vieira",
  "cpf_contact": "66978847380",
  "email_contact": "[email protected]",

  "opendate": "10/12/2010",
  "main_activity": "Atividade principal",

  "amount": 1000.00,
  "installment": 4,
  "revenue": {
    "1": "2522",
    "2": "5454",
    "3": "5454",
    "4": "5454",
    "5": "5454",
    "6": "5454",
    "7": "5454",
    "8": "5454",
    "9": "5454",
    "10": "5454",
    "11": "5454",
        "12": "5454"
  }
}

Exemplo de request pessoa jurídica (PJ)

{
  "name": "Erick Locações de Automóveis",
  "company_name": "Luzia e Erick Locações de Automóveis Ltda",
  "person_type": "PJ",
  "tax_id": "94872972000110",
  "phone1": "1122223333",
  "phone2": "11922223333",
  "phone3": "1122223333",
  "postal_code": "01234567",
  "address_street": "Praça Vidal Antônio de Castro",
  "address_complement": "casa",
  "address_number": "682",
  "address_district": "Lapa",
  "city": "São Paulo",
  "state": "SP",
  "name_contact": "Alexandre Vieira",
  "cpf_contact": "66978847380",
  "email_contact": "[email protected]",

  "opendate": "10/12/2010",
  "main_activity": "Atividade principal",

  "amount": 1000.00,
  "installment": 4,
  "revenue": {
    "1": "2522",
    "2": "5454",
    "3": "5454",
    "4": "5454",
    "5": "5454",
    "6": "5454",
    "7": "5454",
    "8": "5454",
    "9": "5454",
    "10": "5454",
    "11": "5454",
    "12": "5454"
  }
}

Exemplo de ciração informando apenas o hash id do cliente

{
  "amount": 2390,
  "quantity": "1",
  "partner_id": 20,
  "description": "Descrição do Produto",
  "installment": "15",
  "seller_email": "[email protected]",
  "customer_hashid": "hash"
}

Exemplo de response com sucesso:

{
  "success" : true,
  "data": {
    "operation": "yzjd47d5kn",
    "customer": "0pkgr4d6o3"
  }
}

Exemplo de response com erros de validação:

{
  "success": false,
  "message": {
    "tax_id": [
      "\"Tax Id\" não pode ficar em branco."
    ],
    "person_type": [
      "\"Person Type\" não pode ficar em branco."
    ]
  },
  "data": []
}

Permite criar uma operação para pessoa física ou jurídica.

HTTP Request

POST /operation/create

Body Parameters

Propriedade Tipo Obrigatório Descrição
tax_id String Sim Número do "CPF" ou "CNPJ"
person_type String Sim "PF" ou "PJ"
cpf_contact String Sim Número do CPF de quem assina o contato
name_contact String person_type="PJ" Nome de quem assina o contrato
email_contact String Sim Email de utilizado na assinatura do contrato
name String Sim person_type="PF"
phone1 String Não Número de tefone fixo ou móvel com código de área
phone2 String Sim Aceita somente número móvel com código de área. Ex: xx9xxxxxxxx
phone3 String Não Número de tefone fixo ou móvel com código de área
amount Integer ou Float Sim Valor solicitado. Ex: 1000.00
installment Integer Sim Quantidade de parcelas
city String Sim Cidade. Consulte /city/search para verificar os valores permitidos
state String Sim UF
opendate Date person_type="PJ" Data de fundação da empresa
main_activity String person_type="PJ" Atividade principal
revenue [Integer: Float] person_type="PJ" Faturamento dos últimos 12 meses
birthdate Date Não Data de nascimento
postal_code String Não CEP
address_street String Não Endereço
address_complement String Não Complemento do endereço
address_number String Não Número ou identificador da casa/apartamento...
address_district String Não Bairro do endereço

Response Body:

Propriedade Tipo Descrição
success String Indica se a operação foi criada (true) ou não (false)
data.operation String ID da operação
data.customer String ID do cliente

Todas operações

HTTP Request

POST /partner-operation/all/{partnerHashId}/{userHashId}

Exemplo de filtro e paginação

{
    "limit": 50,
    "filter": {
        "customer": "Nome do Cliente"
    },
    "offset": 0
}

Body Parameters

Propriedade Tipo Obrigatório Descrição
limit Inteiro Não Determina o limite de dados retornados
offset Inteiro Não Determina a quantidade registros a serem "ignorados"
filter Objeto Não Informe o paramêtro "customer" para pesquisar pelo nome do cliente.

Exemplo de response sucesso

{
    "data": [
        {
            "id": "hash da operação",
            "ccb": null,
            "total": "R$ 5.788,80",
            "amount": "3290.0000",
            "quantity": 1,
            "cet_anual": "153,67%",
            "status_id": 5,
            "valor_iof": "R$ 89,59",
            "created_at": 1660238117,
            "signatures": null,
            "customer_id": "hash do cliente",
            "description": "iPhone 11 64gb seminovo",
            "installment": 15,
            "person_type": 1,
            "status_name": "Cancelado",
            "status_slug": "cancelado",
            "uploaded_nfe": false,
            "customer_name": "Fulano de Tal",
            "valor_liquido": "R$ 3.290,00",
            "valor_nominal": "R$ 0,00",
            "taxa_juros_mes": "0,07%",
            "can_be_canceled": false,
            "canceled_message": "Bloqueio automático",
            "shopProofUploaded": false,
            "have_all_documents": true
        },
        //...
    ],
    "success": true
}

Verificar status

Exemplo de response:

{
  "success": true,
  "data": {
    "status": "Autorizado",
    "slug": "autorizado"
  }
}

Permite consultar o status de uma operação.

HTTP Request

GET /operation/status/[hashId]

URL Parameters

Propriedade Tipo Obrigatório Descrição
hashId String Sim ID da operação

Response Body:

Propriedade Tipo Descrição
success String Indica se a operação foi criada (true) ou não (false)
data.status String Nome do status
data.slug String Slug do status

Consultar

Exemplo de response:

{
  "success": true,
  "data": {
    "status_operacao": "em-analise",
    "data_criacao": "2021-10-21 19:16:23",
    "cliente": {
      "nome": "Silvana Letícia Isabelle Moraes",
      "email": "[email protected]",
      "cpf_cnpj": "52147032956",
      "endereco": ", SN casa Conjunto Universitário - 69917750 - Rio Branco/AC",
      "fone": "6825486352",
      "celular": "68996743591",
      "data_nascimento": "13/11/1988",
      "nome_mae": "Dona Tera",
      "data_abertura": null,
      "atividade_principal": null,
      "cpf_contato": "52147032956",
      "nome_contato": "Silvana Letícia Isabelle Moraes",
      "razao_social": "João Vicente Albuquerque"
    },
    "dados_operacao": {
      "valor_solicitado": 1797,
      "valor_nominal": 1797,
      "valor_total": 2559.48,
      "taxa_juros_mensal": 5.4,
      "parcelas": 12,
      "valor_parcela": 213.29
    },
    "assinaturas_coletadas": [],
    "url_assinar_contrato": [],
    "documentos_enviados": {
      "carteira_de_habilitacao_cnh": false,
      "nota_fiscal": false,
      "verso_rg": false,
      "boletos_operations": false,
      "frente_rg": false,
      "comprovante_de_compra": false,
      "boleto_da_compra": false,
      "comprovante_residencia": false,
      "contrato_social": false
    },
    "status_antifraude": null,
    "boletos_gerados": null
  }
}

Lista as informações mais relevantes associadas a operação.

HTTP Request

GET /operation/details/[hashId]

URL Parameters

Propriedade Tipo Obrigatório Descrição
hashId String Sim ID da operação

Upload de documentos

Exemplo de request:

{
  "operation_id" : "9w5g51p111",
  "type" : "cnh",
  "path" : "https://www.example-url.com/images/img-xpto.png",
  "mimetype" : "image/png"
}

Exemplo de response:

{
  "success": true,
  "data": true
}

Lista as informações mais relevantes associadas a operação.

HTTP Request

POST /operation-document/upload/link

Body Parameters

Propriedade Tipo Obrigatório Descrição
operation_id String Sim ID da operação
type proof-residence, social-contract, rg-front, rg-back ou cnh Sim Tipo de documento
link Url Sim Endereço (URL) publico do arquivo a ser carregado
mimetype String Não Mime type do arquivo a ser carregado

Descrição dos tipos

Propriedade Descrição
proof-residence Comprovante de endereço
social-contract Contrato social
rg-front Frente do RG
rg-back Verso do RG
cnh CNH (documento aberto)

Cidade

Permite consultar o nome da cidade e o estado ao qual a mesma faz parte.

Consultar

Exemplo de response para name=salvad

{
  "success": true,
  "data": [
    {
      "id": 435,
      "name": "São Salvador do Tocantins - TO",
      "remote_id": 1720259
    },
    {
      "id": 2163,
      "name": "Salvador - BA",
      "remote_id": 2927408
    },
    {
      "id": 4964,
      "name": "Salvador das Missões - RS",
      "remote_id": 4316477
    },
    {
      "id": 4965,
      "name": "Salvador do Sul - RS",
      "remote_id": 4316501
    }
  ]
}

A propriedade city preenchida ao tentar criar uma operação precisa ser uma correspondência valida, do contrario o processo de criação da operação irá falhar avisando que a cidade informada não é valida.

Caso esteja tendo dificuldade para preencher o campo city ao criar uma operação, utilize este endpoint para aferir o nome correto da cidade.

HTTP Request

POST /city/search?name=[city]

URL Parameters

Propriedade Tipo Obrigatório Descrição
name String Sim Informe o nome de uma cidade ou parte dele

Response Body

Propriedade Tipo Descrição
success String Indica se a operação foi criada (true) ou não (false)
data.id Integer ID da cidade
data.name String Nome da cidade o estado ao qual ela está associada

Banco

Todos

HTTP Request

GET bank/search?search={nome, abreviação ou código}

Exemplo de response

{
    "data": [
        {
            "id": 7,
            "name": "237 - BRADESCO"
        },
        {
            "id": 32,
            "name": "036 - BANCO DO ESTADO DO MARANHAO S.A"
        },
        {
            "id": 134,
            "name": "394 - BANCO B.M.C. S.A"
        },
        {
            "id": 401,
            "name": "122 - BCO BRADESCO BERJ S.A."
        }
    ],
    "success": true
}

Simulação

Obter campos da simulação

Retorna os campos utilizados na simulação.

HTTP Request

POST /simulator/fields-partner/{partnerHashId}

Exemplo de response

{
    "success": true,
    "data": {
        "personType": {
            "required": true,
            "type": "string",
            "label": "Tipo de pessoa",
            "options": [
                {
                    "label": "Física",
                    "value": "PF"
                },
                {
                    "label": "Jurídica",
                    "value": "PJ"
                }
            ],
            "typeView": "radioGroup"
        },
        "amount": {
            "required": true,
            "type": "double",
            "label": "Valor"
        },
        "installments": {
            "required": true,
            "type": "integer",
            "label": "Parcelas",
            "options": {
                "pj": [
                    2,
                    3,
                    4,
                    5,
                    6,
                    7,
                    8,
                    9,
                    10,
                    11,
                    12
                ],
                "pf": [
                    2,
                    3,
                    4,
                    5,
                    6,
                    7,
                    8,
                    9,
                    10,
                    11,
                    12
                ]
            },
            "dependency": "personType",
            "typeView": "dropDownList"
        }
    }
}

Realizar uma simulação

HTTP Request

POST /simulator/partner

Body Parameters

Ver: "Obter campos da simulação" Além dos campos obtidos no enpoint acima, deve ser enviado tambem o "partner_id" no body.

Exemplo de response

{
    "success": true,
    "data": {
        "data_simulacao": "2022-11-29",
        "valor_principal": 3150,
        "valor_simulado": 3150,
        "valor_liquido": 3000,
        "valor_total": 3680.4000000000001,
        "taxa_juros_mes": 5,
        "valor_financiado": 3000,
        "taxa_anual_equivalente": 79.585599999999999,
        "taxa_juros_dia": 5.04,
        "qtde_parcelas": 5,
        "iof_adicional": "0.000082",
        "iof_prazo": 24.773686074068173,
        "iof_financiado": 36.883750921376098,
        "percentual_tac": 0.050000000000000003,
        "tac": 150,
        "percentual_iof": 0.0082000000000000007,
        "percentual_iof_adicional": 0.0082000000000000007,
        "parcelas": [
            {
                "data": "2022-12-29",
                "parcela": 1,
                "dias_juros": 30,
                "saldo_devedor_a_amortizar": 3186.8591703441912,
                "valor_parcela": 736.08000000000004,
                "valor_parcela_sem_iof": 734.66122687795234,
                "pagto_valor_juros": 159.34295851720981,
                "pagto_principal": 576.73704148279023,
                "saldo_devedor_amortizado": 2610.1221288614011,
                "iof_prazo": 1.418773122047664
            },
            {
                "data": "2023-01-29",
                "parcela": 2,
                "dias_juros": 61,
                "saldo_devedor_a_amortizar": 2004.5482353044711,
                "valor_parcela": 736.08000000000004,
                "valor_parcela_sem_iof": 733.05091938442831,
                "pagto_valor_juros": 130.50610644307005,
                "pagto_principal": 605.57389355692999,
                "saldo_devedor_amortizado": 1398.9743417475411,
                "iof_prazo": 3.0290806155717642
            },
            {
                "data": "2023-03-01",
                "parcela": 3,
                "dias_juros": 92,
                "saldo_devedor_a_amortizar": 1368.6956470696946,
                "valor_parcela": 736.08000000000004,
                "valor_parcela_sem_iof": 731.28312807435691,
                "pagto_valor_juros": 100.22741176522355,
                "pagto_principal": 635.85258823477648,
                "saldo_devedor_amortizado": 732.84305883491811,
                "iof_prazo": 4.7968719256431536
            },
            {
                "data": "2023-04-01",
                "parcela": 4,
                "dias_juros": 123,
                "saldo_devedor_a_amortizar": 701.05042942317925,
                "valor_parcela": 736.08000000000004,
                "valor_parcela_sem_iof": 729.3461303348173,
                "pagto_valor_juros": 68.434782353484735,
                "pagto_principal": 667.64521764651533,
                "saldo_devedor_amortizado": 33.405211776663918,
                "iof_prazo": 6.7338696651827536
            },
            {
                "data": "2023-05-01",
                "parcela": 5,
                "dias_juros": 153,
                "saldo_devedor_a_amortizar": 0.022950894338123362,
                "valor_parcela": 736.08000000000004,
                "valor_parcela_sem_iof": 727.28490925437723,
                "pagto_valor_juros": 35.052521471158961,
                "pagto_principal": 701.02747852884113,
                "saldo_devedor_amortizado": -701.00452763450301,
                "iof_prazo": 8.79509074562284
            }
        ],
        "valor_liberado": 3000,
        "valor_iof": 36.883750921376098,
        "valor_custo_bancario": 30,
        "total_operacao": 3066.8837509213763,
        "cet_mensal": 7.2247199999999996,
        "cet_anual": 130.96133,
        "cet_mensal_sem_iof": 7.3420199999999998,
        "cet_anual_sem_iof": 134.01159999999999
    }
}

Errors

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
json