Introdução
Para atender os nossos clientes, desenvolvemos esta API onde é possível realizar as consultas de transações e vendas da plataforma, de transações específicas ou por determinados períodos.
Este manual cobre o modelo transacional via API, que realiza a conexão com a Doppus utilizando protocolo HTTPS tendo sua chamada através de Web Services em REST.
Testes na API
Com o objetivo de facilitar a implementação desta API, em alguns métodos são disponibilizadas endpoints de testes que, ao serem executados, validam normalmente os parâmetros enviados. No entanto, como resultado, são sempre retornados valores fixos, apenas como exemplo, independente dos parâmetros enviados.
Autenticação
As APIs listadas nessa documentação utilizam autenticação OAuth2, isso significa que em todas as requisições é necessário informar um token de acesso que será obtido através da autenticação com o seu Client ID e Client Secret.
Token de acesso
Endpoint responsável pela geração do token de acesso utilizado nas demais requisições. Para isso utilizamos HTTP Basic Authentication.
Requisição
POST https://api.app.doppus.com/3.0/auth/
Parâmetros
Header Parameters
Default: "application/x-www-form-urlencoded"
Tipo do conteúdo padrão application/x-www-form-urlencoded.
Authorization: Basic AuthString
Onde AuthString é a concatenação do seu Client ID, seguido de “:” (dois pontos) mais seu Client Secret, convertidos para base64.
Como exemplo: Para o Client ID igual a client-01 e Client Secret igual a secret-key-02, teremos o texto client-01:secret-key-02 após a concatenação, convertendo para base64 teremos o resultado 2xpZW50LTAxOnNlY3JldC1rZXktMDI=.
Neste caso o Authorization no header da requisição será: Authorization: Basic Y2xpZW50LTAxOnNlY3JldC1rZXktMDI=
FormData Parameters
Default: "client_credentials"
Usar o valor fixo "client_credentials".
Response
Request samples
https://api.app.doppus.com/3.0/auth \
-H 'authorization: Basic Y2xpZW50LTAxOnNlY3JldC1rZXktMDI=' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'
Response samples
"success": true,
"error": [],
"return_type": 0,
"message": "Access token successfully generated.",
"data": {
"token": "b3d9217f-4eb7-6f1f-a9c7-99ef069faed0",
"token_type": "Bearer",
"expire_in": 3600
}
}
Vendas
Consultas a uma transação específica ou transações de um determinado período podem ser realizadas através de requisições aos endpoints abaixo.
Consultar venda
Para realizar uma consulta a uma transação específica basta acionar o endpoint abaixo informando o código da transação.
Requisição
GET https://api.app.doppus.com/3.0/sales/{transaction_code}
Endpoint para testes
GET https://api.app.doppus.com/3.0/sales_test/{transaction_code}/
Este endpoint retornará sempre dados estáticos de uma transação qualquer. O objetivo é você testar o envio dos parâmetros e o tratamento dos dados recebidos.
Parâmetros
Header Parameters
Default: "application/json"
Tipo do conteúdo padrão application/json.
Authorization: Bearer AuthString
Onde AuthString é o token de acesso obtido no endpoint de autenticação.
Path parameters
Código de transação da venda. Informe apenas números.
Response
Request samples
Response samples
"success": true,
"error": [],
"return_type": 0,
"message": "Transaction found.",
"data": {
"transaction_code": "27536126",
"registration_date": "2020-12-07 20:45:49",
"customer": {
"name": "Elton John",
"doc_type": "CPF",
"doc": "919.359.381-59",
"email": "eltonjohn@gmail.com",
"phone": "(48) 99123-4567"
},
"address": {
"zipcode": "88123-456",
"address": "Rua dos Artistas",
"number": "123",
"neighborhood": "Centro",
"city": "Florianópolis",
"state": "SC"
},
"transaction": {
"cost_price": 119.76,
"sale_price": 143.07,
"shipping_value": 3.2,
"total": 145.07,
"discount": 1.2,
"platform_rate": 2.9,
"doppus_fee": 3.1,
"estimated_profit": 25.31
},
"payment": {
"payment_type": 2,
"payment_type_text": "Boleto bancário",
"due_date": "2020-12-07",
"digitable_line": "03399.23559 15900.000009 31179.301010 4 84340000002610"
},
"items": [
{
"code": "44293",
"description": "Curso de Guitarra",
"type": 2,
"type_text": "Produto digital/serviço",
"amount": 1,
"cost_price": 7.65,
"sale_price": 10.98
},
{
"code": "24231",
"description": "Guitarra Fender",
"type": 1,
"type_text": "Produto físico",
"amount": 1,
"cost_price": 112.11,
"sale_price": 132.09
}
],
"shipping": {
"method": "Remessa Personalizada 1",
"deadline": 12
},
"tracking": {
"ip_address": "192.230.12.168"
},
"links": {
"get": "https://api.app.doppus.com/3.0/sales/27536126",
"url_billet": "https://doppus.com/checkout/billet/4261.4734.37fd"
},
"last_status_date": "2020-12-07 20:45:49",
"status_code": 0,
"status_text": "Aguardando",
"status_log": [
{
"registration_date": "2020-12-07 20:45:49",
"status": 0,
"status_text": "Aguardando",
"message": "EM ABERTO"
}
]
}
}
Consultar vendas por data de transação
Para realizar consultas das transações ocorridas em um determinado período basta acionar o endpoint abaixo informando os parâmetros solicitados.
Requisição
GET https://api.app.doppus.com/3.0/sales/
Endpoint para testes
GET https://api.app.doppus.com/3.0/sales_test/
Este endpoint retornará sempre dados estáticos de duas transações quaisquer. O objetivo é você testar o envio dos parâmetros e o tratamento dos dados recebidos.
Parâmetros
Header Parameters
Default: "application/json"
Tipo do conteúdo padrão application/json.
Authorization: Bearer AuthString
Onde AuthString é o token de acesso obtido no endpoint de autenticação.
Path parameters
Data inicial do período desejado. Utilize o formato 'YYYY-MM-DD'.
Data final do período desejado. Utilize o formato 'YYYY-MM-DD'.
Página requisitada de uma paginação com 50 registros. Se não informar será retornada a primeira página.
Status desejado. Utilize "1' para aguardando, "2" para recusadas, "3" para canceladas, "4" para pagas, "5" para estornadas, "6" para chargeback, "7" para em análise e "8" para não concluídas.
Response
Request samples
'https://api.app.doppus.com/3.0/sales/?registration_date_start=2020-11-01& registration_date_end=2020-11-20'
Response samples
"success": true,
"error": [],
"return_type": 0,
"message": "Transactions found.",
"data": [
{
"transaction_code": "27536126",
"registration_date": "2020-12-07 20:45:49",
"customer": {
"name": "Elton John",
"doc_type": "CPF",
"doc": "919.359.381-59",
"email": "eltonjohn@gmail.com",
"phone": "(48) 99123-4567"
},
"address": {
"zipcode": "88123-456",
"address": "Rua dos Artistas",
"number": "123",
"neighborhood": "Centro",
"city": "Florianópolis",
"state": "SC"
},
"transaction": {
"cost_price": 119.76,
"sale_price": 143.07,
"shipping_value": 3.2,
"total": 145.07,
"discount": 1.2,
"platform_rate": 2.9,
"doppus_fee": 3.1,
"estimated_profit": 25.31
},
"payment": {
"payment_type": 2,
"payment_type_text": "Boleto bancário",
"due_date": "2020-12-07",
"digitable_line": "03399.23559 15900.000009 31179.301010 4 84340000002610",
},
"items": [
{
"code": "44293",
"description": "Curso de Guitarra",
"type": 2,
"type_text": "Produto digital/serviço",
"amount": 1,
"cost_price": 7.65,
"sale_price": 10.98
},
{
"code": "24231",
"description": "Guitarra Fender",
"type": 1,
"type_text": "Produto físico",
"amount": 1,
"cost_price": 112.11,
"sale_price": 132.09
}
],
"shipping": {
"method": "Remessa Personalizada 1",
"deadline": 12
},
"tracking": {
"ip_address": "192.230.12.168"
},
"links": {
"get": "https://api.app.doppus.com/3.0/sales/27536126",
"url_billet": "https://doppus.com/checkout/billet/4261.4734.37fd"
},
"last_status_date": "2020-12-07 20:45:49",
"status_code": 0,
"status_text": "Aguardando",
"status_log": [
{
"registration_date": "2020-12-07 20:45:49",
"status": 0,
"status_text": "Aguardando",
"message": "EM ABERTO"
}
]
}
]
}
Consultar vendas por data do último status
Para realizar consultas das transações que tiveram seu status alterado em um determinado período basta acionar o endpoint abaixo informando os parâmetros solicitados.
Requisição
GET https://api.app.doppus.com/3.0/sales/
Endpoint para testes
GET https://api.app.doppus.com/3.0/sales_test/
Este endpoint retornará sempre dados estáticos de duas transações quaisquer. O objetivo é você testar o envio dos parâmetros e o tratamento dos dados recebidos.
Parâmetros
Header Parameters
Default: "application/json"
Tipo do conteúdo padrão application/json.
Authorization: Bearer AuthString
Onde AuthString é o token de acesso obtido no endpoint de autenticação.
Path parameters
Data inicial do período desejado. Utilize o formato 'YYYY-MM-DD'.
Data final do período desejado. Utilize o formato 'YYYY-MM-DD'.
Página requisitada de uma paginação com 50 registros. Se não informar será retornada a primeira página.
Status desejado. Utilize "1' para aguardando, "2" para recusadas, "3" para canceladas, "4" para pagas, "5" para estornadas, "6" para chargeback, "7" para em análise e "8" para não concluídas.
Response
Request samples
'https://api.app.doppus.com/3.0/sales/?last_status_date_start=2020-11-01& last_status_date_end=2020-11-20'
Response samples
"success": true,
"error": [],
"return_type": 0,
"message": "Transactions found.",
"data": [
{
"transaction_code": "27536126",
"registration_date": "2020-12-07 20:45:49",
"customer": {
"name": "Elton John",
"doc_type": "CPF",
"doc": "919.359.381-59",
"email": "eltonjohn@gmail.com",
"phone": "(48) 99123-4567"
},
"address": {
"zipcode": "88123-456",
"address": "Rua dos Artistas",
"number": "123",
"neighborhood": "Centro",
"city": "Florianópolis",
"state": "SC"
},
"transaction": {
"cost_price": 119.76,
"sale_price": 143.07,
"shipping_value": 3.2,
"total": 145.07,
"discount": 1.2,
"platform_rate": 2.9,
"doppus_fee": 3.1,
"estimated_profit": 25.31
},
"payment": {
"payment_type": 2,
"payment_type_text": "Boleto bancário",
"due_date": "2020-12-07",
"digitable_line": "03399.23559 15900.000009 31179.301010 4 84340000002610",
},
"items": [
{
"code": "44293",
"description": "Curso de Guitarra",
"type": 2,
"type_text": "Produto digital/serviço",
"amount": 1,
"cost_price": 7.65,
"sale_price": 10.98
},
{
"code": "24231",
"description": "Guitarra Fender",
"type": 1,
"type_text": "Produto físico",
"amount": 1,
"cost_price": 112.11,
"sale_price": 132.09
}
],
"shipping": {
"method": "Remessa Personalizada 1",
"deadline": 12
},
"tracking": {
"ip_address": "192.230.12.168"
},
"links": {
"get": "https://api.app.doppus.com/3.0/sales/27536126",
"url_billet": "https://doppus.com/checkout/billet/4261.4734.37fd"
},
"last_status_date": "2020-12-07 20:45:49",
"status_code": 0,
"status_text": "Aguardando",
"status_log": [
{
"registration_date": "2020-12-07 20:45:49",
"status": 0,
"status_text": "Aguardando",
"message": "EM ABERTO"
}
]
}
]
}
Tabelas de códigos
Para referência dos códigos utilizados nessa API você pode consultar as tabelas abaixo.
Status de transação
Tabela de referência dos status de transação.
Código | Descrição |
---|---|
1 | Aguardando pagamento. |
2 | Pagamento cancelado (Boleto vencido ou PIX expirado). |
3 | Pagamento recusado (problemas nos dados ou no cartão de crédito). |
4 | Transação aguardando análise de pagamento. |
5 | Transação com pagamento realizado. |
6 | Pagamento concluído (após período de devolução). |
7 | Em processo de estorno. |
8 | Transação com pagamento estornado. |
9 | Em processo de contestação. |
10 | Transação com pagamento contestado. |
11 | Transação com pagamento reclamado (pendente). |
12 | Transação com pagamento reembolsado. |
13 | Chargeback realizado. |
Retornos de requisição
Tabela de referência dos retornos das requisições a API.
Código | Descrição |
---|---|
1 | Requisição bem sucedida. Retorno HTTP 200. |
2 | Requisição bem sucedida, objeto criado. Retorno HTTP 201. |
3 | Requisição bem sucedida, sem retorno de dados. Retorno HTTP 204. |
4 | Requisição inválida. Retorno HTTP 400. |
5 | Erro na autenticação. Retorno HTTP 401. |
6 | Sem permissão para executar. Retorno HTTP 403. |
7 | Recurso não encontrado. Retorno HTTP 404. |
Tipos de produto
Tabela de referência dos tipos de produtos de uma transação.
Código | Descrição |
---|---|
1 | Produto físico. |
2 | Info-produto. |
3 | Dropshipping. |
4 | Assinatura. |
5 | Order bump. |
6 | Kit. |
Meios de pagamento
Tabela de referência dos meios de pagamento de uma transação.
Código | Descrição |
---|---|
1 | Cartão de crédito. |
2 | Boleto bancário. |
3 | PIX. |