Opções binárias site:mercadolivre.com.br.
Com esta funcionalidade você pode disponibilizar os detalhes de faturamento realizados no Mercado Livre e Mercado Pago para os vendedores. Para isto, recomendamos consultar o endpoint de periods para obter a informação dos períodos e logo acessar a informação dos documentos por período (documents) , o detalhe de comissões de un período (details) e o resumo de cobranças e bonificação do vendedor em um período (summary) .
Faturamento do Mercado Livre e Mercado Pago.
Cada um dos endpoints permite obter informação de faturamento tanto do Mercado Livre, como do Mercado Pago. Através do parâmetro de query obrigatório group podemos especificar de que grupo de faturamento queremos obter a informação.
- É importante ter em conta que as datas de fim do período expiration date de cada entidade (MP | ML) podem não coincidir. Pontanto ao momento de consultar os endpoints que requerem inserção de uma data de fim de período, o expiration date que for usado tem que estar associado ao group (MP | ML) que foi escolhido no momento de consumir o endpoint “periods”, caso contrário devolverá informação incorreta.
- O parâmetro document type é obrigatório em /periods e opcional em /documents.
- O parâmetro limit suporta até 12 como máximo em /periods.
Obter período.
O período de faturamento pode variar segundo o usuário.
Permite obter informação dos períodos de facturamento para o grupo de facturamento indicado (Mercado Livre ou Mercado Pago). Por padrão devolvemos os últimos 6 períodos, com a possibilidade de consultar períodos mais antigos utilizando a paginação de offset y limit.
Através do parâmetro document type pode ser filtrado o tipo de documento que se deseja obter BILL | CREDIT NOTE .
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods?group=MP&document type=BILL&offset=1&limit=2.
, "expiration date": "2022-03-24", "debt expiration date": "2022-03-24", "debt expiration date move reason": null, "debt expiration date move reason description": null, "period status": "CLOSED" >, , "expiration date": "2022-02-24", "debt expiration date": "2022-03-23", "debt expiration date move reason": "PAYMENT ANNULMENT", "debt expiration date move reason description": "Anulación de pago", "period status": "CLOSED" > ] >
Campos da resposta.
date from : data de início do período. date to : data de fim do período.
expiration date : data de fim do período. Se informa sempre que o estado do período se encontra fechado. Valor utilizado para consumir os endpoints de documents, details e summary.
debt expiration date : data de vencimento da dívida. No caso que não se mova a data de vencimento este campo será igual ao expiration date . debt expiration date move reason : motivo da mudança de data de vencimento da dívida. No caso que não se mova a data de vencimento este campo será null. Valores possíveis: : AUTOMATIC DOCUMENT CLOSURE PROCES | RECEIPT ANNULMENT PROCESS UNRECORDED | RECEIPT ANNULMENT PROCESS | PERIOD EXTENDED BY ADMIN | PAYMENT ANNULMENT.
debt expiration date move reason description : descrição internacionalizada de debt expiration date move reason . No caso que não se mova a data de vencimento este campo será null.
period status : indica se o período se encontra aberto ou fechado. Valores possíveis: OPEN | CLOSED .
Obter documentos de um período.
Permite obter informação de documentos (faturas e notas de crédito) para um período de faturamento em particular para o grupo de faturamento indicado (Mercado Livre ou Mercado Pago).
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods//documents.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods/202 1-06-02/documents?group=MP&document type=BILL&limit=1.
, "currency id": "MXN", "count details": 1, "files": [ , ] >] >
Filtros opcionais.
document id : permite buscar pelo ID da fatura. Ex: document id=987046992 document type : permite buscar por tipo de documento: Fatura ou Nota de Crédito. Valores possíveis: BILL | CREDIT NOTE offset : permite buscar desde um número de resultado adiante. Ex: offset=100 (devollve a partir do resultado número 100). limit : limita a quantidade de resultados. Por padrão o mínimo é 150. Máximo valor permitido: 1000. Ex: limit=300 (devolve até 300 resultados).
Resumo de faturamento.
Permite obter o resumo de comissões e bonificações que teve o vendedor para um período de tempo em particular.
Através do paramêtro document type pode ser filtrado o tipo de documento que se deseja obter BILL | CREDIT NOTE .
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods//summary.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods/2021-06 -02/summary?group=MP&document type=BILL.
, "period": , "summary": , , ], "charges": [ , , , ] > >
Campos da resposta.
summary : cobranças e bonificações que o vendedor teve. amount : total a pagar dentro do período de faturamento consultado. É formado pela soma de Cobranças e Impostos subtraindo as Bonificações. credit note : bonificações de cobranças gerados em outros períodos. As notas de crédito são utilizadas para pagar faturas de dividas. tax : percepções geradas por distintos regimes tributários (Argentina). bonuses : reembolso de comissões por suas vendas e serviços que não se concretizaram. Você vai vê-los discriminados segundo o tipo de bonificação.
As bonificações podem ser pelos seguintes conceitos:
Cobranças de venda e envios : se uma venda não se concretiza devido a uma devolução ou por problemas no transporte (como perda ou dano do produto), reembolsaremos a comissão de venda e a cobrança do envio.
Cobranças de publicidade : se por erro for contratado o serviço ou houve algum problema com o pagamento, reembolsaremos a diferença.
Bonificações por Percepções Tributárias : quando se devolve uma cobrança por venda também se inclui a devolução correspondente da percepção tributária de IVA (já seja por um anúncio de novo ou usado) e da renda bruta. O mesmo se houver erros na aplicação de uma percepção.
charges : diferentes cobranças que pode ter o vendedor: comissões por vendas, custo de publicações, percepções tributárias, pagamento de serviços. Por exemplo: Mercado Envios, Mercado Shops, etc.
No caso de contratar campanhas publicitárias, também aparecerão nas cobranças.
Detalhe de conciliação.
Permite obter o detalhe para conciliar as faturas e as cobranças de vendas para um período em particular, ou grupo de facturamento (Mercado Libre ou Mercado Pago) e o tipo de documento (Fatura ou Nota de Crédito). Esta informação é a mesma que se disponibiliza através da seção de relatórios de faturamento.
- Caso a resposta tenha mais de 10.000 registros, você deve usar os filtros a seguir para restringir os resultados., evitando respostas demoradas. - Através del parámetro document type poderá ser filtrado o tipo de documento que se deseja obter BILL | CREDIT NOTE.
Mercado Livre.
Para o caso de Mercado Livre, se expõe o detalhe das cobranças efetuadas, informação de venda, de descontos, de envios e da publicação.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods//group/ML/details.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods/2021-06-02/group/ML/details?document type=BILL&limit=1.
, "discount info": , "sales info": [ , ], "shipping info": , "items info": [ Pequeños Electrodomésticos > Para Cocina > Máquinas para Postres > Máquinas de Cupcakes", "inventory id": null, "item amount": 1, "item price": 2499, "order id": 1234 > ], "document info": , "marketplace info": , "currency info": > ], errors:[] >
Mercado Pago.
Para Mercado Pago se expõe o detalhe de cobranças facturadas com informação complementar sobre a operação do Mercado Pago, como os movimentos, meios de pagamento, payer, filial, ponto de venda entre outros.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods//group/MP/details.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods/2021-06-02/group/MP/details?document type=BILL&limit=1.
, "operation info": , "perception info": , "document info": , "market type info": , "currency info": > ] >
Filtros opcionais.
order by : permite ordenar a busca. asc: ordena os resultados de forma ascendente (valor por default). desc: ordena os resultados de forma descendente. Ex: order by=asc sort by : permite selecionar por que campo ordenar. Valores possíveis: DATE. detail type permite buscar por tipos de detalhes. charge: traz somente cobranças. bonus: traz somente bonificações. Ex: detail type=charge. detail sub types : permite buscar por tipos de detalhes. Se pueden definir varios separados por comas. Se pueden definir varios separados por coma. Ex: detail sub types=CV, BV detail excluded sub types : permite excluir da busca os subtipos de detalhes indicados. Podem ser definidos vários separados por vírgula. Ex: not subtypes=CXD, BXD marketplace type : permite buscar pelo market do detalhe. Ex: marketplace type=SHIPPING order ids : permite buscar por um ou vários ID de order. Disponível para Mercado Libre. Ex: order ids=2294412230 item ids : permite buscar por um ou mais IDs de publicação. Ex: item ids=724159812 document ids : permite buscar por um ou mais IDs de fatura. Ex: document ids=987046992 detail ids : permite buscar por um ou mais IDs de detalhe. Ex: detail ids=724159812 offset : permite buscar desde um número de resultado em diante. O valor mínimo permitido é 0 e o valor máximo permitido é 10000. Por padrão o valor é 0. Ex: offset=100 (devolve a partir do resultado nro 100). limit : limita a quantidade de resultados. Por padrão o mínimo é 1 e o máximo valor permitido: 1000 . Ex: limit=300 (devolve até 300 resultados).
Campos de resposta Mercado Livre.
charge info : informação da cobrança.
legal document number: número do documento. legal document status: estado de criação do documento. Valores possíveis: PROCESSING | PROCESSED. legal document status description: descrição internacionalizada do estado do documento legal document status. creation date time: data de criação da cobrança. detail id: identificador da cobrança. transaction detail: detalhe da cobrança. debited from operation: indica se está descontado da operação. Valores possíveis: YES | NO | INAPPLICABLE. debited from operation description: descrição internacionalizada do campo debited from operation. status: estado da cobrança. Valores possíveis: BONUS ON CREDIT NOTE | BONUS PART ON CREDIT NOTE | BONUS ON BILL | BONUS PART ON BILL | BONUS ON | BONUS PART ON. status description: descrição internacionalizada de status. charge bonified id: identificador da cobrança que bonifica. detail amount: valor da cobrança. detail type: tipo de detalhe. detail sub type: subtipos de detalhes.
discount info : informação sobre descontos.
charge amount without discount: valor da cobrança sem desconto. discount amount: valor do desconto. discount reason: motivo do desconto. sales info: informação de vendas.
sale info : informação sobre a venda.
order id: identificador da venda. operation id: identificador do pagamento. sale date time: data e hora da venda. sales channel: canal de venda. payer nickname: cliente. state name: estado. transaction amount: valor total da venda.
shipping info : informação do envio.
shipping id: identificador do envio. pack id: identificador do pacote. receiver shipping cost: envio a cobrança do cliente.
items info : informação sobre publicações.
item id: identificador da publicação. item title: título da publicação. item type: tipo de publicação. item category: categoria da publicação. inventory id: código de Mercado Livre. item amount: quantidade de itens vendidos. item price: preço unitário de item. order id: ordem à qual o item pertenece.
documentInfo : informação do documento.
document id: número Id de documentos.
marketplaceInfo : informação do marketplace.
marketplace: nome do marketplace.
currency info : informação da moeda de acordo ao site id.
currency id: identificador da moeda de acordo ao site id.
Campos de resposta Mercado Pago.
charge info : informação da cobrança.
legal document number: número do documento. detail id: identificador da cobrança. movement id: número de movimento. transaction detail: detalhe. creation date time: data da cobrança. detail amount: valor da cobrança. detail type: tipo de detalhe. detail sub type: subtipos de detalhes.
operation info : informação de operação sobre a que se aplica.
operation type: tipo de operação. Valores possíveis BUY | TAX. operation type description: descrição internacionalizada do campo operation. reference id: número de operação relacionada. sales channel: tipo de pagamento. store id: número de filial/loja. store name: nome da filial/loja. external reference: número de referência externa. payer nickname: cliente. transation amount: valor da operação.
perception info : informação da percepção.
aliquot: valor da alíquota. taxable amount: base tributável.
documentInfo : informação do documento.
document id: número Id de documentos.
marketplaceInfo : informação do marketplace.
currency info : informação da moeda de acordo ao site id.
currency id: identificador da moeda de acordo ao site id.
Detalhe de conciliação Insurtech.
Permite obter o detalhe para conciliar os encargos e bonificações das garantias aplicadas sobre os produtos para um período em particular, o grupo de faturamento Mercado Livre e o tipo de documento (fatura ou Nota de Crédito). Esta informação é a mesma que se disponibiliza através da seção de relatório de faturamento para los usuarios de Insurtech. As opções de filtro podem ser usadas da mesma forma que temos disponível para os detalhes do Mercado Livre e Mercado Pago.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION DATE/group/ML/insurtech/details.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods/2022-10-02/group/ML/insurtech/details?document type=BILL&limit=1.
, "warranty info": > ] >, "quote model": null, "quote brand": null, "quote description": "" >, "prepaid info": >, "document info": > ]
Campos de resposta Mercado Livre- Insurtech.
charge info : informação da cobrança.
legal document number: número do documento. legal document status: estado de geração do documento. Valores possiveís: PROCESSING | PROCESSED. legal document status description: descrição internacionalizada do estado do documento legal document status. creation date time: data de criação da cobrança. detail id: identificador da cobrança. detail amount: valor da cobrança. transaction detail: detalhe da cobrança. status: estado da cobrança. Valores possíveis: BONUS ON CREDIT NOTE | BONUS PART ON CREDIT NOTE | BONUS ON BILL | BONUS PART ON BILL | BONUS ON | BONUS PART ON. status description: descrição internacionalizada de status. charge bonified id: identificador da cobrança bonificada. detail type: tipo de detalhe. detail sub type: subtipos de detalhes. concept type: ipo de conceito.
wanrranty info : informação da garantia.
wanrranty id: identificador da garantia. certificate id: identificador do certificado. waranty product: tipo de garantia. Valores possíveís: CARDS, GAREX, RODA. buyer nickname: numero do comprador. buyer state name: província do comprador. order: informação da venda. order items: lista de items da venda. unit price: preço por unidade. listing type id: tipo de publicação. item: informação do item. item id: identificador do produto. tittle: titulo do produto. category id: identificador da categoria. category name: nome da categoria. quote model: modelo do produto. Aplica a RODA. quote brand: marca do produto. Aplica a RODA. quote description: descrição adicional. Aplica a RODA.
prepaid info : informação do pagamento.
operation id: identificador da operação. movement id: identificador do pagamento. doc id: identificador do documento.
payment : informação do pagamento.
payment id: identificador do pagamento. date created: data de papamento. transaction amount: valor do pago. money release date: data de liberação do dinheiro.
Download de documento Legal.
Permite baixar as faturas legais do Mercado Livre e Mercado Pago em formato PDF.
- O file id se obtêm consumindo o endpoint de Documents.Em alguns casos, o endpoint de Documents pode devolver dois file id. Nestes casos sempre se deverá utilizar o file id correspondente ao PDF.
- Se o endpoint de Document devolve um único file id. Então esse é o dado para o download do documento legal.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/legal document/
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/legal document/1234 FE MEPF00869625 pdf.
Resposta: download do arquivo em formato PDF .
Download de relatório de detalhe de conciliação.
Para baixar os relatórios de conciliação do Mercado Livre e Mercado Pago nos formatos XLSX y CSV deverá seguir un processo de criação do relatório que consiste em três passos: Primeiro será gerado o relatório de conciliação, logo deve ser consultado o status de criação do mesmo até que se encontre gerado e finalmente se prossiga para o download.
1. Criação do relatório.
Através deste endpoint, se procede com a criação do relatório.
curl -X POST -H 'Authorization: Bearer $ACCESS TOKEN' -H "Content-Type: application/json" -d https://api.mercadolibre.com/billing/integration/periods//reports.
curl -X POST -H 'Authorization: Bearer $ACCESS TOKEN' -d ' ' https://api.mercadolibre.com/billing/integration/periods/2021-08 -04/reports.
2. Estado de criação de relatório.
Através deste endpoint, se obtêm o status da criação de um relatório.Os estados podem ser:
PROCESSING: o relatório está sendo gerado. READY: o relatório terminou de ser criado. ERROR: a criação do relatório falhou, deverá ser consultado novamente.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/reports//status.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/reports/ML-repo rt-BILL-2021-08-04-11119999-CSV-v2/status?document type=BILL.
3. Download do relatório.
Através deste endpoint se permite realizar o download do relatório. Este download poderá ser realizado uma vez que o estado da criação seja “Ready”.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/reports/
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/reports/ML-repo rt-BILL-2021-08-04-11119999-CSV-v2?document type=BILL.
Resumo de percepções.
Permite obter o resumo de percepções que teve o vendedor para um período em particular, ou grupo de faturamento (Mercado Livre ou Mercado Pago).
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods//perceptions/summary.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/periods/2021-08-02/perceptions/summary?group=MP.
Campos de resposta.
summary : informação do resumo.
document id: identificador do documento. society: sociedade. Valores possíveis ML | MP. legal document number: número do documento. user fiscal condition: condição fiscal do usuário. amount: total a pagar dentro do período consultado. regimen tax type: regime do tipo de imposto. regimen tax type description: descrição internacionalizada do regime do tipo de imposto. taxable amount: base tributária. aliquot: valor da alíquota. coefficient: coeficiente que impacta no cálculo do imposto. perception charge number: número de cobrança de percepção. tax type: tipo de imposto. tax type description: descrição internacionalizada do tipo de imposto. bill date: data de faturamento. status: estado do resumo. status description: descrição internacionalizada do estado. tax ids: tipos de impostos.
Detalhe de percepções.
Permite obter o detalhe de uma determinada percepção.Para percepções de Mercado Livre a partir do código de percepção e número de documento. Para percepções de Mercado Pago a partir do código de percepção, número de documento e identificador fiscal.
- Mercado Pago: com o campo tax type , document id e tax id se acessa o detalhe da percepção e do documento indicado nos filtros. Mercado Livre: com o campo tax type e document id se acessa o detalhe da percepção e do documento indicado nos filtros. - Ambos campos são obtidos do endpoint Resumo de percepções. - Os campos de resultados variam de acordo ao tax type consultado: Régimen General, Régimen Especial, Régimen Tucumán.
Mercado Livre.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/group/ML/perceptions/details.
Exemplo (Régimen General):
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/group/ML/perceptions/details?document id=333555777&tax type=CIVA&offset=1&limit=2.
Resposta (Régimen General):
Mercado Pago.
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/group/MP/perceptions/details.
Exemplo (Régimen General):
curl -X GET -H 'Authorization: Bearer $ACCESS TOKEN' https://api.mercadolibre.com/billing/integration/group/MP/perceptions/details?document id=333555777&tax type=CIVAMP&tax id=12345&offset=1&limit=2.
Resposta (Régimen General):
Campos de resposta.
Para Mercado Livre e para uma percepção de Régimen General retornam os seguintes dados:
detail id : identificador do detalhe.
date created : data de criação.
taxable amount : base tributária.
aliquot : valor da alíquota.
tax amount : importe do imposto.
transaction detai : detalhe da transacção.
transaction detail description : descrição internacionalizada de detalhe da transacção.
charge bonified id : identificador da cobrança que bonifica no caso que o cargo seja um bônus.
amount : valor da percepção.
gross amount : valor bruto da percepção.
gross amount : detail type: tipo de detalhe a que aplica a percepção.
gross amount : detail type description: descrição do tipo de detalhe ao que aplica a percepção.
Para Mercado livre e para uma percepção do Régimen Especial se informam tambémos seguintes dados:
publish number : número da publicação.
publish title : título da publicação.
sale date : data de venda.
sale number : número de venda.
buyer name : número do comprador.
buyer state name : estado do comprador.
Para Mercado Livre e para uma percepção do Régimen Tucumán se informa também o seguinte dado:
coefficient : coeficiente com que se calcula o importe do imposto.
Para Mercado Pago se informam também os seguintes dados:
movement id : número de movimento.
reference id : operação relacionada.
Código de resposta HTTP.
206 – Partial content : em alguns casos, os endpoints devolverão o código 206 – Partial content. Isso acontece quando a solicitação para alguns dos dados falha, servirá para informá-lo de que você receberá uma resposta incompleta (por exemplo, desconto de um detalhe).Os erros serão exibidos no campo de errors da resposta do endpoint.
Estrutura do campo errors:
Descrição dos campos:
index : posição do objeto que não pode ser recuperado.
date created : tipo de erro.
taxable amount : descrição de erro.
Aplica a todos endpoints, exceto o download de documento legal e do reporte de detalhe de conciliação de reporte em formato XLSX y CSV.
Erros.
Os erros esperados que podem ocorrer na aplicação serão retornados tendo a seguinte estrutura:
timestamp : informa a data e hora que foi gerado o erro.
status : informa o código de erro retornado.
type : código de erro de aplicação. Valores possíveis:
ABUSE PREVENTION ERROR AUTHENTICATION ERROR AUTHORIZATION ERROR BAD REQUEST ERROR VALIDATION ERROR TYPE MISMATCH ERROR INTERNAL ERROR MISSING PARAMETER ERROR METHOD NOT ALLOWED ERROR NOT FOUND ERROR.
message : mostra uma mensagem de erro.
path : informa o endpoint que foi consumido.
errors : informa os erros ocorridos.
