Introdução

O objetivo desta API é possibilitar e flexibilizar, aos parceiros e canais, a comercialização de quaisquer produtos e serviços da Cielo. Este manual irá guiar o desenvolvedor com o passo a passo da integração com a API de Comercialização da Cielo, além de possuir algumas dicas e pontos de atenção importantes.

Funcionalidades contempladas atualmente na API

Glossário

Característica da API

A solução API foi desenvolvida com a tecnologia REST, que é padrão de mercado e independe da tecnologia utilizada por nossos clientes. Dessa forma, é possível integrar-se utilizando as mais variadas linguagens de programação, tais como:

Não deve ser enviado no formato XML.

Entre outras características, os atributos que mais se destacam na plataforma Cielo de Comercialização Unificada:

Ambientes Disponíveis

Para utilizar as APIs, as requisições devem ser executadas utilizando as respectivas credenciais dos ambientes de Labs, Sandbox e Produção.

Para solicitar credenciais, entre em contato com o ponto focal do time comercial da Cielo e informe para quais ambientes são necessárias credenciais. Será necessário informar o nome e e-mail da pessoa ou caixa de e-mail do grupo de pessoas que precisam receber essa credencial para o acesso à API. Esse mesmo e-mail deverá ser utilizado para a criação de uma nova conta em nosso portal de desenvolvedores ( ). Para verificar qual foi a credencial gerada, acesse a conta criada e verifique o seu o Client-Id.

Ambiente Descrição Endpoint
Labs Destinado à realização de testes com parceiros e demais canais da Cielo. Utiliza mocks para simular o retorno das operações. As operações não são executadas em ambientes reais.  
Sandbox Destinado à realização de testes com parceiros e demais canaisda Cielo. As operações são executadas em ambiente real, porém não produtivo.  
Produção É o ambiente transacional integrado ao ambiente da Cielo. As operações realizadas nesse ambiente são reais e não podem ser desfeitas.  

Autenticação

Para realizar qualquer acesso às APIs será necessário obter um token de segurança a partir de autenticação oAuth, utilizando o client_id e client_secret. Este token de segurança deverá ser enviado no header das demais operações, e deve ser renovado periodicamente.

Segue um exemplo de requisição de obtenção do token de segurança:

Request

Authorization Basic Base64(client_id e client_secret concatenado com “:” e codificado em base64)

curl --location --request POST 'https://api2.cielo.com.br/v2/oauth/token'
\
--header 'Authorization: Basic base64 \
--header 'Content-Type: text/plain' \
--data-raw '{"grant_type": "client_credentials"}'

Respose

{
  "access_token": "{access_token}",
  "refresh_token": "{refresh_token}",
  "token_type": "access_token",
  "expires_in": "{expiration_time}"
}

Utilização

A API de comercialização foi modelada com base nos conceitos de ofertas e pedidos. Atendendo a esses conceitos básicos, é permitido que o canal seja flexível para oferecer uma experiência diferenciada ao usuário. As necessidades de interação com o cliente serão detalhadas a seguir:

1 - Consulta e apresentação de ofertas para um cliente ou prospect

O canal deverá utilizar a operação GET /offers para obter as ofertas disponíveis para determinado estabelecimento. Uma oferta irá conter toda alista de serviços e produtos com suas respectivas condições. Caberá ao canal coletar as informações de entrada para a consulta e com o retorno,apresentar as condições de cada oferta para que o usuário possa escolher entre uma delas.

Dados de entrada

Para que seja possível direcionar a melhor oferta para o cliente, alguns dados de entrada são obrigatórios para essa operação, e deverão serobtidos pelo canal junto ao cliente, prospect ou intermediador:

{
  "code": "CARD_MACHINE_PAYMENTS",
  "description": "Pagamento por meio de máquina de cartão",
  "mandatoryFields": [
    "taxId",
    "dealTypeFilter",
    "totalPaymentVolume",
    "zipCode",
    "merchantCategoryCode"
  ],
  "filters": [
    {
      "code": "RECEBA_RAPIDO",
      "description": "Ofertas com Receba Rápido"
    },
    {
      "code": "META_FATURAMENTO",
      "description": "Ofertas com meta de faturamento mensal"
    }
  ]
}

Cada tipo de negócio pode possuir campos específicos obrigatórios (mandatoryFields) que devem ser também coletados para possibilitar a consulta de ofertas. Segue abaixo a relação dos possíveis campos obrigatórios que podem ser solicitados de acordo com o tipo de negócio escolhido:

Cada tipo de negócio também possui filtros adicionais (filters). Caso sejam informados, poderão direcionar uma oferta mais personalizada para o cliente.

Exemplo: Se enviarmos os query params abaixo, a API irá filtrar ofertas com o serviço “Receba Rápido” e com “Meta por faturamento”: /v1/offers?filter=RECEBA_RAPIDO&filter=META_POR_FATURAMENTO

Todos os campos são de preenchimento obrigatório para solicitações de pessoa jurídica (exceto o zipCode e merchantCategoryCode) e pessoa física vinculadas aos tipos de negócio pagamento com máquina de cartão e pagamento digital.

Dados saida

Ao executar a operação, deverá ser retornada uma lista de ofertas com os seguintes campos:

[
{
"description":"Cobrança de aluguel com atingimento de
meta de faturamento",
"monthlyPayment": 0,
"minimumTotalPaymentVolume": 10000
},
{
"description":"Cobrança de aluguel sem atingimento de
meta de faturamento",
"monthlyPayment": 123.45
}
]

[
{
"description":"Cobrança de taxa de antecipação sobre
vendas",
"rate":2.01
}
]

[
  {
    "description": "Cobrança de aluguel",
    "monthlyPayment": 100.01
  }
]

[
  {
    "description": "Pagamento único",
    "price": 1234.01
  }
]

[
{
"description":"Cobrança de taxas sobre as vendas por
bandeira e tipo de transação",
"mdr":[
{
"brand":{
"code":"01",
"name":"Visa"
},
"rates":[
{
"transactionProfile":"DEBIT",
"rate":2.01
},
{
"transactionProfile":"CREDIT_IN_CASH",
"rate":2.01
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":3,
"rate":2.22
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":6,
"rate":2.45
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":12,
"rate":2.49
}
]
},
{

"brand":{
"code":"02",
"name":"MasterCard"
},
"rates":[
{
"transactionProfile":"DEBIT",
"rate":2.01
},
{
"transactionProfile":"CREDIT_IN_CASH",
"rate":2.01
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":3,
"rate":2.22
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":6,
"rate":2.45
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":12,
"rate":2.49
}
]
}
]
}
]

[
{
"description":"Cobrança de taxas de antecipação sobre
vendas",
"anticipationRates":[
{
"brand":{
"code":"01",
"name":"Visa"
},
"rates":[
{

"transactionProfile":"DEBIT",
"rate":2.01
},
{
"transactionProfile":"CREDIT_IN_CASH",
"rate":2.01
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":3,
"rate":2.22
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":6,
"rate":2.45
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":12,
"rate":2.49
}
]
},
{
"brand":{
"code":"02",
"name":"MasterCard"
},
"rates":[
{
"transactionProfile":"DEBIT",
"rate":2.01
},
{
"transactionProfile":"CREDIT_IN_CASH",
"rate":2.01
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":3,
"rate":2.22
},
{
"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":6,
"rate":2.45
},
{

"transactionProfile":"
CREDIT_IN_INSTALLMENTS",
"installments":12,
"rate":2.49
}
]
}
]
}
]

Sempre que o campo settlementTiming for retornado em uma oferta, será cobrada uma taxa referente a antecipação do prazo de recebimento (campo anticipationRates).

[
  {
    "description": "Taxa de Receba Rápido",
    "rate": 2.1,
    "settlementTiming": 2,
    "conditionDuration": 12
  }
]

[
  {
    "description": "Taxa de Receba Rápido",
    "settlementTiming": 2,
    "conditionDuration": 12
  }
]

2 - Criação de pedido a partir de uma oferta

O canal precisará coletar a oferta escolhida pelo cliente e, também os dados cadastrais e configurações adicionais de cada serviço que consta na oferta.

A operação POST /orders deverá ser utilizada para criar o pedido.

Dados de Entrada

Após a escolha da oferta, o canal precisará coletar as informações necessárias para a criação do pedido. Parte das informações que o canal deverá solicitar são informados no próprio payload da oferta.

No header da requisição deverão ser informados os seguintes dados:

externalId: é o identificação da requisição de criação do pedido, deve ser um único para cada pedido, e gerado e controlado peloconsumidor da API. Será utilizado para controle de idempotência. intermediaryId: é o identificador da pessoa que negocia a comercialização em nome do prospect ou cliente.

O body da requisição contém as seguintes informações

offerId: id da oferta escolhida (recebido na etapa 1 - consulta de ofertas); itemsConfiguration: lista de configurações dos itens da oferta escolhida. Verificar o campo mandatoryConfiguration da oferta para identificar quais informações são necessárias.

Exemplo:

No item abaixo que consta na oferta escolhida, é solicitado o campo payoutData (dados de liquidação):

"itemId":"2d4e212f-545f-4d97-a07a-0bb01a9b3345",
"name":"Vendas com máquina de cartão de crédito e débito",
"mandatoryConfiguration":[
"payoutData"
],
...

Dessa forma, devemos formatar o campo itemsConfiguration com o campo solicitado:

"itemsConfiguration": [
{
"itemId": "2d4e212f-545f-4d97-a07a-0bb01a9b3345",
"payoutData": {
"payoutMethod": "BANK_ACCOUNT",
"targetBankAccount": {
"bankNumber": "237",
"bankBranchNumber": "12249",
"accountNumber": "14623-7",
"accountType": "CHECKING"
}
}
}
...
]

Possíveis tipos de configuração:Possíveis tipos de configuração:

Caso na oferta venha a opção BANK_ACCOUNT, deverá ser consumido o serviço GET/payout-eligible-banks para escolha do domicílio bancários mais adequado ao cliente.

"payoutData": {
"payoutMethod": "BANK_ACCOUNT",
"targetBankAccount": {
"bankNumber": "237",
"bankBranchNumber": "12249",
"accountNumber": "14623-7",
"accountType": "CHECKING"
}
}

"payoutData": {
"payoutMethod": "PREPAID_CARD"
}

Consulte o ponto focal da Cielo para verificar quais perfis de entrega que serão utilizados

"deliveryData": {
"deliveryType": "IN_PERSON"
}

"deliveryData": {
"deliveryType": "COURIER_SERVICE",
"deliveryAddress": {
"name": "Paulista",
"type": "Avenida",
"number": "1200",
"extraLine": "Apto 251",
"neighborhood": "Jardins",
"city": "Sao Paulo",
"state": "SP",
"country": "BR",
"zipCode": "01539010"
}
}

"registrationData": {
"individual": {
"taxId": "34013415020",
"fullName": "Joaquim Antônio da Cunha Pavão",
"birthDate": "1976-09-09",
"motherName": "Maria Dolores Antônio da Cunha",
"email": "myname@company.com"
},
"phones": [
{
"countryCode": 55,
"areaCode": 11,
"number": 918273645,
"mobilePhone": true
}
],
"address": {
"name": "Paulista",
"type": "Avenida",
"number": "1200",
"extraLine": "Apto 251",
"neighborhood": "Jardins",
"city": "Sao Paulo",
"state": "SP",
"country": "BR",
"zipCode": "01539010"
}
}

"registrationData": {
"company": {
"taxId": "60957392000103",
"companyName": "Green Burguers",
"stateRegistration": "347213796222",
"email": "mycompany@company.com",
"companyOwners": [
{
"taxId": "34013415020",
"fullName": "Joaquim Antônio da Cunha Pavão",
"birthDate": "1976-09-09",
"motherName": "Maria Dolores Antônio da Cunha",
"email": "myname@company.com"
}
]
},
"phones": [
{
"countryCode": 55,
"areaCode": 11,
"number": 918273645,
"mobilePhone": true
}
],
"address": {
"name": "Paulista",
"type": "Avenida",
"number": "1200",
"extraLine": "Apto 251",
"neighborhood": "Jardins",
"city": "Sao Paulo",
"state": "SP",
"country": "BR",
"zipCode": "01539010"
}
}

3- Coleta e registro de consentimento

Para canais de autoatendimento, após a criação do pedido, será necessário realizar a coleta do consentimento do cliente nos termos e no contrato (p. exemplo: política de privacidade, termo de credenciamento, entre outros). Utilize a operação GET /agreements para listar todos os aceites e termos que devem ser coletados e utilize a operação POST /agreements para registrar.

Observação: Nos canais operados por um intermediador, a coleta do consentimento será feita em um momento posterior, e diretamente pelo cliente, por meio de outro canal (como por exemplo a área logada do Site da Cielo).
Além disso, terá limitação no compartilhamento de informação após a conclusão do pedido, visto que não houve o OPTIN/consentimento nos termos e contratos. Por exemplo: não será compartilhado, via API, as chaves de acesso dos cadastros de e-commerce. Essa informação será enviada diretamente por email ao cliente.

4- Tracking e informações do pedido

A API de comercialização provê 2 mecanismos para que o canal possa informar o cliente, prospect ou intermediador do andamento do pedido:

Notificações via webhook

O parceiro deverá implementar um webhook para receber notificações assíncronas de atualizações de status do pedido.

Campo Tipo Obrigatório Descrição
eventType enum S Identificador do evento. Nesse caso os valores possíveis são: order-status-change. Caso o valor for healthcheck, o endpoint deverá responder HTTP 200 indicando que está on-line.
eventCreateDate datetime S Data de criação do evento
eventDetails Objeto N Este objeto contém detalhes do evento.

Após o canal enviar o pedido, será enviado um dos eventos abaixo:

{
   "eventType":"order-created",
   "eventCreateDate":"2019-04-25T09:27:54.783Z",
   "eventDetails":{
      "eventId":"162d8827-ae23-471b-bfa6-2ec7064e40f",
      "externalId":"uk4231y412hjh2134u12h",
      "orderId":"194492435235",
      "newStatus":"CRIADO"
   }

{
   "eventType":"order-created",
   "eventCreateDate":"2019-04-25T09:27:54.783Z",
   "eventDetails":{
      "eventId":"162d8827-ae23-471b-bfa6-2ec7064e40f",
      "externalId":"uk4231y412hjh2134u12h",
      "reasons":[
         {
            "code":1,
            "message":"example reason"
         }
      ]
   }

Se o pedido for aceito (order-created), o canal poderá acompanhar o tracking do pedido através do evento:

{
  "eventType": "order-updated",
  "eventCreateDate": "2019-04-25T09:27:54.783Z",
  "eventDetails": {
    "eventId": "162d8827-ae23-471b-bfa6-2ec7064e40f",
    "externalId": "uk4231y412hjh2134u12h",
    "orderId": "194492435235",
    "newStatus": "INSUCESSO",
    "reasons": [
      {
        "code": 123,
        "description": "Domicilio bancário inválido"
      }
    ],
    "merchantId": "2323232323",
    "merchantKey": "kwfmkmfkmfkfw",
    "clientId": "kwfmkmfkmfkfw",
    "clientSecret": "afmladfm",
    "logicalNumbers": ["314431-1", "314431-2"]
  }
}

{
  "eventType": "healthcheck",
  "eventCreateDate": "2019-04-25T09:27:54.783Z"
}

Consulta de pedido

O canal poderá utilizar a operação GET /orders para consultar todas as informações do pedido como status, etapas, eventos, alterações de status e seus respectivos itens.

Tracking do pedido e do item

O tracking contém as informações de andamento do pedido ou do item do pedido. As informações retornadas no tracking são listadas abaixo:

"currentStatus":{
   "statusCode":5,
   "statusMessage":"Sucesso"
}

"events":[
   {
      "occurenceTime":"2012-04-23T18:25:43.511Z",
      "description":"Pedido criado",
      "nextStatus":{
         "statusCode":1,
         "statusMessage":"Em validação"
      },
      "nextStep":{
         "stepId":1,
         "description":"Validação"
      }
   },
   {
      "occurenceTime":"2012-04-23T18:26:43.511Z",
      "description":"Validação concluída",
      "previousStatus":{
         "statusCode":1,
         "statusMessage":"Em validação"
      },
      "nextStatus":{
         "statusCode":2,
         "statusMessage":"Aguardando pagamento"
      },
      "previousStep":{
         "stepId":1,
         "description":"Validação"
      },
      "nextStep":{
         "stepId":2,
         "description":"Pagamento"
      }
   },
   {
      "occurenceTime":"2012-04-23T18:26:43.511Z",
      "description":"Pagamento realizado",
      "previousStatus":{
         "statusCode":2,
         "statusMessage":"Aguardando pagamento"
      },
      "nextStatus":{
         "statusCode":3,
         "statusMessage":"Em atualização de cadastro"
      },
      "previousStep":{
         "stepId":2,
         "description":"Pagamento"
      },
      "nextStep":{
         "stepId":3,
         "description":"Cadastro"
      }
   },
   {
      "occurenceTime":"2012-04-23T18:27:43.511Z",
      "description":"Cadastro concluído",
      "previousStatus":{
         "statusCode":3,
         "statusMessage":"Em atualização de cadastro"
      },
      "nextStatus":{
         "statusCode":4,
         "statusMessage":"Em processamento"
      },
      "previousStep":{
         "stepId":3,
         "description":"Cadastro"
      },
      "nextStep":{
         "stepId":4,
         "description":"Processamento"
      }
   },
   {
      "occurenceTime":"2012-04-23T18:28:43.511Z",
      "description":"Processamento concluído",
      "previousStatus":{
         "statusCode":4,
         "statusMessage":"Em processamento"
      },
      "nextStatus":{
         "statusCode":5,
         "statusMessage":"Sucesso"
      },
      "previousStep":{
         "stepId":4,
         "description":"Cadastro"
      }
   }
]

"steps":[
   {
      "stepId":1,
      "description":"Validação",
      "sequence":1,
      "status":{
         "statusCode":5,
         "statusMessage":"Sucesso"
      }
   },
   {
      "stepId":2,
      "description":"Pagamento",
      "sequence":1,
      "status":{
         "statusCode":5,
         "statusMessage":"Sucesso"
      }
   },
   {
      "stepId":3,
      "description":"Cadastro",
      "sequence":1,
      "status":{
         "statusCode":5,
         "statusMessage":"Sucesso"
      }
   },
   {
      "stepId":4,
      "description":"Processamento",
      "sequence":1,
      "status":{
         "statusCode":5,
         "statusMessage":"Sucesso"
      }
   }
]
Documentações e tutoriais

Materiais complementares

Contato
GitHub