Version: 1.0.0

API

Endpoint

Os métodos a seguir são disponibilizados para acesso via HTTP em seus respectivos verbos. O header Content-Type e o corpo da mensagem devem seguir o formato application/json.

Todas as respostas de requisições, sendo elas resolvidas(HTTP status code = 200) ou não (HTTP status code != 200), devem retornar um campo status, que identifica o sucesso da execução.

Nos casos de resposta negativa para um método, o campo cod será incluído para identificar o erro específico ocorrido. Verifique a lista dos erros no final deste documento.

Homologação

Endereço da API para execução de testes:

https://hmgafiliador01.tkpp.com.br:443/swagger/index.html

Importante

Alguns métodos só podem ser requisitados de forma segura, ou seja, por meio de uma requisição com o header access_token explícito com o valor do token recebido no método Token

Métodos

Autenticação

POST/secureaccess/token

O token é utilizado como forma de autenticação nos demais métodos dentro da API. Para utilizar é nécessário preencher os parâmetros com informações válidas. O resultado dele será usado como parâmetro em todos os métodos da API. O mesmo possui validade de 24 horas, e após isso um novo token deve ser gerado. (Sem ele, nenhum dos métodos da API devolverão resultados).

Request body

Campo	Tipo	Descrição	Opcional
`grant_type`	Text	Forma de autenticação	Não
`username`	Text	Usuário do serviço de Checkout Api	Não
`password`	Text	Senha do serviço de Checkout Api	Não

{
  "grant_type": "password",
  "username": "Celer ",
  "password": "GErK2N5aEZ6g7RfsKNc8z39OtaNkd3Y9zw0eiq+fOe/nFTivOMEypQ+cOz6emWtZ1YbnKkEjYCDMyrvquwXh9g=="
}

Response body

Code: 200

Campo	Tipo	Descrição
`token_type`	Text	Tipo de Token
`access_token`	Text	Token de acesso
`expires_in`	Number	Tempo de expiração

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsXdR5cCI6IkpXVCJ9.eyJzdWIiOiJ0SzFXUmRVTEdZND0iLCJuYW1lIjoiUEVESUpBICIsImF1ZCI6Imh0dHBzOi8vbG0jYWxob3N0OjQ0MzE4LyIsIlNlcnZpY2VzIjoidGtORjZIMnhKYm69IiwiUGVybWlzc2lvbnMiUiJ0a05GfkgyeEpibz0iLCJBZmZybGlhdG9yIjoidjUrbklBZytja0E9IiwiU3ViRG9tYWluIjoicGVkaWphIiwiQWZmRG9jIjoiOTExMDAwMzc3MjQ1ODIiLCJ0b2tlbl91c2FnZSI6ImFjY2Vzc190b2tlbiIsImp0aSL6ImU0NGVkY2JiLTRlNjYtNDg1OS1hNjA4LTNiZGNhNjg1ZGQ2YiIsIm5iZiI6MTU5NzQzMTU3NiwiZXhwIjoxNTk3NTE3NDc2LCJpYXQiOjE1OTc0MzEwNzYsInlzcyI6Imh0dHBzOi8vbG9jYWxob3N0OjQ0MzE4LyJ5.WTp36dHOTe7cYkynZ4b6lteOU8T6PKor_e0ALEdg5GM",
  "expires_in": 86400
}

Link de pagamento

GET/api/PaymentLink

Este método retorna os links de pagamentos que foram gerados pelos estabelecimentos do afiliador.

Request body

Não há paramêtro para este método

Response body

Retorno Success.

HttpStatusCode	Campo	Tipo	Descrição
200	Url	Text	Url do site
	ExpirationDate	DateTime	Data de expiração
	Code	Text	Identificação do link
	Subdomain	Text	Subdomínio do link
	Variable	Boolean	Valor fixo ou variável
	Split	Boolean	Divisão do valor
	CustomerInterest	Boolean	Juros cliente

Retorno Bad request.

HttpStatusCode	Campo	Tipo	Descrição
400	Success	Text	Url do site
	Message	DateTime	Data de expiração
	StatusCode	Text	Identificação do link
	Data	Text	Subdomínio do link
	Message	Boolean	Valor fixo ou variável

Retorno Server Error.

HttpStatusCode	Campo	Tipo	Descrição
500	Success	Text	Url do site
	Message	DateTime	Data de expiração
	StatusCode	Text	Identificação do link
	Data	Text	Subdomínio do link
	Message	Bolean	Valor fixo ou variável

HttpStatusCode	Description
200	Success Example Value \| Model [ { "url": "https://hmgafiliador01.tkpp.com.br:443/Checkout?code=771d959d-47e6-49t1-8c74-60b2fbb6c245", "expirationDate": "2020-08-29T17:15:09.0371913-03:00", "code": "771d959d-47e6-49u1-8c72-60b2eab6d245", "subdomain": "pedija", "variable": false, "split": false, "customerInterest": true } ]
400	Bad Request Example Value \| Model { "Success": false, "Message": "Invalid ProductsType.", "StatusCode": 400, "Data": { "Message": "Invalid ProductsType." } }
500	Server Error Example Value \| Model { "Success": false, "Message": "Trying to pass a table-valued parameter with 4 column(s) where the corresponding user-defined table type requires 3 column(s).", "StatusCode": 500, "Data": { "Message": "Trying to pass a table-valued parameter with 4 column(s) where the corresponding user-defined table type requires 3 column(s)." } }

POST/api/PaymentLink

O método é usado para gerar um link de pagamento. O link abrirá o checkout whitelabeldo afiliador para o usuário concluir o pagamento.

Request body

Campo	Tipo	Descrição
TerminalOnline	Text	Serial do terminal online
TransactionDescription	Text	Descrição da transação
ProductsValue	Number	Valor do produto
ProductType	Enum	Tipo do produto
Plot	Number	Número de parcelas
Document	Number	Documento do estabelecimento
Products	Array
Products.Name	Text	Nome do produto
Products.UnitaryValue	Number	Valor unitário
Shipping	Objeto
Shipping.Type	Enum	Tipo de de entrega Correios – Entrega pelos correios FixedAmount – Valor Fixo WithoutShippingPickUp – Sem entrega com retirada na loja WithoutShipping – Sem entrega Free - Grátis Se o tipo de produto escolhido for “Asset”, os tipos permitidos de frete são: “Correios, FixedAmount ou Free”. Se o tipo produto escolhido for “Digital” ou “Service”, os tipos permitidos de frete são: “WithoutShipping, WithoutShippingPickUp”. Se o tipo produto escolhido for “Recurrent” o tipo de frete permitido é: “WithoutShipping”
Shipping.Name	Text	Nome do modo de entrega selecionado Ex. "Sedex" Obrigatório para frete tipo “FixedAmount”.
Shipping.Price	Number	O valor do frete. Obrigatório para frete tipo “FixedAmount”.
Shipping.ZipCode	Number	Cep de origem da encomenda. Obrigatório para frete tipo “Correios”. Deve conter apenas números.
IsVariable	Number	Verificação se o link de pagamentos terá um valor fixo.
IsCustomerInterest	Boolean	Caso o campo esteja como true será cobrado o Juros cliente Se o campo estiver como false será cobrado o Juros logista
IsSplit	Boolean	Divisão de valores do link de pagamento.
Providers	Object
SplitValue	Number	Valor do split entre os estabelecimento.
UrlCallback	Text	Url de CallBack da transação
Customer	Object
Name	String	Nome do cliente
EmailAddress	Text	Email do cliente
PhoneNumber	Number	Número do telefone/celular do cliente
Postcode	Number	Cep do cliente
Street	Text	Rua do estabelecimento.
Number	Text	Número do endereço
Neighborhood	Text	Bairro onde o estabelecimento está localizado
City	Text	Cidade
UF	Text	Estado

Name

Description

Request (Body)

Example Value | Model

{
    "TerminalOnline": "OKOKOK.COM",
    "TransactionDescription": "FOURPOINTSVIA",
    "ProductsValue": 100.0,
    "ProductType": "Service",
    "OrderNumber": "teste",
    "Plot": 1,
    "Document": "5027320988924",
    "Products": [
        {
            "Name": "Teste 22",
            "Qty": 1,
            "UnitaryValue": 100.0
        }
    ],
    "Shipping": {
        "Type": "WithoutShipping",
        "Name": "",
        "Price": 0,
        "ZipCode": ""
    },
    "IsVariable": false,
    "IsCustomerInterest": true,
    "IsSplit": false,
    "Providers": [
        {
            "MerchantDoc": "153082839101",
            "SplitValue": 50.0
        },
        {
            "MerchantDoc": "03843721000120",
            "SplitValue": 50.0
        }
    ],
    "UrlCallback": null,
    "Customer": {
        "Name": "Lucas Aguiar",
        "EmailAddress": "lucas99.abreu@gmail.com",
        "PhoneNumber": "11348342885",
        "Postcode": "06715790",
        "Street": "Rua Firmino Pires",
        "Number": "212",
        "Neighborhood": "Rio Cotia",
        "City": "Cotia",
        "UF": "SP"
    }
}

Response body

Retorno Success.

HttpStatusCode	Campo	Tipo	Descrição
200	Url	Text	Url do site
	ExpirationDate	DateTime	Data de expiração
	Code	Text	Identificação do link
	Subdomain	Text	Subdomínio do link
	Variable	Boolean	Valor fixo ou variável
	Split	Boolean	Divisão do valor
	CustomerInterest	Boolean	Juros cliente

Retorno Bad request.

HttpStatusCode	Campo	Tipo	Descrição
400	Success	Boolean	Informação de retorno
	Message	Text	Mensagem de erro
	StatusCode	Number	Código d erro
	Data	Object

Retorno Server Error.

HttpStatusCode	Campo	Tipo	Descrição
500	Success	Boolean	Informação do retorno
	Message	Text	Mensagem do erro
	StatusCode	Number	Código do erro
	Data	Object

HttpStatusCode	Description
200	Success Example Value \| Model { "url": "https://hmgafiliador01.tkpp.com.br:443/Checkout?code=3bcac679-8b96-1747-930b-0d890c3d5213", "expirationDate": "2020-09-01T16:13:37.293816-03:00", "code": "3bcac679-8b96-4747-930b-12fds84c3d5213", "subdomain": "pedija", "variable": false, "split": false, "customerInterest": true }
400	Bad request Example Value \| Model { "Success": false, "Message": "Documento do EC inválido ou inexistente", "StatusCode": 400, "Data": { "Message": "Documento do EC inválido ou inexistente" } }
500	Server Error Example Value \| Model { "Success": false, "Message": "Trying to pass a table-valued parameter with 4 column(s) where the corresponding user-defined table type requires 3 column(s).", "StatusCode": 500, "Data": { "Message": "Trying to pass a table-valued parameter with 4 column(s) where the corresponding user-defined table type requires 3 column(s)." } }

Recorrência

POST/api/Recurring

O método post é utilizado para cadastrar uma recorrência na qual o período pode ser definido por (Semanal, Mensal, Trimestral, Semestral, Anual) com a possíbilidade do valor ser splitado entre mais de um estabelecimento.

Campo	Tipo	Descrição
Identification	Text	Nome da recorrência
Description	Text	Descrição da recorrência
urlCallback	Text	Url de CallBack da transação
LinkCode	String	Situação da recorrência.
Document	Number	Documento do estabelecimento
PeriodType	Enum	Período da recorrência. Weekly - Semanal Monthly- Mensal Quarterly - Trimestral BiAnnual - Semestral Yearly - Anual
hasEmail	Boolean	Informa se o cliente irá receber notificação no email. True - Recebe a notificação no email False - Não enviará a notificação para o email
RecurringDate	DateTime	Data da recorrência. Data inicial - 2020-07-28 Daya final - 2020-11-11
InitialDate	DateTime	Data inicial.
FinalDate	DateTime	Data final.
TransactionData	Object
Transactions.pan	Number	Número do cartão do cliente.
Transactions.cardholderName	String	Nome do proprietário do cartão.
Transactions.expirationDate	Date	Data da expiração do cartão
Transactions.cvv	Number	CVV do cartão
Transactions.brand	String	Bandeira do cartão
Transactions.amount	Number	Valor da recorrência
Transactions.installments	int	Quantidade de parcelas da recorrência
Transactions.splitMode	Boolean	Divisão do valor entre outros estabelecimentos.
Transactions.firstName	String	Primeiro nome do proprietário do cartão
Transactions.lastName	String	Último nome do proprietário do cartão
Transactions.site	Text	Terminal online
Customer	Object
Customer.name	String	Nome do cliente
Customer.ddd	Number	DDD do celular
Customer.phone	Number	Número do celular
Customer.email	Text	Email do cliente
Customer.document	Number	Documento do cliente
Customer.birthDate	Number	Data de nascimento
Shipping	Object
Shipping.number	Number	Número do endereço
Shipping.street	Text	Nome da rua do estabelecimento
Shipping.country	Text	País
Shipping.zipcode	Number	CEP do estabelecimento
Shipping.ddd	Number	ddd do número do cliente.
Shipping.phone	Number	Número do cliente
Shipping.neighborhood	Text	Bairro do cliente
Shipping.city	Text	Cidade do cliente
Shipping.state	String	Estado
Products	Object
Products.name	Text	Nome do produto
Products.price	Number	Valor do produto
Products.quantity	Number	Quantidade de produtos
Providers	Object	Estabelecimentos provedores do produto
Providers.MerchantDoc	Text	Documento do estabelecimento provedor do produto
Providers.SplitValue	Number	Valor do split
Providers.MerchantDoc / Ec participando do split, caso não tenha split apenas informe a documentação do estabelecimento provisor.	Text	Documento do estabelecimento provedor do produto
Providers.SplitValue	Number	Valor do split
UserOnline	Text	Usuário online
PwdOnline	Text	Senha do usuário online

Request body

Name

Description

Request (Body)

Example Value | Model

{
    "identification": "TESTE_123",
    "description": "testetestet",
    "urlCallback": null,
    "linkCode": null,
    "document": "42988901805",
    "periodType": "Yearly",
    "hasEmail": true,
    "recurringDate": [
        "2020-07-28",
        "2020-11-11"
    ],
    "initialDate": "2020-07-28T13:13:08.104Z",
    "finalDate": "2021-07-28T13:13:08.104Z",
    "transactionData": {
        "pan": "5473669551928921",
        "cardholderName": "Lucas A C Abreu",
        "expirationDate": "01/28",
        "cvv": "293",
        "brand": "MASTERCARD",
        "amount": 100,
        "installments": 1,
        "splitMode": true,
        "firstName": "Lucas",
        "lastName": "Aguiar",
        "site": "PEDIJA429ON",
        "customer": {
            "name": "Lucas A",
            "ddd": 11,
            "phone": "946830885",
            "email": "lucas99.abreu@gmail.com",
            "document": "48903772806",
            "birthDate": "11/11/1999",
            "shipping": {
                "number": "305",
                "street": "Rua firmino pires",
                "country": "Brasil",
                "zipcode": "06715790",
                "ddd": "11",
                "phone": "946830885",
                "neighborhood": "Rio Cotia",
                "city": "Cotia",
                "state": "SP"
            }
        },
        "products": [
            {
                "name": "Teste 22",
                "price": 100.00,
                "quantity": 1
            }
        ],
        "providers": [
            {
                "MerchantDoc": "97685755220",
                "SplitValue": 50
            },
            {
                "MerchantDoc": "91770890220",
                "SplitValue": 50
            }
        ],
        "UserOnline": "110661",
        "PwdOnline": "43F732B2-A3C3-4950-BA81-7C663DC0525A"
    }
}

Response body

Retorno Success.

HttpStatusCode	Campo	Tipo	Descrição
200	recurringId	Number	Id da recorrência
	tid	Number	Identificação da transação
	status	Boolean	Status da requesição
	cod	Number	Código da resposta do response
	message	Text	Mensagem de retorno
	details	Boolean	Detalhes da recorrencia

Retorno Bad request.

HttpStatusCode	Campo	Tipo	Descrição
400	Success	Boolean	Informação do retorno
	Message	Text	Mensagem do erro
	StatusCode	Number	Código do erro
	Data	Object

Retorno Server Error.

HttpStatusCode	Campo	Tipo	Descrição
500	Success	Boolean	Informação do retorno
	Message	Text	Mensagem do erro
	StatusCode	Number	Código do erro
	Data	Object

HttpStatusCode	Description
200	Success Example Value \| Model { "recurringId": "00000172", "tid": "15977529105677903", "status": true, "cod": 200, "message": "CONFIRMED", "details": null }
400	Bad request Example Value \| Model { "Success": false, "Message": "Documento do ec inválido", "StatusCode": 400, "Data": { "Message": "Documento do ec inválido" } }
500	Server Error Example Value \| Model { "Success": false, "Message": "Object reference not set to an instance of an object.", "StatusCode": 500, "Data": { "Message": "Object reference not set to an instance of an object." } }

GET/api/Recurring/(recurring)

O método get é utilizado para listar a recorrência e as transações que estão associadas a ela. Utilizando a identificação da recorrência(RecurringId) como filtro.

Request body

Name	Description
Recurring	Id da recorrêcia

Response body

Retorno Success.

HttpStatusCode	Campo	Tipo	Descrição
200	RecurringId	Number	Id da recorrência
	Name	Text	Nome da requesição
	Descrição	Text	Descrição da requesição
	Situation	Text	Situação da requesição
	Amount	Number	Valor da requesição
	PeriodTyoe	Enum	Período de recorrência. Weekly - Semanal Monthly- Mensal Quarterly - Trimestral BiAnnual - Semestral Yearly - Anual
	initialDate	DateTime	Data inicial.
	FinalDate	DateTime	Data final
	hasEmail	Boolean	Informa se o cliente irá receber notificação no email. True - Recebe a notificação no email False - Não enviará a notificação para o email
	Email	Text	Email do cliente
	UrlCallback	Text	Url de CallBack da transação
	QtyInstallmentPaid	Int	Quantidade de parcelas pagas
	Transactions	Object	Quantidade de parcelas pagas
	Transactions.nsu	Number	Identificador da transação
	Transactions.brand	Int	Bandeira do cartão
	Transactions.transactionDate	Int	Data da transação
	Transactions.situation	Int	Situação da transação

Retorno No Content.

HttpStatusCode	Descrição
204	Sem conteúdo

Retorno Bad request.

HttpStatusCode	Campo	Tipo	Descrição
400	Success	Boolean	Informação do retorno
	Message	Text	Mensagem do erro
	StatusCode	Number	Código do erro
	Data	Object

HttpStatusCode	Descrição
401	Token inválido

Retorno Server Error.

HttpStatusCode	Campo	Tipo	Descrição
500	Success	Boolean	Informação do retorno
	Message	Text	Mensagem do erro
	StatusCode	Number	Código do erro
	Data	Object

HttpStatusCode	Description
200	Success Example Value \| Model { "recurringId": "00000170", "name": "TESTE_123", "description": "testetestet", "situation": "CANCELADA", "amount": 100, "periodType": "Yearly", "initialDate": "2020-07-28T00:00:00", "finalDate": "2021-07-28T00:00:00", "hasEmail": true, "email": "lucas99.abreu@gmail.com", "urlCallback": null, "qtyInstallmentPaid": 1, "transactions": [ { "nsu": "15976975659526847", "brand": "MASTERCARD", "transactionDate": "2020-08-17T17:52:46.047", "situation": "CONFIRMADA" } ] }
400	Bad request Example Value \| Model { "Success": false, "Message": "Id da recorrência inválido", "StatusCode": 400, "Data": { "Message": "Id da recorrência inválido" } }
500	Server Error Example Value \| Model { "Success": false, "Message": "Object reference not set to an instance of an object.", "StatusCode": 500, "Data": { "Message": "Object reference not set to an instance of an object." } }

DELETE/api/Recurring/(recurring)

Este método tem como função gerar o cancelamentos das recorrências utilizando o Id da recorrência.

Request body

Name	Description
Recurring	Id da recorrêcia

Retorno Success.

HttpStatusCode	Campo	Tipo	Descrição
200	Success	Boolean	Informação de retorno
	Message	Text	Mensagem de retorno
	StatusCode	Number	Código de retorno
	Data	Object

Retorno Bad request.

HttpStatusCode	Campo	Tipo	Descrição
400	Success	Boolean	Informação de retorno
	Message	Text	Mensagem de retorno
	StatusCode	Number	Código de retorno
	Data	Object

HttpStatusCode	Descrição
401	Token inválido

Retorno Not Found.

HttpStatusCode	Descrição
404	Não encontrado

Retorno Server Error.

HttpStatusCode	Campo	Tipo	Descrição
500	Success	Boolean	Informação de retorno
	Message	Text	Mensagem de retorno
	StatusCode	Number	Código de retorno
	Data	Object

HttpStatusCode	Description
200	Success Example Value \| Model { "success": true, "message": "CANCELADA", "statusCode": 200, "data": null }
400	Bad request Example Value \| Model { "success": false, "message": "Recorrência já cancelada", "statusCode": 400, "data": null }
404	Success Example Value \| Model { "success": true, "message": "CANCELADA", "statusCode": 404, "data": null }
500	Server Error Example Value \| Model { "Success": false, "Message": "Object reference not set to an instance of an object.", "StatusCode": 500, "Data": { "Message": "Object reference not set to an instance of an object." } }

Erros

Abaixo possíveis códigos de erro retornados pela API e suas respectivas descrições

Genéricos (podem ocorrer em requisições para qualquer um dos métodos)

Código	Mensagem	Descrição
`500`	Desculpe, ocorreu um erro na plataforma, por favor, entre em contato com o administrador do site\nTelefone: 3197-8092	Erros causados por parametros invalidos
`401`	Authorization has been denied for this request.	Erro causado ao utilizar um token invalido ou ao não utilizar token.

Relacionados ao método Link de pagamento

Código	Mensagem	Descrição
`400`	"Invalid ProductsType."	Erro causado por informações inválidas no request
`500`	"Trying to pass a table-valued parameter with 4 column(s) where the corresponding user-defined table type requires 3 column(s)."	Parâmetros inválidos.

Relacionados ao método Recorrência

Código	Mensagem	Descrição
`400`	"Informação do ec inválida."	Erro causado por informação sobre o estabelecimento inválida.
`401`	"Token inválido."
`404`	"Não encontrado."	Informação não encontrada.
`500`	"Object reference not set to an instance of an object."	Erro causado quando o estabelecimento não tem o valor selecionado para adiantamento na agenda.

#Endpoint

#Homologação

#Importante

#Métodos

#Autenticação

#Request body

#Response body

#Link de pagamento

#Request body

#Response body

#Request body

#Response body

#Recorrência

#Request body

#Response body

#Request body

#Response body

#Request body

#Erros

Endpoint

Homologação

Importante

Métodos

Autenticação

Request body

Response body

Link de pagamento

Request body

Response body

Request body

Response body

Recorrência

Request body

Response body

Request body

Response body

Request body

Erros