Criação de ordem de compra

POST /api/orders/:slug/

  • Cria uma nova ordem de compra para o plano com o slug fornecido
  • Os campos global_account, client_email e identity são obrigatórios
  • Os campos client_name e client_cpf são opcionais
  • Se o campo active_until for fornecido, será criada uma ordem trial
  • Os campos discount_amount e discount_description são opcionais
  • O valor do campo discount_amount poderá ser exibido para o cliente durante o processo de compra e na faturas onde o desconto for aplicado
Parâmetro Descrição Default Exemplo
global_account UUID do grupo do cliente   bea39914-0291-42cc-8698-6b400f511ff4
client_email email do cliente   fulano@exemplo.com.br
client_name nome completo do cliente   Nome do cliente
client_cpf CPF/CNPJ do cliente   157.027.254-92
active_until Data que o tempo de atividade da ordem termina   2012-05-28
identity UUID do cliente   ac3540c7-5453-424d-bdfd-8ef2d9ff78df
discount_amount Valor do desconto   5.99
discount_description Descrição do desconto   Promoção para novos clientes
Código de retorno Descrição
201 Created Operação completada com sucesso
400 Bad Request Um ou mais parâmetros fornecidos possui valor inválido, ver corpo da resposta
401 Unauthorized Credenciais da aplicação não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
409 Conflict Já existe ordem de compra ativa para este cliente no plano fornecido
500 Internal Server Error Erro interno do Ecommerce

Listagem de ordens de compra

GET /api/orders/:slug/

  • Lista de ordens de compra para o plano com o slug fornecido.
Parâmetro Descrição Default Exemplo
page Determina a página de resultados 1 3
limit Limita o número de notificações 20 50
  • As informações de paginação são incluidas no header Link de cada resposta, conforme necessário, como exemplificado abaixo:

    Link: <https://ecommerce.myfreecomm.com.br/api/orders/:slug?page=3&limit=1>; rel=next,
          <https://ecommerce.myfreecomm.com.br/api/orders/:slug?page=1&limit=1>; rel=prev,
          <https://ecommerce.myfreecomm.com.br/api/orders/:slug?page=3&limit=1>; rel=last,
          <https://ecommerce.myfreecomm.com.br/api/orders/:slug?page=1&limit=1>; rel=first
    
Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Não existe plano identificável pelo slug fornecido
500 Internal Server Error Erro interno do Ecommerce

Detalhes de uma ordem de compra

GET /api/orders/:slug/:id

  • Mostra detalhes da ordem de compra com o id fornecido para o plano com o slug fornecido.
  • Não recebe parâmetros.
Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Não existe plano identificável pelo slug fornecido. Não existe ordem identificável pelo ID fornecido para o plano com o slug fornecido.
500 Internal Server Error Erro interno do Ecommerce

Cancelamento de uma ordem de compra

DELETE /api/orders/:slug/:id

  • Cancela uma ordem de compra com o id fornecido para o plano com o slug fornecido.
  • Não recebe parâmetros.
Código de retorno Descrição
204 No Content Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Não existe plano identificável pelo slug fornecido. Não existe ordem identificável pelo ID fornecido para o plano com o slug fornecido.
500 Internal Server Error Erro interno do Ecommerce

Alteração dos dados do cliente de uma ordem de compra

PUT /api/orders/:slug/:id

  • Altera dados do cliente de uma ordem de compra com o id fornecido para o plano com o slug fornecido.
  • Os campos identity, document_number, client_email e client_name são obrigatórios.
  • Caso o valor fornecido para o campo document_number seja um CNPJ, todos os campos são obrigatórios.
Parâmetro Descrição Default Exemplo
identity UUID do cliente   ac3540c7-5453-424d-bdfd-8ef2d9ff78df
document_number CPF ou CNPJ do cliente   157.027.254-92
client_email Email do cliente   fulano@exemplo.com.br
client_name Nome completo do cliente   Nome do cliente
address Endereço do cliente   Av. Presidente Vargas
address_number Numero do endereço do cliente   43
address_complement Complemento do endereço do cliente   11º andar
address_quarter Bairro do cliente   Centro
address_city Cidade do cliente   Rio de Janeiro
address_state Estado do cliente   RJ
zip_code CEP do cliente   20001-201
Código de retorno Descrição
201 OK Operação completada com sucesso
400 Bad Request Um ou mais parâmetros fornecidos possui valor inválido, ver corpo da resposta
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Não existe plano identificável pelo slug fornecido. Não existe ordem identificável pelo ID fornecido para o plano com o slug fornecido.
500 Internal Server Error Erro interno do Ecommerce

Listagem das faturas associadas a uma ordem de compra

GET /api/orders/:slug/:id/invoices/

  • Lista faturas associadas à ordem de compra referenciada
  • As informações de paginação são incluidas no header Link de cada resposta, conforme necessário, como exemplificado abaixo:

    Link: <https://ecommerce.myfreecomm.com.br/api/orders/:slug/:id/invoices/paid/?page=3&limit=1>; rel=next,
        <https://ecommerce.myfreecomm.com.br/api/orders/:slug/:id/invoices/paid/?page=1&limit=1>; rel=prev,
        <https://ecommerce.myfreecomm.com.br/api/orders/:slug/:id/invoices/paid/?page=3&limit=1>; rel=last,
        <https://ecommerce.myfreecomm.com.br/api/orders/:slug/:id/invoices/paid/?page=1&limit=1>; rel=first
    
Parâmetro Descrição Default Exemplos
page Determina a página de resultados 1 3
limit Limita o número de notificações 20 50
Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Ordem de compra inexistente
500 Internal Server Error Erro interno do Ecommerce

Exemplo (informações somente ilustrativas):

GET http://sandbox.ecommerce.myfreecomm.com.br/api/myfinance-silver_annual/2141/invoices/
Accept-Encoding: gzip, deflate
Cache-Control: no-cache
Content-Type: application/json
Accept: application/json
Authorization: Basic amtBS1sOUsxndgpHUGp6elpac8U3dnNRUWl6WmtceFZG9kxjelK0dNNTZg==
[{
    "redeemed_adjustments": [{
        "amount": "-18.98",
        "description": "Desconto para arredondar valor"
    }],
    "order_url": "http://sandbox.ecommerce.myfreecomm.com.br/api/orders/myfinance-silver_annual/2141/",
    "url": "http://sandbox.ecommerce.myfreecomm.com.br/api/myfinance-silver_annual/2141/invoices/1740/",
    "created_at": "2013-08-09 14:35:16",
    "activated_at": "2013-11-04 19:11:04",
    "number": 1740,
    "user_data": {
        "address_city": "Vale do Juruá",
        "address_complement": "apto 1104",
        "address_number": "120",
        "address_quarter": "Cruzeiro do Sul",
        "client_name": "Vitor M. A. da Cruz",
        "address_state": "AC",
        "client_email": "vitormazzi@test.example",
        "address": "Rua Sávio Saad",
        "document_number": "88888888888",
        "zip_code": "54710-325"
    },
    "amount_with_adjustments": "1000.00",
    "amount": "1018.98",
    "paid_at": "2013-11-04 19:11:00",
    "payment_method": "buypage :: visa",
    "plan_data": {
        "slug": "myfinance-silver_annual",
        "name": "MyFinance Silver Anual",
        "description": "Pequenas empresas que buscam gestão financeira na medida certa."
    },
    "charge_date": "2014-09-08",
    "next_payment_date": "2014-10-08"
}, {
    "redeemed_adjustments": [],
    "order_url": "http://sandbox.ecommerce.myfreecomm.com.br/api/orders/myfinance-silver_annual/2141/",
    "url": "http://sandbox.ecommerce.myfreecomm.com.br/api/myfinance-silver_annual/2141/invoices/1810/",
    "created_at": "2013-11-05 09:33:10",
    "activated_at": null,
    "number": 1810,
    "user_data": {
        "address_city": "Vale do Juruá",
        "address_complement": "apto 1104",
        "address_number": "120",
        "address_quarter": "Cruzeiro do Sul",
        "client_name": "Vitor M. A. da Cruz",
        "address_state": "AC",
        "client_email": "vitormazzi@test.example",
        "address": "Rua Sávio Saad",
        "document_number": "88888888888",
        "zip_code": "54710-325"
    },
    "amount_with_adjustments": "1.00",
    "amount": "1.00",
    "paid_at": "2013-11-05 09:33:12",
    "payment_method": "buypage :: mastercard",
    "plan_data": {
        "slug": "myfinance-silver_annual",
        "name": "MyFinance Silver Anual",
        "description": "Pequenas empresas que buscam gestão financeira na medida certa."
    },
    "charge_date": "2013-11-05",
    "next_payment_date": "2013-12-08"
}]

Obtenção dos dados de uma fatura

GET /api/orders/:slug/:order_id/invoices/:id/

  • Obtém os dados da fatura
Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Fatura inexistente
500 Internal Server Error Erro interno do Ecommerce

Exemplo (informações somente ilustrativas):

GET http://sandbox.ecommerce.myfreecomm.com.br/api/myfinance-silver_annual/2141/invoices/1740/
Accept-Encoding: gzip, deflate
Cache-Control: no-cache
Content-Type: application/json
Accept: application/json
Authorization: Basic amtBS1sOUsxndgpHUGp6elpac8U3dnNRUWl6WmtceFZG9kxjelK0dNNTZg==
{
    "redeemed_adjustments": [{
        "amount": "-18.98",
        "description": "Desconto para arredondar valor"
    }],
    "order_url": "http://sandbox.ecommerce.myfreecomm.com.br/api/orders/myfinance-silver_annual/2141/",
    "url": "http://sandbox.ecommerce.myfreecomm.com.br/api/myfinance-silver_annual/2141/invoices/1740/",
    "created_at": "2013-08-09 14:35:16",
    "activated_at": "2013-11-04 19:11:04",
    "number": 1740,
    "user_data": {
        "address_city": "Vale do Juruá",
        "address_complement": "apto 1104",
        "address_number": "120",
        "address_quarter": "Cruzeiro do Sul",
        "client_name": "Vitor M. A. da Cruz",
        "address_state": "AC",
        "client_email": "vitormazzi@test.example",
        "address": "Rua Sávio Saad",
        "document_number": "88888888888",
        "zip_code": "54710-325"
    },
    "amount_with_adjustments": "1000.00",
    "amount": "1018.98",
    "paid_at": "2013-11-04 19:11:00",
    "payment_method": "buypage :: visa",
    "plan_data": {
        "slug": "myfinance-silver_annual",
        "name": "MyFinance Silver Anual",
        "description": "Pequenas empresas que buscam gestão financeira na medida certa."
    },
    "charge_date": "2014-09-08",
    "next_payment_date": "2014-10-08"
}

Criação de desconto para uma ordem de compra

POST /api/orders/:slug/:id/discounts/

  • Cria um novo desconto para a ordem de compra referenciada
  • Os campos amount e description são obrigatórios
  • Os campos valid_from e valid_until são opcionais
  • Se o campo valid_from for fornecido, a vigência do desconto se iniciará nesta data
  • Se o campo valid_until for fornecido, a vigência do desconto se estenderá até esta data
Parâmetro Descrição Default Exemplo
amount Valor do desconto   5.99
description Descrição do desconto   Promoção para novos clientes
valid_from Inicio da vigência do desconto   2012-05-28
valid_until Fim da vigência do desconto   2012-05-30
Código de retorno Descrição
201 Created Operação completada com sucesso
400 Bad Request Um ou mais parâmetros fornecidos possui valor inválido, ver corpo da resposta
401 Unauthorized Credenciais da aplicação não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Ordem de compra inexistente
500 Internal Server Error Erro interno do Ecommerce

Listagem dos descontos associados a uma ordem de compra

GET /api/orders/:slug/:id/discounts/

  • Lista descontos associados à ordem de compra referenciada
Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Ordem de compra inexistente
500 Internal Server Error Erro interno do Ecommerce

Criação de alteração de valor para uma ordem de compra

POST /api/orders/:slug/:id/adjustments/

  • Cria uma nova alteração de valor para a ordem de compra referenciada. Alterações de valor podem representar acréscimos ou descontos.
  • Os campos amount e description são obrigatórios.
  • Caso o valor fornecido no campo amount seja positivo o ajuste criado será um acréscimo, caso ele seja negativo o ajuste será um desconto
  • Os campos valid_from e valid_until são opcionais
  • Se o campo valid_from for fornecido, a vigência do alteração de valor se iniciará nesta data
  • Se o campo valid_until for fornecido, a vigência do alteração de valor se estenderá até esta data
Parâmetro Descrição Default Exemplo
amount Valor da alteração   -5.99
description Descrição da alteração   Promoção para novos clientes
valid_from Inicio da vigência do alteração   2012-05-28
valid_until Fim da vigência do alteração   2012-05-30
Código de retorno Descrição
201 Created Operação completada com sucesso
400 Bad Request Um ou mais parâmetros fornecidos possui valor inválido, ver corpo da resposta
401 Unauthorized Credenciais da aplicação não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Ordem de compra inexistente
500 Internal Server Error Erro interno do Ecommerce

Listagem das alterações de valor associadas a uma ordem de compra

GET /api/orders/:slug/:id/adjustments/

Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Ordem de compra inexistente
500 Internal Server Error Erro interno do Ecommerce

Obtenção dos dados de uma alteração de valor

GET /api/orders/:slug/:order_id/adjustments/:id/

Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Alteração de valor inexistente
500 Internal Server Error Erro interno do Ecommerce

Remoção de uma alteração de valor

DELETE /api/orders/:slug/:order_id/adjustments/:id/

  • Remove a alteração de valor referenciada
  • Alterações de valor criadas utilizando a api de Criação de desconto para uma ordem de compra também podem ser removidas por esta operação.
  • Somente alterações que ainda não tenham sido associadas a uma fatura poderão ser removidas.
Código de retorno Descrição
204 No Content Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Alteração de valor inexistente
409 Conflict A alteração de valor referenciada já foi associada a uma fatura.
500 Internal Server Error Erro interno do Ecommerce

Listagem das ordens de compra de uma conta

GET /api/accounts/:account_uuid/orders/

  • Lista de ordens de compra para a conta fornecida
  • Leva em consideração todos os produtos acessíveis pelas credenciais utilizadas
Parâmetro Descrição Default Exemplo
page Determina a página de resultados 1 3
limit Limita o número de notificações 20 50
  • As informações de paginação são incluidas no header Link de cada resposta, conforme necessário, como exemplificado abaixo:

    Link: <https://ecommerce.myfreecomm.com.br/api/accounts/:account_uuid/orders/?page=3&limit=1>; rel=next,
          <https://ecommerce.myfreecomm.com.br/api/accounts/:account_uuid/orders/?page=1&limit=1>; rel=prev,
          <https://ecommerce.myfreecomm.com.br/api/accounts/:account_uuid/orders/?page=3&limit=1>; rel=last,
          <https://ecommerce.myfreecomm.com.br/api/accounts/:account_uuid/orders/?page=1&limit=1>; rel=first
    
Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Não existe plano identificável pelo slug fornecido
500 Internal Server Error Erro interno do Ecommerce

Listagem das faturas pagas para um plano

GET /api/:slug/invoices/paid/

  • Lista faturas pagas referentes a um plano
  • As informações de paginação são incluidas no header Link de cada resposta, conforme necessário, como exemplificado abaixo:

    Link: <https://ecommerce.myfreecomm.com.br/api/:slug/invoice/paid/?page=3&limit=1&since=2014-01-13>; rel=next,
        <https://ecommerce.myfreecomm.com.br/api/:slug/invoice/paid/?page=1&limit=1&since=2014-01-13>; rel=prev,
        <https://ecommerce.myfreecomm.com.br/api/:slug/invoice/paid/?page=3&limit=1&since=2014-01-13>; rel=last,
        <https://ecommerce.myfreecomm.com.br/api/:slug/invoice/paid/?page=1&limit=1&since=2014-01-13>; rel=first
    
Parâmetro Descrição Default Exemplos
page Determina a página de resultados 1 3
limit Limita o número de notificações 20 50
since Retorna somente as faturas pagas a partir desta data. Um mês atrás 2014-01-13 ou 2014-01-13 18:21:00
Código de retorno Descrição
200 OK Operação completada com sucesso
401 Unauthorized Credenciais não informadas
403 Forbidden Credenciais informadas são inválidas para este recurso (ex: api_token do consumer). Consumer não autorizado para esta operação.
404 Not Found Ordem de compra inexistente
500 Internal Server Error Erro interno do Ecommerce

Exemplo (informações somente ilustrativas):

GET http://sandbox.ecommerce.myfreecomm.com.br/api/myfinance-silver_annual/invoices/paid/?since=2013-10-01
Accept-Encoding: gzip, deflate
Cache-Control: no-cache
Content-Type: application/json
Accept: application/json
Authorization: Basic amtBS1sOUsxndgpHUGp6elpac8U3dnNRUWl6WmtceFZG9kxjelK0dNNTZg==
[{
    "redeemed_adjustments": [{
        "amount": "-18.98",
        "description": "Desconto para arredondar valor"
    }],
    "order_url": "http://sandbox.ecommerce.myfreecomm.com.br/api/orders/myfinance-silver_annual/2141/",
    "url": "http://sandbox.ecommerce.myfreecomm.com.br/api/myfinance-silver_annual/2141/invoices/1740/",
    "created_at": "2013-08-09 14:35:16",
    "activated_at": "2013-11-04 19:11:04",
    "number": 1740,
    "user_data": {
        "address_city": "Vale do Juruá",
        "address_complement": "apto 1104",
        "address_number": "120",
        "address_quarter": "Cruzeiro do Sul",
        "client_name": "Vitor M. A. da Cruz",
        "address_state": "AC",
        "client_email": "vitormazzi@test.example",
        "address": "Rua Sávio Saad",
        "document_number": "88888888888",
        "zip_code": "54710-325"
    },
    "amount_with_adjustments": "1000.00",
    "amount": "1018.98",
    "paid_at": "2013-11-04 19:11:00",
    "payment_method": "buypage :: visa",
    "plan_data": {
        "slug": "myfinance-silver_annual",
        "name": "MyFinance Silver Anual",
        "description": "Pequenas empresas que buscam gestão financeira na medida certa."
    },
    "charge_date": "2014-09-08",
    "next_payment_date": "2014-10-08"
}, {
    "redeemed_adjustments": [],
    "order_url": "http://sandbox.ecommerce.myfreecomm.com.br/api/orders/myfinance-silver_annual/2141/",
    "url": "http://sandbox.ecommerce.myfreecomm.com.br/api/myfinance-silver_annual/2141/invoices/1810/",
    "created_at": "2013-11-05 09:33:10",
    "activated_at": null,
    "number": 1810,
    "user_data": {
        "address_city": "Vale do Juruá",
        "address_complement": "apto 1104",
        "address_number": "120",
        "address_quarter": "Cruzeiro do Sul",
        "client_name": "Vitor M. A. da Cruz",
        "address_state": "AC",
        "client_email": "vitormazzi@test.example",
        "address": "Rua Sávio Saad",
        "document_number": "88888888888",
        "zip_code": "54710-325"
    },
    "amount_with_adjustments": "1.00",
    "amount": "1.00",
    "paid_at": "2013-11-05 09:33:12",
    "payment_method": "buypage :: mastercard",
    "plan_data": {
        "slug": "myfinance-silver_annual",
        "name": "MyFinance Silver Anual",
        "description": "Pequenas empresas que buscam gestão financeira na medida certa."
    },
    "charge_date": "2013-11-05",
    "next_payment_date": "2013-12-08"
}]