Diretrizes básicas

v2.0: 12 de maio de 2025

Encontre aqui melhores práticas e direções para utilizar APIs e endpoints disponíveis na plataforma.

Antes de começar, verifique as configurações do ambiente de desenvolvimento.

Comportamento do Horizon

Para uma melhor visualização das informações, o Horizon não retorna na resposta da requisição campos que não possuam informações cadastradas nos bancos de dados consultados.

Por exemplo, uma requisição no endpoint de busca de cartão pelo CPF busca os cartões de um portador através do CPF, basta clicar no botão testar na página de documentação do endpoint.

Figura 1. Teste com o CPF do portador do cartão.

Ao fazer a requisição, o Horizon consulta os banco de dados e coleta todas as informações vinculadas ao CPF que farão parte da resposta deste endpoint:

[
  {
    "id": 2001,
    "idPortadorCredito": 2001,
    "cpf": "11111111111",
    "nomePortadorCartao": "Nome Ficticio",
    "statusCartao": "CARTAO_VALIDO",
    "dataExpiracao": "2028-03-24T00:00:00.000+0000",
    "panMascarado": "9999XXXXXXXX9999",

    "telefone": {
      "area": "99",
      "telefone": "999999999"
    },
    "dataEmissao": "2023-03-24T09:45:06.000+0000",
  }
]

Perceba que os campos bandeira, idPortadorDebito, funcaoCartao, virtual, statusEmbossing, idAdicional, bloqueioCartao e cancelamentoCartao presentes na documentação deste endpoint não estão inclusos nesta resposta já que não estão cadastrados para este CPF.

Porém, ao cadastrar mais informações ao CPF do portador, o Horizon passa a incluir estes campos na resposta do endpoint:

[
  { 
    "id": 2001,
    "bandeira": "Teste",
    "idPortadorCredito": 2001,
    "cpf": "11111111111",
    "funcaoCartao": "CREDITO",
    "virtual": false,
    "nomePortadorCartao": "Nome Ficticio",
    "statusEmbossing": "EMBOSSADO",
    "statusCartao": "CARTAO_VALIDO",
    "dataExpiracao": "2028-03-24T00:00:00.000+0000",
    "idAdicional": 2002,
    "panMascarado": "9999XXXXXXXX9999",
    "idPortadorDebito": 2001,
    "bloqueioCartao": {
      "dataBloqueio": "2024-02-29T13:08:59.442+0000",
      "observacao": "Bloqueado",
      "tipoBloqueio": {
        "id": 1,
        "descricao": "Bloqueado",
        "chave": "BLOQUEIO_SENHA_INVALIDA"
      }
    },
    "cancelamentoCartao": {
      "dataCancelamento": "2024-02-29T13:08:59.442+0000",
      "observacao": "CANCELADO",
      "tipoCancelamento": {
        "id": 1,
        "descricao": "CANCELADO",
        "chave": "CANCELAMENTO_TESTE"
      },
      "idCartaoCancelado": 2001,
      "id": 2001
    },
    "telefone": {
      "area": "99",
      "telefone": "999999999"
    },
    "dataEmissao": "2023-03-24T09:45:06.000+0000",
    "codigoExterno": "teste1234ca=1"
  }
]

Mascaramento

Por uma questão de segurança, dados como portadores, cartões, emissores, entre outros, serão retornados de forma mascarada. Como no exemplo abaixo:


{
    "nomeImpresso": "Rodrigo Nogueira",
    "descricaoTipoCartao": "Banco XYZ",
    "nome": "Rodrigo Nogueira",
    "nomeOrigemComercial": "Banco XYZ CARTAO"
}

Ambientes de teste e homologação

O Tote possui um ambiente de sandbox exclusivo para testes de nossos produtos. Para utilizar, comece nosso guia sobre os ambientes de teste.

Processadoras

O Horizon trabalha em parceria com várias processadoras, incluindo Cards e Dock. Para utilizar os serviços de uma delas, basta se autenticar com as informações de usuário e senha disponibilizadas na página de autenticação.