A interface de programação referente ao Cadastro do Portador é primariamente composta por consultas que retornam o tipo CardHolder e destes consultam-se os campos como nome, documentos, endereços, contatos e demais informações.


Cadastro do Portador

Estado do cartão

Cada estado possui seu próprio _payload_ em implementações específicas de
`CardStatusInterface`. Use fragmentos para consultar seus campos.

CardStatus

INACTIVE

Cartão foi ativado e está pronto para o uso

ACTIVE

Cartão foi suspenso e não pode ser utilizado

SUSPENDED

Financiamento do cartão: crédito, débito, múltiplo, Alimentação e Refeição.

CardFunding

CREDIT

DEBIT

Cartão de Crédito e Débito (ambos simultaneamente).

MULTIPLE

MEAL

FOOD

PREPAID

VOUCHER

MULTIPLE_PREPAID

Estados de verificação.

Utilizado, por exemplo, para verificação de contatos de um portador.

VerifiedStatus

UNVERIFIED

Iniciou-se o processo de verificação, porém ele ainda não foi concluído.
Após a conclusão mudará para `VERIFIED` ou `FAILED`.

PENDING

VERIFIED

FAILED

O processo de verificação não se aplica a este ítem.

NOT_APPLICABLE

Gender

FEMALE

MALE

OTHER

MaritalStatus

DIVORCED

MARRIED

SINGLE

WIDOWED

COMMON_LAW_MARRIED

Tipos de contato válidos para a verificação de contato.

TypeContactVerification

PHONE

EMAIL

CommunicationChannelEnum

WHATSAPP

CardVerificationStatus

VERIFIED_LUHN_ALGORITHM

VERIFIED_TRANSACTION

INVALID

PersonContactType

o valor é um número de telefone, celular ou fax

o valor é um número de telefone celular

aplicativo de mensagens instantâneas
O valor é um identificador de usuário com o campo de contexto

Formato de Chave criptográfica a ser serializada ou interpretada.

CryptoKeyFormat

[JSON Web Key - JWK](https://tools.ietf.org/html/rfc7517)

X509

Entrada que filtra cartões a serem retornados

Se não-nula, retorna apenas cartões com dado estado. Exemplo: `ACTIVE`
Se `null`, retorna cartões em todos os estados.

status

Se não-nula, retorna apenas cartões oferecendo um certo serviço
(`CardHolderService`), referente a `availableServices`.
Se `null`, retorna cartões que ofereçam quaisquer serviços.

cardHolderServiceId

Se não-nula, retorna apenas cartões com dado financiamento. Exemplo: `DEBIT`
Se `null`, retorna cartões em todos os tipos.

funding

Se não-nula, retorna apenas cartões de um certo produto (`CardProduct`).
Se `null`, retorna cartões de todos os produtos.

cardProductId

Se não-nula, retorna apenas cartões de uma certa bandeira (`CardBrand`).
Se `null`, retorna cartões de todas as bandeiras.
> **NOTA:** em `cardBrandId` só possuí bandeira ELO disponível.

cardBrandId

Se não-nula, retorna apenas cartões que permitem uma dada captura
(`CardCapture`).
Se `null`, retorna cartões de todas as capturas.

cardCaptureId

Se não-nula, retorna apenas cartões de um certo uso (`CardUsage`).
Se `null`, retorna cartões de todos os usos.

cardUsageId

Se não-nula, retorna apenas cartões de um certa rede (`CardNetwork`).
Se `null`, retorna cartões de todas as redes.

cardNetworkId

Se não-nula, retorna apenas cartões de um certo emissor (`CardIssuer`).
Se `null`, retorna cartões de todos os emissores.

cardIssuerId

CardFilterInput

Entrada para filtragens de busca com informações textuais.

filter

SearchFilterInput

número do RG (dígitos) sem hífen ou pontos.

number

organização emissora do documento (exemplo: `SSP`)

issuerOrganization

estado de emissão do documento (exemplo: `SP`)

issuerState

issueDate

RGInput

cnpj

LegalIdsInput

Entrada com dados básicos para redes sociais.

Nome do provedor da rede social, ex: Facebook, Twitter...

provider

username

SocialNetworkInput

Entrada para filtragens de busca por termo de uso.

Todos os campos especificados (não-`null`) são aplicados
(comportamento `AND`), para obter comportamento `OR`, utilize várias
consultas.

Se `null` ou vazio, não realiza filtragem.
Caso contrário, define texto que deve estar contido no nome do termo de uso.

nameContains

Lista de identificadores globais únicos de termos (`AgreementTerm`)
Se `null` ou vazio, não realiza filtragem.

agreementTermIds

Realiza o filtro pelos termos de uso, que são referentes a carteira digital.
Se o valor informado for "true", somente os termos que forem de carteira digital, serão retornados.
Se o valor informado for "false", somente os termos que não forem de carteira digital, serão retornados.
Se o atributo não for informado na consulta, serão retornados todos os termos
de uso, idenpendente se forem ou não de carteira digital.

isWalletDigital

AgreementTermFilterInput

Entrada para mutação `addCardToWallet()`.

Informações sigilosas precisam ser transmitidas de forma criptografada
utilizando-se a forma compacta _JSON Web Encryption_ (JWE).

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas,
podendo ser usado pelo servidor para perder requisições duplicadas
devido a falhas de rede e retransmissões.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

clientMutationId

O identificador global da carteira onde se quer adicionar o cartão.

walletId

O identificador global único do cartão.

Caso tenha acesso ao ID do cartão, utiliza-se preferencialmente
este campo de modo a reduzir o tráfego de informações sensíveis.

Caso contrário pode-se utilizar o campo `sensitive`.

Exemplo: `"3417E346-49A3-47A8-8196-37BBA09E27A5"`

cardId

Conteúdo sensível o qual foi assinado e então cifrado conforme a
estrutura a seguir. Deve ser utilizado apenas se não tiver acesso
ao identificador global único do cartão, neste caso deverá ser
utilizado `cardId`.

Estrutura de assinatura e criptografia:

```
JWE.Encrypt(recipient=ServerKey, format=compact,
    JWS.Sign(issuer=UserKey, format=compact,
        JSON.Stringify(CardSensitiveInput)
    )
)
```

Ou seja, os dados conforme o esquema JSON
[CardSensitiveInput](https://github.com/cartaoelo/elo-api-schema/blob/master/schema/CardSensitiveInput.json)
devem ser serializados e então assinados utilizando _JSON Web
Signature_ (JWS) em formato compacto e então cifrados utilizando
_JSON Web Encryption_ (JWE) também em formato compacto. O
resultado final deve ser utilizado como valor deste parâmetro.

O esquema define as seguintes chaves para o objeto de entrada
(`CardSensitiveInput`):

 - `pan`: O número da conta primária (_Primary Account Number_),
   também conhecido como \"número do cartão\" físico. Exemplo:
   `"1234567890123456"`
 - `expiry`: Data de validade do cartão, ou seja, quando ele
   expira. É um objeto composto pelas chaves `month` e `year`
   descritas a seguir. Exemplo: `{"month": 2, "year": 2020}`
     - `month`: Mês da validade do cartão. Número inteiro entre 1
       (Janeiro) e 12 (Dezembro).
     - `year`: Ano da validade do cartão. Número inteiro com 4
       dígitos (2017, não 17).
 - `name`: Nome do portador do cartão. Exemplo: `"João da Silva"`.

A autorização é feita com os campos `csc` ou `authCode` e seus
respectivos horários de entrada. Note que apenas um deles deve ser
especificado:

 - `csc`: Código de segurança do cartão (_Card Security Code_),
   usualmente impresso na parte de trás do cartão físico.
 - `cscEntryTime`: Data e horário quando o CSC (Código de
   Segurança do Cartão) foi digitado. É necessário quando o CSC é
   gerado por um chaveiro/_token_ baseado em tempo. Deve estar no
   formato ISO 8601. Exemplo: `"2017-06-01T12:00:00-03:00"`

 - `authCode`: Código de autorização. Este código não é o CSC
   (Código de Segurança do Cartão) pois não está impresso no
   cartão. Exemplo: `"AB123Z1Y"`
 - `authCodeEntryTime`: Data e horário quando o código de
   autorização (`authCode`) foi digitado. Deve estar no formato
   ISO 8601. Exemplo: `"2017-06-01T12:00:00-03:00"`

sensitive

AddCardToWalletInput

Entrada para mutação `removeCardFromWallet()`.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

O identificador global da carteira de onde se quer remover o cartão.

O identificador global do cartão a ser removido. Deve ter sido
previamente adicionado a carteira.

RemoveCardFromWalletInput

Entrada para mutação `createWallet()`.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

name

CreateWalletInput

Entrada para mutação `deleteWallet()`.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

O identificador global da carteira a ser apagada.

O usuário do sistema deve ter permissão para apagar carteiras
do portador da carteira a ser apagada (`Wallet { holder }`).

DeleteWalletInput

Entrada para mutação `updateWallet()`.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

O identificador global da carteira em que se quer editar informação.

Se provido, especifica novo nome da carteira.

UpdateWalletInput

Entrada para mutação `createLoginSalt()`.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

Nome do usuário para acesso ao sistema

Note que o `salt` sempre será retornado, mesmo que o usuário não
exista.

CreateLoginSaltInput

Entrada para mutação `login()`.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

Resultado do desafio (_challenge_) de `login()`.

_Hash_ utilizando o algoritmo
[bcrypt](https://en.wikipedia.org/wiki/Bcrypt) com `salt`
fornecido por `createLoginSalt()` e conteúdo sendo o
`bcryptPassword` especificado em `createUser()` ou
`updateUser()`. Código utilizando as bibliotecas
[crypto](https://nodejs.org/api/crypto.html) e
[bcrypt](https://www.npmjs.com/package/bcrypt) com
[Node.js](https://nodejs.org):

```js
var crypto = require('crypto');
var bcrypt = require('bcrypt'); // or bcryptjs

function sha256AsBase64(data) {
  return crypto.createHash('sha256')
    .update(data)
    .digest('base64');
}

function bcryptSaltFromUsername(username) {
  var hash = crypto.createHash('sha256').update(username).digest();
  return '$2a$12$' + bcrypt.encodeBase64(hash, 16);
}

function bcryptUserPassword(username, password) {
  var userSalt = bcryptSaltFromUsername(username);
  return bcrypt.hashSync(sha256AsBase64(password), userSalt);
}

var username = input(); // Pergunte o nome do usuário
var password = input(); // Pergunte a senha do usuário
var bcryptPassword = bcryptUserPassword(username, password);

var challengeSalt = createLoginSalt(username);
var challenge = bcrypt.hashSync(bcryptPassword, challengeSalt);
```

A `String` final deve estar no formato padrão, com prefixo, custo,
`salt` e por fim o valor computado em Base64, totalizando 60
caracteres. Por exemplo:
`$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy`

challenge

LoginInput

Entrada para mutação `socialNetworkOAuthLogin()`.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

Nome de usuário na **rede social**

> **NOTA:** não confundir com o usuário do sistema `User { username }`.

Chave de acesso do usuário mantida pelo aplicativo na **rede social**

> **NOTA:** não confundir com a chave de acesso retornada em
> `LoginPayload` por `login()` ou `socialNetworkOAuthLogin()`.

accessToken

SocialNetworkOAuthLoginInput

Entrada com dados extras para redes sociais baseadas em OAuth

Caso o processo OAuth foi executado com sucesso, contém o
código de acesso

Caso o processo OAuth foi executado com sucesso, contém o
código de renovação de acesso

refreshToken

Caso o processo OAuth foi executado com sucesso, contém os
escopos autorizados.

scopes

Caso o processo OAuth foi executado com sucesso, contém a data e
horário que o código de acesso (`accessToken`) expira.

expiryTimestamp

SocialNetworkOAuthInput

Entrada para renda anual de uma pessoa física.

Renda anual pessoal (individual) da pessoa física.

personal

Renda anual total da família da pessoa física.

family

Moeda associada aos valores informados.

Código da moeda com 3 letras
[ISO4217](https://en.wikipedia.org/wiki/ISO_4217)
Exemplo: `EUR`, `USD`, `BRL`...

currency

PersonYearlyIncomeInput

Entrada para ítem de contato com o portador de cartão, como email ou
telefone...

Tipo designa como interpretar o valor, podendo ser telefone,
email, ou aplicativo de mensagens instantâneas.

type

Contexto do contato, que varia com o tipo:
 - Se o tipo for `PHONE`, `WHATSAPP` ou `EMAIL`, este poderia ser: vendas, suporte ...
 - Se o tipo for `IM`, pode ser: skype, whatsapp, facebook messenger...
 - Se for `OTHER`, pode ser qualquer texto

context

Valor do contato. Exemplos: `+12345678` para telefone,
`user@server.com` para email, etc.

value

PersonContactInput

Entrada de Endereço Físico Mundial, que pode ser usado para envios ou contas

Contexto do endereço, por exemplo: Casa, Trabalho, Matriz, Filial

Análogo a campo de mesmo nome em `PersonContact` e `CompanyContact`.

Código do país com 3 letras
([ISO3166-alpha3](https://pt.wikipedia.org/wiki/ISO_3166-1_alfa-3)).
Exemplos: `USA`, `BRA`...

country

city

state

stateAbbrev

district

O tipo deve ser `Av.` (Avenida), `R.` (Rua), `Rd.` (Rodovia)...

kind

Nome da via, para ser usado em conjunto com `kind` e `number`, compondo
a primeira linha de endereço.

place

Complemento opcional, como número de apartamento.

complement

Ponto de referência (exemplo: próximo ao posto)

reference

Instruções (exemplo: autorização do receptor)

instructions

Longitude, opcional: em graus.

Contém a longitude caso seja manualmente provido ou automaticamente
descoberto à partir do endereço. Caso não seja possível prover, será
`null`.

Latitude, opcional: em graus.

Contém a latitude caso seja manualmente provido ou automaticamente
descoberto à partir do endereço. Caso não seja possível prover, será
`null`.

AddressUserInput

Entrada para mutação `createUser()`.

> **Nota:** não existe um campo `image` a ser enviado, para tal
> utilize a mutação `setImage()`.

Compatível com [Relay](https://facebook.github.io/relay/docs/en/mutations.html).

Nome do usuário para acesso ao sistema

Pode ser nulo se e somente se for especificado `socialNetwork`, ou
seja, o usuário será criado baseado na rede social.

_Hash_ utilizando o algoritmo
[bcrypt](https://en.wikipedia.org/wiki/Bcrypt) da senha do usuário.

Os parâmetros para cálculo do _hash_ são:
 - `cost`: 12
 - `salt`: os 16 primeiros _bytes_ do _Hash_ utilizando o algoritmo
   `SHA256` do nome do usuário, codificados como `base64`
   utilizando o **alfabeto particular** do `bcrypt`.
 - `data`: a representação Base64 do _Hash_ utilizando `SHA256` da
   senha do usuário. Isto é necessário pois `bcrypt` tem um limite
   de 72 caracteres.

Ou seja:
```js
var crypto = require('crypto');
var bcrypt = require('bcrypt'); // or bcryptjs

function sha256AsBase64(data) {
  return crypto.createHash('sha256')
    .update(data)
    .digest('base64');
}


function bcryptSaltFromUsername(username) {
  var hash = crypto.createHash('sha256').update(username).digest();
  return '$2a$12$' + bcrypt.encodeBase64(hash, 16);
}

function bcryptUserPassword(username, password) {
  var userSalt = bcryptSaltFromUsername(username);
  return bcrypt.hashSync(sha256AsBase64(password), userSalt);
}

var username = input(); // Pergunte o nome do usuário
var password = input(); // Pergunte a senha do usuário
var bcryptPassword = bcryptUserPassword(username, password);
```

A `String` deve ser serializada no formato padrão `bcrypt`
contendo o prefixo, custo, `salt` e o _hash_ serializado em Base64,
totalizando 60 caracteres. Por exemplo:
`$2a$12$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy`

Pode ser nulo se e somente se for especificado `socialNetwork`, ou
seja, o usuário será criado baseado na rede social.

bcryptPassword

Usuário associado a uma rede social.

Contém apenas as informações básicas da rede social (provedor e
usuário da rede). Caso seja uma rede social baseada em OAuth,
então envie também o campo `oauth` com as extensões particulares
deste protocolo.

Pode ser nulo se e somente se ambos `bcryptPassword` e `username`
forem especificados, ou seja, o usuário tradicional com nome e
senha mantidos no sistema.

Caso `username` ou `bcryptPassword` sejam fornecidos em conjunto
com `socialNetwork`, então é similar a criar um usuário e então
chamar `addSocialNetworkToUser()`.

Caso `bcryptPassword` seja nulo a senha será indefinida e a
chamada `login()` não irá funcionar, somente
`socialNetworkOAuthLogin()`.

Caso `username` seja nulo, será gerado um nome de usuário.

socialNetwork

Usuário associado a uma rede social OAuth.

Caso `socialNetwork` se refira a uma rede que utiliza o protocolo
OAuth, então este campo oferece os dados específicos como
`accessToken`, `refreshToken`, `scopes` e `expiryTimestamp`.