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:

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:

ScopeDescrição
card.readConcede acesso para consultar dados não PCI de um cartão.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

NomeTipoDescrição
proxypathObrigató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:

NomeTipoDescrição
createdDatestringData e hora da requisição de rastreio, no formato ISO 8601 - UTC.
externalTrackingobjectObjeto que contém o código de rastreio e o nome do parceiro que realizará a entrega.
externalTracking.codestringCódigo de rastreio do cartão.
externalTracking.partnerstringNome do parceiro responsável pela entrega.
functionstringFunção do cartão, que pode ser “Pre”, “Pos” ou “Debit”.
namestringNome do proprietário do cartão.
aliasstringApelido do cartão. Exemplo: cartão educação.
addressobjectObjeto que contém informações sobre o endereço do titular do cartão no qual deve ser realizada a entrega.
address.zipcodestringCódigo postal do endereço de entrega.
address.addressstringLogradouro (nome da rua, avenida etc.).
address.numberstringNúmero do imóvel.
address.neighborhoodstringNome do bairro.
address.complementstringComplemento do endereço (quando houver).
address.citystringNome da cidade.
address.statestringNome do estado.
address.countrystringNome do país.
statusarray of objectsLista 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.createdAtstringData e hora em que este status passou entrar em vigor, no formato ISO 8601 - UTC.
stastus.typestringTipo ou nome dos status em que se encontra o cartão criado. Consulte a tabela de status para mais detalhes.
status.reasonstringInformações sobre o status do rastreio. Consulte a lista de possíveis reasons para mais detalhes.
estimatedDeliveryDatestringData de entrega estimada. Este campo só será retornado quando o cartão ainda não tiver sido entregue.
finalizedarray of objectsUma vez que o cartão é entregue, o campo finalized é preenchido com informações sobre o recebimento do cartão.
finalized.createdAtstringData de entrega do cartão, no formato ISO 8601 - UTC.
finalized.recipientNamestringNome do recebedor do cartão.
finalized.recipientKinshipstringGrau de parentesco do recebedor com o proprietário do cartão.
finalized.documentNumberstringNúmero de documento do recebedor do cartão.
finalized.atemptsnumberNú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 statusSignificado
CreatedPrimeiro registro do cartão.
BuildingO cartão está sendo confeccionado.
InProgressO cartão está sendo transferido de local.
DeliveredO cartão foi entregue. Este é um status final, portanto, não são necessárias novas consultas.
CancelledDentre 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.
NotDeliveredStatus 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.
CustodySituaçã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 eventoDescrição
TRACKING_STATUS_CHANGEDHouve uma atualização no status de rastreio.