Por proxy
stable pré pós
O endpoint de consulta de rastreio de cartões dá visibilidade de cada etapa do processo de entrega de um cartão físico, desde a fabricação até a operação logística.
O processo de rastreio é iniciado alguns minutos após a solicitação de um novo cartão. Como este tempo é variável, pois depende dos parceiros e de validações internas de segurança, recomendamos que a consulta inicie-se após, no mínimo, 20 minutos.
Pré-requisito
Para que seja possível utilizar este endpoint, é necessário que:
- O cliente tenha solicitado a emissão de um cartão físico, de um cartão múltiplo ou da segunda via de um cartão.
Requisição
Requisição HTTP
GET https://api-mtls.sandbox.bankly.com.br/cards/{{proxy}}/tracking
--request GET \
--url 'https://api-mtls.sandbox.bankly.com.br/cards/{{proxy}}/tracking' \
--header 'accept: application/json' \
--header 'api-version: 1' \
--header 'Authorization: Bearer {{token}}'
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
Scope | Descrição |
---|---|
card.read | Concede acesso para consultar dados não PCI de um cartão. |
Cabeçalhos (Headers)
Nome | Descrição |
---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
Parâmetros da rota (Path)
Nome | Tipo | Descrição |
---|---|---|
proxy | path | Obrigatório. Código do cartão utilizado para localizá-lo no processo de entrega. |
Corpo da requisição (Body)
Não é necessário enviar campos no body desta requisição.
Resposta (Response)
O status code 200 indicará sucesso na busca.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
Nome | Tipo | Descrição |
---|---|---|
createdDate | string | Data e hora da requisição de rastreio, no formato ISO 8601 - UTC. |
externalTracking | object | Objeto que contém o código de rastreio e o nome do parceiro que realizará a entrega. |
externalTracking.code | string | Código de rastreio do cartão. |
externalTracking.partner | string | Nome do parceiro responsável pela entrega. |
function | string | Função do cartão, que pode ser “Pre”, “Pos” ou “Debit”. |
name | string | Nome do proprietário do cartão. |
alias | string | Apelido do cartão. Exemplo: cartão educação. |
address | object | Objeto que contém informações sobre o endereço do titular do cartão no qual deve ser realizada a entrega. |
address.zipcode | string | Código postal do endereço de entrega. |
address.address | string | Logradouro (nome da rua, avenida etc.). |
address.number | string | Número do imóvel. |
address.neighborhood | string | Nome do bairro. |
address.complement | string | Complemento do endereço (quando houver). |
address.city | string | Nome da cidade. |
address.state | string | Nome do estado. |
address.country | string | Nome do país. |
status | array of objects | Lista com o histórico dos status, desde a criação do cartão até a entrega ao destinatário, do mais recente para o mais antigo. |
status.createdAt | string | Data e hora em que este status passou entrar em vigor, no formato ISO 8601 - UTC. |
stastus.type | string | Tipo ou nome dos status em que se encontra o cartão criado. Consulte a tabela de status para mais detalhes. |
status.reason | string | Informações sobre o status do rastreio. Consulte a lista de possíveis reasons para mais detalhes. |
estimatedDeliveryDate | string | Data de entrega estimada. Este campo só será retornado quando o cartão ainda não tiver sido entregue. |
finalized | array of objects | Uma vez que o cartão é entregue, o campo finalized é preenchido com informações sobre o recebimento do cartão. |
finalized.createdAt | string | Data de entrega do cartão, no formato ISO 8601 - UTC. |
finalized.recipientName | string | Nome do recebedor do cartão. |
finalized.recipientKinship | string | Grau de parentesco do recebedor com o proprietário do cartão. |
finalized.documentNumber | string | Número de documento do recebedor do cartão. |
finalized.atempts | number | Número de tentativas de entrega. |
{
"createdDate": "2022-10-20T22:53:12",
"externalTracking": {
"code": "A1234692D592",
"partner": "CORREIOS"
},
"function": "Pre",
"name": "Nísia Floresta",
"alias": "Meu Cartão-Educação",
"address": [
{
"zipCode": "68060100",
"address": "Rua 6 de Março",
"number": "2500",
"neighborhood": "Alter do Chão",
"complement": "",
"city": "Santarém",
"state": "PA",
"country": "Brasil"
}
],
"status": [
{
"createdDate": "2022-11-01T22:55:12",
"type": "Delivered",
"reason": "Object delivered"
},
{
"createdDate": "2022-10-29T22:53:12",
"type": "InProgress",
"reason": "In route to delivery"
}
],
"finalized": [
{
"createdDate": "2022-11-01T22:53:12",
"recipientName": "Dionísia Gonçalves Pinto",
"recipientKinship": "Mãe",
"documentNumber": "31293323080",
"attempts": 1
}
]
}
Tabela de status
Tipo de status | Significado |
---|---|
Created | Primeiro registro do cartão. |
Building | O cartão está sendo confeccionado. |
InProgress | O cartão está sendo transferido de local. |
Delivered | O cartão foi entregue. Este é um status final, portanto, não são necessárias novas consultas. |
Cancelled | Dentre outros motivos, este status é exibido quando o cartão foi extraviado ou quando entrou em processo de custódia, porém o prazo para tomar uma ação a respeito expirou. |
NotDelivered | Status relacionado a cartão não entregue, seja por endereço incorreto, seja por ter sido recusado, ou então porque o número máximo de tentativa de entregas foi excedido. |
Custody | Situação em que o cartão não foi entregue com sucesso e fica sob custódia da transportadora. Dependendo do contrato entre o parceiro e a transportadora, são realizadas algumas tentativas de entrega até o seu retorno e atualização do endereço de entrega. Verifique as reasons a seguir. |
Lista de reasons
-
Created
- "Waiting for post": o cartão foi solicitado.
-
Building
- "Card was embossed": cartão confeccionado pela processadora;
- "Building completed": o processo de fabricação do cartão foi finalizado;
- "Sent to ship company": cartão enviado para a transportadora.
-
InProgress
- "Received by the shipping company": recebido pela empresa de transporte.
- "Sended to Correios": enviado aos Correios;
- "Sended to delivery": enviado à transportadora;
- "In route to delivery": em rota de entrega;
- "Resented to delivery": reenviado para entrega (acontece após atualizar endereço ou quando há acordo de realizar nova tentativa de entrega).
-
Delivered
- "Object delivered": cartão entregue com sucesso.
-
NotDelivered
- "Out": não foi possível entregar;
- "Moved": destinatário mudou-se;
- "Incorrect Address": endereço incorreto;
- "Unable to deliver": não foi possível entregar;
- "Unable to access": não foi possível acessar o endereço;
- "Unknow": destinatário desconhecido no endereço;
- "Refused": recebimento recusado.
-
Custody
- "Waiting action": cartão não entregue e esperando uma ação de atualização de endereço. Caso nenhuma ação seja tomada, o cartão poderá ser cancelado;
- “Returned”: o cartão retornou para o emissor.
-
Cancelled
- "Lost /Sinister": cartão extraviado ou que sofreu algum tipo de sinistro, sem possibilidade de nova entrega e sem possibilidade de solicitar uma nova via;
- "Cancelled": cartão extraviado ou devolvido, sem possibilidade de nova entrega e sem possibilidade de solicitar uma nova via;
- “Destroyed”: o cartão foi completamente destruído. Isso pode ocorrer após algumas tentativas de entrega, de acordo com o contrato entre o parceiro e a transportadora.
Importante
Os status de rastreio "Created" e "Building" têm um limite de permanência de cinco dias; ao final deste período, uma consulta junto à transportadora pode ser realizada, desencadeando uma possível atualização do status para "InProgress".
Status de rastreio
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint não retorna erros específicos. Porém, ele poderá retornar alguns erros comuns entre todos os endpoints.
Eventos
Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:
Nome do evento | Descrição |
---|---|
TRACKING_STATUS_CHANGED | Houve uma atualização no status de rastreio. |
Updated 3 months ago